THE BSON_T STRUCTURE
BSON documents are created using the bson_t structure. This structure encapsulates the necessary logic for encoding using the BSON Specification \&. At the core, bson_t is a buffer manager and set of encoding routines.
NOTE
- BSON documents can live on the stack or the heap based on the performance needs or preference of the consumer.
Let's start by creating a new BSON document on the stack. Whenever using libbson, make sure you #include <bson.h> \&.
This creates an empty document. In JSON, this would be the same as {} \&.
We can now proceed to adding items to the BSON document. A variety of functions prefixed with bson_append_ can be used based on the type of field you want to append. Let's append a UTF-8 encoded string.
Notice the two -1 parameters. The first indicates that the length of key in bytes should be determined with strlen(3) \&. Alternatively, we could have passed the number 3 \&. The same goes for the second -1 , but for value \&.
Libbson provides macros to make this less tedious when using string literals. The following two appends are identical.
Now let's take a look at an example that adds a few different field types to a BSON document.
Notice that we omitted the call to bson_init(3) \&. By specifying BSON_INITIALIZER we can remove the need to initialize the structure to a base state.
SUB-DOCUMENTS AND SUB-ARRAYS
To simplify the creation of sub-documents and arrays, bson_append_document_begin(3) and bson_append_array_begin(3) exist. These can be used to build a sub-document using the parent documents memory region as the destination buffer.
bson_t parent;
bson_t child;
char *str;
bson_init (&parent);
bson_append_document_begin (&parent, "foo", 3, &child);
bson_append_int32 (&child, "baz", 3, 1);
bson_append_document_end (&parent, &child);
str = bson_as_json (&parent, NULL);
printf ("%s\n", str);
bson_free (str);
bson_destroy (&parent);
{ foo : { baz : 1 } }
SIMPLIFIED BSON C OBJECT NOTATION
Creating BSON documents by hand can be tedious and time consuming. BCON, or BSON C Object Notation, was added to allow for the creation of BSON documents in a format that looks closer to the destination format.
The following example shows the use of BCON. Notice that values for fields are wrapped in the BCON_* macros. These are required for the variadic processor to determine the parameter type.
bson_t *doc;
doc = BCON_NEW ("foo", "{",
"int", BCON_INT32 (1),
"array", "[", BCON_INT32 (100), "{", "sub", BCON_UTF8 ("value"), "}", "]",
"}");
Creates the following document
{ foo : { int : 1, array : [ 100, { sub : value } ] } }