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

Detailed Description

Builder for JSON.

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

Example usage:

    // #include <userver/formats/json.hpp>
    formats::json::ValueBuilder builder;
    builder["key1"] = 1;
    builder["key2"]["key3"] = "val";
    formats::json::Value json = builder.ExtractValue();
 
    ASSERT_EQ(json["key1"].As<int>(), 1);
    ASSERT_EQ(json["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::json::Value Serialize(const MyKeyValue& data, formats::serialize::To<formats::json::Value>) {
    formats::json::ValueBuilder builder;
    builder["field1"] = data.field1;
    builder["field2"] = data.field2;
 
    return builder.ExtractValue();
}
 
TEST(JsonValueBuilder, ExampleCustomization) {
    MyKeyValue object = {"val", 1};
    formats::json::ValueBuilder builder;
    builder["example"] = object;
    auto json = builder.ExtractValue();
    ASSERT_EQ(json["example"]["field1"].As<std::string>(), "val");
    ASSERT_EQ(json["example"]["field2"].As<int>(), 1);
}
 
TEST(JsonValueBuilder, StringViewRemove) {
    formats::json::ValueBuilder builder;
    const std::string str = "ab";
    builder["a"] = 1;
    builder[str] = 2;
    builder.Remove(std::string_view(str.data(), 1));
 
    EXPECT_EQ(1, builder.GetSize());
 
    const auto value = builder.ExtractValue();
    EXPECT_EQ(2, value[str].As<int>());
}
 
TEST(JsonValueBuilder, StringViewHasMember) {
    formats::json::ValueBuilder main_builder;
    const std::string str = "ab";
    main_builder[str] = 2;
    EXPECT_EQ(false, main_builder.HasMember("a"));
    EXPECT_EQ(false, main_builder.HasMember(std::string_view(str.data(), 1)));
    EXPECT_EQ(true, main_builder.HasMember(std::string_view(str.data(), 2)));
}
 
TEST(JsonValueBuilder, StringViewEmplaceNocheck) {
    formats::json::ValueBuilder main_builder;
    const std::string str = "ab";
    main_builder.EmplaceNocheck(std::string_view(str.data(), 1), 1);
    main_builder.EmplaceNocheck(std::string_view(str.data(), 2), 2);
    main_builder.EmplaceNocheck(std::string_view(std::string(1024, 'a') + 'b'), 1025);
 
    const auto value = main_builder.ExtractValue();
    EXPECT_EQ(1, value["a"].As<int>());
    EXPECT_EQ(2, value["ab"].As<int>());
    EXPECT_EQ(1025, value[std::string(1024, 'a') + 'b'].As<int>());
}
 
}  // namespace my_namespace
 

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

Examples: samples/config_service/main.cpp, samples/kafka_service/src/consume.cpp, samples/testsuite-support/src/metrics.cpp, samples/testsuite-support/src/now.cpp, samples/testsuite-support/src/tasks.cpp, and samples/testsuite-support/src/testpoint.cpp.

Definition at line 41 of file value_builder.hpp.

Classes
struct	IterTraits

Public Types
using	iterator = Iterator<IterTraits>

Public Member Functions
	ValueBuilder ()=default
	Constructs a ValueBuilder that holds kNull.

	ValueBuilder (formats::common::Type type)
	Constructs a valueBuilder that holds default value for provided `type`.

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

	ValueBuilder (const ValueBuilder &other)

	ValueBuilder (ValueBuilder &&other)

ValueBuilder &	operator= (const ValueBuilder &other)

ValueBuilder &	operator= (ValueBuilder &&other)

	ValueBuilder (const formats::json::Value &other)

	ValueBuilder (formats::json::Value &&other)

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

ValueBuilder	operator[] (std::string key)
	Access member by key for modification.

ValueBuilder	operator[] (std::size_t index)
	Access array member by index for modification.

template<typename Tag, utils::StrongTypedefOps Ops, typename Enable = std::enable_if_t<utils::IsStrongTypedefLoggable(Ops)>>
ValueBuilder	operator[] (utils::StrongTypedef< Tag, std::string, Ops > key)
	Access member by key for modification.

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

void	Remove (std::string_view key)
	Remove key from object. If key is missing nothing happens.

iterator	begin ()

iterator	end ()

bool	IsEmpty () const
	Returns whether the array or object 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 map (Type::kObject).

std::size_t	GetSize () const
	Returns array size or object members count.

bool	HasMember (std::string_view key) const
	Returns true if value holds a `key`.

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

void	Resize (std::size_t size)
	Resize the array value or convert null value into an array of requested size.

void	PushBack (ValueBuilder &&bld)
	Add element into the last position of array.

formats::json::Value	ExtractValue ()
	Take out the resulting `Value` object. After calling this method the object is in unspecified (but valid - possibly null) state.

Concrete type constructors
	ValueBuilder (std::nullptr_t)

	ValueBuilder (bool t)

	ValueBuilder (const char *str)

	ValueBuilder (char *str)

	ValueBuilder (const std::string &str)

	ValueBuilder (std::string_view str)

	ValueBuilder (int t)

	ValueBuilder (unsigned int t)

	ValueBuilder (uint64_t t)

	ValueBuilder (int64_t t)

	ValueBuilder (float t)

	ValueBuilder (double t)

Member Typedef Documentation

◆ iterator

using formats::json::ValueBuilder::iterator = Iterator<IterTraits>

Definition at line 50 of file value_builder.hpp.

Constructor & Destructor Documentation

◆ ValueBuilder() [1/3]

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

noexcept

Transfers the ValueBuilder object.

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

◆ ValueBuilder() [2/3]

formats::json::ValueBuilder::ValueBuilder ( std::nullptr_t )

inline

Definition at line 74 of file value_builder.hpp.

◆ ValueBuilder() [3/3]

template<typename T>

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

inline

Universal constructor using Serialize.

Definition at line 90 of file value_builder.hpp.

Member Function Documentation

◆ EmplaceNocheck()

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

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

Warning: May create invalid JSON with duplicate key.

Exceptions

`TypeMismatchException` if not object or null value.

◆ ExtractValue()

formats::json::Value formats::json::ValueBuilder::ExtractValue ( )

Take out the resulting Value object. After calling this method the object is in unspecified (but valid - possibly null) state.

Exceptions

`JsonException` if called not from the root builder.

Examples: samples/config_service/main.cpp, samples/kafka_service/src/consume.cpp, samples/mongo_service/main.cpp, samples/testsuite-support/src/metrics.cpp, samples/testsuite-support/src/now.cpp, samples/testsuite-support/src/tasks.cpp, and samples/testsuite-support/src/testpoint.cpp.

◆ GetSize()

std::size_t formats::json::ValueBuilder::GetSize ( ) const

Returns array size or object members count.

Exceptions

`TypeMismatchException` if not an array or an object.

◆ HasMember()

bool formats::json::ValueBuilder::HasMember ( std::string_view key ) const

Returns true if value holds a key.

Exceptions

`TypeMismatchException` if *this is not a map or null.

◆ IsEmpty()

bool formats::json::ValueBuilder::IsEmpty ( ) const

Returns whether the array or object is empty.

Exceptions

`TypeMismatchException` if not an array or an object.

◆ operator[]() [1/3]

ValueBuilder formats::json::ValueBuilder::operator[] ( std::size_t index )

Access array member by index for modification.

Exceptions

`TypeMismatchException`	if not an array value.
`OutOfBoundsException`	if index is greater than size.

◆ operator[]() [2/3]

ValueBuilder formats::json::ValueBuilder::operator[] ( std::string key )

Access member by key for modification.

Exceptions

`TypeMismatchException` if not object or null value.

◆ operator[]() [3/3]

template<typename Tag, utils::StrongTypedefOps Ops, typename Enable>

ValueBuilder formats::json::ValueBuilder::operator[] ( utils::StrongTypedef< Tag, std::string, Ops > key )

Access member by key for modification.

Exceptions

`TypeMismatchException` if not object or null value.

Definition at line 229 of file value_builder.hpp.

◆ PushBack()

void formats::json::ValueBuilder::PushBack ( ValueBuilder && bld )

Add element into the last position of array.

Exceptions

`TypeMismatchException` if not an array or null.

◆ Remove()

void formats::json::ValueBuilder::Remove ( std::string_view key )

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

Exceptions

`TypeMismatchException` if value is not an object.

◆ Resize()

void formats::json::ValueBuilder::Resize ( std::size_t size )

Resize the array value or convert null value into an array of requested size.

Exceptions

`TypeMismatchException` if not an array or null.

Friends And Related Symbol Documentation

◆ Iterator< IterTraits, common::IteratorDirection::kForward >

friend class Iterator< IterTraits, common::IteratorDirection::kForward >

friend

Definition at line 197 of file value_builder.hpp.

◆ Iterator< IterTraits, common::IteratorDirection::kReverse >

friend class Iterator< IterTraits, common::IteratorDirection::kReverse >

friend

Definition at line 197 of file value_builder.hpp.

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

userver/formats/json/value_builder.hpp

Detailed Description

Example usage:

Customization example:

Classes

Public Types

Public Member Functions

Member Typedef Documentation

◆ iterator

Constructor & Destructor Documentation

◆ ValueBuilder() [1/3]

◆ ValueBuilder() [2/3]

◆ ValueBuilder() [3/3]

Member Function Documentation

◆ EmplaceNocheck()

◆ ExtractValue()

◆ GetSize()

◆ HasMember()

◆ IsEmpty()

◆ operator[]() [1/3]

◆ operator[]() [2/3]

◆ operator[]() [3/3]

◆ PushBack()

◆ Remove()

◆ Resize()

Friends And Related Symbol Documentation

◆ Iterator< IterTraits, common::IteratorDirection::kForward >

◆ Iterator< IterTraits, common::IteratorDirection::kReverse >