formats::yaml::Value Class Reference

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

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.

Classes
struct	DefaultConstructed
struct	IterTraits

Public Types
using	const_iterator = Iterator<IterTraits>
using	Exception = formats::yaml::Exception
using	ParseException = formats::yaml::ParseException
using	ExceptionWithPath = formats::yaml::ExceptionWithPath
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 >
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().
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.

Member Typedef Documentation

Builder

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

Definition at line 48 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.

ExceptionWithPath

using formats::yaml::Value::ExceptionWithPath = formats::yaml::ExceptionWithPath

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

auto formats::yaml::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

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

As() [2/3]

template<typename T >

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

As() [3/3]

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

auto 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 298 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 61 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.

Parse JSON from stream.

FromString

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

friend

Parse YAML from string.

Definition at line 82 of file from_string.hpp.

Iterator< IterTraits >

friend class Iterator< IterTraits >

friend

Definition at line 259 of file value.hpp.

ValueBuilder

friend class ValueBuilder

friend

Definition at line 262 of file value.hpp.

---

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

• userver/formats/yaml/value.hpp