forked from mongodb/libbson
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: move some bson_t docs to the getting started section.
- Loading branch information
Christian Hergert
committed
May 29, 2014
1 parent
8558765
commit ef5279b
Showing
2 changed files
with
76 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| <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 <bson.h></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> |