Non-mutable JSON value representation. More...

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

Classes
struct	DefaultConstructed

struct	IterTraits

Public Types
using	const_iterator = Iterator< IterTraits, common::IteratorDirection::kForward >

using	const_reverse_iterator = Iterator< IterTraits, common::IteratorDirection::kReverse >

using	Exception = formats::json::Exception

using	ParseException = formats::json::ParseException

using	Builder = ValueBuilder

Public Member Functions
	Value () noexcept=default
	Constructs a Value that holds a null.

	Value (const Value &)=default

	Value (Value &&) noexcept=default

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

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

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

Value	operator[] (std::string_view key) const
	Access member by key for read.

Value	operator[] (std::size_t index) const
	Access array member by index for read.

const_iterator	begin () const
	Returns an iterator to the beginning of the held array or map.

const_iterator	end () const
	Returns an iterator to the end of the held array or map.

const_reverse_iterator	rbegin () const
	Returns an iterator to the reversed begin of the held array.

const_reverse_iterator	rend () const
	Returns an iterator to the reversed end of the held array.

bool	IsEmpty () const
	Returns whether the array or object is empty. Returns true for null.

std::size_t	GetSize () const
	Returns array size, object members count, or 0 for null.

bool	operator== (const Value &other) const
	Compares values.

bool	operator!= (const Value &other) const

bool	IsMissing () const noexcept
	Returns true if this holds nothing. When `IsMissing()` returns `true` any attempt to get the actual value or iterate over this will.

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

bool	IsBool () const noexcept
	Returns true if *this holds a bool.

bool	IsInt () const noexcept
	Returns true if *this holds an int.

bool	IsInt64 () const noexcept
	Returns true if *this holds an int64_t.

bool	IsUInt64 () const noexcept
	Returns true if *this holds an uint64_t.

bool	IsDouble () const noexcept
	Returns true if *this holds a double.

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

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

bool	IsObject () const noexcept
	Returns true if *this holds a map (Type::kObject).

template<typename T >
T	As () const
	Returns value of *this converted to T.

template<typename T , typename First , typename... Rest>
T	As (First &&default_arg, Rest &&... more_default_args) const
	Returns value of *this converted to T or T(args) if this->IsMissing().

template<typename T >
T	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

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

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

Value	Clone () const
	Returns new value that is an exact copy if the existing one but references different memory (a deep copy of a *this). The returned value is a root value with path '/'.

void	CheckNotMissing () const

void	CheckArrayOrNull () const

void	CheckObjectOrNull () const

void	CheckObject () const

void	CheckObjectOrArrayOrNull () const

void	CheckInBounds (std::size_t index) const

bool	IsRoot () const noexcept
	Returns true if *this is a first (root) value.

bool	DebugIsReferencingSameMemory (const Value &other) const
	Returns true if `*this` and `other` reference the value by the same pointer.

template<>
bool	As () const

template<>
int64_t	As () const

template<>
uint64_t	As () const

template<>
double	As () const

template<>
bool	ConvertTo () const

template<>
int64_t	ConvertTo () const

template<>
uint64_t	ConvertTo () const

template<>
double	ConvertTo () const

Friends
template<typename , common::IteratorDirection >
class	Iterator

class	ValueBuilder

class	StringBuilder

class	parser::JsonValueParser

formats::json::Value	FromString (std::string_view)
	Parse JSON from string.

formats::json::Value	FromStream (std::istream &)
	Parse JSON from stream.

void	Serialize (const formats::json::Value &, std::ostream &)
	Serialize JSON to stream.

std::string	ToString (const formats::json::Value &)
	Serialize JSON to string.

std::string	ToStableString (const formats::json::Value &)

std::string	ToStableString (formats::json::Value &&)

logging::LogHelper &	operator<< (logging::LogHelper &, const Value &)
	Log JSON.

Detailed Description

Non-mutable JSON value representation.

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

Example usage:

  // #include <userver/formats/json.hpp>
 
  formats::json::Value json = formats::json::FromString(R"({
    "key1": 1,
    "key2": {"key3":"val"}
  })");
 
  const auto key1 = json["key1"].As<int>();
  ASSERT_EQ(key1, 1);
 
  const auto key3 = json["key2"]["key3"].As<std::string>();
  ASSERT_EQ(key3, "val");

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

Examples: samples/config_service/config_service.cpp, samples/http_caching/http_caching.cpp, samples/testsuite-support/src/logcapture.cpp, samples/testsuite-support/src/metrics.cpp, samples/testsuite-support/src/metrics.hpp, samples/testsuite-support/src/now.cpp, and samples/testsuite-support/src/testpoint.cpp.

Definition at line 54 of file value.hpp.

Member Typedef Documentation

◆ Builder

using formats::json::Value::Builder = ValueBuilder

Definition at line 70 of file value.hpp.

◆ const_iterator

using formats::json::Value::const_iterator = Iterator<IterTraits, common::IteratorDirection::kForward>

Definition at line 64 of file value.hpp.

◆ const_reverse_iterator

using formats::json::Value::const_reverse_iterator = Iterator<IterTraits, common::IteratorDirection::kReverse>

Definition at line 66 of file value.hpp.

◆ Exception

using formats::json::Value::Exception = formats::json::Exception

Definition at line 68 of file value.hpp.

◆ ParseException

using formats::json::Value::ParseException = formats::json::ParseException

Definition at line 69 of file value.hpp.

Member Function Documentation

◆ As() [1/3]

template<typename T >

T formats::json::Value::As ( ) const

Returns value of *this converted to T.

Exceptions

Anything derived from std::exception.

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::json::Value& json,
                 formats::parse::To<MyKeyValue>) {
  return MyKeyValue{
      json["field1"].As<std::string>(""),
      json["field2"].As<int>(1),  // return `1` if "field2" is missing
  };
}
 
TEST(FormatsJson, ExampleUsageMyStruct) {
  formats::json::Value json = formats::json::FromString(R"({
    "my_value": {
        "field1": "one",
        "field2": 1
    }
  })");
  auto data = json["my_value"].As<MyKeyValue>();
  EXPECT_EQ(data.field1, "one");
  EXPECT_EQ(data.field2, 1);
}
}  // namespace my_namespace

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

Examples: components/component_sample_test.cpp, samples/config_service/config_service.cpp, samples/http_caching/http_caching.cpp, and samples/testsuite-support/src/testpoint.cpp.

Definition at line 312 of file value.hpp.

◆ As() [2/3]

template<typename T >

T formats::json::Value::As ( Value::DefaultConstructed ) const

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 365 of file value.hpp.

◆ As() [3/3]

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

T formats::json::Value::As	(	First &&	default_arg,
		Rest &&...	more_default_args
	)		const

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

Exceptions

Anything derived from std::exception.

Definition at line 354 of file value.hpp.

◆ begin()

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

Returns an iterator to the beginning of the held array or map.

Exceptions

TypeMismatchException if not an array, object, or null.

◆ CheckArrayOrNull()

void formats::json::Value::CheckArrayOrNull ( ) const

Exceptions

MemberMissingException if *this is not an array or null.

◆ CheckInBounds()

void formats::json::Value::CheckInBounds ( std::size_t index ) const

Exceptions

TypeMismatchException if *this is not a map, array or null; OutOfBoundsException if index >= this->GetSize().

◆ CheckNotMissing()

void formats::json::Value::CheckNotMissing ( ) const

Exceptions

MemberMissingException if this->IsMissing().

◆ CheckObject()

void formats::json::Value::CheckObject ( ) const

Exceptions

TypeMismatchException if *this is not a map.

◆ CheckObjectOrArrayOrNull()

void formats::json::Value::CheckObjectOrArrayOrNull ( ) const

Exceptions

TypeMismatchException if *this is not a map, array or null.

◆ CheckObjectOrNull()

void formats::json::Value::CheckObjectOrNull ( ) const

Exceptions

TypeMismatchException if *this is not a map or null.

◆ Clone()

Value formats::json::Value::Clone ( ) const

Returns new value that is an exact copy if the existing one but references different memory (a deep copy of a *this). The returned value is a root value with path '/'.

Exceptions

MemberMissingException id this->IsMissing().

◆ ConvertTo() [1/2]

template<typename T >

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

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

Definition at line 370 of file value.hpp.

◆ ConvertTo() [2/2]

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

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

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

Definition at line 386 of file value.hpp.

◆ DebugIsReferencingSameMemory()

bool formats::json::Value::DebugIsReferencingSameMemory ( const Value & other ) const

inline

Returns true if *this and other reference the value by the same pointer.

Definition at line 234 of file value.hpp.

◆ end()

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

Returns an iterator to the end of the held array or map.

Exceptions

TypeMismatchException if not an array, object, or null.

◆ GetSize()

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

Returns array size, object members count, or 0 for null.

Exceptions

TypeMismatchException if not an array, object, or null.

◆ HasMember()

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

Returns true if *this holds a key.

Exceptions

TypeMismatchException if *this is not a map or null.

◆ IsEmpty()

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

Returns whether the array or object is empty. Returns true for null.

Exceptions

TypeMismatchException if not an array, object, or null.

Examples: samples/http_caching/http_caching.cpp.

◆ operator=()

template<class T >

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

inline

Definition at line 82 of file value.hpp.

◆ operator==()

bool formats::json::Value::operator== ( const Value & other ) const

Compares values.

Exceptions

MemberMissingException if *this or other is missing.

◆ operator[]() [1/2]

Value formats::json::Value::operator[] ( std::size_t index ) const

Access array member by index for read.

Exceptions

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

◆ operator[]() [2/2]

Value formats::json::Value::operator[] ( std::string_view key ) const

Access member by key for read.

Exceptions

TypeMismatchException if not a missing value, an object or null.

◆ rbegin()

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

Returns an iterator to the reversed begin of the held array.

Exceptions

TypeMismatchException if not an array or null.

◆ rend()

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

Returns an iterator to the reversed end of the held array.

Exceptions

TypeMismatchException if not an array or null.

Friends And Related Symbol Documentation

◆ FromString

formats::json::Value FromString ( std::string_view doc )

friend

Parse JSON from string.

Definition at line 87 of file from_string.hpp.

◆ Iterator

template<typename , common::IteratorDirection >

friend class Iterator

friend

Definition at line 293 of file value.hpp.

◆ parser::JsonValueParser

friend class parser::JsonValueParser

friend

Definition at line 299 of file value.hpp.

◆ StringBuilder

friend class StringBuilder

friend

Definition at line 295 of file value.hpp.

◆ ToStableString

std::string ToStableString ( const formats::json::Value & )

friend

Stably serialize JSON to string. In result there is no whitespace, keys are sorted and character escaping is stabilized

◆ ValueBuilder

friend class ValueBuilder

friend

Definition at line 294 of file value.hpp.

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

userver/formats/json/value.hpp

Table of Contents

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Example usage:

Member Typedef Documentation

◆ Builder

◆ const_iterator

◆ const_reverse_iterator

◆ Exception

◆ ParseException

Member Function Documentation

◆ As() [1/3]

Example usage:

◆ As() [2/3]

◆ As() [3/3]

◆ begin()

◆ CheckArrayOrNull()

◆ CheckInBounds()

◆ CheckNotMissing()

◆ CheckObject()

◆ CheckObjectOrArrayOrNull()

◆ CheckObjectOrNull()

◆ Clone()

◆ ConvertTo() [1/2]

◆ ConvertTo() [2/2]

◆ DebugIsReferencingSameMemory()

◆ end()

◆ GetSize()

◆ HasMember()

◆ IsEmpty()

◆ operator=()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ rbegin()

◆ rend()

Friends And Related Symbol Documentation

◆ FromString

◆ Iterator

◆ parser::JsonValueParser

◆ StringBuilder

◆ ToStableString

◆ ValueBuilder