.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BSON_STEAL" "3" "Feb 22, 2024" "1.26.0" "libbson"
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
bson_steal (bson_t *dst, bson_t *src);
.EE
.UNINDENT
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.IP \(bu 2
\fBdst\fP: An uninitialized \fI\%bson_t\fP\&.
.IP \(bu 2
\fBsrc\fP: A \fI\%bson_t\fP\&.
.UNINDENT
.SH DESCRIPTION
.sp
Efficiently transfer the contents of \fBsrc\fP to \fBdst\fP and destroy \fBsrc\fP\&.
.sp
Before calling this function, \fBsrc\fP must be initialized and \fBdst\fP must be uninitialized. After this function returns successfully, \fBsrc\fP is destroyed, and \fBdst\fP is initialized and must be freed with \fI\%bson_destroy()\fP\&.
.sp
For example, if you have a higher\-level structure that wraps a \fI\%bson_t\fP, use \fBbson_steal\fP to transfer BSON data into it:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
typedef struct {
   bson_t bson;
} bson_wrapper_t;


bson_wrapper_t *
wrap_bson (bson_t *b)
{
   bson_wrapper_t *wrapper = bson_malloc (sizeof (bson_wrapper_t));

   if (bson_steal (&wrapper\->bson, b)) {
      return wrapper;
   }

   bson_free (wrapper);
   return NULL;
}


void
bson_wrapper_destroy (bson_wrapper_t *wrapper)
{
   bson_destroy (&wrapper\->bson);
   bson_free (wrapper);
}


int
main (int argc, char *argv[])
{
   bson_t bson = BSON_INITIALIZER;
   bson_wrapper_t *wrapper;

   BSON_APPEND_UTF8 (&bson, \(dqkey\(dq, \(dqvalue\(dq);

   /* now \(dqbson\(dq is destroyed */
   wrapper = wrap_bson (&bson);

   /* clean up */
   bson_wrapper_destroy (wrapper);
}
.EE
.UNINDENT
.UNINDENT
.SH RETURNS
.sp
Returns \fBtrue\fP if \fBsrc\fP was successfully moved to \fBdst\fP, \fBfalse\fP if \fBsrc\fP is invalid, or was statically initialized, or another error occurred.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%bson_destroy_with_steal()\fP, a lower\-level function that returns the raw contents of a \fI\%bson_t\fP\&.
.fi
.sp
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.