1BSON_TUTORIAL(3) Libbson BSON_TUTORIAL(3)
2
6 bson_tutorial - Tutorial
7
9 Include bson.h
10 All libbson's functions and types are available in one header file.
11 Simply include bson.h: hello_bson.c.INDENT 0.0
12 #include <stdio.h>
14 #include <bson/bson.h>
15 int
17 main (int argc, const char **argv)
18 {
19 bson_t *b;
20 char *j;
21 b = BCON_NEW ("hello", BCON_UTF8 ("bson!"));
23 j = bson_as_canonical_extended_json (b, NULL);
24 printf ("%s\n", j);
25 bson_free (j);
27 bson_destroy (b);
28 return 0;
30 }
31 CMake
34 The libbson installation includes a CMake config-file package, so you
35 can use CMake's find_package command to find libbson's header and
36 library paths and link to libbson: CMakeLists.txt.INDENT 0.0
37 # Specify the minimum version you require.
39 find_package (libbson-1.0 1.7 REQUIRED)
40 message ("-- libbson found version \"${BSON_VERSION}\"")
42 message ("-- libbson include path \"${BSON_INCLUDE_DIRS}\"")
43 message ("-- libbson libraries \"${BSON_LIBRARIES}\"")
44 # The "hello_bson.c" sample program is shared among four tests.
46 add_executable (hello_bson ../../hello_bson.c)
47 target_include_directories (hello_bson PRIVATE ${BSON_INCLUDE_DIRS})
48 target_link_libraries (hello_bson PRIVATE ${BSON_LIBRARIES})
49 target_compile_definitions (hello_bson PRIVATE ${BSON_DEFINITIONS})
50By default, libbson is dynamically linked. You can use libbson as a static
53library instead: Use the included libbson-static-1.0 config-file package and
54(on Unix) link to pthread:
55 # Specify the minimum version you require.
57 find_package (libbson-static-1.0 1.7 REQUIRED)
58 message ("-- libbson-static found version \"${BSON_STATIC_VERSION}\"")
60 message ("-- libbson-static include path \"${BSON_STATIC_INCLUDE_DIRS}\"")
61 message ("-- libbson-static libraries \"${BSON_STATIC_LIBRARIES}\"")
62 # The "hello_bson.c" sample program is shared among four tests.
64 add_executable (hello_bson ../../hello_bson.c)
65 target_include_directories (hello_bson PRIVATE ${BSON_STATIC_INCLUDE_DIRS})
66 target_link_libraries (hello_bson PRIVATE ${BSON_STATIC_LIBRARIES})
67 target_compile_definitions (hello_bson PRIVATE ${BSON_STATIC_DEFINITIONS})
68 pkg-config
71 If you're not using CMake, use pkg-config on the command line to set
72 header and library paths:
73 gcc -o hello_bson hello_bson.c $(pkg-config --libs --cflags libbson-1.0)
75 Or to statically link to libbson:
78 gcc -o hello_bson hello_bson.c $(pkg-config --libs --cflags libbson-static-1.0)
80
83 The bson_t structure
84 BSON documents are created using the bson_t structure. This structure
85 encapsulates the necessary logic for encoding using the BSON Specifica‐
86 tion. At the core, bson_t is a buffer manager and set of encoding rou‐
87 tines.
88 TIP:
90 BSON documents can live on the stack or the heap based on the per‐
91 formance needs or preference of the consumer.
92 Let's start by creating a new BSON document on the stack. Whenever
94 using libbson, make sure you #include <bson/bson.h>.
95 bson_t b;
97 bson_init (&b);
99 This creates an empty document. In JSON, this would be the same as {}.
101 We can now proceed to adding items to the BSON document. A variety of
103 functions prefixed with bson_append_ can be used based on the type of
104 field you want to append. Let's append a UTF-8 encoded string.
105 bson_append_utf8 (&b, "key", -1, "value", -1);
107 Notice the two -1 parameters. The first indicates that the length of
109 key in bytes should be determined with strlen(). Alternatively, we
110 could have passed the number 3. The same goes for the second -1, but
111 for value.
112 Libbson provides macros to make this less tedious when using string
114 literals. The following two appends are identical.
115 bson_append_utf8 (&b, "key", -1, "value", -1);
117 BSON_APPEND_UTF8 (&b, "key", "value");
118 Now let's take a look at an example that adds a few different field
120 types to a BSON document.
121 bson_t b = BSON_INITIALIZER;
123 BSON_APPEND_INT32 (&b, "a", 1);
125 BSON_APPEND_UTF8 (&b, "hello", "world");
126 BSON_APPEND_BOOL (&b, "bool", true);
127 Notice that we omitted the call to bson_init(). By specifying BSON_INI‐
129 TIALIZER we can remove the need to initialize the structure to a base
130 state.
131 Sub-Documents and Sub-Arrays
133 To simplify the creation of sub-documents and arrays, bson_append_docu‐
134 ment_begin() and bson_append_array_begin() exist. These can be used to
135 build a sub-document using the parent documents memory region as the
136 destination buffer.
137 bson_t parent;
139 bson_t child;
140 char *str;
141 bson_init (&parent);
143 bson_append_document_begin (&parent, "foo", 3, &child);
144 bson_append_int32 (&child, "baz", 3, 1);
145 bson_append_document_end (&parent, &child);
146 str = bson_as_canonical_extended_json (&parent, NULL);
148 printf ("%s\n", str);
149 bson_free (str);
150 bson_destroy (&parent);
152 { "foo" : { "baz" : 1 } }
154 Simplified BSON C Object Notation
156 Creating BSON documents by hand can be tedious and time consuming.
157 BCON, or BSON C Object Notation, was added to allow for the creation of
158 BSON documents in a format that looks closer to the destination format.
159 The following example shows the use of BCON. Notice that values for
161 fields are wrapped in the BCON_* macros. These are required for the
162 variadic processor to determine the parameter type.
163 bson_t *doc;
165 doc = BCON_NEW ("foo",
167 "{",
168 "int",
169 BCON_INT32 (1),
170 "array",
171 "[",
172 BCON_INT32 (100),
173 "{",
174 "sub",
175 BCON_UTF8 ("value"),
176 "}",
177 "]",
178 "}");
179 Creates the following document
181 { "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }
183
185 Description
186 Many libbson functions report errors by returning NULL or -1 and fill‐
187 ing out a bson_error_t structure with an error domain, error code, and
188 message.
189 · error.domain names the subsystem that generated the error.
191 · error.code is a domain-specific error type.
193 · error.message describes the error.
195 Some error codes overlap with others; always check both the domain and
197 code to determine the type of error.
198┌──────────────────┬────────────────────────────────────┬────────────────────────────────┐
204│BSON_ERROR_JSON │ BSON_JSON_ERROR_READ_COR‐ │ bson_json_reader_t │
205│ │ RUPT_JS │ tried to parse │
206│ │ BSON_JSON_ERROR_READ_INVALID_PARAM │ invalid MongoDB │
207│ │ BSON_JSON_ERROR_READ_CB_FAIL‐ │ Extended JSON. │
208│ │ URE │ Tried to parse a │
209│ │ │ valid JSON document │
210│ │ │ that is invalid as │
211│ │ │ MongoDBExtended │
212│ │ │ JSON. An internal │
213│ │ │ callback failure │
214│ │ │ during JSON pars‐ │
215│ │ │ ing. │
216├──────────────────┼────────────────────────────────────┼────────────────────────────────┤
217│BSON_ERROR_READER │ BSON_ERROR_READER_BADFD │ bson_json_reader_new_from_file │
218│ │ │ could not open the │
219│ │ │ file. │
220└──────────────────┴────────────────────────────────────┴────────────────────────────────┘
221
223 Libbson provides a simple way to generate ObjectIDs. It can be used in
224 a single-threaded or multi-threaded manner depending on your require‐
225 ments.
226 The bson_oid_t structure represents an ObjectID in MongoDB. It is a
228 96-bit identifier.
229 Composition
231 · 4 bytes : The UNIX timestamp in big-endian format.
232 · 5 bytes : A random number.
234 · 3 bytes : A 24-bit monotonic counter incrementing from rand() in
236 big-endian.
237 Sorting ObjectIDs
239 The typical way to sort in C is using qsort(). Therefore, Libbson pro‐
240 vides a qsort() compatible callback function named bson_oid_compare().
241 It returns less than 1, greater than 1, or 0 depending on the equality
242 of two bson_oid_t structures.
243 Comparing Object IDs
245 If you simply want to compare two bson_oid_t structures for equality,
246 use bson_oid_equal().
247 Generating
249 To generate a bson_oid_t, you may use the following.
250 bson_oid_t oid;
252 bson_oid_init (&oid, NULL);
254 Parsing ObjectID Strings
256 You can also parse a string containing a bson_oid_t. The input string
257 MUST be 24 characters or more in length.
258 bson_oid_t oid;
260 bson_oid_init_from_string (&oid, "123456789012345678901234");
262 bson_oid_t oid;
264 bson_oid_init_from_string_unsafe (&oid, "123456789012345678901234");
266 Hashing ObjectIDs
268 If you need to store items in a hashtable, you may want to use the
269 bson_oid_t as the key. Libbson provides a hash function for just this
270 purpose. It is based on DJB hash.
271 unsigned hash;
273 hash = bson_oid_hash (oid);
275 Fetching ObjectID Creation Time
277 You can easily fetch the time that a bson_oid_t was generated using
278 bson_oid_get_time_t().
279 time_t t;
281 t = bson_oid_get_time_t (oid);
283 printf ("The OID was generated at %u\n", (unsigned) t);
284
286 Parsing
287 BSON documents are lazily parsed as necessary. To begin parsing a BSON
288 document, use one of the provided Libbson functions to create a new
289 bson_t from existing data such as bson_new_from_data(). This will make
290 a copy of the data so that additional mutations may occur to the BSON
291 document.
292 TIP:
294 If you only want to parse a BSON document and have no need to mutate
295 it, you may use bson_init_static() to avoid making a copy of the
296 data.
297 bson_t *b;
299 b = bson_new_from_data (my_data, my_data_len);
301 if (!b) {
302 fprintf (stderr, "The specified length embedded in <my_data> did not match "
303 "<my_data_len>\n");
304 return;
305 }
306 bson_destroy (b);
308 Only two checks are performed when creating a new bson_t from an exist‐
310 ing buffer. First, the document must begin with the buffer length,
311 matching what was expected by the caller. Second, the document must end
312 with the expected trailing \0 byte.
313 To parse the document further we use a bson_iter_t to iterate the ele‐
315 ments within the document. Let's print all of the field names in the
316 document.
317 bson_t *b;
319 bson_iter_t iter;
320 if ((b = bson_new_from_data (my_data, my_data_len))) {
322 if (bson_iter_init (&iter, b)) {
323 while (bson_iter_next (&iter)) {
324 printf ("Found element key: \"%s\"\n", bson_iter_key (&iter));
325 }
326 }
327 bson_destroy (b);
328 }
329 Converting a document to JSON uses a bson_iter_t and bson_visitor_t to
331 iterate all fields of a BSON document recursively and generate a UTF-8
332 encoded JSON string.
333 bson_t *b;
335 char *json;
336 if ((b = bson_new_from_data (my_data, my_data_len))) {
338 if ((json = bson_as_canonical_extended_json (b, NULL))) {
339 printf ("%s\n", json);
340 bson_free (json);
341 }
342 bson_destroy (b);
343 }
344 Recursing into Sub-Documents
346 Libbson provides convenient sub-iterators to dive down into a sub-docu‐
347 ment or sub-array. Below is an example that will dive into a sub-docu‐
348 ment named "foo" and print it's field names.
349 bson_iter_t iter;
351 bson_iter_t child;
352 char *json;
353 if (bson_iter_init_find (&iter, doc, "foo") &&
355 BSON_ITER_HOLDS_DOCUMENT (&iter) && bson_iter_recurse (&iter, &child)) {
356 while (bson_iter_next (&child)) {
357 printf ("Found sub-key of \"foo\" named \"%s\"\n",
358 bson_iter_key (&child));
359 }
360 }
361 Finding Fields using Dot Notation
363 Using the bson_iter_recurse() function exemplified above,
364 bson_iter_find_descendant() can find a field for you using the MongoDB
365 style path notation such as "foo.bar.0.baz".
366 Let's create a document like {"foo": {"bar": [{"baz: 1}]}} and locate
368 the "baz" field.
369 bson_t *b;
371 bson_iter_t iter;
372 bson_iter_t baz;
373 b =
375 BCON_NEW ("foo", "{", "bar", "[", "{", "baz", BCON_INT32 (1), "}", "]", "}");
376 if (bson_iter_init (&iter, b) &&
378 bson_iter_find_descendant (&iter, "foo.bar.0.baz", &baz) &&
379 BSON_ITER_HOLDS_INT32 (&baz)) {
380 printf ("baz = %d\n", bson_iter_int32 (&baz));
381 }
382 bson_destroy (b);
384 Validating a BSON Document
386 If all you want to do is validate that a BSON document is valid, you
387 can use bson_validate().
388 size_t err_offset;
390 if (!bson_validate (doc, BSON_VALIDATE_NONE, &err_offset)) {
392 fprintf (stderr,
393 "The document failed to validate at offset: %u\n",
394 (unsigned) err_offset);
395 }
396 See the bson_validate() documentation for more information and exam‐
398 ples.
399
401 Encoding
402 Libbson expects that you are always working with UTF-8 encoded text.
403 Anything else is invalid API use.
404 If you should need to walk through UTF-8 sequences, you can use the
406 various UTF-8 helper functions distributed with Libbson.
407 Validating a UTF-8 Sequence
409 To validate the string contained in my_string, use the following. You
410 may pass -1 for the string length if you know the string is NULL-termi‐
411 nated.
412 if (!bson_utf8_validate (my_string, -1, false)) {
414 printf ("Validation failed.\n");
415 }
416 If my_string has NULL bytes within the string, you must provide the
418 string length. Use the following format. Notice the true at the end
419 indicating \0 is allowed.
420 if (!bson_utf8_validate (my_string, my_string_len, true)) {
422 printf ("Validation failed.\n");
423 }
424 For more information see the API reference for bson_utf8_validate().
426
428 MongoDB, Inc
429
431 2017-present, MongoDB, Inc
4321.14.0 Feb 22, 2019 BSON_TUTORIAL(3)