BSON_ITER_T(3)

💅 BSON Document Iterator 💅

okay bestie, welcome to libbson's iterator page — this is the little struct that lets you walk through a BSON document element by element, and honestly? it's iconic. let's get into it 🎀

---

✨ SYNOPSIS ✨

first, the include (mandatory, no skipping):

#include <bson/bson.h>

then the whole family of "hey what type is this field actually" macro checks — every single one of them, here we go:

#define BSON_ITER_HOLDS_DOUBLE(iter) /* ... */

#define BSON_ITER_HOLDS_UTF8(iter) /* ... */

#define BSON_ITER_HOLDS_DOCUMENT(iter) /* ... */

#define BSON_ITER_HOLDS_ARRAY(iter) /* ... */

#define BSON_ITER_HOLDS_BINARY(iter) /* ... */

#define BSON_ITER_HOLDS_VECTOR(iter) /* ... */
#define BSON_ITER_HOLDS_VECTOR_INT8(iter) /* ... */
#define BSON_ITER_HOLDS_VECTOR_FLOAT32(iter) /* ... */
#define BSON_ITER_HOLDS_VECTOR_PACKED_BIT(iter) /* ... */

#define BSON_ITER_HOLDS_UNDEFINED(iter) /* ... */

#define BSON_ITER_HOLDS_OID(iter) /* ... */

#define BSON_ITER_HOLDS_BOOL(iter) /* ... */

#define BSON_ITER_HOLDS_DATE_TIME(iter) /* ... */

#define BSON_ITER_HOLDS_NULL(iter) /* ... */

#define BSON_ITER_HOLDS_REGEX(iter) /* ... */

#define BSON_ITER_HOLDS_DBPOINTER(iter) /* ... */

#define BSON_ITER_HOLDS_CODE(iter) /* ... */

#define BSON_ITER_HOLDS_SYMBOL(iter) /* ... */

#define BSON_ITER_HOLDS_CODEWSCOPE(iter) /* ... */

#define BSON_ITER_HOLDS_INT32(iter) /* ... */

#define BSON_ITER_HOLDS_TIMESTAMP(iter) /* ... */

#define BSON_ITER_HOLDS_INT64(iter) /* ... */

#define BSON_ITER_HOLDS_DECIMAL128(iter) /* ... */

#define BSON_ITER_HOLDS_MAXKEY(iter) /* ... */

#define BSON_ITER_HOLDS_MINKEY(iter) /* ... */

and then the combo macros, the "actually I'm flexible about this" ones 🫶:

#define BSON_ITER_HOLDS_INT(iter) \
   (BSON_ITER_HOLDS_INT32 (iter) || BSON_ITER_HOLDS_INT64 (iter))

#define BSON_ITER_HOLDS_NUMBER(iter) \
   (BSON_ITER_HOLDS_INT (iter) || BSON_ITER_HOLDS_DOUBLE (iter))

#define BSON_ITER_IS_KEY(iter, key) \
   (0 == strcmp ((key), bson_iter_key ((iter))))

and the struct itself — look at it, look away, it's shy:

typedef struct {
   /*< private >*/
} bson_iter_t;

---

🌸 DESCRIPTION 🌸

so bson_iter_t is a struct you use to iterate through the elements of a bson_t. that's the whole vibe. 💖

it's meant to live on the stack, and you can toss it away whenever you want — like, whenever whenever — because it holds no external allocation. no cleanup era, no free() arc, nothing. ✨

the contents of the struct? consider them private. they may change between releases (ngl, they probably will), but the structure size will not change — that part's locked in, periodt.

⚠️ two rules, bestie, and they're not optional: - the bson_t MUST stay valid for the entire lifetime of the iter - modifying the bson_t while you're using the iter is an error 🚫

---

🦋 EXAMPLES 🦋

walk the whole doc and print every field name — the classic:

bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc)) {
   while (bson_iter_next (&iter)) {
      printf ("Found a field named: %s\n", bson_iter_key (&iter));
   }
}

only want one specific field? bson_iter_find has you covered:

bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc) && bson_iter_find (&iter, "my_field")) {
   printf ("Found the field named: %s\n", bson_iter_key (&iter));
}

need to go inside a sub-document or array? recurse into it like the main character you are 👑:

bson_iter_t iter;
bson_iter_t sub_iter;

if (bson_iter_init_find (&iter, my_bson_doc, "mysubdoc") &&
    (BSON_ITER_HOLDS_DOCUMENT (&iter) || BSON_ITER_HOLDS_ARRAY (&iter)) &&
    bson_iter_recurse (&iter, &sub_iter)) {
   while (bson_iter_next (&sub_iter)) {
      printf ("Found key \"%s\" in sub document.\n", bson_iter_key (&sub_iter));
   }
}

and for the dotted-path girlies, bson_iter_find_descendant digging all the way down to a.b.c.d:

bson_iter_t iter;

if (bson_iter_init (&iter, my_doc) &&
    bson_iter_find_descendant (&iter, "a.b.c.d", &sub_iter)) {
   printf ("The type of a.b.c.d is: %d\n", (int) bson_iter_type (&sub_iter));
}

---

💜 AUTHOR 💜

MongoDB, Inc — the icons who wrote it 🫶

🎀 COPYRIGHT 🎀

2009-present, MongoDB, Inc. — slay, that's a long reign.

---

okay that's the whole page, bestie!! this was libbson version 2.5.6, dated Oct 09, 2026, and honestly it ate. go iterate on something gorgeous 💅✨🌈