userver: formats::bson::Value Class Reference
Loading...
Searching...
No Matches
formats::bson::Value Class Reference

#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"));
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, ...)
Examples
samples/mongo_service/mongo_service.cpp.

Definition at line 40 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
 
using const_reverse_iterator
 
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
 
Valueoperator= (const Value &) &=default
 
Valueoperator= (Value &&) &noexcept=default
 
template<class T >
Valueoperator= (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 >
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>
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

Definition at line 51 of file value.hpp.

◆ const_iterator

Initial value:
Iterator<const Value, common::IteratorDirection::kForward>

Definition at line 44 of file value.hpp.

◆ const_reverse_iterator

Initial value:
Iterator<const Value, common::IteratorDirection::kReverse>

Definition at line 46 of file value.hpp.

◆ Exception

◆ ExceptionWithPath

◆ ParseException

Member Enumeration Documentation

◆ DuplicateFieldsPolicy

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,
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) {
"my_value", formats::bson::MakeDoc("field1", "one", "field2", 1));
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, ...)
Examples
samples/mongo_service/mongo_service.cpp.

Definition at line 166 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
Anythingderived from std::exception.
Note
Use as value.As<T>({})

Definition at line 193 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 179 of file value.hpp.

◆ begin()

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

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

Exceptions
TypeMismatchExceptionif value is not a document, array or null

◆ 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 200 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 218 of file value.hpp.

◆ end()

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

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

Exceptions
TypeMismatchExceptionif 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
TypeMismatchExceptionif 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
namefield name
Exceptions
TypeMismatchExcepitonif value is not a document or null

◆ IsEmpty()

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

Returns whether the document/array is empty.

Exceptions
TypeMismatchExceptionif 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 150 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
namefield name
Exceptions
TypeMismatchExceptionif 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
indexelement index
Exceptions
TypeMismatchExceptionif value is not an array or null
OutOfBoundsExceptionif 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
TypeMismatchExceptionif 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
TypeMismatchExceptionif 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 260 of file value.hpp.


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