1BSON_CREATING(3)                    libbson                   BSON_CREATING(3)
2
3
4

THE BSON_T STRUCTURE

6       BSON  documents  are created using the bson_t structure. This structure
7       encapsulates the necessary logic for encoding using the BSON Specifica‐
8       tion.  At the core, bson_t is a buffer manager and set of encoding rou‐
9       tines.
10
11       TIP:
12          BSON documents can live on the stack or the heap based on  the  per‐
13          formance needs or preference of the consumer.
14
15       Let's  start by creating a new BSON document on the stack. Whenever us‐
16       ing libbson, make sure you #include <bson/bson.h>.
17
18          bson_t b;
19
20          bson_init (&b);
21
22       This creates an empty document. In JSON, this would be the same as {}.
23
24       We can now proceed to adding items to the BSON document. A  variety  of
25       functions  prefixed  with bson_append_ can be used based on the type of
26       field you want to append. Let's append a UTF-8 encoded string.
27
28          bson_append_utf8 (&b, "key", -1, "value", -1);
29
30       Notice the two -1 parameters. The first indicates that  the  length  of
31       key  in  bytes  should  be  determined with strlen(). Alternatively, we
32       could have passed the number 3. The same goes for the  second  -1,  but
33       for value.
34
35       Libbson  provides  macros  to  make this less tedious when using string
36       literals. The following two appends are identical.
37
38          bson_append_utf8 (&b, "key", -1, "value", -1);
39          BSON_APPEND_UTF8 (&b, "key", "value");
40
41       Now let's take a look at an example that adds  a  few  different  field
42       types to a BSON document.
43
44          bson_t b = BSON_INITIALIZER;
45
46          BSON_APPEND_INT32 (&b, "a", 1);
47          BSON_APPEND_UTF8 (&b, "hello", "world");
48          BSON_APPEND_BOOL (&b, "bool", true);
49
50       Notice that we omitted the call to bson_init(). By specifying BSON_INI‐
51       TIALIZER we can remove the need to initialize the structure to  a  base
52       state.
53

SUB-DOCUMENTS AND SUB-ARRAYS

55       To  simplify the creation of sub-documents bson_append_document_begin()
56       can be used to build a sub-document using the parent's memory region as
57       the destination buffer.
58
59          bson_t parent = BSON_INITIALIZER;
60          bson_t child;
61
62          bson_append_document_begin (&parent, "foo", 3, &child);
63          bson_append_int32 (&child, "baz", 3, 1);
64          bson_append_document_end (&parent, &child);
65
66          char *str = bson_as_relaxed_extended_json (&parent, NULL);
67          printf ("%s\n", str); // Prints: { "foo" : { "baz" : 1 } }
68          bson_free (str);
69
70          bson_destroy (&parent);
71
72
73       To simplify the creation of sub-arrays bson_array_builder_t can be used
74       to build a sub-array using the parent's memory region as  the  destina‐
75       tion buffer.
76
77          bson_t parent = BSON_INITIALIZER;
78          bson_array_builder_t *bab;
79
80          bson_append_array_builder_begin (&parent, "foo", 3, &bab);
81          bson_array_builder_append_int32 (bab, 9);
82          bson_array_builder_append_int32 (bab, 8);
83          bson_array_builder_append_int32 (bab, 7);
84          bson_append_array_builder_end (&parent, bab);
85
86          char *str = bson_as_relaxed_extended_json (&parent, NULL);
87          printf ("%s\n", str); // Prints: { "foo" : [ 9, 8, 7 ] }
88          bson_free (str);
89
90          bson_destroy (&parent);
91
92

SIMPLIFIED BSON C OBJECT NOTATION

94       Creating  BSON  documents  by  hand  can be tedious and time consuming.
95       BCON, or BSON C Object Notation, was added to allow for the creation of
96       BSON documents in a format that looks closer to the destination format.
97
98       The  following  example  shows  the use of BCON. Notice that values for
99       fields are wrapped in the BCON_* macros. These  are  required  for  the
100       variadic processor to determine the parameter type.
101
102          bson_t *doc;
103
104          doc = BCON_NEW ("foo",
105                          "{",
106                          "int",
107                          BCON_INT32 (1),
108                          "array",
109                          "[",
110                          BCON_INT32 (100),
111                          "{",
112                          "sub",
113                          BCON_UTF8 ("value"),
114                          "}",
115                          "]",
116                          "}");
117
118       Creates the following document
119
120          { "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }
121

AUTHOR

123       MongoDB, Inc
124

126       2017-present, MongoDB, Inc
127
128
129
130
1311.25.1                           Nov 08, 2023                 BSON_CREATING(3)
Impressum