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

Detailed Description

Builder for BSON.

Class provides methods for building BSON. For read only access to the existing BSON values use formats::bson::Value.

Example usage:

    // #include <userver/formats/bson.hpp>
    formats::bson::ValueBuilder builder;
    builder["key1"] = 1;
    builder["key2"]["key3"] = "val";
    const formats::bson::Value bson = builder.ExtractValue();
 
    ASSERT_EQ(bson["key1"].As<int>(), 1);
    ASSERT_EQ(bson["key2"]["key3"].As<std::string>(), "val");

Customization example:

namespace my_namespace {
 
struct MyKeyValue {
    std::string field1;
    int field2;
};
 
// The function must be declared in the namespace of your type
formats::bson::Value Serialize(const MyKeyValue& data, formats::serialize::To<formats::bson::Value>) {
    formats::bson::ValueBuilder builder;
    builder["field1"] = data.field1;
    builder["field2"] = data.field2;
 
    return builder.ExtractValue();
}
 
TEST(BsonValueBuilder, ExampleCustomization) {
    const MyKeyValue object = {"val", 1};
    formats::bson::ValueBuilder builder;
    builder["example"] = object;
    auto bson = builder.ExtractValue();
    ASSERT_EQ(bson["example"]["field1"].As<std::string>(), "val");
    ASSERT_EQ(bson["example"]["field2"].As<int>(), 1);
}
 
TEST(BsonValueBuilder, EmplaceNocheckTest) {
    formats::bson::ValueBuilder builder;
    builder.EmplaceNocheck("field1", 1);
    builder.EmplaceNocheck("field2", 2);
    builder.EmplaceNocheck("ffffqwe3", 91);
 
    const auto value = builder.ExtractValue();
    EXPECT_EQ(1, value["field1"].As<int>());
    EXPECT_EQ(2, value["field2"].As<int>());
    EXPECT_EQ(91, value["ffffqwe3"].As<int>());
}
 
TEST(BsonValueBuilder, GetPathTest) {
    static const auto
        kDoc = fb::MakeDoc("field_1", fb::MakeDoc("field_2", fb::MakeDoc("field_3", 12)), "field_1_1", 42);
 
    formats::bson::ValueBuilder builder{kDoc};
    EXPECT_EQ("/", builder.GetPath());
    EXPECT_EQ("field_1", builder["field_1"].GetPath());
    EXPECT_EQ("field_1.field_2", builder["field_1"]["field_2"].GetPath());
    EXPECT_EQ("field_1.field_2.field_3", builder["field_1"]["field_2"]["field_3"].GetPath());
    EXPECT_EQ("field_1_1", builder["field_1_1"].GetPath());
}
 
}  // namespace my_namespace
 

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

Definition at line 39 of file value_builder.hpp.

Public Types
using	iterator = Iterator<ValueBuilder>

using	Type = formats::common::Type

Public Member Functions
	ValueBuilder ()
	Constructs a `null` value (may be used as either document or array)

	ValueBuilder (formats::common::Type type)
	Constructs a value with the predefined type.

	ValueBuilder (const ValueBuilder &other)

	ValueBuilder (ValueBuilder &&other)

ValueBuilder &	operator= (const ValueBuilder &other)

ValueBuilder &	operator= (ValueBuilder &&other)

template<typename T>
	ValueBuilder (const T &t)
	Universal constructor using Serialize.

	ValueBuilder (common::TransferTag, ValueBuilder &&) noexcept
	Transfers the `ValueBuilder` object.

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

void	EmplaceNocheck (std::string_view key, ValueBuilder value)
	Emplaces new member w/o a check whether the key already exists.

template<typename Tag, utils::StrongTypedefOps Ops> requires (utils::IsStrongTypedefLoggable(Ops))
ValueBuilder	operator[] (const utils::StrongTypedef< Tag, std::string, Ops > &name)
	Access member by key for modification.

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

void	Remove (const std::string &key)
	Remove key from object. If key is missing nothing happens.

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

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

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

bool	IsNull () const noexcept
	Returns true if *this holds a Null (Type::kNull).

bool	IsBool () const noexcept
	Returns true if *this is convertible to bool.

bool	IsInt () const noexcept
	Returns true if *this is convertible to int.

bool	IsInt64 () const noexcept
	Returns true if *this is convertible to int64_t.

bool	IsUInt64 () const noexcept
	Returns true if *this is convertible to uint64_t.

bool	IsDouble () const noexcept
	Returns true if *this is convertible to double.

bool	IsString () const noexcept
	Returns true if *this is convertible to std::string.

bool	IsArray () const noexcept
	Returns true if *this is an array (Type::kArray).

bool	IsObject () const noexcept
	Returns true if *this holds a document (BSON_TYPE_DOCUMENT).

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

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

std::string	GetPath () const
	Returns full path to this value.

void	Resize (uint32_t size)
	Creates or resizes the array.

void	PushBack (ValueBuilder &&elem)
	Appends an element to the array, possibly creating one.

Value	ExtractValue ()
	Retrieves a compiled value from the builder. After calling this method the builder is in unspecified state.


	ValueBuilder (const Value &)

	ValueBuilder (const Document &)

	ValueBuilder (Value &&)

	ValueBuilder (Document &&)

Concrete type constructors
	ValueBuilder (std::nullptr_t)

	ValueBuilder (bool)

	ValueBuilder (int)

	ValueBuilder (unsigned int)

	ValueBuilder (long)

	ValueBuilder (unsigned long)

	ValueBuilder (long long)

	ValueBuilder (unsigned long long)

	ValueBuilder (double)

	ValueBuilder (const char *)

	ValueBuilder (char *)

	ValueBuilder (std::string)

	ValueBuilder (std::string_view)

	ValueBuilder (const std::chrono::system_clock::time_point &)

	ValueBuilder (const Oid &)

	ValueBuilder (Binary)

	ValueBuilder (const Decimal128 &)

	ValueBuilder (MinKey)

	ValueBuilder (MaxKey)

	ValueBuilder (const Timestamp &)

Member Typedef Documentation

◆ iterator

using formats::bson::ValueBuilder::iterator = Iterator<ValueBuilder>

Definition at line 41 of file value_builder.hpp.

◆ Type

using formats::bson::ValueBuilder::Type = formats::common::Type

Definition at line 42 of file value_builder.hpp.

Constructor & Destructor Documentation

◆ ValueBuilder() [1/3]

formats::bson::ValueBuilder::ValueBuilder ( const Value & )

Efficiently constructs a copy of an existing value

◆ ValueBuilder() [2/3]

template<typename T>

formats::bson::ValueBuilder::ValueBuilder ( const T & t )

inline

Universal constructor using Serialize.

Definition at line 98 of file value_builder.hpp.

◆ ValueBuilder() [3/3]

formats::bson::ValueBuilder::ValueBuilder	(	common::TransferTag	,
		ValueBuilder &&	)

noexcept

Transfers the ValueBuilder object.

See also: formats::common::TransferTag for the transfer semantics

Member Function Documentation

◆ begin()

iterator formats::bson::ValueBuilder::begin ( )

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

Exceptions

TypeMismatchException if value is not a document, array or null

◆ EmplaceNocheck()

void formats::bson::ValueBuilder::EmplaceNocheck	(	std::string_view	key,
		ValueBuilder	value )

Emplaces new member w/o a check whether the key already exists.

Warning: May create invalid BSON with duplicate key.

Exceptions

`TypeMismatchException` if not object or null value.

◆ end()

iterator formats::bson::ValueBuilder::end ( )

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::ValueBuilder::GetSize ( ) const

Returns the number of elements in a document/array.

Exceptions

TypeMismatchException if value is not a document, array or null

Note: Returns 0 for null.

◆ HasMember()

bool formats::bson::ValueBuilder::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::ValueBuilder::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.

◆ operator[]() [1/3]

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

Retrieves or creates document field by name.

Exceptions

TypeMismatchException if value is not a document or null

◆ operator[]() [2/3]

template<typename Tag, utils::StrongTypedefOps Ops>
requires (utils::IsStrongTypedefLoggable(Ops))

ValueBuilder formats::bson::ValueBuilder::operator[] ( const utils::StrongTypedef< Tag, std::string, Ops > & name )

inline

Access member by key for modification.

Exceptions

`TypeMismatchException` if not object or null value.

Definition at line 119 of file value_builder.hpp.

◆ operator[]() [3/3]

ValueBuilder formats::bson::ValueBuilder::operator[] ( uint32_t index )

Retrieves array element by index.

Exceptions

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

◆ PushBack()

void formats::bson::ValueBuilder::PushBack ( ValueBuilder && elem )

Appends an element to the array, possibly creating one.

Parameters

elem	element to append

Exceptions

TypeMismatchException if value is not an array or null

◆ Remove()

void formats::bson::ValueBuilder::Remove ( const std::string & key )

Remove key from object. If key is missing nothing happens.

Exceptions

`TypeMismatchException` if value is not an object.

◆ Resize()

void formats::bson::ValueBuilder::Resize ( uint32_t size )

Creates or resizes the array.

Parameters

size new size

Exceptions

TypeMismatchException if value is not an array or null

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

userver/formats/bson/value_builder.hpp

Detailed Description

Example usage:

Customization example:

Public Types

Public Member Functions

Member Typedef Documentation

◆ iterator

◆ Type

Constructor & Destructor Documentation

◆ ValueBuilder() [1/3]

◆ ValueBuilder() [2/3]

◆ ValueBuilder() [3/3]

Member Function Documentation

◆ begin()

◆ EmplaceNocheck()

◆ end()

◆ GetSize()

◆ HasMember()

◆ IsEmpty()

◆ operator[]() [1/3]

◆ operator[]() [2/3]

◆ operator[]() [3/3]

◆ PushBack()

◆ Remove()

◆ Resize()