BSON_PARSING(3)

💖 BSON_PARSING(3) — the libbson parsing page, bestie edition 💖

okay so you wanna parse BSON with libbson? say less. this is the libbson manual page for all things parsing, and i'm gonna walk you through it like we're texting at 2am. no gatekeeping here 💅

---

✨ PARSING ✨

so here's the tea: BSON documents are lazily parsed as necessary. like, they're not doing the work until you actually ask them to. to start parsing one, you grab one of the Libbson functions that makes a new bson_t from data you already have — bson_new_from_data() is the classic. heads up tho: it makes a copy of the data, specifically so you can go ahead and mutate the BSON document afterwards. bestie behavior honestly.

TIP: if all you wanna do is parse a BSON document and you have zero need to mutate it, you can use bson_init_static() instead and skip making that copy entirely. iykyk.

bson_t *b;

b = bson_new_from_data (my_data, my_data_len);
if (!b) {
   fprintf (stderr, "The specified length embedded in <my_data> did not match "
                    "<my_data_len>\n");
   return;
}

bson_destroy (b);

now, when you're creating a new bson_t from an existing buffer, only two checks happen. that's it. two:

1. the document has to begin with the buffer length, and it has to match what the caller expected.
2. the document has to end with the expected trailing \0 byte.

two vibe checks and you're in. 🦋

to parse the document any further, we use a bson_iter_t to iterate the elements inside it. let's print all the field names in the document, why not:

bson_t *b;
bson_iter_t iter;

if ((b = bson_new_from_data (my_data, my_data_len))) {
   if (bson_iter_init (&iter, b)) {
      while (bson_iter_next (&iter)) {
         printf ("Found element key: \"%s\"\n", bson_iter_key (&iter));
      }
   }
   bson_destroy (b);
}

and converting a document to JSON? that uses a bson_iter_t and a bson_visitor_t to iterate all the fields of a BSON document recursively and generate a UTF-8 encoded JSON string. it's giving glow-up:

bson_t *b;
char *json;

if ((b = bson_new_from_data (my_data, my_data_len))) {
   if ((json = bson_as_canonical_extended_json (b, NULL))) {
      printf ("%s\n", json);
      bson_free (json);
   }
   bson_destroy (b);
}

---

🌀 RECURSING INTO SUB-DOCUMENTS 🌀

Libbson hands you convenient sub-iterators so you can dive down into a sub-document or a sub-array like the main character you are. below is an example that dives into a sub-document named "foo" and prints its field names:

bson_iter_t iter;
bson_iter_t child;
char *json;

if (bson_iter_init_find (&iter, doc, "foo") &&
    BSON_ITER_HOLDS_DOCUMENT (&iter) && bson_iter_recurse (&iter, &child)) {
   while (bson_iter_next (&child)) {
      printf ("Found sub-key of \"foo\" named \"%s\"\n",
              bson_iter_key (&child));
   }
}

look at that recursion. we love to see it. 💖

---

🔍 FINDING FIELDS USING DOT NOTATION 🔍

using the bson_iter_recurse() function from the example above, bson_iter_find_descendant() can find a field for you using the MongoDB style path notation — stuff like "foo.bar.0.baz". obsessed.

let's create a document like {"foo": {"bar": [{"baz: 1}]}} and locate the "baz" field:

bson_t *b;
bson_iter_t iter;
bson_iter_t baz;

b =
   BCON_NEW ("foo", "{", "bar", "[", "{", "baz", BCON_INT32 (1), "}", "]", "}");

if (bson_iter_init (&iter, b) &&
    bson_iter_find_descendant (&iter, "foo.bar.0.baz", &baz) &&
    BSON_ITER_HOLDS_INT32 (&baz)) {
   printf ("baz = %d\n", bson_iter_int32 (&baz));
}

bson_destroy (b);

slay. one path string, one field, zero drama. ✨

---

✅ VALIDATING A BSON DOCUMENT ✅

if literally all you want to do is validate that a BSON document is valid, you can just use bson_validate(). that's the whole job:

size_t err_offset;

if (!bson_validate (doc, BSON_VALIDATE_NONE, &err_offset)) {
   fprintf (stderr,
            "The document failed to validate at offset: %u\n",
            (unsigned) err_offset);
}

peep the bson_validate() documentation for more info and more examples — this page is just the trailer, not the whole movie. 🎬

---

👑 AUTHOR 👑

MongoDB, Inc

---

📜 COPYRIGHT 📜

2017-present, MongoDB, Inc

---

and that's the whole page bestie, no cap. this was libbson version 1.26.0, dated Mar 31, 2024 — go forth and parse responsibly 🫶💜🌸