BSON Values

Introduction

BsonValue represents BSON values and reads or writes complete document frames. For usage, type mapping, and input limits, see Reading and Writing BSON.

Truncated input is rejected as ParseError by the throwing decoder, or as an empty optional by the tolerant decoder. Internal bounds errors and resource failures are not converted into malformed-input errors.

Text arguments accept String, StringEditor, and Core string literals directly, including when passed to set() or append(). Stored text retains its value if the original editor is changed later.

Interface

struct BsonBinary

BSON binary payload and its subtype.

Public Members

mem::ByteBlock bytes: Payload bytes.

uint8_t subtype = {}: BSON binary subtype.

typedef util::List<BsonValue> erbsland::data::bson::BsonArray: An ordered BSON array.

typedef text::StringMap<BsonValue> erbsland::data::bson::BsonDocument: A string-keyed BSON document.

class BsonFormatOptions

Extension point for BSON serialization settings.

class BsonOpaqueValue

Known BSON wire value preserved without executing or interpreting it.

Public Functions

inline uint8_t typeCode() const noexcept: Get the BSON type code.

inline mem::ByteBlock payload() const noexcept: Get the encoded value payload, excluding type and key.

class BsonParseOptions

Safety limits for parsing BSON.

Public Functions

inline constexpr unit::ByteCount maximumInputLength() const noexcept: Get the input byte limit.

inline constexpr BsonParseOptions &setMaximumInputLength(unit::ByteCount value) noexcept: Set the input byte limit.

inline constexpr unit::ItemCount maximumNesting() const noexcept: Get the nesting limit.

inline constexpr BsonParseOptions &setMaximumNesting(unit::ItemCount value) noexcept: Set the nesting limit.

inline constexpr unit::ItemCount maximumValueCount() const noexcept: Get the value count limit.

inline constexpr BsonParseOptions &setMaximumValueCount(unit::ItemCount value) noexcept: Set the value count limit.

inline constexpr unit::ByteCount maximumStringLength() const noexcept: Get the maximum byte length of one string or key.

inline constexpr BsonParseOptions &setMaximumStringLength(unit::ByteCount value) noexcept: Set the maximum byte length of one string or key.

Public Static Attributes

static constexpr auto cDefaultMaximumInputLength = unit::ByteCount{16U * 1024U * 1024U}: Document byte limit.

static constexpr auto cDefaultMaximumNesting = unit::ItemCount{64U}: Container depth limit.

static constexpr auto cDefaultMaximumValueCount = unit::ItemCount{1'000'000U}: Value count limit.

static constexpr auto cDefaultMaximumStringLength = unit::ByteCount{8U * 1024U * 1024U}: String byte limit.

enum class erbsland::data::bson::BsonType : uint8_t

Semantic types supported by a BSON value.

Values:

enumerator Null: Null.

enumerator Bool: Boolean.

enumerator Int32: Signed 32-bit integer.

enumerator Int64: Signed 64-bit integer.

enumerator Double: 64-bit floating point.

enumerator Text: UTF-8 string.

enumerator Binary: Binary payload and subtype.

enumerator DateTime: UTC millisecond date/time.

enumerator Array: Ordered array.

enumerator Document: Named document fields.

enumerator Opaque: Known BSON type retained without interpretation.

class BsonValue

A copy-on-write BSON value tree.

See: BSON Values

Public Functions

BsonValue(bool value)

Create a BSON Boolean value.

Parameters:: value – The Boolean to store.

BsonValue(int32_t value)

Create a BSON signed 32-bit integer value.

Parameters:: value – The signed 32-bit integer to store.

BsonValue(int64_t value)

Create a BSON signed 64-bit integer value.

Parameters:: value – The signed 64-bit integer to store.

BsonValue(int8_t value)

Create a BSON signed 8-bit integer value.

Parameters:: value – The signed 8-bit integer to store.

BsonValue(uint8_t value)

Create a BSON unsigned 8-bit integer value.

Parameters:: value – The unsigned 8-bit integer to store.

BsonValue(int16_t value)

Create a BSON signed 16-bit integer value.

Parameters:: value – The signed 16-bit integer to store.

BsonValue(uint16_t value)

Create a BSON unsigned 16-bit integer value.

Parameters:: value – The unsigned 16-bit integer to store.

BsonValue(uint32_t value)

Create a BSON unsigned 32-bit integer value.

Parameters:: value – The unsigned 32-bit integer to store.

BsonValue(uint64_t value)

Create a BSON unsigned 64-bit integer value.

Parameters:: value – The unsigned 64-bit integer to store. Must fit in the BSON signed 64-bit range.

BsonValue(double value)

Create a BSON double-precision number value.

Parameters:: value – The double-precision number to store.

BsonValue(text::String value)

Create a BSON text string value.

Parameters:: value – The text string to store.

template<typename tText> inline BsonValue(tText &&value)

Create a text value from an implicitly convertible string, editor, or literal.

Parameters:: value – The text to store.

BsonValue(BsonBinary value)

Create a BSON binary value with subtype value.

Parameters:: value – The binary value with subtype to store.

BsonValue(mem::ByteBlock value)

Create a BSON binary byte string value.

Parameters:: value – The binary byte string to store.

BsonValue(time::Timestamp value)

Create a BSON UTC date/time value.

Parameters:: value – The UTC date/time to store.

BsonValue(BsonArray value)

Create a BSON array value.

Parameters:: value – The array to store.

BsonValue(BsonDocument value)

Create a BSON document value.

Parameters:: value – The document to store.

BsonValue(BsonOpaqueValue value)

Create a BSON opaque wire value value.

Parameters:: value – The opaque wire value to store.

BsonType type() const noexcept: Get the semantic type.

inline bool is(BsonType expected) const noexcept: Test for a semantic type.

unit::ItemCount itemCount() const noexcept: Get the array or document size, or zero.

BsonValue get(unit::ItemIndex index) const: Get a child or null when absent.

BsonValue get(const text::String &key) const: Get a child or null when absent.

BsonValue getOrThrow(unit::ItemIndex index) const

Get a child or throw.

Throws:: err::OutOfRangeError – If the index does not identify an array element.

BsonValue getOrThrow(const text::String &key) const

Get a child or throw.

Throws:: err::NotFoundError – If the requested key is absent.

std::optional<bool> getBool() const noexcept: Get a Boolean value.

std::optional<int64_t> getInteger() const noexcept: Get an exact signed integer across both BSON integer widths.

std::optional<double> getDouble() const noexcept: Get a floating-point value.

std::optional<text::String> getText() const noexcept: Get a text value.

std::optional<BsonBinary> getBinary() const noexcept: Get a binary value and its subtype.

std::optional<time::Timestamp> getTimestamp() const noexcept: Get a UTC millisecond date/time.

std::optional<BsonArray> getArray() const noexcept: Get a copy of an array.

std::optional<BsonDocument> getDocument() const noexcept: Get a copy of a document.

std::optional<BsonOpaqueValue> getOpaque() const noexcept: Get an opaque value.

BsonValue &set(unit::ItemIndex index, BsonValue value): Replace or append an array child.

BsonValue &set(const text::String &key, BsonValue value): Replace or add a document field.

BsonValue &append(BsonValue value): Append an array child.

mem::ByteBlock toByteBlock(BsonFormatOptions options = {}) const

Serialize a document root to BSON.

This value must be a document root, and every contained value must be encodable as BSON.

Public Static Functions

static auto fromByteBlock(const mem::ByteBlock &bytes, BsonParseOptions options = {}) noexcept -> std::optional<BsonValue>: Parse one complete BSON document, returning no value on failure.

static auto fromByteBlockOrThrow(const mem::ByteBlock &bytes, BsonParseOptions options = {}) -> BsonValue 

Parse one complete BSON document.

Throws:: err::ParseError – For malformed or unsupported wire data.