#include <userver/formats/bson/value.hpp>

Detailed Description

Non-mutable BSON value representation.

Class provides non mutable access BSON value. For modification and construction of new BSON values use formats::bson::ValueBuilder.

Example usage:

    // #include <userver/formats/bson.hpp>
 
    auto doc = formats::bson::MakeDoc("key1", 1, "key2", formats::bson::MakeDoc("key3", "val"));
    formats::bson::Value bson = formats::bson::FromBinaryString(ToBinaryString(doc).GetView());
 
    const auto key1 = bson["key1"].As<int>();
    ASSERT_EQ(key1, 1);
 
    const auto key3 = bson["key2"]["key3"].As<std::string>();
    ASSERT_EQ(key3, "val");

See also: Formats (JSON, YAML, BSON, ...)

To iterate over Value as object use formats::common::Items.

Definition at line 42 of file value.hpp.

Inheritance diagram for formats::bson::Value:

Classes
struct	DefaultConstructed

Public Types
enum class	DuplicateFieldsPolicy { kForbid , kUseFirst , kUseLast }
	Selectors for duplicate fields parsing behavior. More...

using	const_iterator = Iterator<const Value, common::IteratorDirection::kForward>

using	const_reverse_iterator = Iterator<const Value, common::IteratorDirection::kReverse>

using	Exception = formats::bson::BsonException

using	ParseException = formats::bson::ParseException

using	ExceptionWithPath = formats::bson::ExceptionWithPath

using	Builder = ValueBuilder

Public Member Functions
	Value ()
	Constructs a `null` value.

	Value (const Value &)=default

	Value (Value &&) noexcept=default

Value &	operator= (const Value &) &=default

Value &	operator= (Value &&) &noexcept=default

template<class T>
Value &	operator= (T &&) &&

Value	operator[] (const std::string &name) const
	Retrieves document field by name.

Value	operator[] (uint32_t index) const
	Retrieves array element by index.

bool	HasMember (const std::string &name) const
	Checks whether the document has a field.

const_iterator	begin () const
	Returns an iterator to the first array element/document field.

const_iterator	end () const
	Returns an iterator following the last array element/document field.

const_reverse_iterator	rbegin () const
	Returns a reversed iterator to the last array element.

const_reverse_iterator	rend () const
	Returns a reversed iterator following the first array element.

bool	IsEmpty () const
	Returns whether the document/array is empty.

uint32_t	GetSize () const
	Returns the number of elements in a document/array.

std::string	GetPath () const
	Returns value path in a document.

bool	operator== (const Value &) const

bool	operator!= (const Value &) const

bool	IsMissing () const
	Checks whether the selected element exists.

template<typename T>
auto	As () const

template<typename T, typename First, typename... Rest>
auto	As (First &&default_arg, Rest &&... more_default_args) const

template<typename T>
auto	As (DefaultConstructed) const
	Returns value of *this converted to T or T() if this->IsMissing().

template<typename T>
T	ConvertTo () const
	Extracts the specified type with relaxed type checks. For example, `true` may be converted to 1.0.

template<typename T, typename First, typename... Rest>
T	ConvertTo (First &&default_arg, Rest &&... more_default_args) const

void	SetDuplicateFieldsPolicy (DuplicateFieldsPolicy)
	Changes parsing behavior when duplicate fields are encountered. Should not be used normally.

void	CheckNotMissing () const
	Throws a MemberMissingException if the selected element does not exist.

void	CheckArrayOrNull () const
	Throws a TypeMismatchException if the selected element is not an array or null.

void	CheckDocumentOrNull () const
	Throws a TypeMismatchException if the selected element is not a document or null.

Type checking
bool	IsArray () const

bool	IsDocument () const

bool	IsNull () const

bool	IsBool () const

bool	IsInt32 () const

bool	IsInt64 () const

bool	IsDouble () const

bool	IsString () const

bool	IsDateTime () const

bool	IsOid () const

bool	IsBinary () const

bool	IsDecimal128 () const

bool	IsMinKey () const

bool	IsMaxKey () const

bool	IsTimestamp () const

bool	IsObject () const

Protected Member Functions
const impl::BsonHolder &	GetBson () const

Member Typedef Documentation

◆ Builder

using formats::bson::Value::Builder = ValueBuilder

Definition at line 51 of file value.hpp.

◆ const_iterator

using formats::bson::Value::const_iterator = Iterator<const Value, common::IteratorDirection::kForward>

Definition at line 46 of file value.hpp.

◆ const_reverse_iterator

using formats::bson::Value::const_reverse_iterator = Iterator<const Value, common::IteratorDirection::kReverse>

Definition at line 47 of file value.hpp.

◆ Exception

using formats::bson::Value::Exception = formats::bson::BsonException

Definition at line 48 of file value.hpp.

◆ ExceptionWithPath

using formats::bson::Value::ExceptionWithPath = formats::bson::ExceptionWithPath

Definition at line 50 of file value.hpp.

◆ ParseException

using formats::bson::Value::ParseException = formats::bson::ParseException

Definition at line 49 of file value.hpp.

Member Enumeration Documentation

◆ DuplicateFieldsPolicy

enum class formats::bson::Value::DuplicateFieldsPolicy

strong

Selectors for duplicate fields parsing behavior.

See also: SetDuplicateFieldsPolicy

Definition at line 55 of file value.hpp.

Member Function Documentation

◆ As() [1/3]

template<typename T>

auto formats::bson::Value::As ( ) const

inline

Extracts the specified type with strict type checks

Example usage:

namespace my_namespace {
 
struct MyKeyValue {
    std::string field1;
    int field2;
};
//  The function must be declared in the namespace of your type
MyKeyValue Parse(const formats::bson::Value& bson, formats::parse::To<MyKeyValue>) {
    return MyKeyValue{
        bson["field1"].As<std::string>({}),  // default construct string if no value
        bson["field2"].As<int>(1),           // return `1` if "field2" is missing
    };
}
 
TEST(FormatsBson, ExampleUsageMyStruct) {
    auto doc = formats::bson::MakeDoc("my_value", formats::bson::MakeDoc("field1", "one", "field2", 1));
 
    formats::bson::Value bson = formats::bson::FromBinaryString(ToBinaryString(doc).GetView());
    auto data = bson["my_value"].As<MyKeyValue>();
    EXPECT_EQ(data.field1, "one");
    EXPECT_EQ(data.field2, 1);
}
}  // namespace my_namespace

See also: Formats (JSON, YAML, BSON, ...)

Definition at line 170 of file value.hpp.

◆ As() [2/3]

template<typename T>

auto formats::bson::Value::As ( DefaultConstructed ) const

inline

Returns value of *this converted to T or T() if this->IsMissing().

Exceptions

Anything derived from std::exception.

Note: Use as value.As<T>({})

Definition at line 197 of file value.hpp.

◆ As() [3/3]

template<typename T, typename First, typename... Rest>

auto formats::bson::Value::As	(	First &&	default_arg,
		Rest &&...	more_default_args ) const

inline

Extracts the specified type with strict type checks, or constructs the default value when the field is not present

Definition at line 184 of file value.hpp.

◆ begin()

const_iterator formats::bson::Value::begin ( ) const

Returns an iterator to the first array element/document field.

Exceptions

TypeMismatchException if value is not a document, array or null

To iterate over Value as object use formats::common::Items.

◆ ConvertTo() [1/2]

template<typename T>

T formats::bson::Value::ConvertTo ( ) const

inline

Extracts the specified type with relaxed type checks. For example, true may be converted to 1.0.

Definition at line 204 of file value.hpp.

◆ ConvertTo() [2/2]

template<typename T, typename First, typename... Rest>

T formats::bson::Value::ConvertTo	(	First &&	default_arg,
		Rest &&...	more_default_args ) const

inline

Extracts the specified type with strict type checks, or constructs the default value when the field is not present

Definition at line 223 of file value.hpp.

◆ end()

const_iterator formats::bson::Value::end ( ) const

Returns an iterator following the last array element/document field.

Exceptions

TypeMismatchException if value is not a document, array or null

◆ GetSize()

uint32_t formats::bson::Value::GetSize ( ) const

Returns the number of elements in a document/array.

Exceptions

TypeMismatchException if value is not a document, array or null

Note: May require linear time before the first element access.; Returns 0 for null.

◆ HasMember()

bool formats::bson::Value::HasMember ( const std::string & name ) const

Checks whether the document has a field.

Parameters

name	field name

Exceptions

TypeMismatchExcepiton if value is not a document or null

◆ IsEmpty()

bool formats::bson::Value::IsEmpty ( ) const

Returns whether the document/array is empty.

Exceptions

TypeMismatchException if value is not a document, array or null

Note: Returns true for null.

◆ IsMissing()

bool formats::bson::Value::IsMissing ( ) const

Checks whether the selected element exists.

Note: MemberMissingException is throws on nonexisting element access

◆ IsObject()

bool formats::bson::Value::IsObject ( ) const

inline

Definition at line 154 of file value.hpp.

◆ operator=()

template<class T>

Value & formats::bson::Value::operator= ( T && ) &&

inline

Definition at line 66 of file value.hpp.

◆ operator[]() [1/2]

Value formats::bson::Value::operator[] ( const std::string & name ) const

Retrieves document field by name.

Parameters

name	field name

Exceptions

TypeMismatchException if value is not a missing value, a document, or null

◆ operator[]() [2/2]

Value formats::bson::Value::operator[] ( uint32_t index ) const

Retrieves array element by index.

Parameters

index element index

Exceptions

TypeMismatchException	if value is not an array or `null`
OutOfBoundsException	if index is invalid for the array

◆ rbegin()

const_reverse_iterator formats::bson::Value::rbegin ( ) const

Returns a reversed iterator to the last array element.

Exceptions

TypeMismatchException if value is not an array or null

◆ rend()

const_reverse_iterator formats::bson::Value::rend ( ) const

Returns a reversed iterator following the first array element.

Exceptions

TypeMismatchException if value is not an array or null

◆ SetDuplicateFieldsPolicy()

void formats::bson::Value::SetDuplicateFieldsPolicy ( DuplicateFieldsPolicy )

Changes parsing behavior when duplicate fields are encountered. Should not be used normally.

Should be called before the first field access. Only affects documents. Default policy is to throw an exception when duplicate fields are encountered.

Warning: At most one value will be read, all others will be discarded and cannot be serialized back!

Friends And Related Symbol Documentation

◆ ValueBuilder

friend class ValueBuilder

friend

Definition at line 264 of file value.hpp.

The documentation for this class was generated from the following file:

userver/formats/bson/value.hpp

Detailed Description

Example usage:

Classes

Public Types

Public Member Functions

Protected Member Functions

Member Typedef Documentation

◆ Builder

◆ const_iterator

◆ const_reverse_iterator

◆ Exception

◆ ExceptionWithPath

◆ ParseException

Member Enumeration Documentation

◆ DuplicateFieldsPolicy

Member Function Documentation

◆ As() [1/3]

Example usage:

◆ As() [2/3]

◆ As() [3/3]

◆ begin()

◆ ConvertTo() [1/2]

◆ ConvertTo() [2/2]

◆ end()

◆ GetSize()

◆ HasMember()

◆ IsEmpty()

◆ IsMissing()

◆ IsObject()

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ rbegin()

◆ rend()

◆ SetDuplicateFieldsPolicy()

Friends And Related Symbol Documentation

◆ ValueBuilder