NAME

       bson_steal - bson_steal()

SYNOPSIS

          bool
          bson_steal (bson_t *dst, bson_t *src);

PARAMETERS

       • dst: An uninitialized bson_t.

       • src: A bson_t.

DESCRIPTION

       Efficiently transfer the contents of src to dst and destroy src.

       Before calling this function, src must be initialized and dst must be uninitialized. After
       this function returns successfully, src is destroyed, and dst is initialized and  must  be
       freed with bson_destroy.

       For  example,  if you have a higher-level structure that wraps a bson_t, use bson_steal to
       transfer BSON data into it:

          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, "key", "value");

             /* now "bson" is destroyed */
             wrapper = wrap_bson (&bson);

             /* clean up */
             bson_wrapper_destroy (wrapper);
          }

       See also bson_destroy_with_steal, a lower-level function that returns the raw contents  of
       a bson_t.

RETURNS

       Returns  true  if  src  was  successfully  moved  to  dst, false if src is invalid, or was
       statically initialized, or another error occurred.

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2018, MongoDB, Inc