Non-mutable YAML value representation. More...

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

Classes
struct	DefaultConstructed

struct	IterTraits

Public Types
using	const_iterator = Iterator< IterTraits >

using	Exception = formats::yaml::Exception

using	ParseException = formats::yaml::ParseException

using	Builder = ValueBuilder

Public Member Functions
	Value () noexcept
	Constructs a Value that holds a Null.

	Value (Value &&)

	Value (const Value &)

Value &	operator= (Value &&)

Value &	operator= (const Value &)

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

	Value (Value &&other, std::string path_prefix)
	Copies `other`, appending `path_prefix` to the stored `path`

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.

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

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

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

bool	operator!= (const Value &other) const

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

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 is 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().

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

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

int	GetColumn () const
	Returns 0-based column number of this `Value` in the original document. Returns `-1` if `this->IsMissing()`. If `Value` was created using formats::yaml::ValueBuilder, returns `0`.

int	GetLine () const
	Returns 0-based line number of this `Value` in the original document. Returns `-1` if `this->IsMissing()`. If `Value` was created using formats::yaml::ValueBuilder, returns `0`.

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	CheckArray () const

void	CheckArrayOrNull () const

void	CheckObjectOrNull () const

void	CheckObject () const

void	CheckString () 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

Friends
class	Iterator< IterTraits >

class	ValueBuilder

formats::yaml::Value	FromString (const std::string &)
	Parse YAML from string.

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

void	Serialize (const formats::yaml::Value &, std::ostream &)
	Serialize YAML to stream.

Detailed Description

Non-mutable YAML value representation.

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

Example usage:

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

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

Examples: samples/json2yaml/json2yaml.cpp.

Definition at line 34 of file value.hpp.

Member Typedef Documentation

◆ Builder

using formats::yaml::Value::Builder = ValueBuilder

Definition at line 47 of file value.hpp.

◆ const_iterator

using formats::yaml::Value::const_iterator = Iterator<IterTraits>

Definition at line 44 of file value.hpp.

◆ Exception

using formats::yaml::Value::Exception = formats::yaml::Exception

Definition at line 45 of file value.hpp.

◆ ParseException

using formats::yaml::Value::ParseException = formats::yaml::ParseException

Definition at line 46 of file value.hpp.

Constructor & Destructor Documentation

◆ Value()

formats::yaml::Value::Value	(	Value &&	other,
		std::string	path_prefix
	)

Copies other, appending path_prefix to the stored path

Warning: other must have an empty (root) path

Exceptions

`std::logic_error` if other has path other than the root path

See also: GetPath

Member Function Documentation

◆ As() [1/3]

template<typename T >

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

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

Definition at line 268 of file value.hpp.

◆ As() [2/3]

template<typename T >

T formats::yaml::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 306 of file value.hpp.

◆ As() [3/3]

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

T formats::yaml::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 295 of file value.hpp.

◆ begin()

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

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

Exceptions

TypeMismatchException if not an array or an object.

◆ CheckArray()

void formats::yaml::Value::CheckArray ( ) const

Exceptions

MemberMissingException if *this is not an array.

◆ CheckArrayOrNull()

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

Exceptions

MemberMissingException if *this is not an array or Null.

◆ CheckInBounds()

void formats::yaml::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::yaml::Value::CheckNotMissing ( ) const

Exceptions

MemberMissingException if this->IsMissing().

◆ CheckObject()

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

Exceptions

TypeMismatchException if *this is not a map.

◆ CheckObjectOrArrayOrNull()

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

Exceptions

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

◆ CheckObjectOrNull()

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

Exceptions

TypeMismatchException if *this is not a map or Null.

◆ CheckString()

void formats::yaml::Value::CheckString ( ) const

Exceptions

TypeMismatchException if *this is not convertible to std::string.

◆ Clone()

Value formats::yaml::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().

◆ end()

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

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

Exceptions

TypeMismatchException if not an array or an object.

◆ GetColumn()

int formats::yaml::Value::GetColumn ( ) const

Returns 0-based column number of this Value in the original document. Returns -1 if this->IsMissing(). If Value was created using formats::yaml::ValueBuilder, returns 0.

Note: This method available only for formats::yaml::Value.

◆ GetLine()

int formats::yaml::Value::GetLine ( ) const

Returns 0-based line number of this Value in the original document. Returns -1 if this->IsMissing(). If Value was created using formats::yaml::ValueBuilder, returns 0.

Note: This method available only for formats::yaml::Value.

◆ GetSize()

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

Returns array size or object members count.

Exceptions

TypeMismatchException if not an array or an object.

◆ IsEmpty()

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

Returns whether the array or object is empty.

Exceptions

TypeMismatchException if not an array or an object.

◆ operator=()

template<class T >

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

inline

Definition at line 60 of file value.hpp.

◆ operator==()

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

Compares values.

Exceptions

MemberMissingException if *this or other is missing.

◆ operator[]() [1/2]

Value formats::yaml::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::yaml::Value::operator[] ( std::string_view key ) const

Access member by key for read.

Exceptions

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

Friends And Related Symbol Documentation

◆ FromStream

formats::yaml::Value FromStream ( std::istream & )

friend

Parse JSON from stream.

◆ FromString

formats::yaml::Value FromString ( const std::string & doc )

friend

Parse YAML from string.

Definition at line 81 of file from_string.hpp.

◆ Iterator< IterTraits >

friend class Iterator< IterTraits >

friend

Definition at line 257 of file value.hpp.

◆ ValueBuilder

friend class ValueBuilder

friend

Definition at line 260 of file value.hpp.

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

userver/formats/yaml/value.hpp

Table of Contents

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Example usage:

Member Typedef Documentation

◆ Builder

◆ const_iterator

◆ Exception

◆ ParseException

Constructor & Destructor Documentation

◆ Value()

Member Function Documentation

◆ As() [1/3]

Example usage:

◆ As() [2/3]

◆ As() [3/3]

◆ begin()

◆ CheckArray()

◆ CheckArrayOrNull()

◆ CheckInBounds()

◆ CheckNotMissing()

◆ CheckObject()

◆ CheckObjectOrArrayOrNull()

◆ CheckObjectOrNull()

◆ CheckString()

◆ Clone()

◆ end()

◆ GetColumn()

◆ GetLine()

◆ GetSize()

◆ IsEmpty()

◆ operator=()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

Friends And Related Symbol Documentation

◆ FromStream

◆ FromString

◆ Iterator< IterTraits >

◆ ValueBuilder