1BSON_PARSING(3)                     libbson                    BSON_PARSING(3)
2
3
4

NAME

6       bson_parsing - Parsing and Iterating BSON Documents
7

PARSING

9       BSON  documents are lazily parsed as necessary. To begin parsing a BSON
10       document, use one of the provided Libbson functions  to  create  a  new
11       bson_t  from existing data such as bson_new_from_data(). This will make
12       a copy of the data so that additional mutations may occur to  the  BSON
13       document.
14
15       TIP:
16          If you only want to parse a BSON document and have no need to mutate
17          it, you may use bson_init_static() to avoid making  a  copy  of  the
18          data.
19
20          bson_t *b;
21
22          b = bson_new_from_data (my_data, my_data_len);
23          if (!b) {
24             fprintf (stderr, "The specified length embedded in <my_data> did not match "
25                              "<my_data_len>\n");
26             return;
27          }
28
29          bson_destroy (b);
30
31       Only two checks are performed when creating a new bson_t from an exist‐
32       ing buffer. First, the document must  begin  with  the  buffer  length,
33       matching what was expected by the caller. Second, the document must end
34       with the expected trailing \0 byte.
35
36       To parse the document further we use a bson_iter_t to iterate the  ele‐
37       ments  within  the  document. Let's print all of the field names in the
38       document.
39
40          bson_t *b;
41          bson_iter_t iter;
42
43          if ((b = bson_new_from_data (my_data, my_data_len))) {
44             if (bson_iter_init (&iter, b)) {
45                while (bson_iter_next (&iter)) {
46                   printf ("Found element key: \"%s\"\n", bson_iter_key (&iter));
47                }
48             }
49             bson_destroy (b);
50          }
51
52       Converting a document to JSON uses a bson_iter_t and bson_visitor_t  to
53       iterate  all fields of a BSON document recursively and generate a UTF-8
54       encoded JSON string.
55
56          bson_t *b;
57          char *json;
58
59          if ((b = bson_new_from_data (my_data, my_data_len))) {
60             if ((json = bson_as_canonical_extended_json (b, NULL))) {
61                printf ("%s\n", json);
62                bson_free (json);
63             }
64             bson_destroy (b);
65          }
66

RECURSING INTO SUB-DOCUMENTS

68       Libbson provides convenient sub-iterators to dive down into a sub-docu‐
69       ment  or sub-array. Below is an example that will dive into a sub-docu‐
70       ment named "foo" and print it's field names.
71
72          bson_iter_t iter;
73          bson_iter_t child;
74          char *json;
75
76          if (bson_iter_init_find (&iter, doc, "foo") &&
77              BSON_ITER_HOLDS_DOCUMENT (&iter) && bson_iter_recurse (&iter, &child)) {
78             while (bson_iter_next (&child)) {
79                printf ("Found sub-key of \"foo\" named \"%s\"\n",
80                        bson_iter_key (&child));
81             }
82          }
83

FINDING FIELDS USING DOT NOTATION

85       Using   the    bson_iter_recurse()    function    exemplified    above,
86       bson_iter_find_descendant()  can find a field for you using the MongoDB
87       style path notation such as "foo.bar.0.baz".
88
89       Let's create a document like {"foo": {"bar": [{"baz: 1}]}}  and  locate
90       the "baz" field.
91
92          bson_t *b;
93          bson_iter_t iter;
94          bson_iter_t baz;
95
96          b =
97             BCON_NEW ("foo", "{", "bar", "[", "{", "baz", BCON_INT32 (1), "}", "]", "}");
98
99          if (bson_iter_init (&iter, b) &&
100              bson_iter_find_descendant (&iter, "foo.bar.0.baz", &baz) &&
101              BSON_ITER_HOLDS_INT32 (&baz)) {
102             printf ("baz = %d\n", bson_iter_int32 (&baz));
103          }
104
105          bson_destroy (b);
106

VALIDATING A BSON DOCUMENT

108       If  all  you  want to do is validate that a BSON document is valid, you
109       can use bson_validate().
110
111          size_t err_offset;
112
113          if (!bson_validate (doc, BSON_VALIDATE_NONE, &err_offset)) {
114             fprintf (stderr,
115                      "The document failed to validate at offset: %u\n",
116                      (unsigned) err_offset);
117          }
118
119       See the bson_validate() documentation for more  information  and  exam‐
120       ples.
121

AUTHOR

123       MongoDB, Inc
124

126       2017-present, MongoDB, Inc
127
128
129
130
1311.23.1                           Oct 20, 2022                  BSON_PARSING(3)
Impressum