Skip to content
Back to top

# BSON Binary Vector subtype

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

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
- bson_vector_int8_const_view_t
- bson_vector_float32_view_t
- bson_vector_float32_const_view_t
- bson_vector_packed_bit_view_t
- bson_vector_packed_bit_const_view_t

## Integration

- Allocating Vectors inside bson_t:

  - bson_append_vector_int8_uninit()
  - bson_append_vector_float32_uninit()
  - bson_append_vector_packed_bit_uninit()

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

  - bson_vector_int8_view_from_iter()
  - bson_vector_int8_const_view_from_iter()
  - bson_vector_float32_view_from_iter()
  - bson_vector_float32_const_view_from_iter()
  - bson_vector_packed_bit_view_from_iter()
  - bson_vector_packed_bit_const_view_from_iter()

## Array Conversion

- Polymorphic array-from-vector:

  - bson_append_array_from_vector()

- Type specific array-from-vector:

  - bson_append_array_from_vector_int8()
  - bson_append_array_from_vector_float32()
  - bson_append_array_from_vector_packed_bit()

- Using bson_array_builder_t for 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()
  - bson_array_builder_append_vector_elements()

- Type specific vector-from-array:

  - bson_append_vector_int8_from_array()
  - bson_append_vector_float32_from_array()
  - bson_append_vector_packed_bit_from_array()

## 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()
  - bson_vector_float32_binary_data_length()
  - bson_vector_packed_bit_binary_data_length()

- Errors:

      // Error "domain"
      #define BSON_ERROR_VECTOR 4

  - bson_vector_error_code_t