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