1BSON_CREATING(3) libbson BSON_CREATING(3)
2
3
4
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
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
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
123 MongoDB, Inc
124
126 2017-present, MongoDB, Inc
127
128
129
130
1311.25.1 Nov 08, 2023 BSON_CREATING(3)