BSON_APPEND_UTF8(3)

💅 BSON_APPEND_UTF8(3) — the libbson girlies' guide to yeeting strings into a bson 🎀

Okay bestie, settle in, because this one is literally the moment string data enters the chat. This is the BSON_APPEND_UTF8 page from the libbson manual, and we're gonna make it make sense. ✨

---

✨ SYNOPSIS ✨

So there's a macro (the convenient one) and a function (the full-control one). Both iconic, both doing the same job.

#define BSON_APPEND_UTF8(b, key, val) \
   bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val))

bool
bson_append_utf8 (bson_t *bson,
                  const char *key,
                  int key_length,
                  const char *value,
                  int length);

Note how the macro just does the strlen() math for you — no cap, that's the whole flex. 🫶

---

🌸 PARAMETERS 🌸

• bson — a bson_t. The doc you're adding to. Your main character.
• key — an ASCII C string holding the field name.
• key_length — how many bytes long key is, or -1 if you want it to figure that out with strlen().
• value — a UTF-8 encoded string. The actual content, the moment.
• length — how many bytes are in value, not counting the trailing \0, or -1 to let strlen() do its thing.

---

🦋 DESCRIPTION 🦋

bson_append_utf8() shall append a UTF-8 encoded string to bson. That's it, that's the plot. 💖

Now, important vibes-only warning: value MUST be valid UTF-8. Not "should", not "ideally" — must. Periodt.

Some UTF-8 implementations allow a \0 to live inside the string (that's separate from the terminating \0, bestie, don't get it twisted). Is that allowed? Yeah. But lowkey remember it could cause issues when you're talking to external systems that don't support it. 🙈

The suggestion on the table: use modified UTF-8, which uses a 2 byte representation for embedded \0 within the string. Why? Because that lets these UTF-8 encoded strings be used with many libc functions. Practical. Smart. We love. ✨

And here's the legacy-behavior plot twist you need to know: due to legacy behavior, passing NULL for value appends a null value, not a UTF8 value. 😭 If you actually want to append a null value directly, prefer using bson_append_null() instead. Like, that's the whole point of it existing.

---

⭐ RETURNS ⭐

Returns true if the operation was applied successfully. 🎉

The function will fail if appending the value grows bson larger than INT32_MAX. That's the ceiling, and it's not a vibe check you can pass — it's a hard limit. 💀

---

👑 AUTHOR 👑

MongoDB, Inc

---

🌈 COPYRIGHT 🌈

2009-present, MongoDB, Inc.

---

fr fr bestie, bookmark this one — MUST be valid UTF-8, watch your embedded \0s, and don't sleep on bson_append_null() for actual nulls. 💅

---

That's the whole page, mwah 💋 — this was libbson 2.5.6, dated Oct 09, 2026. Go append something iconic. 🍓🧚💜