BSON_CREATING(3)

💖 BSON_CREATING(3) — the libbson page where we make BSON docs 💖

okay bestie, sit down, hydrate, and let's talk about making BSON documents with libbson ✨ this is the BSON_CREATING(3) manual and honestly? it's giving beginner-friendly but make it powerful 🫶

---

🧱 THE BSON_T STRUCTURE

BSON documents get created with the bson_t structure. This little icon encapsulates all the logic you need for encoding stuff per the BSON Specification. At its core, bson_t is a buffer manager plus a set of encoding routines. main character energy fr 💅

TIP: BSON documents can live on the stack or the heap, depending on the performance needs or preference of whoever's consuming them. no cap, you get to choose 🌸

Let's start by making a brand new BSON document on the stack. Whenever you're using libbson, make sure you #include <bson/bson.h> first, bestie 🙈

bson_t b;

bson_init (&b);

Boom. That's an empty document. In JSON, this would be exactly the same as {}. lowkey poetic 🌈

Now we can start adding items to the BSON document. There's a whole lineup of functions prefixed with bson_append_ and you pick whichever one matches the type of field you wanna append. Let's append a UTF-8 encoded string, shall we? ✨

bson_append_utf8 (&b, "key", -1, "value", -1);

Notice the two -1 parameters — they're not a typo, they're a vibe 😌 The first one says the length of key in bytes should be figured out with strlen(). Alternatively, we could've just passed the number 3. Same deal for the second -1, but for value.

Libbson ships macros so this whole thing is way less tedious when you're using string literals. These next two appends are literally identical, bestie:

bson_append_utf8 (&b, "key", -1, "value", -1);
BSON_APPEND_UTF8 (&b, "key", "value");

Now let's peek at an example that adds a few different field types to a BSON document 👑

bson_t b = BSON_INITIALIZER;

BSON_APPEND_INT32 (&b, "a", 1);
BSON_APPEND_UTF8 (&b, "hello", "world");
BSON_APPEND_BOOL (&b, "bool", true);

See how we skipped the call to bson_init()? By specifying BSON_INITIALIZER we can remove the need to initialize the structure to a base state. it's giving efficient 💅

---

🪆 SUB-DOCUMENTS AND SUB-ARRAYS

To make sub-documents less of a hassle, bson_append_document_begin() can be used to build a sub-document using the parent's memory region as the destination buffer. nesting but make it cute 🎀

bson_t parent = BSON_INITIALIZER;
bson_t child;

bson_append_document_begin (&parent, "foo", 3, &child);
bson_append_int32 (&child, "baz", 3, 1);
bson_append_document_end (&parent, &child);

char *str = bson_as_relaxed_extended_json (&parent, NULL);
printf ("%s\n", str); // Prints: { "foo" : { "baz" : 1 } }
bson_free (str);

bson_destroy (&parent);

And to make sub-arrays less of a hassle, bson_array_builder_t can be used to build a sub-array using the parent's memory region as the destination buffer. obsessed 🦋

bson_t parent = BSON_INITIALIZER;
bson_array_builder_t *bab;

bson_append_array_builder_begin (&parent, "foo", 3, &bab);
bson_array_builder_append_int32 (bab, 9);
bson_array_builder_append_int32 (bab, 8);
bson_array_builder_append_int32 (bab, 7);
bson_append_array_builder_end (&parent, bab);

char *str = bson_as_relaxed_extended_json (&parent, NULL);
printf ("%s\n", str); // Prints: { "foo" : [ 9, 8, 7 ] }
bson_free (str);

bson_destroy (&parent);

---

🍓 SIMPLIFIED BSON C OBJECT NOTATION

ngl, creating BSON documents by hand can be tedious and time consuming. so BCON — that's BSON C Object Notation — was added to let you create BSON documents in a format that looks way closer to the destination format. ate and left no crumbs 🔥

The example below shows BCON in action. Notice how the values for fields are wrapped in the BCON_* macros — those are required so the variadic processor can determine the parameter type. don't skip them, bestie 🙈

bson_t *doc;

doc = BCON_NEW ("foo",
                "{",
                "int",
                BCON_INT32 (1),
                "array",
                "[",
                BCON_INT32 (100),
                "{",
                "sub",
                BCON_UTF8 ("value"),
                "}",
                "]",
                "}");

Creates the following document ✨

{ "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }

---

👑 AUTHOR

MongoDB, Inc

📜 COPYRIGHT

2017-present, MongoDB, Inc

---

and that's the whole page, bestie 💖 this was BSON_CREATING(3) from libbson, version 1.26.0, dated Mar 31, 2024. go forth and build documents, you absolute icon 🌟🫶