Provided by: libbson-doc_1.15.0-1_all bug


       bson_creating - Creating a BSON Document


       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.

          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

          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.


       To simplify the creation of sub-documents  and  arrays,  bson_append_document_begin()  and
       bson_append_array_begin()  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_canonical_extended_json (&parent, NULL);
          printf ("%s\n", str);
          bson_free (str);

          bson_destroy (&parent);

          { "foo" : { "baz" : 1 } }


       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",
                          BCON_INT32 (1),
                          BCON_INT32 (100),
                          BCON_UTF8 ("value"),

       Creates the following document

          { "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }


       MongoDB, Inc


       2017-present, MongoDB, Inc