1BSON_STEAL(3)                       libbson                      BSON_STEAL(3)
2
3
4

NAME

6       bson_steal - bson_steal()
7

SYNOPSIS

9          bool
10          bson_steal (bson_t *dst, bson_t *src);
11

PARAMETERS

13       · dst: An uninitialized bson_t.
14
15       · src: A bson_t.
16

DESCRIPTION

18       Efficiently transfer the contents of src to dst and destroy src.
19
20       Before  calling  this function, src must be initialized and dst must be
21       uninitialized.  After  this  function  returns  successfully,  src   is
22       destroyed, and dst is initialized and must be freed with bson_destroy.
23
24       For  example, if you have a higher-level structure that wraps a bson_t,
25       use bson_steal to transfer BSON data into it:
26
27          typedef struct {
28             bson_t bson;
29          } bson_wrapper_t;
30
31
32          bson_wrapper_t *
33          wrap_bson (bson_t *b)
34          {
35             bson_wrapper_t *wrapper = bson_malloc (sizeof (bson_wrapper_t));
36
37             if (bson_steal (&wrapper->bson, b)) {
38                return wrapper;
39             }
40
41             bson_free (wrapper);
42             return NULL;
43          }
44
45
46          void
47          bson_wrapper_destroy (bson_wrapper_t *wrapper)
48          {
49             bson_destroy (&wrapper->bson);
50             bson_free (wrapper);
51          }
52
53
54          int
55          main (int argc, char *argv[])
56          {
57             bson_t bson = BSON_INITIALIZER;
58             bson_wrapper_t *wrapper;
59
60             BSON_APPEND_UTF8 (&bson, "key", "value");
61
62             /* now "bson" is destroyed */
63             wrapper = wrap_bson (&bson);
64
65             /* clean up */
66             bson_wrapper_destroy (wrapper);
67          }
68
69       See also bson_destroy_with_steal, a lower-level function  that  returns
70       the raw contents of a bson_t.
71

RETURNS

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

AUTHOR

77       MongoDB, Inc
78
80       2017-present, MongoDB, Inc
81
82
83
84
851.17.4                           Feb 04, 2021                    BSON_STEAL(3)
Impressum