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

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¶

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¶

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¶

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

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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.

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¶

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¶

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¶

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.