BSON_REFERENCE(3)

💖 BSON_REFERENCE(3) 💖

Okay bestie, this is the libbson manual page — yes, the BSON_REFERENCE(3) one — and it’s giving “C library but make it readable.” Buckle up, we’re doing this together. 🫶

🌈 LIBBSON - API 🌈

A Cross Platform BSON Library for C

This site documents the API. For tutorials, guides, and explainers, see MongoDB C Driver.

✨ Introduction ✨

libbson literally builds, parses, and iterates BSON documents — the native data format of MongoDB. It also converts BSON to and from JSON, and provides a platform compatibility layer for the MongoDB C Driver. Obsessed. 🦋

🧚 API Reference 🧚

💖 bson_t 💖

BSON Document Abstraction

🌸 Synopsis 🌸

#include <bson/bson.h>

/**
 * bson_empty:
 * @b: a bson_t.
 *
 * Checks to see if @b is an empty BSON document. An empty BSON document is
 * a 5 byte document which contains the length (4 bytes) and a single NUL
 * byte indicating end of fields.
 */
#define bson_empty(b) /* ... */

/**
 * bson_empty0:
 *
 * Like bson_empty() but treats NULL the same as an empty bson_t document.
 */
#define bson_empty0(b) /* ... */

/**
 * bson_clear:
 *
 * Easily free a bson document and set it to NULL. Use like:
 *
 * bson_t *doc = bson_new();
 * bson_clear (&doc);
 * BSON_ASSERT (doc == NULL);
 */
#define bson_clear(bptr) /* ... */

/**
 * BSON_MAX_SIZE:
 *
 * The maximum size in bytes of a BSON document.
 */
#define BSON_MAX_SIZE /* ... */

#define BSON_APPEND_ARRAY(b, key, val) \
   bson_append_array (b, key, (int) strlen (key), val)

#define BSON_APPEND_ARRAY_BEGIN(b, key, child) \
   bson_append_array_begin (b, key, (int) strlen (key), child)

#define BSON_APPEND_BINARY(b, key, subtype, val, len) \
   bson_append_binary (b, key, (int) strlen (key), subtype, val, len)

#define BSON_APPEND_BINARY_UNINIT(b, key, subtype, val, len) \
   bson_append_binary_uninit (b, key, (int) strlen (key), subtype, val, len)

#define BSON_APPEND_BOOL(b, key, val) \
   bson_append_bool (b, key, (int) strlen (key), val)

#define BSON_APPEND_CODE(b, key, val) \
   bson_append_code (b, key, (int) strlen (key), val)

#define BSON_APPEND_CODE_WITH_SCOPE(b, key, val, scope) \
   bson_append_code_with_scope (b, key, (int) strlen (key), val, scope)

#define BSON_APPEND_DBPOINTER(b, key, coll, oid) \
   bson_append_dbpointer (b, key, (int) strlen (key), coll, oid)

#define BSON_APPEND_DOCUMENT_BEGIN(b, key, child) \
   bson_append_document_begin (b, key, (int) strlen (key), child)

#define BSON_APPEND_DOUBLE(b, key, val) \
   bson_append_double (b, key, (int) strlen (key), val)

#define BSON_APPEND_DOCUMENT(b, key, val) \
   bson_append_document (b, key, (int) strlen (key), val)

#define BSON_APPEND_INT32(b, key, val) \
   bson_append_int32 (b, key, (int) strlen (key), val)

#define BSON_APPEND_INT64(b, key, val) \
   bson_append_int64 (b, key, (int) strlen (key), val)

#define BSON_APPEND_MINKEY(b, key) \
   bson_append_minkey (b, key, (int) strlen (key))

#define BSON_APPEND_DECIMAL128(b, key, val) \
   bson_append_decimal128 (b, key, (int) strlen (key), val)

#define BSON_APPEND_MAXKEY(b, key) \
   bson_append_maxkey (b, key, (int) strlen (key))

#define BSON_APPEND_NULL(b, key) bson_append_null (b, key, (int) strlen (key))

#define BSON_APPEND_OID(b, key, val) \
   bson_append_oid (b, key, (int) strlen (key), val)

#define BSON_APPEND_REGEX(b, key, val, opt) \
   bson_append_regex (b, key, (int) strlen (key), val, opt)

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

#define BSON_APPEND_SYMBOL(b, key, val) \
   bson_append_symbol (b, key, (int) strlen (key), val, (int) strlen (val))

#define BSON_APPEND_TIME_T(b, key, val) \
   bson_append_time_t (b, key, (int) strlen (key), val)

#define BSON_APPEND_TIMEVAL(b, key, val) \
   bson_append_timeval (b, key, (int) strlen (key), val)

#define BSON_APPEND_DATE_TIME(b, key, val) \
   bson_append_date_time (b, key, (int) strlen (key), val)

#define BSON_APPEND_TIMESTAMP(b, key, val, inc) \
   bson_append_timestamp (b, key, (int) strlen (key), val, inc)

#define BSON_APPEND_UNDEFINED(b, key) \
   bson_append_undefined (b, key, (int) strlen (key))

#define BSON_APPEND_VALUE(b, key, val) \
   bson_append_value (b, key, (int) strlen (key), (val))

typedef struct {
   uint32_t flags;       /* Internal flags for the bson_t. */
   uint32_t len;         /* Length of BSON data. */
   uint8_t padding[120]; /* Padding for stack allocation. */
} bson_t;

💫 Description 💫

The bson_t structure represents a BSON document. This structure manages the underlying BSON encoded buffer. For mutable documents, it can append new data to the document. 💅

🔥 Performance Notes 🔥

The bson_t structure attempts to use an inline allocation within the structure to speed up performance of small documents. When this internal buffer has been exhausted, a heap allocated buffer will be dynamically allocated. Therefore, it is essential to call bson_destroy() on allocated documents. No cap, that cleanup call is not optional. 🧚

🫶 Duplicate Keys 🫶

The BSON specification allows BSON documents to have duplicate keys. Documents are stored as an ordered list of key-value pairs. A bson_t may contain duplicate keys. Applications should refrain from generating such documents, because MongoDB server behavior is undefined when a BSON document contains duplicate keys. That “undefined” is doing a lot of heavy lifting, so don’t test it. 😭

🎀 Example 🎀

static void
create_on_heap (void)
{
   bson_t *b = bson_new ();

   BSON_APPEND_INT32 (b, "foo", 123);
   BSON_APPEND_UTF8 (b, "bar", "foo");
   BSON_APPEND_DOUBLE (b, "baz", 1.23f);

   bson_destroy (b);
}

🦋 bson_t lifetimes 🦋

A bson_t may contain its data directly or may contain pointers to heap-allocated memory. Overwriting an existing bson_t or allowing a stack-allocated bson_t to go out of scope may cause a memory leak. A bson_t should always be destroyed with bson_destroy(). Periodt. 💜

👑 bson_t out parameters 👑

A bson_t pointer used as an out parameter must point to valid overwritable storage for a new bson_t which must be one of:

1. Uninitialized storage for a bson_t.
2. A zero-initialized bson_t object.
3. A bson_t object initialized with BSON_INITIALIZER.
4. A bson_t object not created with bson_new() that was destroyed with bson_destroy().

This can be on the stack:

bson_t stack_doc = BSON_INITIALIZER;
example_get_doc (&stack_doc);
bson_destroy (&stack_doc);

Or on the heap:

bson_t *heap_doc = bson_malloc (sizeof (bson_t));
example_get_doc (heap_doc);
bson_destroy (heap_doc);
bson_free (heap_doc);

Omitting bson_destroy() in either case may cause memory leaks.

WARNING: Passing a bson_t pointer obtained from bson_new() as an out parameter will result in a leak of the bson_t struct.

bson_t *heap_doc = bson_new ();
example_get_doc (heap_doc);
bson_destroy (heap_doc); // Leaks the `bson_t` struct!

💅 bson_array_builder_t 💅

typedef struct _bson_array_builder_t bson_array_builder_t;

bson_array_builder_t may be used to build BSON arrays. bson_array_builder_t internally tracks and uses the array index as a key ("0", "1", "2", ...) when appending elements. It’s giving organized. 🍓

🌈 Appending an array value 🌈

typedef struct _bson_array_builder_t bson_array_builder_t;

bool
bson_append_array_builder_begin (bson_t *bson,
                                 const char *key,
                                 int key_length,
                                 bson_array_builder_t **child);

bool
bson_append_array_builder_end (bson_t *bson, bson_array_builder_t *child);

#define BSON_APPEND_ARRAY_BUILDER_BEGIN(b, key, child) \
  bson_append_array_builder_begin (b, key, (int) strlen (key), child)

bson_append_array_builder_begin may be used to append an array as a value. Example:

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);

🧁 Creating a top-level array 🧁

bson_array_builder_t * bson_array_builder_new (void);

bool
bson_array_builder_build (bson_array_builder_t *bab, bson_t *out);

void
bson_array_builder_destroy (bson_array_builder_t *bab);

bson_array_builder_new and bson_array_builder_build may be used to build a top-level BSON array. bson_array_builder_build initializes and moves BSON data to out. The bson_array_builder_t may be reused and will start appending a new array at index "0":

Example:

bson_t out;
bson_array_builder_t *bab = bson_array_builder_new();

bson_array_builder_append_int32(bab, 9);
bson_array_builder_append_int32(bab, 8);
bson_array_builder_append_int32(bab, 7);
bson_array_builder_build(bab, &out);

char *str = bson_array_as_relaxed_extended_json(&out, NULL);
printf("%s\n", str); // Prints: [ 9, 8, 7 ]
bson_free(str);

bson_array_builder_destroy(bab);

🍓 Appending values to an array 🍓

bson_array_builder_append_* functions are provided to append values to a BSON array. The bson_array_builder_append_* functions internally use bson_append_* and provide the array index as a key:

bool
bson_array_builder_append_value (bson_array_builder_t *bab,
                                 const bson_value_t *value);

bool
bson_array_builder_append_array (bson_array_builder_t *bab,
                                 const bson_t *array);

bool
bson_array_builder_append_binary (bson_array_builder_t *bab,
                                  bson_subtype_t subtype,
                                  const uint8_t *binary,
                                  uint32_t length);

bool
bson_array_builder_append_binary_uninit (bson_array_builder_t *bab,
                                         bson_subtype_t subtype,
                                         uint8_t **binary,
                                         uint32_t length);

bool
bson_array_builder_append_bool (bson_array_builder_t *bab, bool value);

bool
bson_array_builder_append_code (bson_array_builder_t *bab,
                                const char *javascript);

okay bestie, we're still deep in bson_array_builder_t land and there are… a LOT of append girlies left to meet. deep breath. full roster, signatures and all, no skips: 💖

• bson_array_builder_append_code_with_scope — bool bson_array_builder_append_code_with_scope (bson_array_builder_t *bab, const char *javascript, const bson_t *scope); — code with scope, bestie: the javascript plus the bson_t scope it lives with. ✨
• bson_array_builder_append_dbpointer — bool bson_array_builder_append_dbpointer (bson_array_builder_t *bab, const char *collection, const bson_oid_t *oid); — drops in a DBPointer built from a collection name and an oid. 🎀
• bson_array_builder_append_double — bool bson_array_builder_append_double (bson_array_builder_t *bab, double value); — one double, zero drama. 💅
• bson_array_builder_append_document — bool bson_array_builder_append_document (bson_array_builder_t *bab, const bson_t *value); — slides a whole bson_t document in as one element. 🦋
• bson_array_builder_append_document_begin — bool bson_array_builder_append_document_begin (bson_array_builder_t *bab, bson_t *child); — opens a nested document and hands you the child to fill in. 🌸
• bson_array_builder_append_document_end — bool bson_array_builder_append_document_end (bson_array_builder_t *bab, bson_t *child); — closes that child document back up. 🫶
• bson_array_builder_append_int32 — bool bson_array_builder_append_int32 (bson_array_builder_t *bab, int32_t value); — an int32_t. iconic, tiny. 😭
• bson_array_builder_append_int64 — bool bson_array_builder_append_int64 (bson_array_builder_t *bab, int64_t value); — the int64_t upgrade, same energy. 🔥
• bson_array_builder_append_decimal128 — bool bson_array_builder_append_decimal128 (bson_array_builder_t *bab, const bson_decimal128_t *value); — appends a bson_decimal128_t (yes, that struct comes later on this page, keep reading 💜).
• bson_array_builder_append_iter — bool bson_array_builder_append_iter (bson_array_builder_t *bab, const bson_iter_t *iter); — takes a bson_iter_t and appends from it. 👑
• bson_array_builder_append_minkey — bool bson_array_builder_append_minkey (bson_array_builder_t *bab); — MinKey, no args, no notes. ⭐
• bson_array_builder_append_maxkey — bool bson_array_builder_append_maxkey (bson_array_builder_t *bab); — MaxKey. the other end of the universe. 🌈
• bson_array_builder_append_null — bool bson_array_builder_append_null (bson_array_builder_t *bab); — null. that's it. that's the whole function. 💀
• bson_array_builder_append_oid — bool bson_array_builder_append_oid (bson_array_builder_t *bab, const bson_oid_t *oid); — an bson_oid_t, no cap. 🙈
• bson_array_builder_append_regex — bool bson_array_builder_append_regex (bson_array_builder_t *bab, const char *regex, const char *options); — a regex with its options string. 🍓
• bson_array_builder_append_regex_w_len — bool bson_array_builder_append_regex_w_len (bson_array_builder_t *bab, const char *regex, int regex_length, const char *options); — same thing but you pass regex_length yourself, main character energy. 🧚
• bson_array_builder_append_utf8 — bool bson_array_builder_append_utf8 (bson_array_builder_t *bab, const char *value, int length); — a UTF-8 string with an explicit length. ✨
• bson_array_builder_append_symbol — bool bson_array_builder_append_symbol (bson_array_builder_t *bab, const char *value, int length); — a symbol, length and all. 💖
• bson_array_builder_append_time_t — bool bson_array_builder_append_time_t (bson_array_builder_t *bab, time_t value); — from a time_t. 🌸
• bson_array_builder_append_timeval — bool bson_array_builder_append_timeval (bson_array_builder_t *bab, struct timeval *value); — from a struct timeval *. 🎀
• bson_array_builder_append_date_time — bool bson_array_builder_append_date_time (bson_array_builder_t *bab, int64_t value); — a date-time as an int64_t. 🦋
• bson_array_builder_append_now_utc — bool bson_array_builder_append_now_utc (bson_array_builder_t *bab); — literally now, in UTC. time is a construct but this one slaps. 🔥
• bson_array_builder_append_timestamp — bool bson_array_builder_append_timestamp (bson_array_builder_t *bab, uint32_t timestamp, uint32_t increment); — a BSON timestamp from timestamp + increment. 👑
• bson_array_builder_append_undefined — bool bson_array_builder_append_undefined (bson_array_builder_t *bab); — undefined. the vibe check of types. 💀
• bson_array_builder_append_array_builder_begin — bool bson_array_builder_append_array_builder_begin (bson_array_builder_t *bab, bson_array_builder_t **child); — nests an array builder and gives you child (double pointer, she's fancy). 🌈
• bson_array_builder_append_array_builder_end — bool bson_array_builder_append_array_builder_end (bson_array_builder_t *bab, bson_array_builder_t *child); — closes that nested child builder. 🙈

---

and the two convenience macros, written out exactly so you can't mess them up:

#define BSON_APPEND_ARRAY_BUILDER_APPEND_UTF8(b, value) bson_array_builder_append_utf8(b, value, (int)strlen(value))

#define BSON_APPEND_ARRAY_BUILDER_APPEND_SYMBOL(b, value) bson_array_builder_append_symbol(b, value, (int)strlen(value))

both of them just do the (int)strlen(value) math for you so you don't have to. considerate queens. 🫶

---

🪪 bson_context_t — BSON OID Generation Context

✨ Synopsis ✨

#include <bson/bson.h>

typedef enum {
  BSON_CONTEXT_NONE = 0,
  BSON_CONTEXT_DISABLE_PID_CACHE = (1 << 2),
} bson_context_flags_t;

typedef struct _bson_context_t bson_context_t;

bson_context_t *
bson_context_get_default (void);
bson_context_t *
bson_context_new (bson_context_flags_t flags);
void
bson_context_destroy (bson_context_t *context);

💅 Description 💅

okay so bson_context_t is the context used for generating BSON Object IDs, and it exists so you can override how that ObjectID generation behaves. the flags that actually do something are BSON_CONTEXT_NONE, BSON_CONTEXT_THREAD_SAFE, and BSON_CONTEXT_DISABLE_PID_CACHE — those are the only ones used, periodt. the others? literally no effect. 💀

🌸 Example 🌸

#include <bson/bson.h>

int
main (int argc, char *argv[])
{
   bson_context_t *ctx = NULL;
   bson_oid_t oid;

   /* use default context, via bson_context_get_default() */
   bson_oid_init (&oid, NULL);

   /* specify a local context for additional control */
   ctx = bson_context_new (BSON_CONTEXT_NONE);
   bson_oid_init (&oid, ctx);

   bson_context_destroy (ctx);

   return 0;
}

---

🔢 bson_decimal128_t — BSON Decimal128 Abstraction

✨ Synopsis ✨

#include <bson/bson.h>

#define BSON_DECIMAL128_STRING 43
#define BSON_DECIMAL128_INF "Infinity"
#define BSON_DECIMAL128_NAN "NaN"

typedef struct {
#if BSON_BYTE_ORDER == BSON_LITTLE_ENDIAN
   uint64_t low;
   uint64_t high;
#elif BSON_BYTE_ORDER == BSON_BIG_ENDIAN
   uint64_t high;
   uint64_t low;
#endif
} bson_decimal128_t;

💅 Description 💅

bson_decimal128_t is the struct for the IEEE-754 Decimal128 data type. it's an aggregate holding two uint64_ts named high and low, and the way they're declared (and the order they sit in) depends on the endianness of the target platform: low always means the low-order bits of the Decimal128 object, high always means the high-order bits. and here's the slay: bson_decimal128_t is always sixteen (16) bytes, and you can bit-cast it to/from a _Decimal128. 🤯

🌸 Example 🌸

#include <bson/bson.h>
#include <stdio.h>

int
main (int argc, char *argv[])
{
   char string[BSON_DECIMAL128_STRING];
   bson_decimal128_t decimal128;

   bson_decimal128_from_string ("100.00", &decimal128);
   bson_decimal128_to_string (&decimal128, string);
   printf ("Decimal128 value: %s\n", string);

   return 0;
}

---

🚨 bson_error_t — BSON Error Encapsulation

✨ Synopsis ✨

#include <bson/bson.h>

typedef struct {
   uint32_t domain;
   uint32_t code;
   char message[504];
} bson_error_t;

💅 Description 💅

bson_error_t is the out-parameter you use to hand error info back to whoever called you. it should be stack-allocated, and it does not need freeing — no cleanup era, we love that for us. 🫶

see Handling Errors for more.

🌸 Example 🌸

bson_reader_t *reader;
bson_error_t error;

reader = bson_reader_new_from_file ("dump.bson", &error);
if (!reader) {
   fprintf (
      stderr, "ERROR: %d.%d: %s\n", error.domain, error.code, error.message);
}

---

🔍 bson_iter_t — BSON Document Iterator

✨ Synopsis ✨

#include <bson/bson.h>

#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) /* ... */

#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))))

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

💅 Description 💅

bson_iter_t is the struct you use to iterate through the elements of a bson_t. live your best stack life — it's meant to be used on the stack and you can discard it whenever, because it holds no external allocation. ✨ the contents of the struct are private, consider them off-limits, and they may change between releases — but the size of the structure will not change. no cap.

🚨 the bson_t MUST stay valid for the entire lifetime of the iter, and modifying the bson_t while you're using the iter is an error. do not do it. i'm serious. 😭

🌸 Examples 🌸

walk every field:

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));
   }
}

or go find one specific field:

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));
}

or dive into a sub-document, because we're nosy:

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 the descendant hunt, for when the field is buried deep:

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));
}

---

🗂️ bson_json_reader_t — Bulk JSON to BSON conversion

✨ Synopsis ✨

#include <bson/bson.h>

typedef struct _bson_json_reader_t bson_json_reader_t;

that's the whole synopsis this section gives us, bestie — a typedef and the promise of bulk JSON → BSON conversion. the rest of the reader girlies are further down the page, so keep scrolling. 💜

typedef enum {
   BSON_JSON_ERROR_READ_CORRUPT_JS = 1,
   BSON_JSON_ERROR_READ_INVALID_PARAM,
   BSON_JSON_ERROR_READ_CB_FAILURE,
} bson_json_error_code_t;

📖 Description

The bson_json_reader_t structure is literally your bestie for reading a sequence of JSON documents and transforming them into bson_t documents.

It’s lowkey super useful when you wanna do bulk operations that are defined in a file containing JSON documents. Like, bulk stuff? From a JSON file? Yes bestie, that’s the vibe.

💡 TIP: bson_json_reader_t works upon JSON documents formatted in MongoDB extended JSON format.

🌟 Example

/*
 * Copyright 2009-present MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/*
 * This program will print each JSON document contained in the provided files
 * as a BSON string to STDOUT.
 */

#include <bson/bson.h>
#include <stdlib.h>
#include <stdio.h>

int
main (int argc, char *argv[])
{
   bson_json_reader_t *reader;
   bson_error_t error;
   const char *filename;
   bson_t doc = BSON_INITIALIZER;
   int i;
   int b;

   /*
    * Print program usage if no arguments are provided.
    */
   if (argc == 1) {
      fprintf (stderr, "usage: %s FILE...\n", argv[0]);
      return 1;
   }

   /*
    * Process command line arguments expecting each to be a filename.
    */
   for (i = 1; i < argc; i++) {
      filename = argv[i];

      /*
       * Open the filename provided in command line arguments.
       */
      if (0 == strcmp (filename, "-")) {
         reader = bson_json_reader_new_from_fd (STDIN_FILENO, false);
      } else {
         if (!(reader = bson_json_reader_new_from_file (filename, &error))) {
            fprintf (
               stderr, "Failed to open \"%s\": %s\n", filename, error.message);
            continue;
         }
      }

      /*
       * Convert each incoming document to BSON and print to stdout.
       */
      while ((b = bson_json_reader_read (reader, &doc, &error))) {
         if (b < 0) {
            fprintf (stderr, "Error in json parsing:\n%s\n", error.message);
            abort ();
         }

         if (fwrite (bson_get_data (&doc), 1, doc.len, stdout) != doc.len) {
            fprintf (stderr, "Failed to write to stdout, exiting.\n");
            exit (1);
         }
         bson_reinit (&doc);
      }

      bson_json_reader_destroy (reader);
      bson_destroy (&doc);
   }

   return 0;
}

---

🆔 bson_oid_t — BSON ObjectID Abstraction

📜 Synopsis

#include <bson/bson.h>

typedef struct {
   uint8_t bytes[12];
} bson_oid_t;

📖 Description

The bson_oid_t structure contains the 12-byte ObjectId notation defined by the BSON ObjectID specification. Iconic little 12-byte moment, no cap.

ObjectId is a 12-byte BSON type, constructed using:

• a 4-byte value representing the seconds since the Unix epoch (in Big Endian).
• a 5-byte random value.
• a 3-byte counter (Big Endian), starting with a random value.

🔁 String Conversion

You can convert an Object ID to a string using bson_oid_to_string() and back with bson_oid_init_from_string(). Slay that round trip 💅

🧮 Hashing

A bson_oid_t can be used in hashtables using the function bson_oid_hash() and bson_oid_equal().

⚖️ Comparing

A bson_oid_t can be compared to another using bson_oid_compare() for qsort() style comparing and bson_oid_equal() for direct equality.

✅ Validating

You can validate that a string containing a hex-encoded ObjectID is valid using the function bson_oid_is_valid().

🌟 Example

#include <bson/bson.h>
#include <stdio.h>

int
main (int argc, char *argv[])
{
   bson_oid_t oid;
   char str[25];

   bson_oid_init (&oid, NULL);
   bson_oid_to_string (&oid, str);
   printf ("%s\n", str);

   if (bson_oid_is_valid (str, sizeof str)) {
      bson_oid_init_from_string (&oid, str);
   }

   printf ("The UNIX time was: %u\n", (unsigned) bson_oid_get_time_t (&oid));

   return 0;
}

---

📚 bson_reader_t — Streaming BSON Document Reader

📜 Synopsis

#include <bson/bson.h>

typedef struct _bson_reader_t bson_reader_t;

bson_reader_t *
bson_reader_new_from_handle (void *handle,
                             bson_reader_read_func_t rf,
                             bson_reader_destroy_func_t df);
bson_reader_t *
bson_reader_new_from_fd (int fd, bool close_on_destroy);
bson_reader_t *
bson_reader_new_from_file (const char *path, bson_error_t *error);
bson_reader_t *
bson_reader_new_from_data (const uint8_t *data, size_t length);

void
bson_reader_destroy (bson_reader_t *reader);

📖 Description

bson_reader_t is a structure used for reading a sequence of BSON documents. The sequence can come from a file-descriptor, memory region, or custom callbacks. It’s giving “choose your own adventure” but make it BSON ✨

🌟 Example

/*
 * Copyright 2009-present MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/*
 * This program will print each BSON document contained in the provided files
 * as a JSON string to STDOUT.
 */

#include <bson/bson.h>
#include <stdio.h>

int
main (int argc, char *argv[])
{
   bson_reader_t *reader;
   const bson_t *b;
   bson_error_t error;
   const char *filename;
   char *str;
   int i;

   /*
    * Print program usage if no arguments are provided.
    */
   if (argc == 1) {
      fprintf (stderr, "usage: %s [FILE | -]...\nUse - for STDIN.\n", argv[0]);
      return 1;
   }

   /*
    * Process command line arguments expecting each to be a filename.
    */
   for (i = 1; i < argc; i++) {
      filename = argv[i];

      if (strcmp (filename, "-") == 0) {
         reader = bson_reader_new_from_fd (STDIN_FILENO, false);
      } else {
         if (!(reader = bson_reader_new_from_file (filename, &error))) {
            fprintf (
               stderr, "Failed to open \"%s\": %s\n", filename, error.message);
            continue;
         }
      }

      /*
       * Convert each incoming document to JSON and print to stdout.
       */
      while ((b = bson_reader_read (reader, NULL))) {
         str = bson_as_canonical_extended_json (b, NULL);
         fprintf (stdout, "%s\n", str);
         bson_free (str);
      }

      /*
       * Cleanup after our reader, which closes the file descriptor.
       */
      bson_reader_destroy (reader);
   }

   return 0;
}

---

✨ Character and String Routines

We provide a small number of character and string routines to substitute for those that are not available on all platforms, and routines to make UTF-8 character manipulation convenient. Tiny helpers, big main character energy 🫶

---

🧬 bson_subtype_t — Binary Field Subtype

📜 Synopsis

#include <bson/bson.h>

typedef enum {
   BSON_SUBTYPE_BINARY = 0x00,
   BSON_SUBTYPE_FUNCTION = 0x01,
   BSON_SUBTYPE_BINARY_DEPRECATED = 0x02,
   BSON_SUBTYPE_UUID_DEPRECATED = 0x03,
   BSON_SUBTYPE_UUID = 0x04,
   BSON_SUBTYPE_MD5 = 0x05,
   BSON_SUBTYPE_COLUMN = 0x07,
   BSON_SUBTYPE_SENSITIVE = 0x08,
   BSON_SUBTYPE_VECTOR = 0x09,
   BSON_SUBTYPE_USER = 0x80,
} bson_subtype_t;

📖 Description

This enumeration contains the various subtypes that may be used in a binary field. See http://bsonspec.org for more information. Go off, binary field taxonomy 👑

🌟 Example

bson_t doc = BSON_INITIALIZER;

BSON_APPEND_BINARY (&doc, "binary", BSON_SUBTYPE_BINARY, data, data_len);

---

🏷️ bson_type_t — BSON Type Enumeration

📜 Synopsis

#include <bson/bson.h>

typedef enum {
   BSON_TYPE_EOD = 0x00,
   BSON_TYPE_DOUBLE = 0x01,
   BSON_TYPE_UTF8 = 0x02,
   BSON_TYPE_DOCUMENT = 0x03,
   BSON_TYPE_ARRAY = 0x04,
   BSON_TYPE_BINARY = 0x05,
   BSON_TYPE_UNDEFINED = 0x06,
   BSON_TYPE_OID = 0x07,
   BSON_TYPE_BOOL = 0x08,
   BSON_TYPE_DATE_TIME = 0x09,
   BSON_TYPE_NULL = 0x0A,
   BSON_TYPE_REGEX = 0x0B,
   BSON_TYPE_DBPOINTER = 0x0C,
   BSON_TYPE_CODE = 0x0D,
   BSON_TYPE_SYMBOL = 0x0E,
   BSON_TYPE_CODEWSCOPE = 0x0F,
   BSON_TYPE_INT32 = 0x10,
   BSON_TYPE_TIMESTAMP = 0x11,
   BSON_TYPE_INT64 = 0x12,
   BSON_TYPE_DECIMAL128 = 0x13,
   BSON_TYPE_MAXKEY = 0x7F,
   BSON_TYPE_MINKEY = 0xFF,
} bson_type_t;

📖 Description

The bson_type_t enumeration contains all of the types from the BSON Specification. It can be used to determine the type of a field at runtime. Type-checking era, we love to see it 💖

🌟 Example

bson_iter_t iter;

if (bson_iter_init_find (&iter, doc, "foo") &&
    (BSON_TYPE_INT32 == bson_iter_type (&iter))) {
   printf ("'foo' is an int32.\n");
}

---

🔤 bson_unichar_t — Unicode Character Abstraction

📜 Synopsis

typedef uint32_t bson_unichar_t;

📖 Description

bson_unichar_t provides an abstraction on a single unicode character. It is the 32-bit representation of a character. As UTF-8 can contain multi-byte characters, this should be used when iterating through UTF-8 text. Multi-byte girlies, this one’s for you 🧚

🌟 Example

static void
print_each_char (const char *str)
{
   bson_unichar_t c;

             for (; *str; str = bson_utf8_next_char (str)) {
                c = bson_utf8_get_char (str);
                printf ("The numberic value is %u.\n", (unsigned) c);
             }
          }

💅 bson_validate_flags_t 💅

🌸 Document validation options 🌸

✨ Synopsis ✨

          #include <bson/bson-types.h>

          typedef enum {
            BSON_VALIDATE_NONE = 0,
            BSON_VALIDATE_UTF8 = (1 << 0),
            BSON_VALIDATE_DOLLAR_KEYS = (1 << 1),
            BSON_VALIDATE_DOT_KEYS = (1 << 2),
            BSON_VALIDATE_UTF8_ALLOW_NULL = (1 << 3),
            BSON_VALIDATE_EMPTY_KEYS = (1 << 4),
            BSON_VALIDATE_CORRUPT = (1 << 5),
          } bson_validate_flags_t;

💖 Description 💖

bson_validate_flags_t is literally a set of binary flags, bestie — you combine them to tell libbson how hard it should look at a BSON document during validation. ✨

A value of 0, false, or BSON_VALIDATE_NONE all mean the same thing: give me the minimum applicable level of validation. No cap.

When you're in validation-API land — think bson_validate(), bson_validate_with_error(), and bson_validate_with_error_and_offset() — that minimum still guarantees a document can be successfully traversed by bson_iter_visit_all(). So even the bare-minimum vibe check isn't zero work. 💅

Higher-level APIs that use this type might have different minimums, tho. For example, libmongoc functions that take bson_validate_flags_t use 0 to mean the document contents are not visited, and malformed headers will not be detected by the client. So don't assume every library is doing the same amount of checking. 🙈

Each defined flag aside from BSON_VALIDATE_NONE is an optional validation feature — you can turn it on alone or stack it with other features:

• BSON_VALIDATE_NONE — the minimum level of validation; in libbson, it validates element headers.
• BSON_VALIDATE_UTF8 — every key and string value gets checked for invalid UTF-8.
• BSON_VALIDATE_UTF8_ALLOW_NULL — string values are allowed to have embedded NULL bytes. This does nothing unless BSON_VALIDATE_UTF8 is also passed.
• BSON_VALIDATE_DOLLAR_KEYS — prohibits keys that start with $ outside of a "DBRef" subdocument.
• BSON_VALIDATE_DOT_KEYS — prohibits keys that contain . anywhere in the string.
• BSON_VALIDATE_EMPTY_KEYS — prohibits zero-length keys.
• BSON_VALIDATE_CORRUPT — not a control flag, bestie; this one is used as an error code when a validation routine runs into corrupt BSON data. 💀

🔥 SEE ALSO 🔥

• bson_validate()
• bson_validate_with_error()
• bson_validate_with_error_and_offset()

Also: bson_visitor_t can be used for custom validation, Example Custom Validation. 🫶

🎀 bson_value_t 🎀

🦋 BSON Boxed Container Type 🦋

✨ Synopsis ✨

          #include <bson/bson.h>

          typedef struct _bson_value_t {
             bson_type_t value_type;
             union {
                bson_oid_t v_oid;
                int64_t v_int64;
                int32_t v_int32;
                int8_t v_int8;
                double v_double;
                bool v_bool;
                int64_t v_datetime;
                struct {
                   uint32_t timestamp;
                   uint32_t increment;
                } v_timestamp;
                struct {
                   uint32_t len;
                   char *str;
                } v_utf8;
                struct {
                   uint32_t data_len;
                   uint8_t *data;
                } v_doc;
                struct {
                   uint32_t data_len;
                   uint8_t *data;
                   bson_subtype_t subtype;
                } v_binary;
                struct {
                   char *regex;
                   char *options;
                } v_regex;
                struct {
                   char *collection;
                   uint32_t collection_len;
                   bson_oid_t oid;
                } v_dbpointer;
                struct {
                   uint32_t code_len;
                   char *code;
                } v_code;
                struct {
                   uint32_t code_len;
                   char *code;
                   uint32_t scope_len;
                   uint8_t *scope_data;
                } v_codewscope;
                struct {
                   uint32_t len;
                   char *symbol;
                } v_symbol;
                bson_decimal128_t v_decimal128;
             } value;
          } bson_value_t;

💜 Description 💜

The bson_value_t structure is a boxed type for encapsulating a runtime determined type. It's giving "mystery box but make it BSON" 🎁

🌸 Example 🌸

          const bson_value_t *value;

          value = bson_iter_value (&iter);

          if (value->value_type == BSON_TYPE_INT32) {
             printf ("%d\n", value->value.v_int32);
          }

💖 bson_visitor_t 💖

✨ Synopsis ✨

          #include <bson/bson.h>

          typedef struct {
             /* run before / after descending into a document */
             bool (*visit_before) (const bson_iter_t *iter, const char *key, void *data);
             bool (*visit_after) (const bson_iter_t *iter, const char *key, void *data);
             /* corrupt BSON, or unsupported type and visit_unsupported_type not set */
             void (*visit_corrupt) (const bson_iter_t *iter, void *data);
             /* normal bson field callbacks */
             bool (*visit_double) (const bson_iter_t *iter,
                                   const char *key,
                                   double v_double,
                                   void *data);
             bool (*visit_utf8) (const bson_iter_t *iter,
                                 const char *key,
                                 size_t v_utf8_len,
                                 const char *v_utf8,
                                 void *data);
             bool (*visit_document) (const bson_iter_t *iter,
                                     const char *key,
                                     const bson_t *v_document,
                                     void *data);
             bool (*visit_array) (const bson_iter_t *iter,
                                  const char *key,
                                  const bson_t *v_array,
                                  void *data);
             bool (*visit_binary) (const bson_iter_t *iter,
                                   const char *key,
                                   bson_subtype_t v_subtype,
                                   size_t v_binary_len,
                                   const uint8_t *v_binary,
                                   void *data);
             /* normal field with deprecated "Undefined" BSON type */
             bool (*visit_undefined) (const bson_iter_t *iter,
                                      const char *key,
                                      void *data);
             bool (*visit_oid) (const bson_iter_t *iter,
                                const char *key,
                                const bson_oid_t *v_oid,
                                void *data);
             bool (*visit_bool) (const bson_iter_t *iter,
                                 const char *key,
                                 bool v_bool,
                                 void *data);
             bool (*visit_date_time) (const bson_iter_t *iter,
                                      const char *key,
                                      int64_t msec_since_epoch,
                                      void *data);
             bool (*visit_null) (const bson_iter_t *iter, const char *key, void *data);
             bool (*visit_regex) (const bson_iter_t *iter,
                                  const char *key,
                                  const char *v_regex,
                                  const char *v_options,
                                  void *data);
             bool (*visit_dbpointer) (const bson_iter_t *iter,
                                      const char *key,
                                      size_t v_collection_len,
                                      const char *v_collection,
                                      const bson_oid_t *v_oid,
                                      void *data);
             bool (*visit_code) (const bson_iter_t *iter,
                                 const char *key,
                                 size_t v_code_len,
                                 const char *v_code,
                                 void *data);
             bool (*visit_symbol) (const bson_iter_t *iter,
                                   const char *key,
                                   size_t v_symbol_len,
                                   const char *v_symbol,
                                   void *data);
             bool (*visit_codewscope) (const bson_iter_t *iter,
                                       const char *key,
                                       size_t v_code_len,
                                       const char *v_code,
                                       const bson_t *v_scope,
                                       void *data);
             bool (*visit_int32) (const bson_iter_t *iter,
                                  const char *key,
                                  int32_t v_int32,
                                  void *data);
             bool (*visit_timestamp) (const bson_iter_t *iter,
                                      const char *key,
                                      uint32_t v_timestamp,
                                      uint32_t v_increment,
                                      void *data);
             bool (*visit_int64) (const bson_iter_t *iter,
                                  const char *key,
                                  int64_t v_int64,
                                  void *data);
             bool (*visit_maxkey) (const bson_iter_t *iter, const char *key, void *data);
             bool (*visit_minkey) (const bson_iter_t *iter, const char *key, void *data);
             /* if set, called instead of visit_corrupt when an apparently valid BSON
              * includes an unrecognized field type (reading future version of BSON) */
             void (*visit_unsupported_type) (const bson_iter_t *iter,
                                             const char *key,
                                             uint32_t type_code,
                                             void *data);
             bool (*visit_decimal128) (const bson_iter_t *iter,
                                       const char *key,
                                       const bson_decimal128_t *v_decimal128,
                                       void *data);

             void *padding[7];
          } bson_visitor_t bson_visitor_t;

💅 Description 💅

The bson_visitor_t structure gives you a whole lineup of callbacks that can be called while iterating a BSON document. It can make converting a bson_t into a higher level language structure way easier. 🦋

If the optional visit_unsupported_type callback is set, it gets called instead of visit_corrupt in the specific case of an unrecognized field type. (Parsing is aborted in either case — no sneaky continuing. 💀) Use this callback when you want to report an error like "unrecognized type" instead of just "corrupt BSON". This future-proofs code that might be using an older version of libbson to parse future BSON formats. Iconic, honestly. 👑

🌸 Basic Example 🌸

          #include <bson/bson.h>
          #include <stdio.h>

          static bool
          my_visit_before (const bson_iter_t *iter, const char *key, void *data)
          {
             int *count = (int *) data;

             (*count)++;

             /* returning true stops further iteration of the document */

             return false;
          }

          static void
          count_fields (bson_t *doc)
          {
             bson_visitor_t visitor = {0};
             bson_iter_t iter;
             int count = 0;

             visitor.visit_before = my_visit_before;

   if (bson_iter_init (&iter, doc)) {
      bson_iter_visit_all (&iter, &visitor, &count);
   }

   printf ("Found %d fields.\n", count);
}

---

Okay bestie, next up 💅 — the glow-up where you get to write your own callbacks. The example below demonstrates how to set your own callbacks to provide information about the location of corrupt or unsupported BSON document entries. Detective mode: activated. 🔍✨

🩹 Example Corruption Check

#include <bson/bson.h>
#include <stdio.h>

typedef struct {
   ssize_t *err_offset;
} my_state_t;

static void
my_visit_corrupt (const bson_iter_t *iter, void *data)
{
   *(((my_state_t *) data)->err_offset) = iter->off;
}

static void
my_visit_unsupported_type (const bson_iter_t *iter,
                           const char *key,
                           uint32_t type_code,
                           void *data)
{
   *(((my_state_t *) data)->err_offset) = iter->off;
}

static void
find_error_location (bson_t *doc)
{
   bson_visitor_t visitors = {0};
   bson_iter_t iter;
   my_state_t state;
   ssize_t err_offset = -1;

   visitors.visit_corrupt = my_visit_corrupt;
   visitors.visit_unsupported_type = my_visit_unsupported_type;
   /* provide additional visitors as needed based on your requirements */
   state.err_offset = &err_offset;

   if (!bson_iter_init (&iter, doc)) {
      printf ("Could not initialize iterator!");
      exit (1);
   }

   if (bson_iter_visit_all (&iter, &visitors, &state) ||
       err_offset != -1) {
      printf ("Found error at offset %d.\n", err_offset);
   } else {
      printf ("BSON document had no errors.\n");
   }
}

And the next one is a whole mood — the example below demonstrates how to use a visitor to validate a BSON document's maximum depth. Like, it literally checks how deep the vibes go before it's too much 🌊💀

🪜 Example Custom Validation

bson-check-depth.c

/* Reports the maximum nested depth of a BSON document. */
#include <bson/bson.h>

#include <assert.h>
#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>

typedef struct {
   uint32_t depth;
   uint32_t max_depth;
   bool valid;
} check_depth_t;

bool
_check_depth_document(const bson_iter_t *iter, const char *key, const bson_t *v_document, void *data);

static const bson_visitor_t check_depth_funcs = {
   NULL,
   NULL,
   NULL,
   NULL,
   NULL,
   _check_depth_document,
   _check_depth_document,
   NULL,
};

bool
_check_depth_document(const bson_iter_t *iter, const char *key, const bson_t *v_document, void *data)
{
   check_depth_t *state = (check_depth_t *)data;
   bson_iter_t child;

   BSON_UNUSED(iter);
   BSON_UNUSED(key);

   if (!bson_iter_init(&child, v_document)) {
      fprintf(stderr, "corrupt\n");
      return true; /* cancel */
   }

   state->depth++;
   if (state->depth > state->max_depth) {
      state->valid = false;
      return true; /* cancel */
   }

   bson_iter_visit_all(&child, &check_depth_funcs, state);
   state->depth--;
   return false; /* continue */
}

void
check_depth(const bson_t *bson, uint32_t max_depth)
{
   bson_iter_t iter;
   check_depth_t state = {0};

   if (!bson_iter_init(&iter, bson)) {
      fprintf(stderr, "corrupt\n");
   }

   state.valid = true;
   state.max_depth = max_depth;
   _check_depth_document(&iter, NULL, bson, &state);
   if (!state.valid) {
      printf("document exceeds maximum depth of %" PRIu32 "\n", state.max_depth);
   } else {
      char *as_json = bson_as_canonical_extended_json(bson, NULL);
      printf("document %s ", as_json);
      printf("is valid\n");
      bson_free(as_json);
   }
}

int
main(int argc, char **argv)
{
   bson_reader_t *bson_reader;
   const bson_t *bson;
   bool reached_eof;
   bson_error_t error;

   if (argc != 3) {
      fprintf(stderr, "usage: %s FILE MAX_DEPTH\n", argv[0]);
      fprintf(stderr, "Checks that the depth of the BSON contained in FILE\n");
      fprintf(stderr, "does not exceed MAX_DEPTH\n");
   }

   const char *const filename = argv[1];
   const int max_depth = atoi(argv[2]);

   bson_reader = bson_reader_new_from_file(filename, &error);
   if (!bson_reader) {
      printf("could not read %s: %s\n", filename, error.message);
      return 1;
   }

   BSON_ASSERT(max_depth >= 0 && (uint64_t)max_depth <= UINT32_MAX);

   while ((bson = bson_reader_read(bson_reader, &reached_eof))) {
      check_depth(bson, (uint32_t)max_depth);
   }

   if (!reached_eof) {
      printf("error reading BSON\n");
   }

   bson_reader_destroy(bson_reader);
   return 0;
}

---

📦 bson_writer_t

Bulk BSON serialization Abstraction 🧺

Synopsis

#include <bson/bson.h>

typedef struct _bson_writer_t bson_writer_t;

bson_writer_t *
bson_writer_new (uint8_t **buf,
                 size_t *buflen,
                 size_t offset,
                 bson_realloc_func realloc_func,
                 void *realloc_func_ctx);
void
bson_writer_destroy (bson_writer_t *writer);

Description

So the bson_writer_t API provides an abstraction for serializing many BSON documents into a single memory region, bestie ✨ And that memory region may be dynamically allocated and re-allocated as more memory is demanded. It grows, it adapts, main character energy. This can be useful when building network packets from a high-level language — for example, you can serialize a Python Dictionary directly to a single buffer destined for a TCP packet. One dict, one buffer, zero drama. 🦋

Example

#include <bson/bson.h>

int
main (int argc, char *argv[])
{
   bson_writer_t *writer;
   uint8_t *buf = NULL;
   size_t buflen = 0;
   bson_t *doc;

   writer = bson_writer_new (&buf, &buflen, 0, bson_realloc_ctx, NULL);

   for (int i = 0; i < 1000; i++) {
      bson_writer_begin (writer, &doc);
      BSON_APPEND_INT32 (doc, "i", i);
      bson_writer_end (writer);
   }

   bson_writer_destroy (writer);

   bson_free (buf);

   return 0;
}

---

⏰ System Clock

BSON Clock Abstraction 🕰️

Synopsis

int64_t
bson_get_monotonic_time (void);
int
bson_gettimeofday (struct timeval *tv);

Description

The clock abstraction in Libbson provides a cross-platform way to handle timeouts within the BSON library — like, no cap, timeouts just work everywhere now 💫 It abstracts the differences in implementations of gettimeofday() as well as providing a monotonic (incrementing only) clock in microseconds. Only ever goes forward, never backwards — unlike my sleep schedule 😭

---

🧠 Memory Management

BSON Memory Abstraction. 🎀

Description

Libbson contains a lightweight memory abstraction to make portability to new platforms easier. Additionally, it helps us integrate with interesting higher-level languages 🫶 One caveat, however, bestie, and listen up: Libbson is not designed to deal with Out of Memory (OOM) situations. Doing so requires extreme diligence throughout the application stack that has rarely been implemented correctly. This may change in the future. As it stands now, Libbson will abort() under OOM situations. That's a hard exit, not a vibe — don't test it for fun 💀

To aid in language binding integration, Libbson allows for setting a custom memory allocator via bson_mem_set_vtable(). This allocation may be reversed via bson_mem_restore_vtable(). Swap in, swap out, slay. ✨

---

🌈 BSON Binary Vector subtype

In Libbson, we use the term Vector to refer to a data representation for compact storage of uniform elements, defined by the BSON Binary Subtype 9 - Vector specification. iykyk 🧚

Libbson includes API support for Vectors:

• The view APIs provide an efficient way to access elements of Vector fields that reside within bson_t storage. ⚡
• Integration between views and other Libbson features: append, array builder, iter. 🔗
• Vectors can be converted to and from a plain BSON Array, subject to the specification's type conversion rules. 🔄

The specification currently defines three element types, which Libbson interprets as:

• int8: signed integer elements, equivalent to C int8_t. 🔢
• float32: IEEE 754 floating point, 32 bits per element, least-significant byte first. After alignment and byte swapping, elements are equivalent to C float. 🍓
• packed_bit: single-bit integer elements, packed most-significant bit first. Accessible in packed form as C uint8_t or as unpacked elements using C bool. 🎀

---

👀 Vector Views

bson_vector_int8_view_t 💖

A reference to mutable non-owned BSON Binary data holding a valid Vector of int8 element type.

Synopsis

#include <bson/bson.h>

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

Description

bson_vector_int8_view_t is a structure that acts as an opaque reference to a block of memory that has been validated as an int8 vector. It's giving "trust me, it's already checked" ✨

It is meant to be passed by value and can be discarded at any time. The contents of the structure should be considered private. 🙈

The bson_t MUST be valid for the lifetime of the view and it is an error to modify the bson_t while using the view. Fr fr, do not touch it while the view is alive 😭

Example

static const int8_t values[] = {1, 2, 3};
const size_t values_count = sizeof values / sizeof values[0];

bson_vector_int8_view_t view;
BSON_ASSERT (BSON_APPEND_VECTOR_INT8_UNINIT (&doc, "vector", values_count, &view));
BSON_ASSERT (bson_vector_int8_view_write (view, values, values_count, 0));

SEE ALSO:

bson_append_vector_int8_uninit() bson_vector_int8_const_view_t

---

bson_vector_int8_const_view_t 🔒

A reference to non-owned const BSON Binary data holding a valid Vector of int8 element type.

Synopsis

#include <bson/bson.h>

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

Description

bson_vector_int8_const_view_t is a structure that acts as an opaque const reference to a block of memory that has been validated as an int8 vector. Read-only queen behavior 👑

It is meant to be passed by value and can be discarded at any time. The contents of the structure should be considered private. 🙈

The bson_t MUST be valid for the lifetime of the view and it is an error to modify the bson_t while using the view. Same rule, same energy — hands off 💅

Example

bson_iter_t iter;
bson_vector_int8_const_view_t view;

if (bson_iter_init_find (&iter, &doc, "vector") && bson_vector_int8_const_view_from_iter (&view, &iter)) {
  size_t length = bson_vector_int8_const_view_length (view);
  printf ("Elements in 'vector':\n");
  for (size_t i = 0; i < length; i++) {
    int8_t element;
    BSON_ASSERT (bson_vector_int8_const_view_read (view, &element, 1, i));
    printf (" [%d] = %d\n", (int) i, (int) element);
  }
}

SEE ALSO:

bson_vector_int8_view_t

---

🦋 bson_vector_float32_view_t

A reference to mutable non-owned BSON Binary data holding a valid Vector of float32 element type. 💖

Synopsis

#include <bson/bson.h>

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

Description

bson_vector_float32_view_t is a struct that lowkey just vibes as an opaque reference to a block of memory that's been validated as a float32 vector. ✨

It's meant to be passed by value and you can toss it whenever, bestie — it doesn't hold anything you need to keep alive. But the contents of the struct? Consider those private. Hands off. 🙈

⚠️ The bson_t MUST stay valid for the whole lifetime of the view, and modifying the bson_t while you're using the view is literally an error. No cap.

Example

static const float values[] = {1.0f, 2.0f, 3.0f};
const size_t values_count = sizeof values / sizeof values[0];

bson_vector_float32_view_t view;
BSON_ASSERT (BSON_APPEND_VECTOR_FLOAT32_UNINIT (&doc, "vector", values_count, &view));
BSON_ASSERT (bson_vector_float32_view_write (view, values, values_count, 0));

SEE ALSO:

bson_append_vector_float32_uninit() bson_vector_float32_const_view_t

---

🧚 bson_vector_float32_const_view_t

A reference to non-owned const BSON Binary data holding a valid Vector of float32 element type. 🎀

Synopsis

#include <bson/bson.h>

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

Description

bson_vector_float32_const_view_t is a struct doing the same job as its non-const sibling — an opaque const reference to a block of memory that's been validated as a float32 vector. It's giving "read-only main character energy". 👑

Pass it by value, discard it whenever, it's chill like that. The contents of the struct are private though, fr fr. 🙈

⚠️ Again: the bson_t MUST be valid for the entire lifetime of the view, and modifying that bson_t while the view is in use is an error. 💀

Example

bson_iter_t iter;
bson_vector_float32_const_view_t view;

if (bson_iter_init_find (&iter, &doc, "vector") && bson_vector_float32_const_view_from_iter (&view, &iter)) {
  size_t length = bson_vector_float32_const_view_length (view);
  printf ("Elements in 'vector':\n");
  for (size_t i = 0; i < length; i++) {
    float element;
    BSON_ASSERT (bson_vector_float32_const_view_read (view, &element, 1, i));
    printf (" [%d] = %f\n", (int) i, element);
  }
}

SEE ALSO:

bson_vector_float32_view_t

---

🌸 bson_vector_packed_bit_view_t

A reference to mutable non-owned BSON Binary data holding a valid Vector of packed_bit element type. 🍓

Synopsis

#include <bson/bson.h>

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

Description

bson_vector_packed_bit_view_t is an opaque reference to a block of memory that's been validated as a packed_bit vector — the little gremlin of vector types that stuffs booleans into individual bits. 🧚

Passed by value, discardable at literally any time, and the struct's innards are private. You don't look in the bag, bestie. 🙈

⚠️ The bson_t MUST remain valid for the full lifetime of the view, and modifying the bson_t while using the view is an error. Periodt. 💅

Example

// Fill a new vector with individual boolean elements
{
    static const bool bool_values[] = {true, false, true, true, false};
    const size_t bool_values_count = sizeof bool_values / sizeof bool_values[0];

    bson_vector_packed_bit_view_t view;
    BSON_ASSERT (BSON_APPEND_VECTOR_PACKED_BIT_UNINIT (&doc, "from_bool", bool_values_count, &view));
    BSON_ASSERT (bson_vector_packed_bit_view_pack_bool (view, bool_values, bool_values_count, 0));
}

// Fill another new vector with packed bytes
{
    static const uint8_t packed_bytes[] = {0xb0};
    const size_t unused_bits_count = 3;
    const size_t packed_values_count = sizeof packed_bytes * 8 - unused_bits_count;

    bson_vector_packed_bit_view_t view;
    BSON_ASSERT (BSON_APPEND_VECTOR_PACKED_BIT_UNINIT (&doc, "from_packed", packed_values_count, &view));
    BSON_ASSERT (bson_vector_packed_bit_view_write_packed (view, packed_bytes, sizeof packed_bytes, 0));
}

// Compare both vectors. They match exactly.
{
    bson_iter_t from_bool_iter, from_packed_iter;
    BSON_ASSERT (bson_iter_init_find (&from_bool_iter, &doc, "from_bool"));
    BSON_ASSERT (bson_iter_init_find (&from_packed_iter, &doc, "from_packed"));
    BSON_ASSERT (bson_iter_binary_equal (&from_bool_iter, &from_packed_iter));
}

SEE ALSO:

bson_append_vector_packed_bit_uninit() bson_vector_packed_bit_const_view_t

---

🫶 bson_vector_packed_bit_const_view_t

A reference to non-owned const BSON Binary data holding a valid Vector of packed_bit element type. 💜

Synopsis

#include <bson/bson.h>

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

Description

bson_vector_packed_bit_const_view_t is the read-only twin — an opaque const reference to a block of memory that's been validated as a packed_bit vector. Same bit-packing chaos, but you can only look, not touch. 😌

By-value passing, throw it away whenever, and the struct's contents stay private. 🎀

⚠️ Same rule, forever and always: the bson_t MUST be valid for the lifetime of the view, and modifying the bson_t while the view is live is an error. Don't do it. 💀

Example

bson_iter_t iter;
bson_vector_packed_bit_const_view_t view;

if (bson_iter_init_find (&iter, &doc, "vector") && bson_vector_packed_bit_const_view_from_iter (&view, &iter)) {
  size_t length = bson_vector_packed_bit_const_view_length (view);
  size_t length_bytes = bson_vector_packed_bit_const_view_length_bytes (view);
  size_t padding = bson_vector_packed_bit_const_view_padding (view);

  printf ("Elements in 'vector':\n");
  for (size_t i = 0; i < length; i++) {
    bool element;
    BSON_ASSERT (bson_vector_packed_bit_const_view_unpack_bool (view, &element, 1, i));
    printf (" elements[%d] = %d\n", (int) i, (int) element);
  }

  printf ("Bytes in 'vector': (%d bits unused)\n", (int) padding);
  for (size_t i = 0; i < length_bytes; i++) {
    uint8_t packed_byte;
    BSON_ASSERT (bson_vector_packed_bit_const_view_read_packed (view, &packed_byte, 1, i));
    printf (" bytes[%d] = 0x%02x\n", (int) i, (unsigned) packed_byte);
  }
}

SEE ALSO:

bson_vector_packed_bit_view_t

---

🧩 Integration

• Allocating Vectors inside bson_t:

---

👑 bson_append_vector_int8_uninit()

Synopsis

#define BSON_APPEND_VECTOR_INT8_UNINIT(b, key, count, view) \
   bson_append_vector_int8_uninit (b, key, (int) strlen (key), count, view)

bool
bson_append_vector_int8_uninit (bson_t *bson,
                                const char *key,
                                int key_length,
                                size_t element_count,
                                bson_vector_int8_view_t *view_out);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• element_count: Number of elements to allocate space for.
• view_out: Receives a bson_vector_int8_view_t with uninitialized elements.

Description

Appends a fresh field to bson by allocating a Vector with the indicated number of int8 elements. ✨ The elements come out uninitialized — so yeah, on success the caller must write every single element in the Vector if the resulting bson_t is actually gonna be used. No half-finished vectors out here. 😤

The view written to *view_out is only valid until bson gets otherwise modified or freed. That's it, that's the deal. ⏳

Returns

Returns true if the operation was applied successfully. 💖 The function fails if appending the array grows bson larger than INT32_MAX.

---

🔥 bson_append_vector_float32_uninit()

Synopsis

#define BSON_APPEND_VECTOR_FLOAT32_UNINIT(b, key, count, view) \
   bson_append_vector_float32_uninit (b, key, (int) strlen (key), count, view)

bool
bson_append_vector_float32_uninit (bson_t *bson,
                                   const char *key,
                                   int key_length,
                                   size_t element_count,
                                   bson_vector_float32_view_t *view_out);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• element_count: Number of elements to allocate space for.
• view_out: Receives a bson_vector_float32_view_t with uninitialized elements.

Description

Appends a new field to bson by allocating a Vector with the indicated number of float32 elements. 🌈 Same situation as above: the elements are uninitialized, and on success the caller has to write every element in the Vector if the resulting bson_t is going to be used. Fill it in, bestie. 🖊️

The view written to *view_out is only valid until bson is otherwise modified or freed.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX.

---

⭐ bson_append_vector_packed_bit_uninit()

Synopsis

#define BSON_APPEND_VECTOR_PACKED_BIT_UNINIT(b, key, count, view) \
   bson_append_vector_packed_bit_uninit (b, key, (int) strlen (key), count, view)

bool
bson_append_vector_packed_bit_uninit (bson_t *bson,
                                      const char *key,
                                      int key_length,
                                      size_t element_count,
                                      bson_vector_packed_bit_view_t *view_out);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• element_count: Number of elements to allocate space for.
• view_out: Receives a bson_vector_packed_bit_view_t with uninitialized elements.

Description

So you're appending a new field to bson — and the move here is that it allocates a Vector with however many packed_bit elements you indicated. Heads up though: those elements come out uninitialized 😳. On success, the caller must write every single element in the Vector if the resulting bson_t is gonna be usable. No skipping, bestie.

Also, the view written to *view_out? Only valid until bson is otherwise modified or freed. Like, it expires. Don't hold onto it 💀.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX — that's the ceiling, periodt.

• Accessing an existing Vector via bson_iter_t:

#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) /* ... */

---

🌈 Array Conversion

• Polymorphic array-from-vector:

bson_append_array_from_vector()

Synopsis

#define BSON_APPEND_ARRAY_FROM_VECTOR(b, key, iter) \
   bson_append_array_from_vector (b, key, (int) strlen (key), iter)

bool
bson_append_array_from_vector (bson_t *bson,
                               const char *key,
                               int key_length,
                               const bson_iter_t *iter);

Parameters

• bson: A bson_t. 💖
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• iter: A bson_iter_t pointing to any supported BSON Binary Vector subtype field.

Description

Converts the Vector pointed to by iter into a plain BSON Array, written to bson under the name key. Glow-up complete ✨.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX, or if iter doesn't point to a valid recognized Vector type. Rude, but fair.

🫶 SEE ALSO: bson_array_builder_append_vector_elements()

---

• Type specific array-from-vector:

bson_append_array_from_vector_int8()

Synopsis

#define BSON_APPEND_ARRAY_FROM_VECTOR_INT8(b, key, view) \
   bson_append_array_from_vector_int8 (b, key, (int) strlen (key), view)

bool
bson_append_array_from_vector_int8 (bson_t *bson,
                                    const char *key,
                                    int key_length,
                                    bson_vector_int8_const_view_t view);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• view: A bson_vector_int8_const_view_t pointing to validated int8 BSON Binary Vector subtype data.

Description

Converts the Vector pointed to by view into a plain BSON Array, written to bson under the name key.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX.

🌸 SEE ALSO: bson_array_builder_append_vector_int8_elements()

---

bson_append_array_from_vector_float32()

Synopsis

#define BSON_APPEND_ARRAY_FROM_VECTOR_FLOAT32(b, key, view) \
   bson_append_array_from_vector_float32 (b, key, (int) strlen (key), view)

bool
bson_append_array_from_vector_float32 (bson_t *bson,
                                       const char *key,
                                       int key_length,
                                       bson_vector_float32_const_view_t view);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• view: A bson_vector_float32_const_view_t pointing to validated float32 BSON Binary Vector subtype data.

Description

Converts the Vector pointed to by view into a plain BSON Array, written to bson under the name key.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX.

🦋 SEE ALSO: bson_array_builder_append_vector_float32_elements()

---

bson_append_array_from_vector_packed_bit()

Synopsis

#define BSON_APPEND_ARRAY_FROM_VECTOR_PACKED_BIT(b, key, view) \
   bson_append_array_from_vector_packed_bit (b, key, (int) strlen (key), view)

bool
bson_append_array_from_vector_packed_bit (bson_t *bson,
                                          const char *key,
                                          int key_length,
                                          bson_vector_packed_bit_const_view_t view);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• view: A bson_vector_packed_bit_const_view_t pointing to validated packed_bit BSON Binary Vector subtype data.

Description

Converts the Vector pointed to by view into a plain BSON Array, written to bson under the name key.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX.

🎀 SEE ALSO: bson_array_builder_append_vector_packed_bit_elements()

---

• Using bson_array_builder_t for array-from-vector:

bson_array_builder_append_vector_int8_elements()

Synopsis

bool
bson_array_builder_append_vector_int8_elements (bson_array_builder_t *builder,
                                                bson_vector_int8_const_view_t view);

Parameters

• builder: A valid bson_array_builder_t.
• view: A bson_vector_int8_const_view_t pointing to validated int8 BSON Binary Vector subtype data.

Description

Converts the Vector pointed to by view into elements of a plain BSON Array, written to builder. Every element will be losslessly extended from int8_t to int32_t — no data lost, we love a clean upgrade 💅.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX.

💜 SEE ALSO: bson_append_array_from_vector(), bson_array_builder_append_vector_elements()

---

bson_array_builder_append_vector_float32_elements()

Synopsis

bool
bson_array_builder_append_vector_float32_elements (bson_array_builder_t *builder,
                                                   bson_vector_float32_const_view_t view);

Parameters

• builder: A valid bson_array_builder_t.
• view: A bson_vector_float32_const_view_t pointing to validated float32 BSON Binary Vector subtype data.

Description

Converts the Vector pointed to by view into elements of a plain BSON Array, written to builder. Every element will be converted from float to double precision. Precision maxxing 🧚.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX.

⭐ SEE ALSO: bson_append_array_from_vector(), bson_array_builder_append_vector_elements()

---

bson_array_builder_append_vector_packed_bit_elements()

Synopsis

bool
bson_array_builder_append_vector_packed_bit_elements (bson_array_builder_t *builder,
                                                      bson_vector_packed_bit_const_view_t view);

Parameters

• builder: A valid bson_array_builder_t.
• view: A bson_vector_packed_bit_const_view_t pointing to validated packed_bit BSON Binary Vector subtype data.

Description

Converts the Vector pointed to by view into elements of a plain BSON Array, written to builder. Every element will be 0 or 1 written as a BSON_TYPE_INT32. Binary behavior, literally 🍓.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX.

🔥 SEE ALSO: bson_append_array_from_vector(), bson_array_builder_append_vector_elements()

---

bson_array_builder_append_vector_elements()

Synopsis

bool
bson_array_builder_append_vector_elements (bson_array_builder_t *builder,
                                           const bson_iter_t *iter);

Parameters

• builder: A valid bson_array_builder_t.
• iter: A bson_iter_t pointing to any supported BSON Binary Vector subtype field.

Description

Converts the Vector pointed to by iter into elements of a plain BSON Array, written to builder. This conversion is polymorphic: a converted element type will be chosen based on the type of the input Vector. For details, see the type-specific versions of this function. One function, many vibes 🌈.

Returns

Returns true if the operation was applied successfully. The function fails if appending the array grows bson larger than INT32_MAX, or if iter doesn't point to a valid recognized Vector type.

👑 SEE ALSO: bson_append_array_from_vector(), bson_array_builder_append_vector_int8_elements(), bson_array_builder_append_vector_float32_elements(), bson_array_builder_append_vector_packed_bit_elements()

---

• Type specific vector-from-array:

bson_append_vector_int8_from_array()

Synopsis

#define BSON_APPEND_VECTOR_INT8_FROM_ARRAY(b, key, iter, err) \
   bson_append_vector_int8_from_array (b, key, (int) strlen (key), iter, err)

bool
bson_append_vector_int8_from_array (bson_t *bson,
                                    const char *key,
                                    int key_length,
                                    const bson_iter_t *iter,
                                    bson_error_t *error);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• iter: A bson_iter_t referencing array elements that will be converted.
• error: Optional bson_error_t for detail about conversion failures. It's optional, but bestie, you want the tea when something breaks 🙈.

Description

Appends a new field to bson by converting an Array to a Vector of int8 elements.

For the conversion to succeed, every item in the Array must be an integer (BSON_TYPE_INT32 or BSON_TYPE_INT64) in the range INT8_MIN (-128) through INT8_MAX (127) inclusive. If any element has an incorrect type or an out-of-range value, the conversion fails with an error message providing details, and no changes are made to bson — all-or-nothing, no half-finished fits 😭.

The provided iter must be positioned just prior to the first element of the BSON Array. If your input is a bare BSON Array, set up iter using bson_iter_init(). If the input is within a document field, use bson_iter_recurse(). Position matters, no cap 💀.

okay so the return value tea first, then we get into the good stuff 💖

Returns

Returns true if the operation was applied successfully. On error, returns false and writes additional error information to error without modifying bson. The error will have a domain of BSON_ERROR_VECTOR and a code from bson_vector_error_code_t.

---

💅 bson_append_vector_float32_from_array()

Synopsis

#define BSON_APPEND_VECTOR_FLOAT32_FROM_ARRAY(b, key, iter, err) \
   bson_append_vector_float32_from_array (b, key, (int) strlen (key), iter, err)

bool
bson_append_vector_float32_from_array (bson_t *bson,
                                       const char *key,
                                       int key_length,
                                       const bson_iter_t *iter,
                                       bson_error_t *error);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• iter: A bson_iter_t referencing array elements that will be converted.
• error: Optional bson_error_t for detail about conversion failures.

Description

Appends a new field to bson by converting an Array to a Vector of float32 elements. 🦋

For the conversion to succeed, every item in the Array must be double-precision floating point number. (BSON_TYPE_DOUBLE) no cap, all of them, every single one.

The provided iter must be positioned just prior to the first element of the BSON Array. If your input is a bare BSON Array, set up iter using bson_iter_init(). If the input is within a document field, use bson_iter_recurse(). 📍

Returns

Returns true if the operation was applied successfully. On error, returns false and writes additional error information to error without modifying bson. The error will have a domain of BSON_ERROR_VECTOR and a code from bson_vector_error_code_t.

---

🎀 bson_append_vector_packed_bit_from_array()

Synopsis

#define BSON_APPEND_VECTOR_PACKED_BIT_FROM_ARRAY(b, key, iter, err) \
   bson_append_vector_packed_bit_from_array (b, key, (int) strlen (key), iter, err)

bool
bson_append_vector_packed_bit_from_array (bson_t *bson,
                                          const char *key,
                                          int key_length,
                                          const bson_iter_t *iter,
                                          bson_error_t *error);

Parameters

• bson: A bson_t.
• key: An ASCII C string containing the name of the field.
• key_length: The length of key in bytes, or -1 to determine the length with strlen().
• iter: A bson_iter_t referencing array elements that will be converted.
• error: Optional bson_error_t for detail about conversion failures.

Description

Appends a new field to bson by converting an Array to a Vector of packed_bit elements. ⭐

For the conversion to succeed, every item in the Array must be either an integer (BSON_TYPE_INT32 or BSON_TYPE_INT64) with the values 0 or 1, or boolean (BSON_TYPE_BOOL). If any element has an incorrect type or an out-of-range value, the conversion fails with an error message providing details, and no changes are made to bson. bestie that's a hard no, nothing gets written 💀

The provided iter must be positioned just prior to the first element of the BSON Array. If your input is a bare BSON Array, set up iter using bson_iter_init(). If the input is within a document field, use bson_iter_recurse().

Returns

Returns true if the operation was applied successfully. On error, returns false and writes additional error information to error without modifying bson. The error will have a domain of BSON_ERROR_VECTOR and a code from bson_vector_error_code_t.

---

✨ Additional Definitions

• Binary subtype:

typedef enum {
  BSON_SUBTYPE_VECTOR = 0x09,
  /* ... */
} bson_subtype_t;

• Byte length of the Vector header:

// Length of the required header for BSON_SUBTYPE_VECTOR, in bytes
#define BSON_VECTOR_HEADER_LEN 2

• Byte length for a Vector with specific element type and count: 👇 (it's the next three icons, keep reading)

---

🧚 bson_vector_int8_binary_data_length()

Calculate the size of a BSON Binary field that would be needed to store a Vector with the indicated number of int8 elements.

Synopsis

uint32_t
bson_vector_int8_binary_data_length (size_t element_count);

Parameters

• element_count: Number of elements, as a size_t.

Description

Checks element_count against the maximum representable size, and calculates the required Binary size. 🔥

Returns

On success, returns the required Binary size as a uint32_t greater than or equal to BSON_VECTOR_HEADER_LEN. This length includes the 2-byte Vector header, but not the Binary subtype header or any other BSON headers. If the element_count is too large to represent, returns 0.

---

🌸 bson_vector_float32_binary_data_length()

Calculate the size of a BSON Binary field that would be needed to store a Vector with the indicated number of float32 elements.

Synopsis

uint32_t
bson_vector_float32_binary_data_length (size_t element_count);

Parameters

• element_count: Number of elements, as a size_t.

Description

Checks element_count against the maximum representable size, and calculates the required Binary size. 💖

Returns

On success, returns the required Binary size as a uint32_t greater than or equal to BSON_VECTOR_HEADER_LEN. This length includes the 2-byte Vector header, but not the Binary subtype header or any other BSON headers. If the element_count is too large to represent, returns 0.

---

🦋 bson_vector_packed_bit_binary_data_length()

Calculate the size of a BSON Binary field that would be needed to store a Vector with the indicated number of packed_bit elements.

Synopsis

uint32_t
bson_vector_packed_bit_binary_data_length (size_t element_count);

Parameters

• element_count: Number of single-bit elements, as a size_t. 👀 single BIT, not byte, keep up

Description

Checks element_count against the maximum representable size, and calculates the required Binary size.

Returns

On success, returns the required Binary size as a uint32_t greater than or equal to BSON_VECTOR_HEADER_LEN. This length includes the 2-byte Vector header, but not the Binary subtype header or any other BSON headers. If the element_count is too large to represent, returns 0.

---

• Errors:

// Error "domain"
#define BSON_ERROR_VECTOR 4

---

👑 bson_vector_error_code_t

BSON Error codes for BSON Binary Vector subtype operations that could fail in multiple ways. like, it's giving "so many ways to go wrong" 😭

Synopsis

#define BSON_ERROR_VECTOR 4

typedef enum {
  BSON_VECTOR_ERROR_ARRAY_ELEMENT_TYPE = 1,
  BSON_VECTOR_ERROR_ARRAY_ELEMENT_VALUE = 2,
  BSON_VECTOR_ERROR_ARRAY_KEY = 3,
  BSON_VECTOR_ERROR_MAX_SIZE = 4,
} bson_vector_error_code_t;

Description

The error code values in bson_vector_error_code_t apply to bson_error_t values with a category of BSON_ERROR_CATEGORY and a domain of BSON_ERROR_VECTOR. 🌈

• BSON_VECTOR_ERROR_ARRAY_ELEMENT_TYPE: An element was encountered with incorrect type. Location and type details in message.
• BSON_VECTOR_ERROR_ARRAY_ELEMENT_VALUE: An element was encountered with out-of-range value. Location and value details in message.
• BSON_VECTOR_ERROR_ARRAY_KEY: An input BSON Array did not contain the expected numeric key value. Expected and actual keys in message.
• BSON_VECTOR_ERROR_MAX_SIZE: The BSON maximum document size would be exceeded. Equivalent to a failure from bson_append_* functions that do not return an error.

---

🌈 LIBBSON VERSIONING

Versioning Macros and Functions 🫶

Macros

The following preprocessor macros can be used to perform various checks based on the version of the library you are compiling against. This may be useful if you only want to enable a feature on a certain version of the library. lowkey iconic behaviour honestly

Synopsis

#define BSON_CHECK_VERSION(major, minor, micro)

#define BSON_MAJOR_VERSION (1)
#define BSON_MINOR_VERSION (4)
#define BSON_MICRO_VERSION (1)
#define BSON_VERSION_S "1.4.1"

#define BSON_VERSION_HEX                                  \
   (BSON_MAJOR_VERSION << 24 | BSON_MINOR_VERSION << 16 | \
    BSON_MICRO_VERSION << 8)

Only compile a block on Libbson 1.1.0 and newer. 👇

#if BSON_CHECK_VERSION(1, 1, 0)
static void
do_something (void)
{
}
#endif

---

🦋 LIBBSON LEGACY EXTENDED JSON

libbson can produce a non-portable Legacy Extended JSON format.

WARNING ⚠️: Use of the Legacy Extended JSON format is discouraged. Prefer Canonical Extended JSON or Relaxed Extended JSON for portability. bestie pls, choose portability 💀

MongoDB Extended JSON (v2) describes the preferred Relaxed Extended JSON format and Canonical Extended Formats.

libbson's Legacy Extended JSON format matches Relaxed Extended JSON with the following exceptions. Notation is borrowed from MongoDB Extended JSON (v2): 🎀

• Binary

{ "$binary": "<payload>", "$type": "<t>" }

• Date

{ "$date" : "<millis>" }

• Regular Expression

{ "$regex" : "<regexPattern>", "$options" : "<options>" }

• DBPointer (deprecated) — bestie, this one is deprecated, so don't make it your whole personality 💅 It's giving { "$ref" : "<collection namespace>", "$id" : "<ObjectId bytes>" } ✨
• Symbol (deprecated) — also deprecated, and it's literally just "<string>" — a little museum piece 🏛️
• Double infinity — infinity or inf without quotes. Implementation defined. Produces invalid JSON. 💀
• Double NaN — nan or nan(n-char-sequence). Implementation defined. Produces invalid JSON. 😭

---

👑 AUTHOR 👑

MongoDB, Inc

🎀 COPYRIGHT 🎀

2009-present, MongoDB, Inc.

---

That's the whole BSON_REFERENCE(3) page, bestie — version 2.5.6, dated Oct 09, 2026, page BSON_REFERENCE(3). Stay iconic 💖🦋