userver: formats::json::Value Class Reference
Loading...
Searching...
No Matches
formats::json::Value Class Referencefinal

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

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

Classes

struct  DefaultConstructed
 
struct  IterTraits
 

Public Types

using const_iterator
 
using const_reverse_iterator
 
using Exception = formats::json::Exception
 
using ParseException = formats::json::ParseException
 
using ExceptionWithPath = formats::json::ExceptionWithPath
 
using Builder = ValueBuilder
 

Public Member Functions

 Value ()
 Constructs a Value that holds a null.
 
 Value (const Value &)=default
 
 Value (Value &&) noexcept
 
Valueoperator= (const Value &) &=default
 
Valueoperator= (Value &&) noexcept
 
template<class T >
Valueoperator= (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 >
auto As () const
 Returns value of *this converted to the result type of Parse(const Value&, parse::To<T>). Almost always it is T.
 
template<typename T , typename First , typename... Rest>
auto 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 >
auto As (DefaultConstructed) const
 Returns value of *this converted to T or T() if this->IsMissing().
 
template<typename 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>
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 of 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 ConvertTo () const
 
template<>
int64_t ConvertTo () const
 
template<>
uint64_t ConvertTo () const
 
template<>
double ConvertTo () const
 

Member Typedef Documentation

◆ Builder

◆ const_iterator

Initial value:
Iterator<IterTraits, common::IteratorDirection::kForward>

Definition at line 68 of file value.hpp.

◆ const_reverse_iterator

Initial value:
Iterator<IterTraits, common::IteratorDirection::kReverse>

Definition at line 70 of file value.hpp.

◆ Exception

◆ ExceptionWithPath

◆ ParseException

Member Function Documentation

◆ As() [1/3]

template<typename T >
auto formats::json::Value::As ( ) const

Returns value of *this converted to the result type of Parse(const Value&, parse::To<T>). Almost always it is T.

Exceptions
Anythingderived 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,
return MyKeyValue{
json["field1"].As<std::string>(""),
json["field2"].As<int>(1), // return `1` if "field2" is missing
};
}
TEST(FormatsJson, ExampleUsageMyStruct) {
"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
samples/config_service/config_service.cpp, and samples/testsuite-support/src/testpoint.cpp.

Definition at line 339 of file value.hpp.

◆ As() [2/3]

template<typename T >
auto formats::json::Value::As ( Value::DefaultConstructed ) const

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

Exceptions
Anythingderived from std::exception.
Note
Use as value.As<T>({})

Definition at line 387 of file value.hpp.

◆ As() [3/3]

template<typename T , typename First , typename... Rest>
auto 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
Anythingderived from std::exception.

Definition at line 376 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
TypeMismatchExceptionif not an array, object, or null.

◆ CheckArrayOrNull()

void formats::json::Value::CheckArrayOrNull ( ) const
Exceptions
MemberMissingExceptionif *this is not an array or null.

◆ CheckInBounds()

void formats::json::Value::CheckInBounds ( std::size_t index) const
Exceptions
TypeMismatchExceptionif *this is not a map, array or null; OutOfBoundsException if index >= this->GetSize().

◆ CheckNotMissing()

void formats::json::Value::CheckNotMissing ( ) const
Exceptions
MemberMissingExceptionif this->IsMissing().

◆ CheckObject()

void formats::json::Value::CheckObject ( ) const
Exceptions
TypeMismatchExceptionif *this is not a map.

◆ CheckObjectOrArrayOrNull()

void formats::json::Value::CheckObjectOrArrayOrNull ( ) const
Exceptions
TypeMismatchExceptionif *this is not a map, array or null.

◆ CheckObjectOrNull()

void formats::json::Value::CheckObjectOrNull ( ) const
Exceptions
TypeMismatchExceptionif *this is not a map or null.

◆ Clone()

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

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

Exceptions
MemberMissingExceptionif 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 392 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 408 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 244 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
TypeMismatchExceptionif 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
TypeMismatchExceptionif 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
TypeMismatchExceptionif *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
TypeMismatchExceptionif not an array, object, or null.

◆ operator=()

template<class T >
Value & formats::json::Value::operator= ( T && ) &&
inline

Definition at line 87 of file value.hpp.

◆ operator==()

Compares values.

Exceptions
MemberMissingExceptionif *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
TypeMismatchExceptionif not an array value.
OutOfBoundsExceptionif 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
TypeMismatchExceptionif 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
TypeMismatchExceptionif 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
TypeMismatchExceptionif 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 88 of file from_string.hpp.

◆ Iterator

Definition at line 309 of file value.hpp.

◆ parser::JsonValueParser

Definition at line 316 of file value.hpp.

◆ Schema

Definition at line 312 of file value.hpp.

◆ StringBuilder

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

Definition at line 310 of file value.hpp.


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