.\" Man page generated from reStructuredText.
.
.TH "BSON_CREATING" "3" "Feb 23, 2019" "1.14.0" "Libbson"
.SH NAME
bson_creating \- Creating a BSON Document
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH THE BSON_T STRUCTURE
.sp
BSON documents are created using the \fBbson_t\fP structure. This structure encapsulates the necessary logic for encoding using the \fI\%BSON Specification\fP\&. At the core, \fBbson_t\fP is a buffer manager and set of encoding routines.
.sp
\fBTIP:\fP
.INDENT 0.0
.INDENT 3.5
BSON documents can live on the stack or the heap based on the performance needs or preference of the consumer.
.UNINDENT
.UNINDENT
.sp
Let\(aqs start by creating a new BSON document on the stack. Whenever using libbson, make sure you \fB#include <bson/bson.h>\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_t b;

bson_init (&b);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This creates an empty document. In JSON, this would be the same as \fB{}\fP\&.
.sp
We can now proceed to adding items to the BSON document. A variety of functions prefixed with \fBbson_append_\fP can be used based on the type of field you want to append. Let\(aqs append a UTF\-8 encoded string.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_append_utf8 (&b, "key", \-1, "value", \-1);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice the two \fB\-1\fP parameters. The first indicates that the length of \fBkey\fP in bytes should be determined with \fBstrlen()\fP\&. Alternatively, we could have passed the number \fB3\fP\&. The same goes for the second \fB\-1\fP, but for \fBvalue\fP\&.
.sp
Libbson provides macros to make this less tedious when using string literals. The following two appends are identical.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_append_utf8 (&b, "key", \-1, "value", \-1);
BSON_APPEND_UTF8 (&b, "key", "value");
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now let\(aqs take a look at an example that adds a few different field types to a BSON document.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_t b = BSON_INITIALIZER;

BSON_APPEND_INT32 (&b, "a", 1);
BSON_APPEND_UTF8 (&b, "hello", "world");
BSON_APPEND_BOOL (&b, "bool", true);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice that we omitted the call to \fBbson_init()\fP\&. By specifying \fBBSON_INITIALIZER\fP we can remove the need to initialize the structure to a base state.
.SH SUB-DOCUMENTS AND SUB-ARRAYS
.sp
To simplify the creation of sub\-documents and arrays, \fBbson_append_document_begin()\fP and \fBbson_append_array_begin()\fP exist. These can be used to build a sub\-document using the parent documents memory region as the destination buffer.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\en", str);
bson_free (str);

bson_destroy (&parent);
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{ "foo" : { "baz" : 1 } }
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SIMPLIFIED BSON C OBJECT NOTATION
.sp
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.
.sp
The following example shows the use of BCON. Notice that values for fields are wrapped in the \fBBCON_*\fP macros. These are required for the variadic processor to determine the parameter type.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_t *doc;

doc = BCON_NEW ("foo",
                "{",
                "int",
                BCON_INT32 (1),
                "array",
                "[",
                BCON_INT32 (100),
                "{",
                "sub",
                BCON_UTF8 ("value"),
                "}",
                "]",
                "}");
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Creates the following document
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{ "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.