Abstract base class of a JSON value. More...

#include <tsjsonValue.h>

Inheritance diagram for ts::json::Value:

[legend]

Public Member Functions
constexpr	Value ()=default
	Default constructor.

void	add (const UString &name, const UString &value)
	Add a string field into an object.

void	add (const UString &name, const ValuePtr &value)
	Add a field into an object.

template<typename T > requires std::integral<T>
void	add (const UString &name, T value)
	Add an integer number field into an object.

template<typename T > requires std::floating_point<T>
void	add (const UString &name, T value)
	Add a floating-point number field into an object.

virtual Value &	at (size_t index)
	Get an element of an array (modifiable version).

virtual const Value &	at (size_t index) const
	Get an element of an array (const version).

virtual void	clear ()
	Clear the content of the value;.

virtual void	erase (size_t index, size_t count=1)
	Erase elements from an array.

virtual ValuePtr	extract (const UString &name)
	Extract a field from an object.

virtual ValuePtr	extractAt (size_t index)
	Extract an element from an array.

virtual void	getNames (UStringList &names) const
	Get all field names in an object.

virtual bool	isArray () const
	Check if this instance is a JSON array.

virtual bool	isFalse () const
	Check if this instance is a JSON false literal.

virtual bool	isInteger () const
	Check if this instance is a JSON number and an integer value (an integral value).

virtual bool	isNull () const
	Check if this instance is a JSON null literal.

virtual bool	isNumber () const
	Check if this instance is a JSON number.

virtual bool	isObject () const
	Check if this instance is a JSON object.

virtual bool	isString () const
	Check if this instance is a JSON string.

virtual bool	isTrue () const
	Check if this instance is a JSON true literal.

virtual UString	oneLiner (Report &report=(ts::NullReport::Instance())) const
	Format the value as a one-liner JSON text.

virtual void	print (TextFormatter &output) const =0
	Format the value as JSON text.

virtual UString	printed (size_t indent=2, Report &report=(ts::NullReport::Instance())) const
	Format the value as structured JSON text.

virtual const Value &	query (const UString &path) const
	Query a JSON value using a composite path.

virtual Value &	query (const UString &path, bool create=false, Type type=Type::Object)
	Query a JSON value using a composite path, creating intermediate objects when necessary.

virtual void	remove (const UString &name)
	Remove a field from an object.

virtual bool	save (const fs::path &fileName, size_t indent=2, bool stdOutputIfEmpty=false, Report &report=(ts::NullReport::Instance()))
	Save the value as a JSON file.

size_t	set (const UString &value, size_t index=std::numeric_limits< size_t >::max())
	Set a string element of an array.

size_t	set (const ValuePtr &value, size_t index=std::numeric_limits< size_t >::max())
	Set an element of an array.

template<typename T > requires std::integral<T>
size_t	set (T value, size_t index=std::numeric_limits< size_t >::max())
	Set an integer number element of an array.

template<typename T > requires std::floating_point<T>
size_t	set (T value, size_t index=std::numeric_limits< size_t >::max())
	Set a floating-point number element of an array.

virtual size_t	size () const
	Get the "size" of the value.

virtual bool	toBoolean (bool defaultValue=false) const
	Convert this instance to a boolean.

virtual double	toFloat (double defaultValue=0.0) const
	Convert this instance to a double-precision float.

virtual int64_t	toInteger (int64_t defaultValue=0) const
	Convert this instance to an integer.

virtual UString	toString (const UString &defaultValue=UString()) const
	Convert this instance to a string.

virtual Type	type () const =0
	Get the JSON value type.

virtual const Value &	value (const UString &name) const
	Get the value of an object field (const version).

virtual Value &	value (const UString &name, bool create=false, Type type=Type::Object)
	Get the value of an object field (modifiable version).

virtual ValuePtr	valuePtr (const UString &name)
	Get the value of an object field (pointer version).

Protected Member Functions
virtual void	addFloat (const UString &name, double value)
	Add a double-precision floating-point number field into an object.

virtual void	addInteger (const UString &name, int64_t value)
	Add a 64-bit signed integer number field into an object.

virtual void	addString (const UString &name, const UString &value)
	Add a string field into an object.

virtual void	addValue (const UString &name, const ValuePtr &value)
	Add a field into an object.

virtual size_t	setFloat (double value, size_t index)
	Set a double-precision floating-point number element of an array.

virtual size_t	setInteger (int64_t value, size_t index)
	Set a 64-bit signed integer number element of an array.

virtual size_t	setString (const UString &value, size_t index)
	Set a string element of an array.

virtual size_t	setValue (const ValuePtr &value, size_t index)
	Set an element of an array.

Detailed Description

Abstract base class of a JSON value.

A JSON document is composed of one value (usually of type "object" or "array"). JSON is defined by RFC 8259.

This implementation is simple and basic.

Fetching a non-existent element, field or whatever always fails silently by returning a reference to a "null" value. Thus, it is possible to access a complex chain of references without caring about intermediate errors. At the end, a "null" value will be returned.

Floating-point values are not yet implemented. Reading a number always give a null object.

See also: http://json.org/; https://tools.ietf.org/html/rfc8259

Member Function Documentation

◆ type()

virtual Type ts::json::Value::type ( ) const

pure virtual

Get the JSON value type.

Returns: The JSON value type.

Implemented in ts::json::Array, ts::json::False, ts::json::Null, ts::json::Number, ts::json::Object, ts::json::String, and ts::json::True.

◆ print()

virtual void ts::json::Value::print ( TextFormatter & output ) const

pure virtual

Format the value as JSON text.

Parameters

[in,out] output The output object to format.

Implemented in ts::json::Array, ts::json::False, ts::json::Null, ts::json::Number, ts::json::Object, ts::json::String, and ts::json::True.

◆ printed()

virtual UString ts::json::Value::printed	(	size_t	indent = `2`,
		Report &	report = `(ts::NullReport::Instance())`
	)		const

virtual

Format the value as structured JSON text.

Parameters

[in]	indent	Indentation width of each level.
[in,out]	report	Where to report errors.

Returns: The formatted JSON text.

◆ oneLiner()

virtual UString ts::json::Value::oneLiner ( Report & report = (ts::NullReport::Instance()) ) const

virtual

Format the value as a one-liner JSON text.

Parameters

[in,out] report Where to report errors.

Returns: The formatted one-line JSON text.

◆ save()

virtual bool ts::json::Value::save	(	const fs::path &	fileName,
		size_t	indent = `2`,
		bool	stdOutputIfEmpty = `false`,
		Report &	report = `(ts::NullReport::Instance())`
	)

virtual

Save the value as a JSON file.

Parameters

[in]	fileName	Name of the JSON file to save.
[in]	indent	Indentation width of each level.
[in]	stdOutputIfEmpty	If true and if fileName is empty or "-", writes to the standard output.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ isNull()

virtual bool ts::json::Value::isNull ( ) const

virtual

Check if this instance is a JSON null literal.

Returns: True if this instance is a JSON null literal.

Reimplemented in ts::json::Null.

◆ isTrue()

virtual bool ts::json::Value::isTrue ( ) const

virtual

Check if this instance is a JSON true literal.

Returns: True if this instance is a JSON true literal.

Reimplemented in ts::json::True.

◆ isFalse()

virtual bool ts::json::Value::isFalse ( ) const

virtual

Check if this instance is a JSON false literal.

Returns: True if this instance is a JSON false literal.

Reimplemented in ts::json::False.

◆ isNumber()

virtual bool ts::json::Value::isNumber ( ) const

virtual

Check if this instance is a JSON number.

Returns: True if this instance is a JSON number.

Reimplemented in ts::json::Number.

◆ isInteger()

virtual bool ts::json::Value::isInteger ( ) const

virtual

Check if this instance is a JSON number and an integer value (an integral value).

Returns: True if this instance is a JSON number and an integer value.

Reimplemented in ts::json::Number.

◆ isString()

virtual bool ts::json::Value::isString ( ) const

virtual

Check if this instance is a JSON string.

Returns: True if this instance is a JSON string.

Reimplemented in ts::json::String.

◆ isObject()

virtual bool ts::json::Value::isObject ( ) const

virtual

Check if this instance is a JSON object.

Returns: True if this instance is a JSON object.

Reimplemented in ts::json::Object.

◆ isArray()

virtual bool ts::json::Value::isArray ( ) const

virtual

Check if this instance is a JSON array.

Returns: True if this instance is a JSON array.

Reimplemented in ts::json::Array.

◆ toBoolean()

virtual bool ts::json::Value::toBoolean ( bool defaultValue = false ) const

virtual

Convert this instance to a boolean.

Parameters

[in] defaultValue Default value to return when no conversion is possible.

Returns: The boolean value of this instance or defaultValue if no conversion is possible. For numbers, zero is false, all other values are true. For string, "yes", "true", "on" and non-zero integers are true; "no", "false", "off" and zero integers are false.

Reimplemented in ts::json::False, ts::json::Number, ts::json::String, and ts::json::True.

◆ toInteger()

virtual int64_t ts::json::Value::toInteger ( int64_t defaultValue = 0 ) const

virtual

Convert this instance to an integer.

Parameters

[in] defaultValue Default value to return when no conversion is possible.

Returns: The integer value of this instance or defaultValue if no conversion is possible. Strings containing integers are converted.

Reimplemented in ts::json::False, ts::json::Number, ts::json::String, and ts::json::True.

◆ toFloat()

virtual double ts::json::Value::toFloat ( double defaultValue = 0.0 ) const

virtual

Convert this instance to a double-precision float.

Parameters

[in] defaultValue Default value to return when no conversion is possible.

Returns: The floating-point value of this instance or defaultValue if no conversion is possible. Strings containing floats are converted.

Reimplemented in ts::json::False, ts::json::Number, ts::json::String, and ts::json::True.

◆ toString()

virtual UString ts::json::Value::toString ( const UString & defaultValue = UString() ) const

virtual

Convert this instance to a string.

Parameters

[in] defaultValue Default value to return when no conversion is possible.

Returns: The string value of this instance or defaultValue if no conversion is possible.

Reimplemented in ts::json::False, ts::json::Number, ts::json::String, and ts::json::True.

◆ clear()

virtual void ts::json::Value::clear ( )

virtual

Clear the content of the value;.

Reimplemented in ts::json::Array, ts::json::Number, ts::json::Object, and ts::json::String.

◆ size()

virtual size_t ts::json::Value::size ( ) const

virtual

Get the "size" of the value.

Returns: The size of the value: the number of characters for strings, of fields for objects, of elements for arrays, zero for other types.

Reimplemented in ts::json::Array, ts::json::Object, and ts::json::String.

◆ getNames()

virtual void ts::json::Value::getNames ( UStringList & names ) const

virtual

Get all field names in an object.

Parameters

[out] names Receive the list of field names.

Reimplemented in ts::json::Object.

◆ value() [1/2]

virtual const Value & ts::json::Value::value ( const UString & name ) const

virtual

Get the value of an object field (const version).

Parameters

[in] name Field name.

Returns: For a JSON object, return a constant reference to the given element. When the field does not exist or for other types of JSON values, return a reference to a null JSON.

Reimplemented in ts::json::Object.

◆ value() [2/2]

virtual Value & ts::json::Value::value	(	const UString &	name,
		bool	create = `false`,
		Type	type = `Type::Object`
	)

virtual

Get the value of an object field (modifiable version).

Parameters

[in]	name	Field name.
[in]	create	If true and the field does not exist, create it.
[in]	type	When the field is created, provide the object type.

Returns: For a JSON object, return a reference to the given element. When the field does not exist or for other types of JSON values, return a reference to a null JSON.

Reimplemented in ts::json::Object.

◆ valuePtr()

virtual ValuePtr ts::json::Value::valuePtr ( const UString & name )

virtual

Get the value of an object field (pointer version).

Must be a non-const object since we can potentially modify the field.

Parameters

[in] name Field name.

Returns: For a JSON object, return a safe pointer to the given element. When the field does not exist or for other types of JSON values, return a null pointer.

Reimplemented in ts::json::Object.

◆ remove()

virtual void ts::json::Value::remove ( const UString & name )

virtual

Remove a field from an object.

Parameters

[in] name Field name.

Reimplemented in ts::json::Object.

◆ extract()

virtual ValuePtr ts::json::Value::extract ( const UString & name )

virtual

Extract a field from an object.

The field is removed but its previous content is returned.

Parameters

[in] name Field name.

Returns: A smart pointer to the extracted content or a null pointer if the field does not exist.

Reimplemented in ts::json::Object.

◆ add() [1/4]

void ts::json::Value::add	(	const UString &	name,
		const ValuePtr &	value
	)

inline

Add a field into an object.

Parameters

[in]	name	Field name.
[in]	value	Smart pointer to a JSON value. The pointed object is shared.

◆ add() [2/4]

template<typename T >
requires std::integral<T>

void ts::json::Value::add	(	const UString &	name,
		T	value
	)

inline

Add an integer number field into an object.

Template Parameters

T	An integer type.

Parameters

[in]	name	Field name.
[in]	value	Field value.

◆ add() [3/4]

template<typename T >
requires std::floating_point<T>

void ts::json::Value::add	(	const UString &	name,
		T	value
	)

inline

Add a floating-point number field into an object.

Template Parameters

T	A floating-point type.

Parameters

[in]	name	Field name.
[in]	value	Field value.

◆ add() [4/4]

void ts::json::Value::add	(	const UString &	name,
		const UString &	value
	)

inline

Add a string field into an object.

Parameters

[in]	name	Field name.
[in]	value	Field value.

◆ at() [1/2]

virtual const Value & ts::json::Value::at ( size_t index ) const

virtual

Get an element of an array (const version).

Parameters

[in] index Index to fetch in the array.

Returns: For a JSON array, return a constant reference to the given element. When out of bound or for other types of JSON values, return a reference to a null JSON.

Reimplemented in ts::json::Array.

◆ at() [2/2]

virtual Value & ts::json::Value::at ( size_t index )

virtual

Get an element of an array (modifiable version).

Parameters

[in] index Index to fetch in the array.

Returns: For a JSON array, return a reference to the given element. When out of bound or for other types of JSON values, return a reference to a null JSON.

Reimplemented in ts::json::Array.

◆ set() [1/4]

size_t ts::json::Value::set	(	const ValuePtr &	value,
		size_t	index = `std::numeric_limits<size_t>::max()`
	)

inline

Set an element of an array.

Parameters

[in]	value	Smart pointer to a JSON value. The pointed object is shared.
[in]	index	Index to fetch in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

◆ set() [2/4]

template<typename T >
requires std::integral<T>

size_t ts::json::Value::set	(	T	value,
		size_t	index = `std::numeric_limits<size_t>::max()`
	)

inline

Set an integer number element of an array.

Template Parameters

T	An integer type.

Parameters

[in]	value	Value to set.
[in]	index	Index in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

◆ set() [3/4]

template<typename T >
requires std::floating_point<T>

size_t ts::json::Value::set	(	T	value,
		size_t	index = `std::numeric_limits<size_t>::max()`
	)

inline

Set a floating-point number element of an array.

Template Parameters

T	A floating-point type.

Parameters

[in]	value	Value to set.
[in]	index	Index in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

◆ set() [4/4]

size_t ts::json::Value::set	(	const UString &	value,
		size_t	index = `std::numeric_limits<size_t>::max()`
	)

inline

Set a string element of an array.

Parameters

[in]	value	Value to set.
[in]	index	Index in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

◆ erase()

virtual void ts::json::Value::erase	(	size_t	index,
		size_t	count = `1`
	)

virtual

Erase elements from an array.

Parameters

[in]	index	Index to erase in the array. Ignored if out of bound.
[in]	count	Number of elements to erase.

Reimplemented in ts::json::Array.

◆ extractAt()

virtual ValuePtr ts::json::Value::extractAt ( size_t index )

virtual

Extract an element from an array.

The element is removed but its previous content is returned.

Parameters

[in] index Index to erase in the array. Ignored if out of bound.

Returns: A smart pointer to the extracted content or a null pointer if the element does not exist.

Reimplemented in ts::json::Array.

◆ query() [1/2]

virtual const Value & ts::json::Value::query ( const UString & path ) const

virtual

Query a JSON value using a composite path.

Parameters

[in] path Full path from this object to final object. May contain object field names and array indexes. Example: "obj1.arr[3].obj2". If this object is an array, the path must start with a index (example: "[3].obj2"). If the path is empty, this object is returned.

Returns: A reference to the final object or a reference to a null JSON if not found.

Reimplemented in ts::json::Array, and ts::json::Object.

◆ query() [2/2]

virtual Value & ts::json::Value::query	(	const UString &	path,
		bool	create = `false`,
		Type	type = `Type::Object`
	)

virtual

Query a JSON value using a composite path, creating intermediate objects when necessary.

Parameters

[in]	path	Full path from this object to final object. May contain object field names and array indexes. Example: "obj1.arr[3].obj2". If this object is an array, the path must start with a index (example: "[3].obj2"). When an array index is empty and create is true, a new element is created at the end of the array (example: "obj1.arr[].obj2"). If the path is empty, this object is returned.
[in]	create	If true create all missing intermediate objects.
[in]	type	When the final field is created, provide the object type.

Returns: A reference to the final object. When the field does not exist or could not be created, return a reference to a null JSON.

Reimplemented in ts::json::Array, and ts::json::Object.

◆ addValue()

virtual void ts::json::Value::addValue	(	const UString &	name,
		const ValuePtr &	value
	)

protectedvirtual

Add a field into an object.

Parameters

[in]	name	Field name.
[in]	value	Smart pointer to a JSON value. The pointed object is shared.

Reimplemented in ts::json::Object.

◆ addInteger()

virtual void ts::json::Value::addInteger	(	const UString &	name,
		int64_t	value
	)

protectedvirtual

Add a 64-bit signed integer number field into an object.

Parameters

[in]	name	Field name.
[in]	value	Field value.

Reimplemented in ts::json::Object.

◆ addFloat()

virtual void ts::json::Value::addFloat	(	const UString &	name,
		double	value
	)

protectedvirtual

Add a double-precision floating-point number field into an object.

Parameters

[in]	name	Field name.
[in]	value	Field value.

Reimplemented in ts::json::Object.

◆ addString()

virtual void ts::json::Value::addString	(	const UString &	name,
		const UString &	value
	)

protectedvirtual

Add a string field into an object.

Parameters

[in]	name	Field name.
[in]	value	Field value.

Reimplemented in ts::json::Object.

◆ setValue()

virtual size_t ts::json::Value::setValue	(	const ValuePtr &	value,
		size_t	index
	)

protectedvirtual

Set an element of an array.

Parameters

[in]	value	Smart pointer to a JSON value. The pointed object is shared.
[in]	index	Index to fetch in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

Reimplemented in ts::json::Array.

◆ setInteger()

virtual size_t ts::json::Value::setInteger	(	int64_t	value,
		size_t	index
	)

protectedvirtual

Set a 64-bit signed integer number element of an array.

Parameters

[in]	value	Value to set.
[in]	index	Index in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

Reimplemented in ts::json::Array.

◆ setFloat()

virtual size_t ts::json::Value::setFloat	(	double	value,
		size_t	index
	)

protectedvirtual

Set a double-precision floating-point number element of an array.

Parameters

[in]	value	Value to set.
[in]	index	Index in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

Reimplemented in ts::json::Array.

◆ setString()

virtual size_t ts::json::Value::setString	(	const UString &	value,
		size_t	index
	)

protectedvirtual

Set a string element of an array.

Parameters

[in]	value	Value to set.
[in]	index	Index in the array. If out of bound, the value is added at the end of the array.

Returns: The actual index of the added value.

Reimplemented in ts::json::Array.

The documentation for this class was generated from the following file:

tsjsonValue.h

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ type()

◆ print()

◆ printed()

◆ oneLiner()

◆ save()

◆ isNull()

◆ isTrue()

◆ isFalse()

◆ isNumber()

◆ isInteger()

◆ isString()

◆ isObject()

◆ isArray()

◆ toBoolean()

◆ toInteger()

◆ toFloat()

◆ toString()

◆ clear()

◆ size()

◆ getNames()

◆ value() [1/2]

◆ value() [2/2]

◆ valuePtr()

◆ remove()

◆ extract()

◆ add() [1/4]

◆ add() [2/4]

◆ add() [3/4]

◆ add() [4/4]

◆ at() [1/2]

◆ at() [2/2]

◆ set() [1/4]

◆ set() [2/4]

◆ set() [3/4]

◆ set() [4/4]

◆ erase()

◆ extractAt()

◆ query() [1/2]

◆ query() [2/2]

◆ addValue()

◆ addInteger()

◆ addFloat()

◆ addString()

◆ setValue()

◆ setInteger()

◆ setFloat()

◆ setString()