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

A class used for writing a JSON array. More...

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

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

Public Member Functions

 Array ()=delete
 This type is not user-constructible.
 
 ~Array () noexcept(false)
 Destructor.
 
auto addElement () -> Value
 Adds a new generic element.
 
auto close () -> void
 Writes the termination of the array, if it has not already been written.
 
Adding elements with standard JSON types
auto addObject () -> Object
 Adds a JSON object as an element.
 
auto addArray () -> Array
 Adds a JSON array as an element.
 
auto addString () -> String
 Adds a string as an element.
 
template<std::convertible_to< std::string_view > String>
auto add (const String &value) -> void
 Adds a string as an element.
 
template<tools::Arithmetic Number>
auto add (Number value) -> void
 Adds a number as an element.
 
auto add (bool value) -> void
 Adds a Boolean value as an element.
 
auto add (Null value) -> void
 Adds a JSON null value as an element.
 
Adding elements with non-JSON types
auto add (const xentara::utils::core::Uuid &uuid) -> void
 Adds a string containing a UUID as an element.
 
auto add (std::chrono::system_clock::time_point timePoint, std::chrono::minutes shownUtcOffset=std::chrono::minutes::zero()) -> void
 Adds a string containing a date and time as an element.
 
auto addDate (std::chrono::sys_days date) -> void
 Adds a string containing a date as an element.
 
auto addTime (std::chrono::system_clock::duration time, std::chrono::minutes shownUtcOffset=std::chrono::minutes::zero()) -> void
 Adds a string containing a time with with time zone information as an element.
 
auto addNakedTime (std::chrono::system_clock::duration time) -> void
 Adds a string containing a time with without time zone information as an element.
 
template<typename Units = std::chrono::microseconds>
auto addTimeDuration (std::chrono::nanoseconds timeDuration) -> void
 Adds a string containing a time duration as an element.
 

Detailed Description

A class used for writing a JSON array.

Objects of this class can be moved, but not copied.

Constructor & Destructor Documentation

◆ Array()

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

This type is not user-constructible.

◆ ~Array()

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

Destructor.

This destructor writes the termination, if it has not already been written.

This destructor will throw an exception if the termination cannot be written. To prevent termination of the program, no exceptions are thrown during stack windup, though. You can prevent the destructor from throwing any exceptions by closing the objects manually beforehand using close().

Exceptions
std::runtime_errorAn error occured writing to the stream

Member Function Documentation

◆ add() [1/6]

auto xentara::utils::json::encoder::Array::add ( bool  value) -> void

Adds a Boolean value as an element.

Parameters
valueThe value of the new element
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ add() [2/6]

auto xentara::utils::json::encoder::Array::add ( const String value) -> void

Adds a string as an element.

Parameters
valueThe value of the new element
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ add() [3/6]

auto xentara::utils::json::encoder::Array::add ( const xentara::utils::core::Uuid uuid) -> void

Adds a string containing a UUID as an element.

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

◆ add() [4/6]

auto xentara::utils::json::encoder::Array::add ( Null  value) -> void

Adds a JSON null value as an element.

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

◆ add() [5/6]

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

Adds a number as an element.

Parameters
valueThe value of the new element
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ add() [6/6]

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

Adds a string containing a date and time as an element.

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

Parameters
timePointThe time point to add
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 value less than 0000 or greater than 9999.

◆ addArray()

auto xentara::utils::json::encoder::Array::addArray ( ) -> Array

Adds a JSON array as an element.

Returns
An object that can be used to add elements to the array
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ addDate()

auto xentara::utils::json::encoder::Array::addDate ( std::chrono::sys_days  date) -> void

Adds a string containing a date as an element.

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 value less than 0000 or greater than 9999.

◆ addElement()

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

Adds a new generic element.

Returns
An object that must be used to write element’s value
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ addNakedTime()

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

Adds a string containing a time with without time zone information as an element.

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.

◆ addObject()

auto xentara::utils::json::encoder::Array::addObject ( ) -> Object

Adds a JSON object as an element.

Returns
An object that can be used to add members to the object
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ addString()

auto xentara::utils::json::encoder::Array::addString ( ) -> String

Adds a string as an element.

Returns
An object that can be used to add data to the string
Exceptions
std::runtime_errorAn error occured writing to the stream

◆ addTime()

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

Adds a string containing a time with with time zone information as an element.

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.

◆ addTimeDuration()

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

Adds a string containing a time duration as an element.

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.

◆ close()

auto xentara::utils::json::encoder::Array::close ( ) -> void

Writes the termination of the array, if it has not already been written.

Note
This function can be safely called on objects that have been moved away using the move constructor or move assignment operator.
Exceptions
std::runtime_errorAn error occured writing to the stream