LIBBSON_BINARY_VECTOR(3)

📦
version 2.5.6 · 3 versions
, in epel 10

okay bestie, welcome to LIBBSON_BINARY_VECTOR(3) — the libbson manual page that’s basically the group chat for BSON vectors. 💅✨

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. no cap, that’s the whole vibe.

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. lowkey the best way to peek 👀
  • integration between views and other Libbson features: append, array builder, iter. the way that views just mesh with the rest of Libbson? iconic.
  • Vectors can be converted to and from a plain BSON Array, subject to the specification’s type conversion rules. fr fr, with rules.

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

  • int8: signed integer elements, equivalent to C int8_t. tiny signed gremlins 🧚
  • float32: IEEE 754 floating point, 32 bits per element, least-significant byte first. After alignment and byte swapping, elements are equivalent to C float. she’s floating, she’s 32 bits, she’s byte-ordered 🌊
  • 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. bits on bits on bits 🎀

💅 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 meant to be passed by value and can be discarded at any time, and 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. like, do not touch her while she’s working 💀

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.

it’s meant to be passed by value and can be discarded at any time, and 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. she’s read-only for a reason, bestie 💀

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 structure that acts as an opaque reference to a block of memory that has been validated as a float32 vector.

it’s meant to be passed by value and can be discarded at any time, and 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. no sneaky edits while the view is live 💀

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 structure that acts as an opaque const reference to a block of memory that has been validated as a float32 vector.

it’s meant to be passed by value and can be discarded at any time, and 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. const means const, periodt 💀

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 a structure that acts as an opaque reference to a block of memory that has been validated as a packed_bit vector.

it’s meant to be passed by value and can be discarded at any time, and 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. packed bits are still bits, and the rules still apply 💀

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 a structure that acts as an opaque const reference to a block of memory that has been validated as a packed_bit vector.

it’s meant to be passed by value and can be discarded at any time, and 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. read-only energy only, bestie 💀

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 ✨

Okay so this is the part where the Vectors actually get into your bson_t, and honestly? It's giving "glow up era" for your data. Let's go through all the ways 🫶

🎀 Allocating Vectors inside bson_t

These are the "I'll make space, you fill it in" girlies. Uninitialized on purpose — no cap, that's the whole point 💅

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 new field to bson by allocating a Vector with the indicated number of int8 elements. The elements will be uninitialized. On success, the caller must write every element in the Vector if the resulting bson_t is to be used.

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_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. The elements will be uninitialized. On success, the caller must write every element in the Vector if the resulting bson_t is to be used.

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

Appends a new field to bson by allocating a Vector with the indicated number of packed_bit elements. The elements will be uninitialized. On success, the caller must write every element in the Vector if the resulting bson_t is to be used.

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.

🫶 Bestie reminder on all three of these: "uninitialized" is not a vibe, it's a chore. If you leave those elements unwritten, the resulting bson_t is not usable. Main character energy means finishing what you started 💅

🦋 Accessing an existing Vector via bson_iter_t

Type-checking macros, so you can vibe check what you're looking at before you touch it:

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

So you've got a Vector but what you actually need is a plain BSON Array. Iconic. We got you, three different ways ✨

🧚 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.

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_array_builder_append_vector_elements()

🌸 Type specific array-from-vector

Same energy, but you already know exactly which subtype you're holding. iykyk 💖

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

Already building an array and just wanna drop the elements in? Obsessed. This is the way 🎀

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.

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.

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. This is where the output array gets built, bestie.
  • view — a bson_vector_packed_bit_const_view_t pointing to validated packed_bit BSON Binary Vector subtype data. Validated is the whole vibe here.

🦋 Description

Converts the Vector that view points to into elements of a plain BSON Array, written to builder. Every element will be 0 or 1 written as a BSON_TYPE_INT32. So packed bits go in, lil 0/1 int32s come out. Cute, honestly.

🌸 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, no cap.

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. Your output spot.
  • 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: the converted element type gets chosen based on the type of the input Vector. For the details, see the type-specific versions of this function. It's giving "one function, many looks."

🌸 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. Both of those are a no.

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.

🦋 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. No changes. Zero. Zilch. The function is not about to leave you half-converted.

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(). That positioning matters, okay?

🌸 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) That's the whole type check, bestie. Keep it double.

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(). Same positioning rules as always.

🌸 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. So: 0, 1, or a bool. Anything else and it's a wrap, but not the good kind.

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(). Yes, still the same ritual.

🌸 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 🧩

Okay bestie, here’s the extra definition-y stuff you need so nothing feels mysterious later. 💅

  • 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:

📏 Byte length for a Vector with specific element type and count

🧮 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. Literally doing the math so you don’t have to. ✨

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. Same energy, different element type. 🫶

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. Tiny bits, real calculations. 🎀

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.

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

  • 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. Not every mission is a slay, sometimes it’s an error code. 😭

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.

👑 AUTHOR 👑

MongoDB, Inc

2009-present, MongoDB, Inc.

Signing off with libbson 2.5.6, dated Oct 09, 2026 — bestie, you’re officially caught up on the vector lore. 💖✨🦋

📦 where this page comes from