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.

       TIP:
          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/bson.h>.

          bson_t b;

          bson_init (&b);

       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.

          bson_append_utf8 (&b, "key", -1, "value", -1);

       Notice  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.

       Libbson  provides  macros to make this less tedious when using string literals. The following two appends
       are identical.

          bson_append_utf8 (&b, "key", -1, "value", -1);
          BSON_APPEND_UTF8 (&b, "key", "value");

       Now let's take a look at an example that adds a few different field types to a BSON document.

          bson_t b = BSON_INITIALIZER;

          BSON_APPEND_INT32 (&b, "a", 1);
          BSON_APPEND_UTF8 (&b, "hello", "world");
          BSON_APPEND_BOOL (&b, "bool", true);

       Notice that we omitted the call to bson_init(). 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  bson_append_document_begin()  can  be  used  to  build  a
       sub-document using the parent's memory region as the destination buffer.

          bson_t parent = BSON_INITIALIZER;
          bson_t child;

          bson_append_document_begin (&parent, "foo", 3, &child);
          bson_append_int32 (&child, "baz", 3, 1);
          bson_append_document_end (&parent, &child);

          char *str = bson_as_relaxed_extended_json (&parent, NULL);
          printf ("%s\n", str); // Prints: { "foo" : { "baz" : 1 } }
          bson_free (str);

          bson_destroy (&parent);

       To simplify the creation of sub-arrays bson_array_builder_t can be used to build a  sub-array  using  the
       parent's memory region as the destination buffer.

          bson_t parent = BSON_INITIALIZER;
          bson_array_builder_t *bab;

          bson_append_array_builder_begin (&parent, "foo", 3, &bab);
          bson_array_builder_append_int32 (bab, 9);
          bson_array_builder_append_int32 (bab, 8);
          bson_array_builder_append_int32 (bab, 7);
          bson_append_array_builder_end (&parent, bab);

          char *str = bson_as_relaxed_extended_json (&parent, NULL);
          printf ("%s\n", str); // Prints: { "foo" : [ 9, 8, 7 ] }
          bson_free (str);

          bson_destroy (&parent);

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" } ] } }

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc