formats::json::Value Class Reference

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