LIBBSON_BINARY_VECTOR(3)

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 <https://github.com/mongodb/specifications/blob/master/source/bson-binary-vector/bson-binary-vector.md> specification.

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