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

1.9.2                                             Jan 12, 2018                                     BSON_STEAL(3)