xentara::utils::json::encoder::Array Class Reference

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_error

An 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

value

The value of the new element

Exceptions

std::runtime_error

An error occured writing to the stream

add() [2/6]

template<std::convertible_to< std::string_view > String>

auto xentara::utils::json::encoder::Array::add

(

const String &

value

)

-> void

Adds a string as an element.

Parameters

value

The value of the new element

Exceptions

std::runtime_error

An 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

uuid	The UUID to add

Exceptions

std::runtime_error

An 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

value

An arbitrary object of type xentara::utils::json::encoder::Null. You should normally just pass the constant kNull as this parameter.

Exceptions

std::runtime_error

An 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

value

The value of the new element

Exceptions

std::runtime_error

An 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

timePoint

The time point to add

shownUtcOffset

The 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_error	An error occured writing to the stream
std::overflow_error	The 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_error

An 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

date	A 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_error	An error occured writing to the stream
std::overflow_error	The 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_error

An 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

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

Exceptions

std::runtime_error	An error occured writing to the stream
std::overflow_error	The 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_error

An 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_error

An 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

time	The desired time as an offset from 00:00:00 UTC
shownUtcOffset	The 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_error	An error occured writing to the stream
std::overflow_error	The 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

Units

The 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

timeDuration

The time duration to write

Exceptions

std::runtime_error	An error occured writing to the stream
std::range_error	timeDuration 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_error

An error occured writing to the stream