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

#include <json/encoder/Object.hpp>

Inheritance diagram for xentara::utils::json::encoder::Object:

Public Member Functions
	Object ()=delete
	This type is not user-constructible.

	~Object () noexcept(false)
	Destructor.

auto	addMember (std::string_view name) -> Value
	Adds a new generic member.

auto	close () -> void
	Writes the termination of the object, if it has not already been written.

Adding nembers with standard JSON types
auto	addObject (std::string_view name) -> Object
	Adds a JSON object as a member.

auto	addArray (std::string_view name) -> Array
	Adds a JSON array as a member.

auto	addString (std::string_view name) -> String
	Adds a string as a member.

template<std::convertible_to< std::string_view > String>
auto	add (std::string_view name, const String &value) -> void
	Adds a string as a member.

template<tools::Arithmetic Number>
auto	add (std::string_view name, Number value) -> void
	Adds a number as a member.

auto	add (std::string_view name, bool value) -> void
	Adds a Boolean value as a member.

auto	add (std::string_view name, Null value) -> void
	Adds a JSON null value as a member.

Adding members with non-JSON types
auto	add (std::string_view name, const xentara::utils::core::Uuid &uuid) -> void
	Adds a string containing a UUID as a member.

auto	add (std::string_view name, 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 a member.

auto	addDate (std::string_view name, std::chrono::sys_days date) -> void
	Adds a string containing a date as a member.

auto	addTime (std::string_view name, 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 a member.

auto	addNakedTime (std::string_view name, std::chrono::system_clock::duration time) -> void
	Adds a string containing a time with without time zone information as a member.

template<typename Units = std::chrono::microseconds>
auto	addTimeDuration (std::string_view name, std::chrono::nanoseconds timeDuration) -> void
	Adds a string containing a time duration as a member.

Detailed Description

A class used for writing a JSON object.

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

Constructor & Destructor Documentation

◆ Object()

xentara::utils::json::encoder::Object::Object ( )

delete

This type is not user-constructible.

◆ ~Object()

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

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::Object::add	(	std::string_view	name,
		bool	value
	)		-> void

Adds a Boolean value as a member.

Parameters

name	The name of the new member
value	The value of the new member

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::Object::add	(	std::string_view	name,
		const String &	value
	)		-> void

Adds a string as a member.

Parameters

name	The name of the new member
value	The value of the new member

Exceptions

std::runtime_error An error occured writing to the stream

◆ add() [3/6]

auto xentara::utils::json::encoder::Object::add	(	std::string_view	name,
		const xentara::utils::core::Uuid &	uuid
	)		-> void

Adds a string containing a UUID as a member.

Parameters

name	The name of the new member
uuid	The UUID to add

Exceptions

std::runtime_error An error occured writing to the stream

◆ add() [4/6]

auto xentara::utils::json::encoder::Object::add	(	std::string_view	name,
		Null	value
	)		-> void

Adds a JSON null value as a member.

Parameters

name	The name of the new member
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::Object::add	(	std::string_view	name,
		Number	value
	)		-> void

Adds a number as a member.

Parameters

name	The name of the new member
value	The value of the new member

Exceptions

std::runtime_error An error occured writing to the stream

◆ add() [6/6]

auto xentara::utils::json::encoder::Object::add	(	std::string_view	name,
		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 a member.

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

Parameters

name	The name of the new member
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 less than 0000 or greater than 9999.

◆ addArray()

auto xentara::utils::json::encoder::Object::addArray ( std::string_view name ) -> Array

Adds a JSON array as a member.

Parameters

name	The name of the new member

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::Object::addDate	(	std::string_view	name,
		std::chrono::sys_days	date
	)		-> void

Adds a string containing a date as a member.

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

Parameters

name	The name of the new member
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 less than 0000 or greater than 9999.

◆ addMember()

auto xentara::utils::json::encoder::Object::addMember ( std::string_view name ) -> Value

Adds a new generic member.

Parameters

name	The name of the new member

Returns: An object that must be used to write member’s value

Exceptions

std::runtime_error An error occured writing to the stream

◆ addNakedTime()

auto xentara::utils::json::encoder::Object::addNakedTime	(	std::string_view	name,
		std::chrono::system_clock::duration	time
	)		-> void

Adds a string containing a time with without time zone information as a member.

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

Parameters

name	The name of the new member
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::Object::addObject ( std::string_view name ) -> Object

Adds a JSON object as a member.

Parameters

name	The name of the new member

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::Object::addString ( std::string_view name ) -> String

Adds a string as a member.

Parameters

name	The name of the new member

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::Object::addTime	(	std::string_view	name,
		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 a member.

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

Parameters

name	The name of the new member
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::Object::addTimeDuration	(	std::string_view	name,
		std::chrono::nanoseconds	timeDuration
	)		-> void

Adds a string containing a time duration as a member.

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 3ns, for example, will be written as

"0.003µs"

if std::chrono::microseconds is specified for Units.

A time duration of 0 ns is simple written as

"0"

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

name	The name of the new member
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::Object::close ( ) -> void

Writes the termination of the object, 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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Object()

◆ ~Object()

Member Function Documentation

◆ add() [1/6]

◆ add() [2/6]

◆ add() [3/6]

◆ add() [4/6]

◆ add() [5/6]

◆ add() [6/6]

◆ addArray()

◆ addDate()

◆ addMember()

◆ addNakedTime()

◆ addObject()

◆ addString()

◆ addTime()

◆ addTimeDuration()

◆ close()