NAME

       Creating_a_BSON_Document - None

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

COLOPHON

       This page is part of libbson.  Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.

libbson                                            2016‐01‐18                        CREATING_A_BSON_DOCUMENT(3)