<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="creating">
  <info><link type="guide" xref="index#intro"/></info>
  <title>Creating a BSON Document</title>

  <section id="basic">
    <title>The bson_t structure</title>
    <p>BSON documents are created using the <link xref="bson_t">bson_t</link> structure. This structure encapsulates the necessary logic for encoding using the <link href="http://bsonspec.org">BSON Specification</link>. At the core, <link xref="bson_t">bson_t</link> is a buffer manager and set of encoding routines.</p>
    <note style="tip"><p>BSON documents can live on the stack or the heap based on the performance needs or preference of the consumer.</p></note>
    <p>Let's start by creating a new BSON document on the stack. Whenever using libbson, make sure you <code>#include &lt;bson.h&gt;</code>.</p>
    <example><code mime="text/x-csrc"><![CDATA[bson_t b;

bson_init (&b);]]></code></example>
    <p>This creates an empty document. In JSON, this would be the same as <code mime="text/x-javascript">{}</code>.</p>
    <p>We can now proceed to adding items to the BSON document. A variety of functions prefixed with <code>bson_append_</code> can be used based on the type of field you want to append. Let's append a UTF-8 encoded string.</p>
    <example><code mime="text/x-csrc"><![CDATA[bson_append_utf8 (&b, "key", -1, "value", -1);]]></code></example>
    <p>Notice the two <code>-1</code> parameters. The first indicates that <code>key</code>'s length in bytes should be determined with <code>strlen()</code>. Alternatively, we could have passed the number <code>3</code>. The same goes for the second <code>-1</code>, but for <code>value</code>.</p>
    <p>Libbson provides macros to make this less tedious when using string literals. The following two appends are identical.</p>
    <example><code mime="text/x-csrc"><![CDATA[bson_append_utf8 (&b, "key", -1, "value", -1);
BSON_APPEND_UTF8 (&b, "key", "value");]]></code></example>
    <p>Now let's take a look at an example that adds a few different field types to a BSON document.</p>
    <example><code mime="text/x-csrc"><![CDATA[bson_t b = BSON_INITIALIZER;

BSON_APPEND_INT32 (&b, "a", 1);
BSON_APPEND_UTF8 (&b, "hello", "world");
BSON_APPEND_BOOL (&b, "bool", true);]]></code></example>
    <p>Notice that we ommitted the call to <link xref="bson_init">bson_init()</link>. By specifying <code>BSON_INITIALIZER</code> we can remove the need to initialize the structure to a base state.</p>
  </section>

  <section id="subdocs">
    <title>Sub-Documents and Sub-Arrays</title>
    <p>To simplify the creation of sub-documents and arrays, <link xref="bson_append_document_begin">bson_append_document_begin()</link> and <link xref="bson_append_array_begin">bson_append_array_begin()</link> exist. These can be used to build a sub-document using the parent documents memory region as the destination buffer.</p>
    <listing>
      <title>Creating Sub-Documents</title>
      <synopsis><code mime="text/x-csrc"><![CDATA[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);
]]></code></synopsis>
      <screen><output>{ "foo" : { "baz" : 1 } }</output></screen>
    </listing>
  </section>

  <section id="bcon">
    <title>Simplified BSON C Object Notation</title>
    <p>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.</p>
    <p>The following example shows the use of BCON. Notice that values for fields are wrapped in the <code>BCON_*</code> macros. These are required for the variadic processor to determine the parameter type.</p>
    <listing>
      <title></title>
      <synopsis><code mime="text/x-csrc"><![CDATA[bson_t *doc;

doc = BCON_NEW ("foo", "{",
   "int", BCON_INT32 (1),
   "array", "[", BCON_INT32 (100), "{", "sub", BCON_UTF8 ("value"), "}", "]",
"}");
]]></code></synopsis>
      <p>Creates the following document</p>
      <screen><output>{ "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }</output></screen>
    </listing>
  </section>

</page>
