# bson_t

## BSON Document Abstraction

## Synopsis

    #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);

## Description

The bson_t structure represents a BSON document. This structure manages the underlying BSON encoded buffer. For mutable documents, it can append new data to the document.

## Performance Notes

The bson_t 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 bson_destroy() on allocated documents.

## Example

###

    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);
    }