BSON_ITER_INIT_FROM_DATA(3)

💅 BSON_ITER_INIT_FROM_DATA 💅

okay so bestie, welcome to the libbson manual page for bson_iter_init_from_data(3) — yes that's the manual name, it's giving "long function name energy" and honestly? iconic. this one's about booting up an iterator straight from a raw buffer of bytes, and it's lowkey one of the most useful little functions in the whole iterator family. let's get into it 🫶

---

✨ SYNOPSIS ✨

bool
bson_iter_init_from_data (bson_iter_t *iter, const uint8_t *data, size_t length);

like, that's the whole signature. three args, one bool back. no cap, that's it 💖

---

🎀 PARAMETERS 🎀

• iter — a bson_iter_t. this is the iterator you're waking up, the main character of this whole operation 👑
• data — a buffer to initialize with. this is where your bytes live, so hand it over 💅
• length — the length of data in bytes. yes bestie, you gotta tell it how big the buffer is, it can't read your mind 😭

---

🦋 DESCRIPTION 🦋

so the bson_iter_init_from_data() function shall initialize iter to iterate upon the buffer data, which — and this is the important part — must contain a BSON document. like, that's non-negotiable, that's the vibe check, the buffer has to actually be a BSON doc or this whole thing is not it 🙈

upon initialization, iter is placed before the first element. not on it. before it. so don't come for it when nothing's returned yet, it's literally positioned pre-first-element by design ✨

so what do you do next? callers must call bson_iter_next(), bson_iter_find(), or bson_iter_find_case() to advance to an element. pick your fighter:

• bson_iter_next() — just walk forward, one at a time
• bson_iter_find() — hunt for an exact key name
• bson_iter_find_case() — same hunt, case-insensitive, be free 🌈

---

🌸 RETURNS 🌸

returns true if the iter was successfully initialized. that's it, that's the return. no extra lore 💀

---

⭐ EXAMPLE ⭐

here's a whole little function that pulls the _id out of a document and prints it as a string, and honestly it ate:

static void
print_doc_id (const uint8_t *data, size_t length)
{
   bson_iter_t iter;
   bson_oid_t oid;
   char oidstr[25];

   if (bson_iter_init_from_data (&iter, data, length) && bson_iter_find (&iter, "_id") &&
       BSON_ITER_HOLDS_OID (&iter)) {
      bson_iter_oid (&iter, &oid);
      bson_oid_to_string (&oid, oidstr);
      printf ("%s\n", oidstr);
   } else {
      printf ("Document is missing _id.\n");
   }
}

walk through it with me: init from data, find "_id", check BSON_ITER_HOLDS_OID(), then grab it with bson_iter_oid(), stringify with bson_oid_to_string() into oidstr[25], and printf it. and if any of those checks fail? you get Document is missing _id. — blunt, honest, we respect it 😌

---

🧚 AUTHOR 🧚

MongoDB, Inc

---

💜 COPYRIGHT 💜

2009-present, MongoDB, Inc.

---

okay bestie that's the whole page, go forth and iterate 🦋✨

cute little sign-off: this was libbson version 2.5.6, dated Oct 09, 2026 — see you in the next manpage, mwah 💋💖