BSON_ITER_UTF8(3)

💅 BSON_ITER_UTF8 (3) — a libbson moment

ok so bestie, this is the page for bson_iter_utf8 from libbson, and it's honestly not that deep — it just grabs a string out of your BSON iterator. but there are ✨rules✨ and we're gonna respect them. let's go 🎀

---

✨ SYNOPSIS ✨

the whole thing, verbatim, no cap:

#define BSON_ITER_HOLDS_UTF8(iter) (bson_iter_type ((iter)) == BSON_TYPE_UTF8)

const char *
bson_iter_utf8 (const bson_iter_t *iter, uint32_t *length);

so you've got a cute lil macro that tells you "hey, is this thing a UTF-8 string?" and then the actual function that hands you the goods. 🫶

---

🌸 PARAMETERS 🌸

• iter — a bson_iter_t. your iterator. the main character. 💫
• length — an optional spot to stash the length of the resulting UTF-8 encoded string. optional bestie, so you can literally pass nothing if you don't care. 🙈

---

💖 DESCRIPTION 💖

bson_iter_utf8() retrieves the contents of a BSON_TYPE_UTF8 element that iter is currently looking at. that's it. that's the vibe check. ⭐

🚨 BUT — it is invalid to call this function while your iterator is observing an element that is not BSON_TYPE_UTF8. like, do not do that. it's giving "reading the wrong file" energy and the function will not be happy. 💀

that's why BSON_ITER_HOLDS_UTF8 exists up in the synopsis — check first, slay after. 👑

---

🔥 RETURNS 🔥

you get back a UTF-8 encoded string — not modified, not freed. it's a borrowed string, so don't go freeing it yourself, that's not your job. 🎀

it is suggested that you validate the content is actually valid UTF-8 before using it elsewhere. nobody's forcing you, but like… it's a good idea, iykyk. you can do that by calling bson_utf8_validate(), or by validating the underlying bson_t before you even start iterating it. two paths, both valid. 🌈

⚠️ heads up: not all drivers use multi-byte representation for \0 in UTF-8 encodings — this is commonly referred to as modified-UTF8 — so you probably wanna take a look at the length field when you're marshaling to other runtimes. like, actually look at it. don't just assume. 😭

---

👑 AUTHOR 👑

MongoDB, Inc — yes, the whole company. iconic. 💜

---

🦋 COPYRIGHT 🦋

2009-present, MongoDB, Inc. — that's a long run fr fr, respect. 🌸

---

and that's the page bestie!! this was libbson 2.5.6, dated Oct 09, 2026 — go forth and iterate responsibly 💅✨🍓