xentara-utils v2.0
The Xentara Utility Library
Loading...
Searching...
No Matches
xentara::utils::json::encoder::Value Class Referencefinal

A class used for writing a JSON value Objects of this class can be moved, but not copied. More...

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

+ Inheritance diagram for xentara::utils::json::encoder::Value:

Public Member Functions

 Value ()=delete
 This type is not user-constructible.
 
 ~Value () noexcept(false)
 Destructor.
 
Writing standard JSON types
auto asObject () -> Object
 Turns the value into a JSON object.
 
auto asArray () -> Array
 Turns the value into a JSON array.
 
auto asString () -> String
 Turns the value into a JSON string.
 
template<std::convertible_to< std::string_view > String>
auto write (const String &value) -> void
 Writes the value as a string.
 
template<tools::Arithmetic Number>
auto write (Number value) -> void
 Writes the value as a number.
 
auto write (bool value) -> void
 Writes the value as a Boolean value.
 
auto write (Null value) -> void
 Writes the value as a JSON null value.
 
Writing non-JSON types
auto write (const xentara::utils::core::Uuid &uuid) -> void
 Writes the value as string containing a UUID.
 
auto write (std::chrono::system_clock::time_point timePoint, std::chrono::minutes shownUtcOffset=std::chrono::minutes::zero()) -> void
 Writes the value as string containing a date and time.
 
auto writeDate (std::chrono::sys_days date) -> void
 Writes the value as string containing a date.
 
auto writeTime (std::chrono::system_clock::duration time, std::chrono::minutes shownUtcOffset=std::chrono::minutes::zero()) -> void
 Writes the value as string containing a time with with time zone information.
 
auto writeNakedTime (std::chrono::system_clock::duration time) -> void
 Writes the value as string containing a time with without time zone information.
 
template<typename Units = std::chrono::microseconds>
auto writeTimeDuration (std::chrono::nanoseconds timeDuration) -> void
 Writes the value as string containing a time duration.
 

Detailed Description

A class used for writing a JSON value Objects of this class can be moved, but not copied.

Constructor & Destructor Documentation

◆ Value()

xentara::utils::json::encoder::Value::Value ( )
delete

This type is not user-constructible.

◆ ~Value()

xentara::utils::json::encoder::Value::~Value ( )

Destructor.

This destructor will throw an exception if no value was written. To prevent termination of the program, no exceptions are thrown during stack windup, though.

Member Function Documentation

◆ asArray()

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

Turns the value into a JSON array.

Attention
The value object must no longer be accessed after calling this function
Returns
An object that can be used to add elements to the array
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ asObject()

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

Turns the value into a JSON object.

Attention
The value object must no longer be accessed after calling this function
Returns
An object that can be used to add members to the object
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ asString()

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

Turns the value into a JSON string.

Attention
The value object must no longer be accessed after calling this function
Returns
An object that can be used to add data to the string
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ write() [1/6]

auto xentara::utils::json::encoder::Value::write ( bool  value) -> void

Writes the value as a Boolean value.

Parameters
valueThe value to write
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ write() [2/6]

auto xentara::utils::json::encoder::Value::write ( const String value) -> void

Writes the value as a string.

Parameters
valueThe value to write
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ write() [3/6]

auto xentara::utils::json::encoder::Value::write ( const xentara::utils::core::Uuid uuid) -> void

Writes the value as string containing a UUID.

Parameters
uuidThe UUID to write
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ write() [4/6]

auto xentara::utils::json::encoder::Value::write ( Null  value) -> void

Writes the value as a JSON null value.

Parameters
valueAn arbitrary object of type xentara::utils::json::encoder::Null. You should normally just pass the constant kNull as this parameter.
Exceptions
std::runtime_errorAn error occured writing to the stream
See also
xentara::utils::json::encoder::kNull

◆ write() [5/6]

template<tools::Arithmetic Number>
auto xentara::utils::json::encoder::Value::write ( Number  value) -> void

Writes the value as a number.

Parameters
valueThe value to write
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ write() [6/6]

auto xentara::utils::json::encoder::Value::write ( std::chrono::system_clock::time_point  timePoint,
std::chrono::minutes  shownUtcOffset = std::chrono::minutes::zero() 
) -> void

Writes the value as string containing a date and time.

The string will use the date-time profile described in section 5.6 of RFC3339.

Parameters
timePointThe time point to write
shownUtcOffsetThe UTC offset to represent the time in. The UTC offset is also part of the time format, so that the original UTC time can be reconstructed. The UTC offset only influences how the time is represented in the string: timePoint must always be a regular UTC time without any offset. If you pass a time of 1 January 2001, 00:00:00.000 UTC and a UTC offset of +1 hours, the time will be written as "2001-01-01T01:00:00+01:00", for example.
Exceptions
std::runtime_errorAn error occured writing to the stream
std::overflow_errorThe value would result in a year less than 0000 or greater than 9999.

◆ writeDate()

auto xentara::utils::json::encoder::Value::writeDate ( std::chrono::sys_days  date) -> void

Writes the value as string containing a date.

The string will use the full-date profile described in section 5.6 of RFC3339.

Parameters
dateA time point representing 00:00:00 UTC on the desired date. If you have a time point representing the start of the day in a different time zone, you must manually add the corresponding UTC offset before passing it to this function.
Exceptions
std::runtime_errorAn error occured writing to the stream
std::overflow_errorThe value would result in a year less than 0000 or greater than 9999.

◆ writeNakedTime()

auto xentara::utils::json::encoder::Value::writeNakedTime ( std::chrono::system_clock::duration  time) -> void

Writes the value as string containing a time with without time zone information.

The string will use the partial-time profile described in section 5.6 of RFC3339.

Parameters
timeThe desired time as an offset from 00:00:00 in the same time zone
Exceptions
std::runtime_errorAn error occured writing to the stream
std::overflow_errorThe value would result in an hour value less than 00 or greater than 23.

◆ writeTime()

auto xentara::utils::json::encoder::Value::writeTime ( std::chrono::system_clock::duration  time,
std::chrono::minutes  shownUtcOffset = std::chrono::minutes::zero() 
) -> void

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

The string will use the full-time profile described in section 5.6 of RFC3339.

Parameters
timeThe desired time as an offset from 00:00:00 UTC
shownUtcOffsetThe UTC offset to represent the time in. The UTC offset is also part of the time format, so that the original UTC time can be reconstructed. The UTC offset only influences how the time is represented in the string: time must always be an offset from 00:00:00 UTC. If you pass a time of 0 and a UTC offset of +1 hours, the time will be written as "01:00:00+01:00", for example.
Exceptions
std::runtime_errorAn error occured writing to the stream
std::overflow_errorThe value would result in an hour value less than 00 or greater than 23.

◆ writeTimeDuration()

template<typename Units = std::chrono::microseconds>
auto xentara::utils::json::encoder::Value::writeTimeDuration ( std::chrono::nanoseconds  timeDuration) -> void

Writes the value as string containing a time duration.

The string will contain a number followed by a units string. The units are determined by the Units template parameter. The following units are supported:

Units String
std::chrono::hours h
std::chrono::minutes m
std::chrono::seconds s
std::chrono::milliseconds ms
std::chrono::microseconds µs
std::chrono::nanoseconds ns

The number can contain decimals. A value of 50µs, for example, will be written as "0.05ms" if std::chrono::milliseconds is specified for Units.

A time duration of 0 is always written as "0" (in quotes), without any units.

Template Parameters
UnitsThe units to use. Must be std::chrono::nanoseconds, std::chrono::microseconds, std::chrono::milliseconds, std::chrono::seconds, std::chrono::minutes, or std::chrono::hours.
Parameters
timeDurationThe time duration to write
Exceptions
std::runtime_errorAn error occured writing to the stream
std::range_errortimeDuration cannot be represented in the given units. This exception is only thrown for the units std::chrono::minutes and std::chrono::hours if timeDuration is not a multiple of 6 or 36 nanoseconds, respectively.