A single value in a JSON document. More...

#include <xentara/utils/json/decoder/Value.hpp>

Inheritance diagram for xentara::utils::json::decoder::Value:

Public Types
enum class	Type { Object , Array , String , Number , Boolean , Null , Defunct , MovedAway }
	JSON types. More...

Public Member Functions
	Value () noexcept=default
	Constructor for a null value.

auto	skip () -> void
	Skips the value.

auto	document () const -> const Document *
	Gets the JSON document that the value belongs to.

auto	lineNumber () const -> std::uint_least32_t
	Gets the line number in the JSON document that the value is on.

auto	location () const -> Location
	Gets the location of the value within its JSON document.

template<>
auto	asString () -> String

Accessing the value type
auto	getType () const noexcept -> Type
	gets the type of the object

auto	isObject () const noexcept -> bool
	Determines if the value is an object.

auto	isArray () const noexcept -> bool
	Determines if the value is an array.

auto	isString () const noexcept -> bool
	Determines if the value is a string.

auto	isNumber () const noexcept -> bool
	Determines if the value is a number.

auto	isBoolean () const noexcept -> bool
	Determines if the value is a Boolean value.

auto	isNull () const noexcept -> bool
	Determines if the value is a null value.

Getting the value as a standard JSON type
auto	asObject () -> Object
	Interprets the value as a JSON object.

auto	asArray () -> Array
	Interprets the value as a JSON array.

template<std::same_as< String > >
auto	asString () -> String
	Interprets the value as a string.

template<tools::StringType StdString>
auto	asString (const typename StdString::allocator_type &allocator=typename StdString::allocator_type()) -> StdString
	Reads the value as an std::basic_string.

template<tools::Arithmetic Number>
auto	asNumber () -> Number
	Reads the value as a number.

template<std::same_as< Number > >
auto	asNumber () -> Number
	Reads the value as a generic number.

auto	asBoolean () -> bool
	Reads the value as a Boolean value.

Getting the value as non-JSON type
auto	toUuid () -> core::Uuid
	Reads the value as a string containing a UUID.

auto	toDateTime () -> std::chrono::system_clock::time_point
	Reads the value as a string containing a date and time.

auto	toDate () -> std::chrono::sys_days
	Reads the value as a string containing a date.

auto	toTime () -> std::chrono::system_clock::duration
	Reads the value as a string containing a time with time zone information.

auto	toNakedTime () -> std::chrono::system_clock::duration
	Reads the value as a string containing a time without time zone information.

template<typename Duration = std::chrono::nanoseconds>
auto	toTimeDuration () -> Duration
	Reads the value as a string containing a duration.

template<typename Duration = std::chrono::nanoseconds>
auto	toTimeDuration (AllowLegacyMicrosecondsTag) -> Duration
	Reads the value as a string containing a duration, or as a number containing microseconds.

Detailed Description

A single value in a JSON document.

This object lazily reads the data from the document when you call one of the conversion functions (asObject(), asArray(), asString(), asNumber(), or asBoolean()). This means that you must call one and only one of these function exactly once. The only exception are JSON null values. For null values, there is no conversion function, and you do not need to call any function.

If you are not interested in the value, you can also call skip() to skip the entire value. In that case, you must not call any of the conversion functions.

JSON values can be moved but not copied

Member Enumeration Documentation

◆ Type

enum class xentara::utils::json::decoder::Value::Type

strong

JSON types.

Enumerator
Object	A JSON object.
Array	A JSON array.
String	A JSON string.
Number	A JSON number.
Boolean	A JSON Boolean.
Null	A JSON null value.
Defunct	Special value for values that have already been parsed.
MovedAway	Special value for values that have been moved away using the move constructor or move assignment operator.

Constructor & Destructor Documentation

◆ Value()

xentara::utils::json::decoder::Value::Value ( )

defaultnoexcept

Constructor for a null value.

Member Function Documentation

◆ asArray()

auto xentara::utils::json::decoder::Value::asArray ( ) -> Array

Interprets the value as a JSON array.

This method does not return the actual array, but rather an accessor that allows reading the elements one by one.

Returns: An accessor than can be used to read the array elements

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON array, but another type
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ asBoolean()

auto xentara::utils::json::decoder::Value::asBoolean ( ) -> bool

Reads the value as a Boolean value.

Returns: The value as a Boolean value

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON Boolean value, but another type
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ asNumber() [1/2]

template<tools::Arithmetic Number>

auto xentara::utils::json::decoder::Value::asNumber ( ) -> Number

Reads the value as a number.

Returns: The value as a number

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON number, but another type
std::range_error	The number contained in the value cannot be represented by the given type
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ asNumber() [2/2]

template<std::same_as< Number > >

template auto xentara::utils::json::decoder::Value::asNumber< Number > ( ) -> Number

Reads the value as a generic number.

Returns: The value as a number

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON number, but another type
std::range_error	The number contained in the value cannot be represented by the given type
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ asObject()

auto xentara::utils::json::decoder::Value::asObject ( ) -> Object

Interprets the value as a JSON object.

This method does not return the actual object, but rather an accessor that allows reading the members one by one.

Returns: An accessor than can be used to read the object's members

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON object, but another type
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ asString() [1/3]

template<std::same_as< String > >

auto xentara::utils::json::decoder::Value::asString ( ) -> String

Interprets the value as a string.

This method does not return the actual string, but rather an accessor that allows reading the characters one by one.

Returns: An accessor than can be used to read the string

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ asString() [2/3]

template<>

auto xentara::utils::json::decoder::Value::asString ( ) -> String

◆ asString() [3/3]

template<tools::StringType StdString>

auto xentara::utils::json::decoder::Value::asString ( const typename StdString::allocator_type & allocator = typename StdString::allocator_type() ) -> StdString

Reads the value as an std::basic_string.

Parameters

allocator The allocator for the returned string

Returns: The value as a string, in UTF-8, UTF-16, or UTF-32 encoding.

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ document()

auto xentara::utils::json::decoder::Value::document ( ) const -> const Document *

Gets the JSON document that the value belongs to.

Returns: The document, or nullptr for a default constructed object

◆ getType()

auto xentara::utils::json::decoder::Value::getType ( ) const -> Type

noexcept

gets the type of the object

Returns: Returns the value type

◆ isArray()

auto xentara::utils::json::decoder::Value::isArray ( ) const -> bool

noexcept

Determines if the value is an array.

Returns: Returns true if the value is a JSON array

◆ isBoolean()

auto xentara::utils::json::decoder::Value::isBoolean ( ) const -> bool

noexcept

Determines if the value is a Boolean value.

Returns: Returns true if the value is true or false

◆ isNull()

auto xentara::utils::json::decoder::Value::isNull ( ) const -> bool

noexcept

Determines if the value is a null value.

Returns: Returns true if the value is null

◆ isNumber()

auto xentara::utils::json::decoder::Value::isNumber ( ) const -> bool

noexcept

Determines if the value is a number.

Returns: Returns true if the value is a number

◆ isObject()

auto xentara::utils::json::decoder::Value::isObject ( ) const -> bool

noexcept

Determines if the value is an object.

Returns: Returns true if the value is a JSON object

◆ isString()

auto xentara::utils::json::decoder::Value::isString ( ) const -> bool

noexcept

Determines if the value is a string.

Returns: Returns true if the value is a string

◆ lineNumber()

auto xentara::utils::json::decoder::Value::lineNumber ( ) const -> std::uint_least32_t

Gets the line number in the JSON document that the value is on.

Returns: The line number, or 0 for a default constructed object

◆ location()

auto xentara::utils::json::decoder::Value::location ( ) const -> Location

Gets the location of the value within its JSON document.

Returns: The location of the value within the JSON document, or a default constructed location for a default constructed object

◆ skip()

auto xentara::utils::json::decoder::Value::skip ( ) -> void

Skips the value.

Exceptions

SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ toDate()

auto xentara::utils::json::decoder::Value::toDate ( ) -> std::chrono::sys_days

Reads the value as a string containing a date.

The string must conform to the full-date profile described in section 5.6 of RFC3339.

Returns: A time point representing 00:00:00 UTC on the parsed date. If you need the start of the day in a different time zone, you must manually subtract the corresponding UTC offset.

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
std::runtime_error	The string contained in the value is not a valid RFC3339 full-date string.
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ toDateTime()

auto xentara::utils::json::decoder::Value::toDateTime ( ) -> std::chrono::system_clock::time_point

Reads the value as a string containing a date and time.

The string must conform to the date-time profile described in section 5.6 of RFC3339.

Returns: A time point representing the parsed time and date

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
std::runtime_error	The string contained in the value is not a valid RFC3339 date-time string.
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ toNakedTime()

auto xentara::utils::json::decoder::Value::toNakedTime ( ) -> std::chrono::system_clock::duration

Reads the value as a string containing a time without time zone information.

The string must conform to the partial-time profile described in section 5.6 of RFC3339.

Returns: The parsed time as an offset from 00:00:00 in the same time zone

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
std::runtime_error	The string contained in the value is not a valid RFC3339 partial-time string.
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ toTime()

auto xentara::utils::json::decoder::Value::toTime ( ) -> std::chrono::system_clock::duration

Reads the value as a string containing a time with time zone information.

The string must conform to the full-time profile described in section 5.6 of RFC3339.

Returns: The parsed time as an offset from 00:00:00 UTC

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
std::runtime_error	The string contained in the value is not a valid RFC3339 full-time string.
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ toTimeDuration() [1/2]

template<typename Duration >

auto xentara::utils::json::decoder::Value::toTimeDuration ( ) -> Duration

Reads the value as a string containing a duration.

The string must contain a number, followed by the time units. The number can contain decimals.

The supported units are:

String	Units
ns	nanoseconds
ms	milliseconds
µs (or us)	microseconds
s	second
m	minutes
h	hours

A value of 50µs can be represented by the strings "50µs", "0.05ms", or "0.00005s", for example.

If the time span is 0, then the string need not contain units. A time stamp of 0 simply be represented by the string "0" (in quotes).

Template Parameters

Duration The type of duration to parse. Must be a specialization of std::chrono::duration. If Duration::rep is an integral type, then the duration must be a multiple of nanoseconds.

Returns: The parsed duration

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
std::runtime_error	The string contained in the value is not a valid duration string.
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ toTimeDuration() [2/2]

template<typename Duration >

auto xentara::utils::json::decoder::Value::toTimeDuration ( AllowLegacyMicrosecondsTag ) -> Duration

Reads the value as a string containing a duration, or as a number containing microseconds.

This overload can be used to read a time duration in the format of the normal toTimeDuration(), but also allow a JSON number representing a number of microseconds for backward compatibility.

Template Parameters

Duration The type of duration to parse. Must be a specialization of std::chrono::duration. If Duration::rep is an integral type, then the duration must be a multiple of nanoseconds.

Returns: The parsed duration

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string or a JSON number, but another type
std::runtime_error	The string contained in the value is not a valid duration string.
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

◆ toUuid()

auto xentara::utils::json::decoder::Value::toUuid ( ) -> core::Uuid

Reads the value as a string containing a UUID.

Returns: The parsed UUID

Exceptions

NullValueError	The value is null
TypeMismatchError	The value is not a JSON string, but another type
std::runtime_error	The string contained in the value is not a valid UUID text representation
SyntaxError	The stream does not contain a valid JSON element
std::runtime_error	An error occurred reading from the stream

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ Value()

Member Function Documentation

◆ asArray()

◆ asBoolean()

◆ asNumber() [1/2]

◆ asNumber() [2/2]

◆ asObject()

◆ asString() [1/3]

◆ asString() [2/3]

◆ asString() [3/3]

◆ document()

◆ getType()

◆ isArray()

◆ isBoolean()

◆ isNull()

◆ isNumber()

◆ isObject()

◆ isString()

◆ lineNumber()

◆ location()

◆ skip()

◆ toDate()

◆ toDateTime()

◆ toNakedTime()

◆ toTime()

◆ toTimeDuration() [1/2]

◆ toTimeDuration() [2/2]

◆ toUuid()