formats::bson::ValueBuilder Class Reference

Table of Contents

• 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()

#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";
  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) {
  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>());
}
 
}  // namespace my_namespace
 

See also

Formats (JSON, YAML, BSON, ...)

Definition at line 44 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, typename Enable = std::enable_if_t<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.
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 46 of file value_builder.hpp.

Type

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

Definition at line 47 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 103 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, typename Enable >

ValueBuilder formats::bson::ValueBuilder::operator[]

(

const utils::StrongTypedef< Tag, std::string, Ops > &

name

)

Access member by key for modification.

Exceptions

`TypeMismatchException`

if not object or null value.

Definition at line 210 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