#include <json.hpp>

Public Types
using	value_type = Json

using	size_type = std::size_t

using	difference_type = std::ptrdiff_t

using	allocator_type = std::allocator< value_type >

using	reference = value_type &

using	const_reference = const value_type &

using	pointer = typename std::allocator_traits< allocator_type >::pointer

using	const_pointer = typename std::allocator_traits< allocator_type >::const_pointer

using	iterator = detail::JsonIterator< Json >

using	const_iterator = detail::JsonIterator< const Json >

using	reverse_iterator = detail::JsonReverseIterator< iterator >

using	const_reverse_iterator = detail::JsonReverseIterator< const_iterator >

Public Member Functions
	Json ()=default

	Json (json_null_type value) noexcept

template<JsonStringLike T>
	Json (T value) noexcept(false)

template<JsonObject T>
	Json (T value) noexcept(false)

template<JsonArray T>
	Json (T value) noexcept(false)

template<JsonBoolean T>
	Json (T value) noexcept

template<JsonSignedInteger T>
	Json (T value) noexcept

template<JsonUnsignedInteger T>
	Json (T value) noexcept

template<JsonFloatingPoint T>
	Json (T value) noexcept

	Json (const_reference json) noexcept

	Json (Json &&json) noexcept

	Json (std::initializer_list< Json > initializer) noexcept

reference	operator= (Json json) noexcept

json_string_type	serialize () const

bool	is_null () const

bool	is_string () const

bool	is_object () const

bool	is_object_like () const

bool	is_array () const

bool	is_boolean () const

bool	is_signed_integer () const

bool	is_unsigned_integer () const

bool	is_float () const

	operator json_null_type () const noexcept(false)

template<JsonString T>
	operator T () const &noexcept(false)

	operator json_string_type () &&noexcept(false)

template<JsonObject T>
	operator T () const &noexcept(false)

	operator json_object_type () &&noexcept(false)

template<JsonArray T>
	operator T () const &noexcept(false)

	operator json_array_type () &&noexcept(false)

template<typename T , std::size_t N>
	operator std::array< T, N > () const noexcept(false)

template<JsonBoolean T>
	operator T () const noexcept

template<JsonNumber T>
	operator T () const noexcept(false)

template<JsonStringLike T>
reference	at (T key)

template<JsonStringLike T>
const_reference	at (T key) const

reference	at (size_type index)

const_reference	at (size_type index) const

template<JsonStringLike T>
reference	operator[] (T key)

template<JsonStringLike T>
const_reference	operator[] (T key) const

reference	operator[] (size_type index)

const_reference	operator[] (size_type index) const

reference	front ()

const_reference	front () const

reference	back ()

const_reference	back () const

iterator	begin ()

const_iterator	begin () const

const_iterator	cbegin () const

iterator	end ()

const_iterator	end () const

const_iterator	cend () const

reverse_iterator	rbegin ()

const_reverse_iterator	rbegin () const

const_reverse_iterator	crbegin () const

reverse_iterator	rend ()

const_reverse_iterator	rend () const

const_reverse_iterator	crend () const

bool	empty () const

size_type	size () const

void	resize (size_type size)

size_type	capacity () const

void	reserve (size_type capacity)

void	clear ()

template<JsonStringLike Key>
std::pair< iterator, bool >	insert (Key key, const Json &value)

template<JsonStringLike Key>
std::pair< iterator, bool >	insert (Key key, Json &&value)

void	insert (const_iterator first, const_iterator last)

iterator	insert (const_iterator position, const Json &value)

iterator	insert (const_iterator position, Json &&value)

iterator	insert (const_iterator position, size_type count, const Json &value)

iterator	insert (const_iterator position, const_iterator first, const_iterator last)

iterator	insert (const_iterator position, std::initializer_list< Json > initializer)

template<JsonStringLike Key>
std::pair< iterator, bool >	insert_or_assign (Key key, Json &&value)

template<JsonStringLike Key, typename Value >
std::pair< iterator, bool >	emplace (Key key, Value &&value)

template<typename... Args>
Json::reference	emplace_back (Args &&...args)

void	push_back (const Json &value)

void	push_back (Json &&value)

void	pop_back ()

template<JsonStringLike T>
size_type	erase (T key)

void	erase (size_type index)

iterator	erase (const_iterator position)

iterator	erase (const_iterator first, const_iterator last)

void	swap (reference json)

template<JsonString T>
void	swap (T &other)

template<JsonObject T>
void	swap (T &other)

template<JsonArray T>
void	swap (T &other)

void	merge (Json &other)

void	merge (Json &&other)

template<JsonObject T>
void	merge (T &other)

template<JsonObject T>
void	merge (T &&other)

template<JsonStringLike T>
size_type	count (T key) const

template<JsonStringLike T>
iterator	find (T key)

template<JsonStringLike T>
const_iterator	find (T key) const

template<JsonStringLike T>
bool	contains (T key) const

template<JsonString T>
	operator T () const &noexcept(false)

template<JsonObject T>
	operator T () const &noexcept(false)

template<JsonArray T>
	operator T () const &noexcept(false)

Friends
struct	std::hash< Json >

bool	operator== (const_reference json1, const_reference json2)

bool	operator!= (const_reference json1, const_reference json2)

bool	operator< (const_reference json1, const_reference json2)

bool	operator<= (const_reference json1, const_reference json2)

bool	operator> (const_reference json1, const_reference json2)

bool	operator>= (const_reference json1, const_reference json2)

Detailed Description

Class to represent JSON values defined by https://www.json.org.

This class is designed to treat JSON as a first-class container, and to feel as easy to use as a Python dictionary.

There are a myriad of user-friendly initializers to create a JSON value from any compatible type:

A JSON string is a Unicode string. Internally, strings are stored with UTF-8 encoding.
However, all methods that accept a JSON string will accept ASCII, UTF-8, UTF-16, and UTF-32
encoded strings. All strings are validated for strict Unicode compliance and converted to
UTF-8. Further, the provided string type may be an STL string, a null-terminated character
array, or a string view. For example:

    fly::Json json = "This is an ASCII string";
    fly::Json json = u8"This is a UTF-8 string";
    fly::Json json = u"This is a UTF-16 string";
    fly::Json json = U"This is a UTF-32 string";
    fly::Json json = L"This is a wide string"; // UTF-16 on Windows, UTF-32 on Linux & macOS.

    std::string string = "This is an ASCII string";
    fly::Json json = string;

    std::u32string string = "This is a UTF-32 string";
    std::u32string_view view = string;
    fly::Json json = view;

A JSON object may be created from a std::map, std::unordered_multimap, etc., as long as the
map key is a JSON string (where any of the above Unicode encodings are valid). Further,
initializer lists with mixed types are also valid. For example:

    std::map<std::string, int> map = {{"key1", 1}, {"key2", 2}};
    fly::Json json = map;

    std::unordered_map<std::u16string, int> map = {{u"key1", 1}, {u"key2", 2}};
    fly::Json json = map;

    fly::Json json = {{"key1", nullptr}, {u8"key2", L"value2"}, {U"key3", 123.89f}};

A JSON array may be created from a std::vector, std::list, std::array, etc. Further,
initializer lists with mixed types are also valid. For example:

    std::vector<std::string> array = {"value1", "value2"};
    fly::Json json = array;

    std::array<std::u8string, 2> array = {u8"value1", u8"value2"};
    fly::Json json = array;

    fly::Json json = {"value1", u8"value2", nullptr, 123.89f};

A JSON boolean, number, or null value may be created from analogous C++ plain-old-data types.
Internally, 64-bit integers are used for storing integer numbers and long doubles for
floating-point numbers. The signedness of the 64-bit integer is the same as the integer from
which the JSON value is created. For example:

    fly::Json json = true;
    fly::Json json = -12389;
    fly::Json json = 123.89f;
    fly::Json json = nullptr;

A JSON value may be converted to any compatible C++ type. Attempting to convert a JSON value to an incompatible type is considered exceptional. Further, conversions must be explicit. To define conversion operators implicitly would introduce ambiguity in which conversion operator the compiler should choose. For example:

    fly::Json json = { 1, 2, 3, 4 };
    std::vector<int> vector(json); // Would not compile if conversions were implicit.

Which JSON conversion operator should be called for the std::vector constructor? Conversions from a JSON value to std::vector and std::size_t are defined, creating ambiguity in which std::vector constructor would be called (copy constructor or count constructor), even though the std::size_t converter would actually throw an exception. Explicit conversion operators remove this ambiguity.

Converting a JSON string to a string type permits the same Unicode flexibility as creating
the JSON string. For example:

    fly::Json json = "This is an ASCII string";
    std::string string(json);
    std::u8string string(json);
    std::wstring string(json);

A restriction is that while creating a JSON value from a character array is allowed,
converting a JSON value to a character array is not allowed. There is no safe way to do the
following without allocating memory that the caller must remember to free:

    fly::Json json = "string";
    char *string = json; // Will not compile.

Converting other JSON types works similarly. Like JSON strings, the keys of the C++ type may
be any compatible string type.

    fly::Json json = {{"key1", 1}, {u8"key2", "2"}};
    std::map<std::u32string, int> map(json); // map = {{U"key1", 1}, {U"key2", 2}}

    fly::Json json = {"value1", u8"value2", nullptr, 123.89f};
    std::vector<std::string> array(json); // array = {"value1", "value2", "null", "123.89"}

    fly::Json json = true;
    bool value(json);

    fly::Json json = 12389;
    std::uint16_t value(json);

    fly::Json json = -123.89f;
    float value(json);

Some leniency is allowed for converting a JSON value to a type which differs from the type
of the JSON value itself:

    JSON strings may be converted to numeric values if the string represents a number. For
    example, the string "12389" may be converted to an integer. The string "abc" may not.

    Numeric JSON types may be converted to a string type.

    All JSON types may be converted to a boolean. String, object, and array JSON values will
    convert based on whether the value is empty. JSON numbers will convert based on whether
    the value is non-zero. Null JSON values always convert to false.

    JSON numbers may be converted to any numeric type. For example, a floating-point JSON
    value may be converted to an integer.

Lastly, this class defines the canonical interfaces of STL container types. This includes element accessor, iterator, modifier, and capacity/lookup operations.

Author: Timothy Flynn (trfly.nosp@m.nn89.nosp@m.@pm.m.nosp@m.e)

Version: September 24, 2017

Member Typedef Documentation

◆ value_type

using fly::Json::value_type = Json

Aliases for canonical STL container member types.

Constructor & Destructor Documentation

◆ Json() [1/12]

fly::Json::Json ( )

default

Default constructor. Intializes the Json instance to a null value.

◆ Json() [2/12]

fly::Json::Json ( json_null_type value )

noexcept

Null constructor. Intializes the Json instance to a null value.

Parameters

value The null value.

◆ Json() [3/12]

template<JsonFloatingPoint T>

fly::Json::Json ( T value )

noexcept

String constructor. Intializes the Json instance to a string value. The SFINAE declaration allows construction of a string value from any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

T	The string-like type.

Parameters

value The string-like value.

Exceptions

JsonException If the string-like value is not valid.

◆ Json() [4/12]

template<JsonObject T>

fly::Json::Json ( T value )

noexcept

Object constructor. Intializes the Json instance to an object's values. The SFINAE declaration allows construction of an object value from any object-like type (e.g. std::map, std::multimap).

Template Parameters

T	The object-like type.

Parameters

value The object-like value.

Exceptions

JsonException If an object key is not a valid string.

◆ Json() [5/12]

template<JsonArray T>

fly::Json::Json ( T value )

noexcept

Array constructor. Intializes the Json instance to an array's values. The SFINAE declaration allows construction of an array value from any array-like type (e.g. std::list, std::vector).

Template Parameters

T	The array-like type.

Parameters

value The array-like value.

Exceptions

JsonException If an string-like value in the array is not valid.

◆ Json() [6/12]

template<JsonBoolean T>

fly::Json::Json ( T value )

noexcept

Boolean constructor. Intializes the Json instance to a boolean value. The SFINAE declaration forbids construction of a boolean value from any non-boolean type (e.g. int could be implicitly cast to bool).

Template Parameters

T	The boolean type.

Parameters

value The boolean value.

◆ Json() [7/12]

template<JsonSignedInteger T>

fly::Json::Json ( T value )

noexcept

Signed integer constructor. Intializes the Json instance to a signed integer value. The SFINAE declaration allows construction of a signed integer value from any signed type (e.g. char, int, int64_t).

Template Parameters

T	The signed type.

Parameters

value The signed value.

◆ Json() [8/12]

template<JsonUnsignedInteger T>

fly::Json::Json ( T value )

noexcept

Unsigned integer constructor. Intializes the Json instance to an unsigned integer value. The SFINAE declaration allows construction of an unsigned integer value from any unsigned type (e.g. unsigned char, unsigned int, uint64_t).

Template Parameters

T	The unsigned type.

Parameters

value The unsigned value.

◆ Json() [9/12]

template<JsonFloatingPoint T>

fly::Json::Json ( T value )

noexcept

Floating-point constructor. Intializes the Json instance to a floating-point value. The SFINAE declaration allows construction of a floating-point value from any floating-point type (e.g. float, double).

Template Parameters

T	The floating-point type.

Parameters

value The floating-point value.

◆ Json() [10/12]

fly::Json::Json ( const_reference json )

noexcept

Copy constructor. Intializes the Json instance with the type and value of another Json instance.

Parameters

json	The Json instance to copy.

◆ Json() [11/12]

fly::Json::Json ( Json && json )

noexcept

Move constructor. Intializes the Json instance with the type and value of another Json instance. The other Json instance is set to a null value.

Parameters

json	The Json instance to move.

◆ Json() [12/12]

fly::Json::Json ( std::initializer_list< Json > initializer )

noexcept

Initializer list constructor. Intializes the Json instance with an initializer list. Creates either an object or an array instance. If all values in the initializer list are object-like (see IsObjectLike()), then the Json instance is created as an object. Otherwise, it is created as an array.

Parameters

initializer The initializer list.

Member Function Documentation

◆ at() [1/4]

Json::reference fly::Json::at ( size_type index )

Array read-only accessor.

If the Json instance is an array, perform a lookup on the array with an index.

Parameters

index The index to lookup.

Returns: A reference to the Json instance at the index.

Exceptions

JsonException If the Json instance is not an array or the index does not exist.

◆ at() [2/4]

Json::const_reference fly::Json::at ( size_type index ) const

Array read-only accessor.

If the Json instance is an array, perform a lookup on the array with an index.

Parameters

index The index to lookup.

Returns: A reference to the Json instance at the index.

Exceptions

JsonException If the Json instance is not an array or the index does not exist.

◆ at() [3/4]

template<JsonStringLike T>

Json::reference fly::Json::at ( T key )

Object read-only accessor. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

If the Json instance is an object, perform a lookup on the object with a key value.

Template Parameters

T	The string-like key type.

Parameters

key	The key value to lookup.

Returns: A reference to the Json instance at the key value.

Exceptions

JsonException If the Json instance is not an object, or the key value does not exist, or the key value is invalid.

◆ at() [4/4]

template<JsonStringLike T>

Json::const_reference fly::Json::at ( T key ) const

Object read-only accessor. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

If the Json instance is an object, perform a lookup on the object with a key value.

Template Parameters

T	The string-like key type.

Parameters

key	The key value to lookup.

Returns: A reference to the Json instance at the key value.

Exceptions

JsonException If the Json instance is not an object, or the key value does not exist, or the key value is invalid.

◆ back() [1/2]

Json::reference fly::Json::back ( )

Obtain a reference to the last element in the Json instance. Only valid if the Json instance is an object or an array.

For JSON objects, the returned reference will be to the value part of the back element's key-value pair.

Returns: A reference to the last element.

Exceptions

JsonException If the Json instance is not an object or array, or if the Json instance is empty.

◆ back() [2/2]

Json::const_reference fly::Json::back ( ) const

Obtain a reference to the last element in the Json instance. Only valid if the Json instance is an object or an array.

For JSON objects, the returned reference will be to the value part of the back element's key-value pair.

Returns: A reference to the last element.

Exceptions

JsonException If the Json instance is not an object or array, or if the Json instance is empty.

◆ begin() [1/2]

Json::iterator fly::Json::begin ( )

Retrieve an iterator to the beginning of the Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ begin() [2/2]

Json::const_iterator fly::Json::begin ( ) const

Retrieve a constant iterator to the beginning of the Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ capacity()

Json::size_type fly::Json::capacity ( ) const

Get the number of elements that the Json instance has currently allocated space for.

If the Json instance is null, returns 0.

If the Json instance is a string or array, returns the number of elements allocated for the string or array.

If the Json instance is an object, returns the number of elements stored in the object (effectively the same as invoking Json::size).

If the Json instance is a boolean or numeric, returns 1.

Returns: The capacity of the Json instance.

◆ cbegin()

Json::const_iterator fly::Json::cbegin ( ) const

Retrieve a constant iterator to the beginning of the Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ cend()

Json::const_iterator fly::Json::cend ( ) const

Retrieve a constant iterator to the end of the Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ clear()

void fly::Json::clear ( )

Clear the contents of the Json instance.

If the Json instance is an object, array, or string, clears the stored container.

If the Json instance is a boolean, sets to false.

If the Json instance is numeric, sets to zero.

◆ contains()

template<JsonStringLike T>

bool fly::Json::contains ( T key ) const

Check if there is an element in the Json instance with a given key. Only valid if the Json instance is an object. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

T	The string-like key type.

Parameters

key	The key value to lookup.

Returns: True if an element was found at the key value.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ count()

template<JsonStringLike T>

Json::size_type fly::Json::count ( T key ) const

Count the number of elements in the Json instance with a given key. Only valid if the Json instance is an object. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

T	The string-like key type.

Parameters

key	The key value to lookup.

Returns: If found, number of elements at the key value. If not found, returns 0.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ crbegin()

Json::const_reverse_iterator fly::Json::crbegin ( ) const

Retrieve a constant reverse iterator to the beginning of the reversed Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ crend()

Json::const_reverse_iterator fly::Json::crend ( ) const

Retrieve a constant reverse iterator to the end of the reversed Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ emplace()

template<JsonStringLike Key, typename Value >

std::pair< Json::iterator, bool > fly::Json::emplace	(	Key	key,
		Value &&	value
	)

Construct an element in-place within the Json instance. Only valid if the Json instance is an object or null. If the Json instance is null, it is first converted to an object. The SFINAE declaration allows inserting a value with a key of any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

Key	The string-like type of the emplaced value's key.
Value	The type of the emplaced value.

Parameters

key	The key of the value to emplace.
value	The value to emplace at the given key.

Returns: An iterator-boolean pair. The boolean indicates whether the emplacement was successful. If so, the iterator is that of the emplaced element. If not, the iterator points to the element which prevented the emplacement.

Exceptions

JsonException If the Json instance is neither an object nor null.

◆ emplace_back()

template<typename... Args>

Json::reference fly::Json::emplace_back ( Args &&... args )

Construct an element in-place at the end of the Json instance. Only valid if the Json instance is an array or null. If the Json instance is null, it is first converted to an array.

Template Parameters

Args	Variadic template arguments for value construction.

Parameters

args	The list of arguments for value construction.

Returns: An iterator pointed at the emplaced element.

Exceptions

JsonException If the Json instance is neither an array nor null.

◆ empty()

bool fly::Json::empty ( ) const

Check if the Json instance contains zero elements.

If the Json instance is null, returns true.

If the Json instance is a string, object, or array, returns whether the stored container is empty.

If the Json instance is a boolean or numeric, returns false.

Returns: True if the instance is empty.

◆ end() [1/2]

Json::iterator fly::Json::end ( )

Retrieve an iterator to the end of the Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ end() [2/2]

Json::const_iterator fly::Json::end ( ) const

Retrieve a constant iterator to the end of the Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ erase() [1/4]

Json::iterator fly::Json::erase	(	const_iterator	first,
		const_iterator	last
	)

Remove all values from the Json instance in the range [first, last). Only valid if the Json instance is an object or array.

Parameters

first	The beginning of the range of values to remove.
last	The end of the range of values to remove.

Returns: An iterator pointed at the element following the last removed element.

Exceptions

JsonException If the Json instance is not an object or array, or the provided iterators are not for this Json instance.

◆ erase() [2/4]

Json::iterator fly::Json::erase ( const_iterator position )

Remove a value from the Json instance at the provided position. Only valid if the Json instance is an object or array.

The provided position must be valid and dereferenceable. Thus the past-the-end iterator (which is valid, but is not dereferenceable) cannot be used as a position.

Parameters

position The iterator position which should be removed.

Returns: An iterator pointed at the element following the removed element.

Exceptions

JsonException If the Json instance is not an object or array, the provided position is not for this Json instance, or if the provided position is past-the-end.

◆ erase() [3/4]

void fly::Json::erase ( size_type index )

Remove a value from the Json instance at the provided index. Only valid if the Json instance is an array.

Parameters

index The index to remove.

Exceptions

JsonException If the Json instance is not an array or the index does not exist.

◆ erase() [4/4]

template<JsonStringLike T>

Json::size_type fly::Json::erase ( T key )

Remove a value from the Json instance with the provided key. Only valid if the Json instance is an object. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

T	The string-like key type.

Parameters

key	The key value to remove.

Returns: The number of elements removed.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ find() [1/2]

template<JsonStringLike T>

Json::iterator fly::Json::find ( T key )

Search for an element in the Json instance with a given key. Only valid if the Json instance is an object. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

T	The string-like key type.

Parameters

key	The key value to lookup.

Returns: If found, an iterator to the element at the key value. If not found, returns a past-the-end iterator.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ find() [2/2]

template<JsonStringLike T>

Json::const_iterator fly::Json::find ( T key ) const

Search for an element in the Json instance with a given key. Only valid if the Json instance is an object. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

T	The string-like key type.

Parameters

key	The key value to lookup.

Returns: If found, an iterator to the element at the key value. If not found, returns a past-the-end iterator.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ front() [1/2]

Json::reference fly::Json::front ( )

Obtain a reference to the first element in the Json instance. Only valid if the Json instance is an object or an array.

For JSON objects, the returned reference will be to the value part of the front element's key-value pair.

Returns: A reference to the first element.

Exceptions

JsonException If the Json instance is not an object or array, or if the Json instance is empty.

◆ front() [2/2]

Json::const_reference fly::Json::front ( ) const

Obtain a reference to the first element in the Json instance. Only valid if the Json instance is an object or an array.

For JSON objects, the returned reference will be to the value part of the front element's key-value pair.

Returns: A reference to the first element.

Exceptions

JsonException If the Json instance is not an object or array, or if the Json instance is empty.

◆ insert() [1/8]

void fly::Json::insert	(	const_iterator	first,
		const_iterator	last
	)

Insert all values into the Json instance in the range [first, last). Only valid if the Json instance is an object.

Parameters

first	The beginning of the range of values to insert.
last	The end of the range of values to insert.

Exceptions

JsonException If the Json instance is not an object, the key value is invalid, the provided iterators are not for the same Json instance, or the provided iterators are for non-object Json instances.

◆ insert() [2/8]

Json::iterator fly::Json::insert	(	const_iterator	position,
		const Json &	value
	)

Insert a copy of a Json value into the Json instance before the provided position. Only valid if the Json instance is an array.

Parameters

position	The iterator position before which the value should be inserted.
value	The Json value to insert.

Returns: An iterator pointed at the inserted element.

Exceptions

JsonException If the Json instance is not an array or the provided position is not for this Json instance.

◆ insert() [3/8]

Json::iterator fly::Json::insert	(	const_iterator	position,
		const_iterator	first,
		const_iterator	last
	)

Insert all values into the Json instance in the range [first, last) before the provided position. Only valid if the Json instance is an array. The iterators in the range [first, last) may not be iterators into this Json instance; this limitation is due to otherwise undefined behavior of std::vector.

Parameters

position	The iterator position before which the value should be inserted.
first	The beginning of the range of values to insert.
last	The end of the range of values to insert.

Returns: An iterator pointed at the first element inserted.

Exceptions

JsonException If the Json instance is not an array, the provided position is not for this Json instance, the provided iterators are not for the same Json instance, the provided iterators are for non-array Json instances, or the provided iterators are for this Json instance.

◆ insert() [4/8]

Json::iterator fly::Json::insert	(	const_iterator	position,
		Json &&	value
	)

Insert a moved Json value into the Json instance before the provided position. Only valid if if the Json instance is an array.

Parameters

position	The iterator position before which the value should be inserted.
value	The Json value to insert.

Returns: An iterator pointed at the inserted element.

Exceptions

JsonException If the Json instance is not an array or the provided position is not for this Json instance.

◆ insert() [5/8]

Json::iterator fly::Json::insert	(	const_iterator	position,
		size_type	count,
		const Json &	value
	)

Insert a number of copies of a Json value into the Json instance before the provided position. Only valid if the Json instance is an array.

Parameters

position	The iterator position before which the value should be inserted.
count	The number of copies to insert.
value	The Json value to insert.

Returns: An iterator pointed at the first element inserted.

Exceptions

JsonException If the Json instance is not an array or the provided position is not for this Json instance.

◆ insert() [6/8]

Json::iterator fly::Json::insert	(	const_iterator	position,
		std::initializer_list< Json >	initializer
	)

Insert all values into the Json instance from the provided initializer list before the provided position instance. Only valid if the Json instance is an array.

Parameters

position	The iterator position before which the value should be inserted.
initializer	The list of values to insert.

Returns: An iterator pointed at the first element inserted.

Exceptions

JsonException If the Json instance is not an array or the provided position is not for this Json instance.

◆ insert() [7/8]

template<JsonStringLike Key>

std::pair< Json::iterator, bool > fly::Json::insert	(	Key	key,
		const Json &	value
	)

Insert a copy of a key-value pair into the Json instance. Only valid if the Json instance is an object. The SFINAE declaration allows inserting a value with a key of any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

Key	The string-like type of the inserted value's key.

Parameters

key	The key of the value to insert.
value	The value to insert at the given key.

Returns: An iterator-boolean pair. The boolean indicates whether the insertion was successful. If so, the iterator is that of the inserted element. If not, the iterator points to the element which prevented the insertion.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ insert() [8/8]

template<JsonStringLike Key>

std::pair< Json::iterator, bool > fly::Json::insert	(	Key	key,
		Json &&	value
	)

Insert a moved key-value pair into the Json instance. Only valid if the Json instance is an object. The SFINAE declaration allows inserting a value with a key of any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

Key	The string-like type of the inserted value's key.

Parameters

key	The key of the value to insert.
value	The value to insert at the given key.

Returns: An iterator-boolean pair. The boolean indicates whether the insertion was successful. If so, the iterator is that of the inserted element. If not, the iterator points to the element which prevented the insertion.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ insert_or_assign()

template<JsonStringLike Key>

std::pair< Json::iterator, bool > fly::Json::insert_or_assign	(	Key	key,
		Json &&	value
	)

Insert or update a moved key-value pair into the Json instance. If the provided key already exists, assigns the provided value to the key. Only valid if the Json instance is an object. The SFINAE declaration allows inserting a value with a key of any string-like type (e.g. std::string, char8_t[], std::u16string_view).

Template Parameters

Key	The string-like type of the inserted value's key.

Parameters

key	The key of the value to insert.
value	The value to insert at the given key.

Returns: An iterator-boolean pair. The boolean will be true if insertion took place, or false if assignment took place. The iterator points to the inserted or updated element.

Exceptions

JsonException If the Json instance is not an object or the key value is invalid.

◆ is_array()

bool fly::Json::is_array ( ) const

Returns: True if the Json instance is an array.

◆ is_boolean()

bool fly::Json::is_boolean ( ) const

Returns: True if the Json instance is a boolean.

◆ is_float()

bool fly::Json::is_float ( ) const

Returns: True if the Json instance is a float.

◆ is_null()

bool fly::Json::is_null ( ) const

Returns: True if the Json instance is null.

◆ is_object()

bool fly::Json::is_object ( ) const

Returns: True if the Json instance is an object.

◆ is_object_like()

bool fly::Json::is_object_like ( ) const

Determine if the Json instance is object-like. This is mostly useful for constructing a Json instance from an initializer list. If this instance is an array with two elements, and the first element is a string, then this instance is object-like.

Returns: True if the Json instance is object-like.

◆ is_signed_integer()

bool fly::Json::is_signed_integer ( ) const

Returns: True if the Json instance is a signed integer.

◆ is_string()

bool fly::Json::is_string ( ) const

Returns: True if the Json instance is a string.

◆ is_unsigned_integer()

bool fly::Json::is_unsigned_integer ( ) const

Returns: True if the Json instance is an unsigned integer.

◆ merge() [1/4]

void fly::Json::merge ( fly::Json && other )

Extract each element from a Json instance into this Json instance. Only valid if this Json instance is an object or null, and the other Json instance is an object. If this Json instance is null, it is first converted to an object.

If there is an element in the other Json instance with a key equivalent to a key of an element in this Json instance, that element is not merged.

Parameters

other The Json instance to merge into this Json instance.

Exceptions

JsonException If this Json instance is neither an object nor null, or the other Json instance is not an object.

◆ merge() [2/4]

void fly::Json::merge ( fly::Json & other )

Extract each element from a Json instance into this Json instance. Only valid if this Json instance is an object or null, and the other Json instance is an object. If this Json instance is null, it is first converted to an object.

If there is an element in the other Json instance with a key equivalent to a key of an element in this Json instance, that element is not merged.

Parameters

other The Json instance to merge into this Json instance.

Exceptions

JsonException If this Json instance is neither an object nor null, or the other Json instance is not an object.

◆ merge() [3/4]

template<JsonObject T>

void fly::Json::merge ( T && other )

Extract each element from an object-like type into the Json instance. Only valid if the Json instance is an object or null. If the Json instance is null, it is first converted to an object. The SFINAE declaration allows merging any object-like type (e.g. std::map, std::multimap).

If there is an element in the object-like type with a key equivalent to a key of an element in the Json instance, that element is not merged.

Parameters

other The object to merge into this Json instance.

Exceptions

JsonException If this Json instance is neither an object nor null.

◆ merge() [4/4]

template<JsonObject T>

void fly::Json::merge ( T & other )

Extract each element from an object-like type into the Json instance. Only valid if the Json instance is an object or null. If the Json instance is null, it is first converted to an object. The SFINAE declaration allows merging any object-like type (e.g. std::map, std::multimap).

If there is an element in the object-like type with a key equivalent to a key of an element in the Json instance, that element is not merged.

Parameters

other The object to merge into this Json instance.

Exceptions

JsonException If this Json instance is neither an object nor null.

◆ operator json_array_type()

fly::Json::operator json_array_type ( ) &&

explicitnoexcept

Array move-conversion operator. If the Json instance is an array, transfers ownership of the stored value to the caller. The Json instance is set to a null value.

Returns: The Json instance's stored array value.

Exceptions

JsonException If the Json instance is not an array.

◆ operator json_null_type()

fly::Json::operator json_null_type ( ) const

explicitnoexcept

Null conversion operator. Converts the Json instance to a null type.

Returns: The Json instance as a number.

Exceptions

JsonException If the Json instance is not null.

◆ operator json_object_type()

fly::Json::operator json_object_type ( ) &&

explicitnoexcept

Object move-conversion operator. If the Json instance is an object, transfers ownership of the stored value to the caller. The Json instance is set to a null value.

Returns: The Json instance's stored object value.

Exceptions

JsonException If the Json instance is not an object.

◆ operator json_string_type()

fly::Json::operator json_string_type ( ) &&

explicitnoexcept

String move-conversion operator. If the Json instance is a string, transfers ownership of the stored value to the caller. The Json instance is set to a null value.

Returns: The Json instance's stored string value.

Exceptions

JsonException If the Json instance is not a string.

◆ operator std::array< T, N >()

template<typename T , std::size_t N>

fly::Json::operator std::array< T, N >

explicitnoexcept

Array conversion operator. Converts the Json instance to a std::array. If the Json instance has more values than the std::array can hold, the values are dropped. If the Json instance has less values than the std::array can hold, the remainder are value-initialized.

Template Parameters

T	The std::array value type.
N	The std::array size.

Returns: The Json instance as a std::array.

Exceptions

JsonException If the Json instance is not an array, or a stored element could not be converted to the target array's value type.

◆ operator T() [1/5]

template<JsonNumber T>

fly::Json::operator T

explicitnoexcept

String conversion operator. Converts the Json instance to a string. The SFINAE declaration allows conversion to any string type (e.g. std::string, std::u8string). Also allows for converting from a numeric type (e.g. 12389) to a string type.

Note that although a Json instance can be constructed from a character array, it is not allowed to directly convert a Json instance into a character array.

Template Parameters

T	The string type.

Returns: The Json instance as a string.

Exceptions

JsonException If the Json instance is not a string, or the stored value could not be converted to the target string type.

◆ operator T() [2/5]

template<JsonObject T>

fly::Json::operator T ( ) const &

explicitnoexcept

Object conversion operator. Converts the Json instance to an object. The SFINAE declaration allows conversion to any object-like type (e.g. std::map, std::multimap).

Template Parameters

T	The object-like type.

Returns: The Json instance as the object-like type.

Exceptions

JsonException If the Json instance is not an object, or a stored element could not be converted to the target object's value type.

◆ operator T() [3/5]

template<JsonArray T>

fly::Json::operator T ( ) const &

explicitnoexcept

Array conversion operator. Converts the Json instance to an array. The SFINAE declaration allows conversion to any array-like type (e.g. std::list, std::vector). This excludes std::array, which due to being an aggregate type, has its own explicit conversion operator.

Template Parameters

T	The array-like type.

Returns: The Json instance as the array-like type.

Exceptions

JsonException If the Json instance is not an array, or a stored element could not be converted to the target array's value type.

◆ operator T() [4/5]

template<JsonBoolean T>

fly::Json::operator T ( ) const

explicitnoexcept

Boolean conversion operator. Converts the Json instance to a boolean. For strings, objects, and arrays, returns true if the value is non-empty. For signed integers, unsigned integers, and floats, returns true if the value is non-zero. For booleans, returns the boolean value. For null, returns false.

Template Parameters

T	The boolean type.

Returns: The Json instance as a boolean.

◆ operator T() [5/5]

template<JsonNumber T>

fly::Json::operator T ( ) const

explicitnoexcept

Numeric conversion operator. Converts the Json instance to a numeric type. The SFINAE declaration allows conversion to any numeric type type (e.g. char, uint64_t, float) from the Json instance. Allows for converting between signed integers, unsigned integers, and floats. Also allows for converting from a numeric-like string (e.g. "12389") to a numeric type.

Template Parameters

T	The numeric type.

Returns: The Json instance as the numeric type.

Exceptions

JsonException If the Json instance is not numeric, or the stored value could not be converted to the target numeric type.

◆ operator=()

Json::reference fly::Json::operator= ( Json json )

noexcept

Copy assignment operator. Intializes the Json instance with the type and value of another Json instance, using the copy-and-swap idiom.

Parameters

json	The Json instance to copy-and-swap.

Returns: A reference to this Json instance.

◆ operator[]() [1/4]

Json::reference fly::Json::operator[] ( size_type index )

Array access operator.

If the Json instance is an array, perform a lookup on the array with an index. If the index is not found, the array is filled with null values up to and including the index.

If the Json instance is null, it is first converted to an array.

Parameters

index The index to lookup.

Returns: A reference to the Json instance at the index.

Exceptions

JsonException If the Json instance is neither an array nor null.

◆ operator[]() [2/4]

Json::const_reference fly::Json::operator[] ( size_type index ) const

Array read-only access operator.

If the Json instance is an array, perform a lookup on the array with an index.

Parameters

index The index to lookup.

Returns: A reference to the Json instance at the index.

Exceptions

JsonException If the Json instance is not an array or the index does not exist.

◆ operator[]() [3/4]

template<JsonStringLike T>

Json::reference fly::Json::operator[] ( T key )

Object access operator. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

If the Json instance is an object, perform a lookup on the object with a key value. If the key value is not found, a null Json instance will be created for that key.

If the Json instance is null, it is first converted to an object.

Template Parameters

T	The string-like key type.

Parameters

key	The key value to lookup.

Returns: A reference to the Json instance at the key value.

Exceptions

JsonException If the Json instance is neither an object nor null, or the key value is invalid.

◆ operator[]() [4/4]

template<JsonStringLike T>

Json::const_reference fly::Json::operator[] ( T key ) const

Object read-only access operator. The SFINAE declaration allows lookups with any string-like type (e.g. std::string, char8_t[], std::u16string_view).

If the Json instance is an object, perform a lookup on the object with a key value.

Parameters

key	The key value to lookup.

Returns: A reference to the Json instance at the key value.

Exceptions

JsonException If the Json instance is not an object, or the key value does not exist, or the key value is invalid.

◆ pop_back()

void fly::Json::pop_back ( )

Remove the last element from the Json instance. Only valid if the Json instance is an array.

Exceptions

JsonException If the Json instance is not an array or the array is empty.

◆ push_back() [1/2]

void fly::Json::push_back ( const Json & value )

Append a copy of a Json value to the end of the Json instance. Only valid if the Json instance is an array or null. If the Json instance is null, it is first converted to an array.

Parameters

value The Json value to append.

Exceptions

JsonException If the Json instance is neither an array nor null.

◆ push_back() [2/2]

void fly::Json::push_back ( Json && value )

Append a moved Json value to the end of the Json instance. Only valid if the Json instance is an array or null. If the Json instance is null, it is first converted to an array.

Parameters

value The Json value to append.

Exceptions

JsonException If the Json instance is neither an array nor null.

◆ rbegin() [1/2]

Json::reverse_iterator fly::Json::rbegin ( )

Retrieve a reverse iterator to the beginning of the reversed Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ rbegin() [2/2]

Json::const_reverse_iterator fly::Json::rbegin ( ) const

Retrieve a constant reverse iterator to the beginning of the reversed Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ rend() [1/2]

Json::reverse_iterator fly::Json::rend ( )

Retrieve a reverse iterator to the end of the reversed Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ rend() [2/2]

Json::const_reverse_iterator fly::Json::rend ( ) const

Retrieve a constant reverse iterator to the end of the reversed Json instance.

Returns: The retrieved iterator.

Exceptions

JsonException If the Json instance is not an object or array.

◆ reserve()

void fly::Json::reserve ( size_type capacity )

Increase the capacity of the Json instance to a value that's greater or equal to the provided capacity. Only valid if the Json instance is a string or array.

Parameters

capacity The new capacity of the Json instance.

Exceptions

JsonException If the Json instance is not a string or array.

◆ resize()

void fly::Json::resize ( size_type size )

Resize the Json instance to contain the provided number of elements. Only valid if the Json instance is a string or array.

Parameters

size	The new size of the Json instance.

Exceptions

JsonException If the Json instance is not a string or array.

◆ serialize()

json_string_type fly::Json::serialize ( ) const

Serialize the Json instance to a string.

Returns: The serialized Json instance.

◆ size()

Json::size_type fly::Json::size ( ) const

Get the number of elements in the Json instance.

If the Json instance is null, returns 0.

If the Json instance is a string, returns the length of the string.

If the Json instance is an object or array, returns the number of elements stored in the object or array.

If the Json instance is a boolean or numeric, returns 1.

Returns: The size of the Json instance.

◆ swap() [1/4]

void fly::Json::swap ( reference json )

Exchange the contents of the Json instance with another instance.

Parameters

json	The Json instance to swap with.

◆ swap() [2/4]

template<JsonArray T>

void fly::Json::swap ( T & other )

Exchange the contents of the Json instance with another string. Only valid if the Json instance is a string. The SFINAE declaration allows swapping with any string type (e.g. std::string, std::u8string).

Note that although a Json instance can be constructed from a character array, it is not allowed to directly swap a Json instance with a character array.

Template Parameters

T	The string type to swap with.

Parameters

json	The string to swap with.

Exceptions

JsonException If the Json instance is not a string.

◆ swap() [3/4]

template<JsonObject T>

void fly::Json::swap ( T & other )

Exchange the contents of the Json instance with another object. Only valid if the Json instance is an object. The SFINAE declaration allows swapping with any object-like type (e.g. std::map, std::multimap).

Template Parameters

T	The object type to swap with.

Parameters

json	The object to swap with.

Exceptions

JsonException If the Json instance is not an object.

◆ swap() [4/4]

template<JsonArray T>

void fly::Json::swap ( T & other )

Exchange the contents of the Json instance with another array. Only valid if the Json instance is an array. The SFINAE declaration allows swapping with any array-like type (e.g. std::list, std::vector).

Template Parameters

T	The array type to swap with.

Parameters

json	The array to swap with.

Exceptions

JsonException If the Json instance is not an array.

Friends And Related Function Documentation

◆ operator!=

bool operator!=	(	Json::const_reference	json1,
		Json::const_reference	json2
	)

friend

Unequality operator. Compares two Json instances for unequality. They are unequal if none of the conditions of the equality operator are met.

Returns: True if the two Json instances are unequal.

◆ operator<

bool operator<	(	Json::const_reference	json1,
		Json::const_reference	json2
	)

friend

Less-than operator. The first Json instance is less-than the second Json instance if one of the following is true:

One of the two JSON types are floating-point, the other is a numeric type (signed, unsigned, or float) and the default less-than operator returns true after converting both types to floating-point.
The two Json instances are an integer type (signed or unsigned) and have the default less-than operator returns true after converting the second Json value to the same type as the first Json value.
The two Json instances are of the same type and the default less-than operator returns true.
The two Json instances are of incompatible types and the type of the first Json instance is considered less-than the type of the second Json instance. The ordering is determined by the order of the types listed in the fly::json_type alias.

Returns: True if the first Json instance is less-than the second Json instance.

◆ operator<=

bool operator<=	(	Json::const_reference	json1,
		Json::const_reference	json2
	)

friend

Less-than-or-equal-to operator. The first Json instance is less-than-or-equal-to the second Json instance if any of the conditions of the equality or less-than operators are met.

Returns: True if the first Json instance is less-than-or-equal-to the second Json instance.

◆ operator==

bool operator==	(	Json::const_reference	json1,
		Json::const_reference	json2
	)

friend

Equality operator. Compares two Json instances for equality. They are equal if one of the following is true:

One of the two JSON types are floating-point, the other is a numeric type (signed, unsigned, or float) and have approximately the same value after converting both types to floating-point. Approximation is determined by comparing the difference between the two values to the machine epsilon.
The two Json instances are an integer type (signed or unsigned) and have the same value after converting the second Json value to the same type as the first Json value.
The two Json instances are of the same type and have the same value.

Returns: True if the two Json instances are equal.

◆ operator>

bool operator>	(	Json::const_reference	json1,
		Json::const_reference	json2
	)

friend

Greater-than operator. The first Json instance is greater-than the second Json instance if none of the conditions of the less-than-or-equal-to operator are met.

Returns: True if the first Json instance is greater-than the second Json instance.

◆ operator>=

bool operator>=	(	Json::const_reference	json1,
		Json::const_reference	json2
	)

friend

Greater-than-or-equal-to operator. The first Json instance is greater-than-or-equal-to the second Json instance if any of the conditions of the equality or greater-than operators are met.

Returns: True if the first Json instance is greater-than-or-equal-to the second Json instance.

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

fly/types/json/json.hpp
fly/types/json/json.cpp

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ value_type

Constructor & Destructor Documentation

◆ Json() [1/12]

◆ Json() [2/12]

◆ Json() [3/12]

◆ Json() [4/12]

◆ Json() [5/12]

◆ Json() [6/12]

◆ Json() [7/12]

◆ Json() [8/12]

◆ Json() [9/12]

◆ Json() [10/12]

◆ Json() [11/12]

◆ Json() [12/12]

Member Function Documentation

◆ at() [1/4]

◆ at() [2/4]

◆ at() [3/4]

◆ at() [4/4]

◆ back() [1/2]

◆ back() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ cbegin()

◆ cend()

◆ clear()

◆ contains()

◆ count()

◆ crbegin()

◆ crend()

◆ emplace()

◆ emplace_back()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ erase() [1/4]

◆ erase() [2/4]

◆ erase() [3/4]

◆ erase() [4/4]

◆ find() [1/2]

◆ find() [2/2]

◆ front() [1/2]

◆ front() [2/2]

◆ insert() [1/8]

◆ insert() [2/8]

◆ insert() [3/8]

◆ insert() [4/8]

◆ insert() [5/8]

◆ insert() [6/8]

◆ insert() [7/8]

◆ insert() [8/8]

◆ insert_or_assign()

◆ is_array()

◆ is_boolean()

◆ is_float()

◆ is_null()

◆ is_object()

◆ is_object_like()

◆ is_signed_integer()

◆ is_string()

◆ is_unsigned_integer()

◆ merge() [1/4]

◆ merge() [2/4]

◆ merge() [3/4]

◆ merge() [4/4]

◆ operator json_array_type()

◆ operator json_null_type()

◆ operator json_object_type()

◆ operator json_string_type()

◆ operator std::array< T, N >()

◆ operator T() [1/5]

◆ operator T() [2/5]

◆ operator T() [3/5]

◆ operator T() [4/5]