<?xml version="1.0"?>
<page id="bson_t"
      type="guide"
      style="class"
      xmlns="http://projectmallard.org/1.0/"
      xmlns:api="http://projectmallard.org/experimental/api/"
      xmlns:ui="http://projectmallard.org/experimental/ui/">

  <info>
    <link type="guide" xref="index#api-reference" />
  </info>

  <title>bson_t</title>
  <subtitle>BSON Document Abstraction</subtitle>

  <section id="description">
    <title>Synopsis</title>
    <synopsis><code mime="text/x-csrc"><![CDATA[#include <bson.h>

BSON_ALIGNED_BEGIN (128)
typedef struct
{
   uint32_t flags;         /* Internal flags for the bson_t. */
   uint32_t len;           /* Length of BSON data. */
   uint8_t  padding[120];  /* Padding for stack allocation. */
} bson_t
BSON_ALIGNED_END (128);]]></code></synopsis>
  </section>

  <section id="description">
    <title>Description</title>
    <p>The <link xref="bson_t">bson_t</link> structure represents a BSON document. This structure manages the underlying BSON encoded buffer. For mutable documents, it can append new data to the document.</p>
  </section>

  <section id="perf">
    <title>Performance Notes</title>
    <p>The <link xref="bson_t">bson_t</link> structure attepts to use an inline allocation within the structure to speed up performance of small documents. When this internal buffer has been exhausted, a heap allocated buffer will be dynamically allocated. Therefore, it is essential to call <code>bson_destroy()</code> on allocated documents.</p>
  </section>

  <links type="topic" groups="function" style="2column">
    <title>Functions</title>
  </links>

  <section id="examples">
    <title>Example</title>
    <listing>
      <title></title>
      <synopsis><code mime="text/x-csrc"><![CDATA[
static void
create_on_heap (void)
{
   bson_t *b = bson_new ();

   BSON_APPEND_INT32 (b, "foo", 123);
   BSON_APPEND_UTF8 (b, "bar", "foo");
   BSON_APPEND_DOUBLE (b, "baz", 1.23f);

   bson_destroy (b);
}
]]></code></synopsis>
    </listing>
  </section>
</page>
