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

PARSING

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

RECURSING INTO SUB-DOCUMENTS

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

FINDING FIELDS USING DOT NOTATION

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

VALIDATING A BSON DOCUMENT

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

AUTHOR

120       MongoDB, Inc
121

123       2017-present, MongoDB, Inc
124
125
126
127
1281.25.1                           Nov 08, 2023                  BSON_PARSING(3)
Impressum