1:man_page: bson_creating 2 3Creating a BSON Document 4======================== 5 6The bson_t structure 7-------------------- 8 9BSON documents are created using the :symbol:`bson_t` structure. This structure encapsulates the necessary logic for encoding using the `BSON Specification <http://bsonspec.org>`_. At the core, :symbol:`bson_t` is a buffer manager and set of encoding routines. 10 11.. tip:: 12 13 BSON documents can live on the stack or the heap based on the performance needs or preference of the consumer. 14 15Let's start by creating a new BSON document on the stack. Whenever using libbson, make sure you ``#include <bson.h>``. 16 17.. code-block:: c 18 19 bson_t b; 20 21 bson_init (&b); 22 23This creates an empty document. In JSON, this would be the same as ``{}``. 24 25We 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. 26 27.. code-block:: c 28 29 bson_append_utf8 (&b, "key", -1, "value", -1); 30 31Notice the two ``-1`` parameters. The first indicates that the length of ``key`` in bytes should be determined with ``strlen()``. Alternatively, we could have passed the number ``3``. The same goes for the second ``-1``, but for ``value``. 32 33Libbson provides macros to make this less tedious when using string literals. The following two appends are identical. 34 35.. code-block:: c 36 37 bson_append_utf8 (&b, "key", -1, "value", -1); 38 BSON_APPEND_UTF8 (&b, "key", "value"); 39 40Now let's take a look at an example that adds a few different field types to a BSON document. 41 42.. code-block:: c 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 50Notice that we omitted the call to :symbol:`bson_init()`. By specifying ``BSON_INITIALIZER`` we can remove the need to initialize the structure to a base state. 51 52Sub-Documents and Sub-Arrays 53---------------------------- 54 55To simplify the creation of sub-documents and arrays, :symbol:`bson_append_document_begin()` and :symbol:`bson_append_array_begin()` exist. These can be used to build a sub-document using the parent documents memory region as the destination buffer. 56 57.. code-block:: c 58 59 bson_t parent; 60 bson_t child; 61 char *str; 62 63 bson_init (&parent); 64 bson_append_document_begin (&parent, "foo", 3, &child); 65 bson_append_int32 (&child, "baz", 3, 1); 66 bson_append_document_end (&parent, &child); 67 68 str = bson_as_canonical_extended_json (&parent, NULL); 69 printf ("%s\n", str); 70 bson_free (str); 71 72 bson_destroy (&parent); 73 74.. code-block:: none 75 76 { "foo" : { "baz" : 1 } } 77 78Simplified BSON C Object Notation 79--------------------------------- 80 81Creating 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. 82 83The 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. 84 85.. code-block:: c 86 87 bson_t *doc; 88 89 doc = BCON_NEW ("foo", 90 "{", 91 "int", 92 BCON_INT32 (1), 93 "array", 94 "[", 95 BCON_INT32 (100), 96 "{", 97 "sub", 98 BCON_UTF8 ("value"), 99 "}", 100 "]", 101 "}"); 102 103Creates the following document 104 105.. code-block:: none 106 107 { "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } } 108 109