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);
          }

RETURNS

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

       SEE ALSO:
          bson_destroy_with_steal, a lower-level function that returns the raw contents of a bson_t.

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc

1.21.0                                            Feb 09, 2022                                     BSON_STEAL(3)