.\" This manpage is Copyright (C) 2016 MongoDB, Inc.
.\" 
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3
.\" or any later version published by the Free Software Foundation;
.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the section entitled "GNU
.\" Free Documentation License".
.\" 
.TH "BSON_DESTROY_WITH_STEAL" "3" "2016\(hy10\(hy12" "libbson"
.SH NAME
bson_destroy_with_steal() \- The bson_destroy_with_steal() function shall destroy a bson_t structure but return the underlying buffer instead of freeing it. If steal is false, this is equivalent to calling bson_destroy(). It is a programming error to call this function on a bson_t that is not a top-level bson_t, such as those initialized with bson_append_document_begin(), bson_append_array_begin(), and bson_writer_begin().
.SH "SYNOPSIS"

.nf
.nf
uint8_t *
bson_destroy_with_steal (bson_t   *bson,
                         bool      steal,
                         uint32_t *length);
.fi
.fi

.SH "PARAMETERS"

.TP
.B
bson
A
.B bson_t
.
.LP
.TP
.B
steal
A bool indicating if the underlying buffer should be stolen.
.LP
.TP
.B
length
A location for storing the resulting buffer length.
.LP

.SH "DESCRIPTION"

The
.B bson_destroy_with_steal(3)
function shall destroy a
.B bson_t
structure but return the underlying buffer instead of freeing it. If steal is false, this is equivalent to calling bson_destroy(). It is a programming error to call this function on a
.B bson_t
that is not a top\(hylevel
.B bson_t
, such as those initialized with
.B bson_append_document_begin(3)
,
.B bson_append_array_begin(3)
, and
.B bson_writer_begin(3)
.

See also
.B bson_steal
, a higher\(hylevel function that efficiently transfers the contents of one
.B bson_t
to another.

.SH "RETURNS"

.B bson_destroy_with_steal(3)
shall return a buffer containing the contents of the
.B bson_t
if
.B steal
is non\(hyzero. This should be freed with
.B bson_free(3)
when no longer in use.
.B length
will be set to the length of the bson document if non\(hyNULL.


.B
.SH COLOPHON
This page is part of libbson.
Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.