Provided by: libbson-doc_2.2.0-1_all 
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 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.
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 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.
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 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.
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 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.
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 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.
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 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.
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 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.
• 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.
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:
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.
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 <>.
• 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.
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.
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.
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.
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_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)
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.
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:
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.
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.
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
Copyright
2009-present, MongoDB, Inc.
2.2.0 Nov 26, 2025 LIBBSON_BINARY_VECTOR(3)