JSON

A full-blown ECMA-404 implementation with read, write, and iterators support. More...

Classes
class	sourcemeta::jsontoolkit::JSONArray< Value >
class	sourcemeta::jsontoolkit::ParseError
class	sourcemeta::jsontoolkit::FileParseError
struct	sourcemeta::jsontoolkit::FastHash< T >
struct	sourcemeta::jsontoolkit::KeyHash< T >
class	sourcemeta::jsontoolkit::JSONObject< Key, Value, Hash >
class	sourcemeta::jsontoolkit::JSON

Typedefs
using	sourcemeta::jsontoolkit::Hash = FastHash< JSON >
using	sourcemeta::jsontoolkit::Callback = std::function< void(const CallbackPhase phase, const JSON::Type type, const std::uint64_t line, const std::uint64_t column, const JSON &value)>
using	sourcemeta::jsontoolkit::KeyComparison = std::function< bool(const JSON::String &, const JSON::String &)>

Enumerations
enum class	CallbackPhase { Pre , Post }

Functions
auto	sourcemeta::jsontoolkit::parse (std::basic_istream< JSON::Char, JSON::CharTraits > &stream, const Callback &callback=nullptr) -> JSON
auto	sourcemeta::jsontoolkit::parse (const std::basic_string< JSON::Char, JSON::CharTraits > &input, const Callback &callback=nullptr) -> JSON
auto	sourcemeta::jsontoolkit::parse (std::basic_istream< JSON::Char, JSON::CharTraits > &stream, std::uint64_t &line, std::uint64_t &column, const Callback &callback=nullptr) -> JSON
auto	sourcemeta::jsontoolkit::parse (const std::basic_string< JSON::Char, JSON::CharTraits > &input, std::uint64_t &line, std::uint64_t &column, const Callback &callback=nullptr) -> JSON
auto	sourcemeta::jsontoolkit::read_file (const std::filesystem::path &path) -> std::basic_ifstream< JSON::Char, JSON::CharTraits >
auto	sourcemeta::jsontoolkit::from_file (const std::filesystem::path &path) -> JSON
auto	sourcemeta::jsontoolkit::stringify (const JSON &document, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream) -> void
auto	sourcemeta::jsontoolkit::prettify (const JSON &document, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream) -> void
auto	sourcemeta::jsontoolkit::stringify (const JSON &document, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream, const KeyComparison &compare) -> void
auto	sourcemeta::jsontoolkit::prettify (const JSON &document, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream, const KeyComparison &compare) -> void
auto	sourcemeta::jsontoolkit::operator<< (std::basic_ostream< JSON::Char, JSON::CharTraits > &stream, const JSON &document) -> std::basic_ostream< JSON::Char, JSON::CharTraits > &
auto	sourcemeta::jsontoolkit::operator<< (std::basic_ostream< JSON::Char, JSON::CharTraits > &stream, const JSON::Type type) -> std::basic_ostream< JSON::Char, JSON::CharTraits > &

Detailed Description

A full-blown ECMA-404 implementation with read, write, and iterators support.

This functionality is included as follows:

#include <sourcemeta/jsontoolkit/json.h>

---

Class Documentation

sourcemeta::jsontoolkit::JSONArray

class sourcemeta::jsontoolkit::JSONArray

template<typename Value>
class sourcemeta::jsontoolkit::JSONArray< Value >

Public Types
using	Container = std::vector< Value, typename Value::template Allocator< Value > >
using	value_type = typename Container::value_type
using	allocator_type = typename Container::allocator_type
using	size_type = typename Container::size_type
using	difference_type = typename Container::difference_type
using	reference = typename Container::reference
using	const_reference = typename Container::const_reference
using	pointer = typename Container::pointer
using	const_pointer = typename Container::const_pointer
using	iterator = typename Container::iterator
using	const_iterator = typename Container::const_iterator
using	reverse_iterator = typename Container::reverse_iterator
using	const_reverse_iterator = typename Container::const_reverse_iterator
Public Member Functions
	JSONArray (std::initializer_list< Value > values)
auto	operator< (const JSONArray< Value > &other) const noexcept -> bool
auto	operator<= (const JSONArray< Value > &other) const noexcept -> bool
auto	operator> (const JSONArray< Value > &other) const noexcept -> bool
auto	operator>= (const JSONArray< Value > &other) const noexcept -> bool
auto	operator== (const JSONArray< Value > &other) const noexcept -> bool
auto	operator!= (const JSONArray< Value > &other) const noexcept -> bool
auto	begin () noexcept -> iterator
	Get a mutable begin iterator on the array.
auto	end () noexcept -> iterator
	Get a mutable end iterator on the array.
auto	begin () const noexcept -> const_iterator
	Get a constant begin iterator on the array.
auto	end () const noexcept -> const_iterator
	Get a constant end iterator on the array.
auto	cbegin () const noexcept -> const_iterator
	Get a constant begin iterator on the array.
auto	cend () const noexcept -> const_iterator
	Get a constant end iterator on the array.
auto	rbegin () noexcept -> reverse_iterator
	Get a mutable reverse begin iterator on the array.
auto	rend () noexcept -> reverse_iterator
	Get a mutable reverse end iterator on the array.
auto	rbegin () const noexcept -> const_reverse_iterator
	Get a constant reverse begin iterator on the array.
auto	rend () const noexcept -> const_reverse_iterator
	Get a constant reverse end iterator on the array.
auto	crbegin () const noexcept -> const_reverse_iterator
	Get a constant reverse begin iterator on the array.
auto	crend () const noexcept -> const_reverse_iterator
	Get a constant reverse end iterator on the array.

sourcemeta::jsontoolkit::ParseError

class sourcemeta::jsontoolkit::ParseError

This class represents a parsing error

Inheritance diagram for sourcemeta::jsontoolkit::ParseError:

Public Member Functions
	ParseError (const std::uint64_t line, const std::uint64_t column)
	Create a parsing error.
auto	what () const noexcept -> const char *override
auto	line () const noexcept -> std::uint64_t
	Get the line number of the error.
auto	column () const noexcept -> std::uint64_t

sourcemeta::jsontoolkit::FileParseError

class sourcemeta::jsontoolkit::FileParseError

This class represents a parsing error occurring from parsing a file

Inheritance diagram for sourcemeta::jsontoolkit::FileParseError:

Public Member Functions
	FileParseError (const std::filesystem::path &path, const std::uint64_t line, const std::uint64_t column)
	Create a file parsing error.
	FileParseError (const std::filesystem::path &path, const ParseError &parent)
	Create a file parsing error from a parse error.
auto	path () const noexcept -> const std::filesystem::path
	Get the fiel path of the error.
Public Member Functions inherited from sourcemeta::jsontoolkit::ParseError
	ParseError (const std::uint64_t line, const std::uint64_t column)
	Create a parsing error.
auto	what () const noexcept -> const char *override
auto	line () const noexcept -> std::uint64_t
	Get the line number of the error.
auto	column () const noexcept -> std::uint64_t

sourcemeta::jsontoolkit::FastHash

struct sourcemeta::jsontoolkit::FastHash

template<typename T>
struct sourcemeta::jsontoolkit::FastHash< T >

Public Types
using	hash_type = std::uint64_t
Public Member Functions
auto	operator() (const T &value) const noexcept -> hash_type
auto	is_perfect (const hash_type) const noexcept -> bool

sourcemeta::jsontoolkit::KeyHash

struct sourcemeta::jsontoolkit::KeyHash

template<typename T>
struct sourcemeta::jsontoolkit::KeyHash< T >

Public Member Functions
auto	perfect (const T &value, const std::size_t size) const noexcept -> hash_type
auto	operator() (const T &value) const noexcept -> hash_type
auto	is_perfect (const hash_type &hash) const noexcept -> bool

sourcemeta::jsontoolkit::JSONObject

class sourcemeta::jsontoolkit::JSONObject

template<typename Key, typename Value, typename Hash>
class sourcemeta::jsontoolkit::JSONObject< Key, Value, Hash >

Public Types
using	Container = sourcemeta::noa::FlatMap< Key, Value, Hash >
using	key_type = typename Container::key_type
using	mapped_type = typename Container::mapped_type
using	value_type = typename Container::Entry
using	size_type = typename Container::size_type
using	difference_type = typename Container::difference_type
using	allocator_type = typename Container::allocator_type
using	reference = typename Container::reference
using	const_reference = typename Container::const_reference
using	pointer = typename Container::pointer
using	const_pointer = typename Container::const_pointer
using	const_iterator = typename Container::const_iterator
Public Member Functions
	JSONObject (std::initializer_list< typename Container::value_type > values)
auto	operator< (const JSONObject< Key, Value, Hash > &other) const noexcept -> bool
auto	operator<= (const JSONObject< Key, Value, Hash > &other) const noexcept -> bool
auto	operator> (const JSONObject< Key, Value, Hash > &other) const noexcept -> bool
auto	operator>= (const JSONObject< Key, Value, Hash > &other) const noexcept -> bool
auto	operator== (const JSONObject< Key, Value, Hash > &other) const noexcept -> bool
auto	operator!= (const JSONObject< Key, Value, Hash > &other) const noexcept -> bool
auto	begin () const noexcept -> const_iterator
auto	end () const noexcept -> const_iterator
	Get a constant end iterator on the object.
auto	cbegin () const noexcept -> const_iterator
	Get a constant begin iterator on the object.
auto	cend () const noexcept -> const_iterator
	Get a constant end iterator on the object.
auto	find (const Key &key) const -> const_iterator
	Attempt to find an entry by key.
auto	defines (const Key &key, const typename Container::hash_type hash) const -> bool
	Check if an entry with the given key exists.
auto	size () const -> std::size_t
	Check the size of the object.
auto	at (const size_type index) const noexcept -> const Container::Entry &
	Access an object entry by its underlying positional index.

sourcemeta::jsontoolkit::JSON

class sourcemeta::jsontoolkit::JSON

Public Types
enum class	Type : std::uint8_t {   Null = 0 , Boolean = 1 , Integer = 2 , Real = 3 ,   String = 4 , Array = 5 , Object = 6 }
	The different types of a JSON instance.
using	Char = char
	The character type used by the JSON document.
using	CharTraits = std::char_traits< Char >
	The character traits used by the JSON document.
using	Integer = std::int64_t
	The integer type used by the JSON document.
using	Real = double
	The real type used by the JSON document.
template<typename T >
using	Allocator = std::allocator< T >
	The allocator used by the JSON document.
using	String = std::basic_string< Char, CharTraits, Allocator< Char > >
	The string type used by the JSON document.
using	Array = JSONArray< JSON >
	The array type used by the JSON document.
using	Object = JSONObject< String, JSON, KeyHash< JSON::String > >
	The object type used by the JSON document.
Public Member Functions
	JSON (const std::int64_t value)
	JSON (const std::size_t value)
	JSON (const int value)
template<typename T = std::int64_t, typename = std::enable_if_t<!std::is_same_v<T, std::int64_t>>>
	JSON (const long value)
	JSON (const double value)
	JSON (const float value)
	JSON (const bool value)
	JSON (const std::nullptr_t)
	JSON (const String &value)
	JSON (const std::basic_string_view< Char, CharTraits > &value)
	JSON (const Char *const value)
	JSON (std::initializer_list< JSON > values)
	JSON (const Array &value)
	A copy constructor for the array type.
	JSON (std::initializer_list< typename Object::Container::value_type > values)
	JSON (const Object &value)
	A copy constructor for the object type.
	JSON (const JSON &)
	Misc constructors.
	JSON (JSON &&)
auto	operator= (const JSON &) -> JSON &
auto	operator= (JSON &&) -> JSON &
	~JSON ()
	Destructor.
auto	operator< (const JSON &other) const noexcept -> bool
auto	operator<= (const JSON &other) const noexcept -> bool
auto	operator> (const JSON &other) const noexcept -> bool
auto	operator>= (const JSON &other) const noexcept -> bool
auto	operator== (const JSON &other) const noexcept -> bool
auto	operator!= (const JSON &) const noexcept -> bool=default
auto	operator+ (const JSON &other) const -> JSON
auto	operator- (const JSON &other) const -> JSON
auto	operator+= (const JSON &additive) -> JSON &
auto	operator-= (const JSON &substractive) -> JSON &
auto	is_boolean () const noexcept -> bool
auto	is_null () const noexcept -> bool
auto	is_integer () const noexcept -> bool
auto	is_real () const noexcept -> bool
auto	is_integer_real () const noexcept -> bool
auto	is_number () const noexcept -> bool
auto	is_positive () const noexcept -> bool
auto	is_string () const noexcept -> bool
auto	is_array () const noexcept -> bool
auto	is_object () const noexcept -> bool
auto	type () const noexcept -> Type
auto	to_boolean () const noexcept -> bool
auto	to_integer () const noexcept -> Integer
auto	to_real () const noexcept -> Real
auto	to_string () const noexcept -> const String &
auto	to_stringstream () const -> std::basic_istringstream< Char, CharTraits, Allocator< Char > >
auto	as_array () const noexcept -> const Array &
auto	as_array () noexcept -> Array &
auto	as_object () noexcept -> Object &
auto	as_object () const noexcept -> const Object &
auto	as_real () const noexcept -> Real
auto	as_integer () const noexcept -> Integer
auto	at (const typename Array::size_type index) const -> const JSON &
auto	at (const typename Array::size_type index) -> JSON &
auto	at (const String &key) const -> const JSON &
auto	at (const String &key, const typename Object::Container::hash_type hash) const -> const JSON &
auto	at (const String &key) -> JSON &
auto	at (const String &key, const typename Object::Container::hash_type hash) -> JSON &
auto	front () -> JSON &
auto	front () const -> const JSON &
auto	back () -> JSON &
auto	back () const -> const JSON &
auto	size () const -> std::size_t
auto	string_size () const -> std::size_t
auto	array_size () const -> std::size_t
auto	object_size () const -> std::size_t
auto	byte_size () const -> std::size_t
auto	estimated_byte_size () const -> std::uint64_t
auto	fast_hash () const -> std::uint64_t
auto	divisible_by (const JSON &divisor) const -> bool
auto	empty () const -> bool
auto	try_at (const String &key, const typename Object::Container::hash_type hash) const -> const JSON *
auto	defines (const String &key) const -> bool
auto	defines (const String &key, const typename Object::Container::hash_type hash) const -> bool
auto	defines (const typename Array::size_type index) const -> bool
template<typename Iterator >
auto	defines_any (Iterator begin, Iterator end) const -> bool
auto	defines_any (std::initializer_list< String > keys) const -> bool
auto	contains (const JSON &element) const -> bool
auto	contains (const String &input) const -> bool
auto	contains (const String::value_type input) const -> bool
auto	unique () const -> bool
auto	push_back (const JSON &value) -> void
auto	push_back (JSON &&value) -> void
auto	push_back_if_unique (const JSON &value) -> std::pair< std::reference_wrapper< const JSON >, bool >
auto	push_back_if_unique (JSON &&value) -> std::pair< std::reference_wrapper< const JSON >, bool >
auto	assign (const String &key, const JSON &value) -> void
auto	assign (const String &key, JSON &&value) -> void
auto	assign_if_missing (const String &key, const JSON &value) -> void
auto	assign_if_missing (const String &key, JSON &&value) -> void
auto	erase (const String &key) -> typename Object::size_type
template<typename Iterator >
auto	erase_keys (Iterator first, Iterator last) -> void
auto	erase_keys (std::initializer_list< String > keys) -> void
auto	erase (typename Array::const_iterator position) -> typename Array::iterator
auto	erase (typename Array::const_iterator first, typename Array::const_iterator last) -> typename Array::iterator
auto	clear () -> void
template<typename Iterator >
auto	clear_except (Iterator first, Iterator last) -> void
auto	clear_except (std::initializer_list< String > keys) -> void
auto	into (const JSON &other) -> void
auto	into (JSON &&other) noexcept -> void
auto	into_array () -> void
auto	into_object () -> void
Static Public Member Functions
static auto	make_array () -> JSON
static auto	make_object () -> JSON
static auto	size (const String &value) noexcept -> std::size_t

Constructor & Destructor Documentation

JSON() [1/12]

sourcemeta::jsontoolkit::JSON::JSON ( const std::int64_t  value )

explicit

This constructor creates a JSON document from an integer type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_integer{4};

JSON() [2/12]

sourcemeta::jsontoolkit::JSON::JSON ( const std::size_t  value )

explicit

This constructor creates a JSON document from an integer type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_integer{4};

JSON() [3/12]

sourcemeta::jsontoolkit::JSON::JSON ( const int  value )

explicit

This constructor creates a JSON document from an integer type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_integer{4};

JSON() [4/12]

sourcemeta::jsontoolkit::JSON::JSON ( const double  value )

explicit

This constructor creates a JSON document from an real number type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_real{3.14};

JSON() [5/12]

sourcemeta::jsontoolkit::JSON::JSON ( const float  value )

explicit

This constructor creates a JSON document from an real number type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_real{3.14};

JSON() [6/12]

sourcemeta::jsontoolkit::JSON::JSON ( const bool  value )

explicit

This constructor creates a JSON document from a boolean type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_boolean{true};

JSON() [7/12]

sourcemeta::jsontoolkit::JSON::JSON ( const std::nullptr_t  )

explicit

This constructor creates a JSON document from a null type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_null{nullptr};

JSON() [8/12]

sourcemeta::jsontoolkit::JSON::JSON ( const String &  value )

explicit

This constructor creates a JSON document from a string type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_string{"foo"};

JSON() [9/12]

sourcemeta::jsontoolkit::JSON::JSON ( const std::basic_string_view< Char, CharTraits > &  value )

explicit

This constructor creates a JSON document from a string type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_string{"foo"};

JSON() [10/12]

sourcemeta::jsontoolkit::JSON::JSON ( const Char *const  value )

explicit

This constructor creates a JSON document from a string type. For example:

#include <sourcemeta/jsontoolkit/json.h>
 
const sourcemeta::jsontoolkit::JSON my_string{"foo"};

JSON() [11/12]

sourcemeta::jsontoolkit::JSON::JSON ( std::initializer_list< JSON >  values )

explicit

This constructor creates a JSON array from a set of other JSON documents. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_array{
  sourcemeta::jsontoolkit::JSON{1},
  sourcemeta::jsontoolkit::JSON{2},
  sourcemeta::jsontoolkit::JSON{3}};
 
assert(my_array.is_array());

JSON() [12/12]

sourcemeta::jsontoolkit::JSON::JSON ( std::initializer_list< typename Object::Container::value_type >  values )

explicit

This constructor creates a JSON object from a pair of other JSON documents. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_object{
  {"foo", sourcemeta::jsontoolkit::JSON{1}},
  {"bar", sourcemeta::jsontoolkit::JSON{1}},
  {"baz", sourcemeta::jsontoolkit::JSON{1}}};
 
assert(my_object.is_object());

Member Function Documentation

array_size()

auto sourcemeta::jsontoolkit::JSON::array_size

(

)

const -> std::size_t

If the input JSON instance is an array, return its number of elements.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_array =
  sourcemeta::jsontoolkit::parse("[ 1, 2 ]");
assert(my_array.array_size() == 2);

as_array() [1/2]

auto sourcemeta::jsontoolkit::JSON::as_array ( ) const -> const Array &

noexcept

Get the JSON document as an array instance. This is convenient for using constant iterators on the array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <algorithm>
#include <iostream>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
std::for_each(document.as_array().cbegin(),
              document.as_array().cend(),
              [](const auto &element) {
                std::cout << "Element: "
                          << element.to_integer()
                          << "\n";
              });

as_array() [2/2]

auto sourcemeta::jsontoolkit::JSON::as_array ( ) -> Array &

noexcept

Get the JSON document as an array instance. This is convenient for using mutable iterators on the array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <algorithm>
#include <iostream>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
std::sort(document.as_array().begin(), document.as_array().end());

as_integer()

auto sourcemeta::jsontoolkit::JSON::as_integer ( ) const -> Integer

noexcept

Get the JSON numeric document as an integer number if it is not one already. If the number is a real number, truncation will take place. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{5.3};
assert(document.as_integer() == 5);

as_object() [1/2]

auto sourcemeta::jsontoolkit::JSON::as_object ( ) const -> const Object &

noexcept

Get the JSON document as an object instance. This is convenient for using mutable iterators on the object. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <algorithm>
#include <iostream>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_object();
document.assign("foo", sourcemeta::jsontoolkit::JSON{1});
document.assign("bar", sourcemeta::jsontoolkit::JSON{2});
document.assign("baz", sourcemeta::jsontoolkit::JSON{3});
 
for (auto &[key, value] : document.as_object()) {
  value += sourcemeta::jsontoolkit::JSON{1};
}

as_object() [2/2]

auto sourcemeta::jsontoolkit::JSON::as_object ( ) -> Object &

noexcept

Get the JSON document as an object instance. This is convenient for using constant iterators on the object. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <algorithm>
#include <iostream>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_object();
document.assign("foo", sourcemeta::jsontoolkit::JSON{1});
document.assign("bar", sourcemeta::jsontoolkit::JSON{2});
document.assign("baz", sourcemeta::jsontoolkit::JSON{3});
 
std::for_each(document.as_object().cbegin(),
              document.as_object().cend(),
              [](const auto &pair) {
                std::cout << "Value: "
                          << pair.second.to_integer()
                          << "\n";
              });

as_real()

auto sourcemeta::jsontoolkit::JSON::as_real ( ) const -> Real

noexcept

Get the JSON numeric document as a real number if it is not one already. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{5};
assert(document.as_real() == 5.0);

assign() [1/2]

auto sourcemeta::jsontoolkit::JSON::assign	(	const String &	key,
		const JSON &	value
	)		-> void

This method sets or updates an object key. For example, an object can be updated to contain a new bar boolean member as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
const sourcemeta::jsontoolkit::JSON value{false};
document.assign("bar", value);
assert(document.defines("foo"));
assert(document.defines("bar"));

assign() [2/2]

auto sourcemeta::jsontoolkit::JSON::assign	(	const String &	key,
		JSON &&	value
	)		-> void

This method sets or updates an object key. For example, an object can be updated to contain a new bar boolean member as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
document.assign("bar", sourcemeta::jsontoolkit::JSON{false});
assert(document.defines("foo"));
assert(document.defines("bar"));

assign_if_missing() [1/2]

auto sourcemeta::jsontoolkit::JSON::assign_if_missing	(	const String &	key,
		const JSON &	value
	)		-> void

This method sets an object key if it is not already defined. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
 
const sourcemeta::jsontoolkit::JSON value_1{1};
const sourcemeta::jsontoolkit::JSON value_2{2};
 
document.assign_if_missing("foo", value_1);
document.assign_if_missing("bar", value_2);
 
assert(document.defines("foo"));
assert(document.at("foo").is_boolean());
assert(document.defines("bar"));
assert(document.at("bar").is_integer());

assign_if_missing() [2/2]

auto sourcemeta::jsontoolkit::JSON::assign_if_missing	(	const String &	key,
		JSON &&	value
	)		-> void

This method sets an object key if it is not already defined. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
 
document.assign_if_missing("foo", sourcemeta::jsontoolkit::JSON{1});
document.assign_if_missing("bar", sourcemeta::jsontoolkit::JSON{2});
 
assert(document.defines("foo"));
assert(document.at("foo").is_boolean());
assert(document.defines("bar"));
assert(document.at("bar").is_integer());

at() [1/6]

auto sourcemeta::jsontoolkit::JSON::at

(

const String &

key

)

-> JSON &

This method retrieves an object element.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1, \"bar\": 2 }");
assert(my_object.at("bar").to_integer() == 2);

at() [2/6]

auto sourcemeta::jsontoolkit::JSON::at

(

const String &

key

)

const -> const JSON &

This method retrieves an object element.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1, \"bar\": 2 }");
assert(my_object.at("bar").to_integer() == 2);

at() [3/6]

auto sourcemeta::jsontoolkit::JSON::at	(	const String &	key,
		const typename Object::Container::hash_type	hash
	)		-> JSON &

This method retrieves an object element given a pre-calculated property hash.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1, \"bar\": 2 }");
const sourcemeta::jsontoolkit::Hash hasher;
assert(my_object.at("bar", hasher("bar")).to_integer() == 2);

at() [4/6]

auto sourcemeta::jsontoolkit::JSON::at	(	const String &	key,
		const typename Object::Container::hash_type	hash
	)		const -> const JSON &

This method retrieves an object element given a pre-calculated property hash.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1, \"bar\": 2 }");
const sourcemeta::jsontoolkit::Hash hasher;
assert(my_object.at("bar", hasher("bar")).to_integer() == 2);

at() [5/6]

auto sourcemeta::jsontoolkit::JSON::at

(

const typename Array::size_type

index

)

-> JSON &

This method retrieves a element by its index. If the input JSON instance is an object, a property that corresponds to the stringified integer will be accessed.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON my_array =
  sourcemeta::jsontoolkit::parse("[ 1, 2 ]");
assert(my_array.at(1).to_integer() == 2);
 
sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"1\": "foo" }");
assert(my_array.at(1).to_string() == "foo");

at() [6/6]

auto sourcemeta::jsontoolkit::JSON::at

(

const typename Array::size_type

index

)

const -> const JSON &

This method retrieves a element by its index. If the input JSON instance is an object, a property that corresponds to the stringified integer will be accessed.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_array =
  sourcemeta::jsontoolkit::parse("[ 1, 2 ]");
assert(my_array.at(1).to_integer() == 2);
 
const sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"1\": "foo" }");
assert(my_array.at(1).to_string() == "foo");

back() [1/2]

auto sourcemeta::jsontoolkit::JSON::back

(

)

-> JSON &

This method retrieves a reference to the last element of a JSON array. This method is undefined if the input JSON instance is an empty array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.back().to_integer() == 3);

back() [2/2]

auto sourcemeta::jsontoolkit::JSON::back

(

)

const -> const JSON &

This method retrieves a reference to the last element of a JSON array. This method is undefined if the input JSON instance is an empty array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.back().to_integer() == 3);

byte_size()

auto sourcemeta::jsontoolkit::JSON::byte_size

(

)

const -> std::size_t

If the input JSON instance is string, input JSON instance is a string, return its number of bytes. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_string{
  sourcemeta::jsontoolkit::parse("\"\\uD83D\\uDCA9\"")};
assert(my_string.size() == 2);

clear()

auto sourcemeta::jsontoolkit::JSON::clear

(

)

-> void

This method deletes all members of an object or all elements of an array, leaving them empty. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
sourcemeta::jsontoolkit::JSON my_array =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
my_object.clear();
my_array.clear();
assert(my_object.empty());
assert(my_array.empty());

clear_except() [1/2]

template<typename Iterator >

auto sourcemeta::jsontoolkit::JSON::clear_except ( Iterator  first, Iterator  last  ) -> void

inline

This method deletes all members of an object except for the JSON keys declares as the second argument. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <string>
#include <vector>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_object();
document.assign("foo", sourcemeta::jsontoolkit::JSON{true});
document.assign("bar", sourcemeta::jsontoolkit::JSON{false});
document.assign("baz", sourcemeta::jsontoolkit::JSON{true});
 
const std::vector<std::string> keys{"foo"};
document.clear_except(keys.cbegin(), keys.cend());
 
assert(document.defines("foo"));
assert(!document.defines("bar"));
assert(!document.defines("baz"));

clear_except() [2/2]

auto sourcemeta::jsontoolkit::JSON::clear_except

(

std::initializer_list< String >

keys

)

-> void

This method deletes all members of an object except for the JSON keys declares as the second argument. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_object();
document.assign("foo", sourcemeta::jsontoolkit::JSON{true});
document.assign("bar", sourcemeta::jsontoolkit::JSON{false});
document.assign("baz", sourcemeta::jsontoolkit::JSON{true});
 
document.clear_except({ "foo" });
 
assert(document.defines("foo"));
assert(!document.defines("bar"));
assert(!document.defines("baz"));

contains() [1/3]

auto sourcemeta::jsontoolkit::JSON::contains

(

const JSON &

element

)

const -> bool

This method checks if an JSON array contains a given JSON instance. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.contains(sourcemeta::jsontoolkit::JSON{2}));
assert(!document.contains(sourcemeta::jsontoolkit::JSON{4}));

contains() [2/3]

auto sourcemeta::jsontoolkit::JSON::contains

(

const String &

input

)

const -> bool

This method checks if an JSON string contains a given string. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{"foo bar baz"};
assert(document.contains("bar"));
assert(!document.contains("baz"));

contains() [3/3]

auto sourcemeta::jsontoolkit::JSON::contains

(

const String::value_type

input

)

const -> bool

This method checks if an JSON string contains a given character. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{"foo"};
assert(document.contains('f'));
assert(!document.contains('b'));

defines() [1/3]

auto sourcemeta::jsontoolkit::JSON::defines

(

const String &

key

)

const -> bool

This method checks whether an input JSON object defines a specific key. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
assert(document.defines("foo"));
assert(!document.defines("bar"));

defines() [2/3]

auto sourcemeta::jsontoolkit::JSON::defines	(	const String &	key,
		const typename Object::Container::hash_type	hash
	)		const -> bool

This method checks whether an input JSON object defines a specific key given a pre-calculated property hash. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
const sourcemeta::jsontoolkit::Hash hasher;
assert(document.defines("foo", hasher("foo")));
assert(!document.defines("bar", hasher("bar")));

defines() [3/3]

auto sourcemeta::jsontoolkit::JSON::defines

(

const typename Array::size_type

index

)

const -> bool

This method checks whether an input JSON object defines a specific integer key. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"0\": 1 }");
assert(document.defines(0));
assert(!document.defines(1));

defines_any() [1/2]

template<typename Iterator >

auto sourcemeta::jsontoolkit::JSON::defines_any ( Iterator  begin, Iterator  end  ) const -> bool

inline

This method checks whether an input JSON object defines at least one given key.

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <string>
#include <vector>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true, \"bar\": false }");
 
const std::vector<std::string> keys{"foo", "qux"};
assert(document.defines_any(keys.cbegin(), keys.cend()));

defines_any() [2/2]

auto sourcemeta::jsontoolkit::JSON::defines_any

(

std::initializer_list< String >

keys

)

const -> bool

This method checks whether an input JSON object defines at least one given key.

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true, \"bar\": false }");
 
assert(document.defines_any({ "foo", "qux" }));

divisible_by()

auto sourcemeta::jsontoolkit::JSON::divisible_by

(

const JSON &

divisor

)

const -> bool

Check whether a numeric instance is divisible by another numeric instance. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON dividend{6};
const sourcemeta::jsontoolkit::JSON divisor{1.5};
 
assert(dividend.divisible_by(divisor));

empty()

auto sourcemeta::jsontoolkit::JSON::empty

(

)

const -> bool

A convenience method to check whether the input JSON document is an empty object, empty array or empty string.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{}");
const sourcemeta::jsontoolkit::JSON my_array =
  sourcemeta::jsontoolkit::parse("[]");
const sourcemeta::jsontoolkit::JSON my_string{""};
 
assert(my_object.empty());
assert(my_array.empty());
assert(my_string.empty());

erase() [1/3]

auto sourcemeta::jsontoolkit::JSON::erase

(

const String &

key

)

-> typename Object::size_type

This method deletes an object key. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
document.erase("foo");
assert(!document.defines("foo"));

erase() [2/3]

auto sourcemeta::jsontoolkit::JSON::erase	(	typename Array::const_iterator	first,
		typename Array::const_iterator	last
	)		-> typename Array::iterator

This method deletes a set of array elements using iterators. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <iterator>
 
sourcemeta::jsontoolkit::JSON array =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
array.erase(std::next(array.begin()), array.end());
assert(array.size(), 1);
assert(array.at(0), 1);

erase() [3/3]

auto sourcemeta::jsontoolkit::JSON::erase

(

typename Array::const_iterator

position

)

-> typename Array::iterator

This method deletes an array element using an iterator. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <iterator>
 
sourcemeta::jsontoolkit::JSON array =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
array.erase(std::next(array.begin()));
assert(array.size(), 2);
assert(array.at(0), 1);
assert(array.at(1), 3);

erase_keys() [1/2]

template<typename Iterator >

auto sourcemeta::jsontoolkit::JSON::erase_keys ( Iterator  first, Iterator  last  ) -> void

inline

This method deletes a set of object keys. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <string>
#include <vector>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_object();
document.assign("foo", sourcemeta::jsontoolkit::JSON{true});
document.assign("bar", sourcemeta::jsontoolkit::JSON{false});
document.assign("baz", sourcemeta::jsontoolkit::JSON{true});
 
const std::vector<std::string> keys{"foo", "bar"};
document.erase_keys(keys.cbegin(), keys.cend());
 
assert(!document.defines("foo"));
assert(!document.defines("bar"));
assert(document.defines("baz"));

erase_keys() [2/2]

auto sourcemeta::jsontoolkit::JSON::erase_keys

(

std::initializer_list< String >

keys

)

-> void

This method deletes a set of object keys. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_object();
document.assign("foo", sourcemeta::jsontoolkit::JSON{true});
document.assign("bar", sourcemeta::jsontoolkit::JSON{false});
document.assign("baz", sourcemeta::jsontoolkit::JSON{true});
 
document.erase_keys({ "foo", "bar" });
 
assert(!document.defines("foo"));
assert(!document.defines("bar"));
assert(document.defines("baz"));

estimated_byte_size()

auto sourcemeta::jsontoolkit::JSON::estimated_byte_size

(

)

const -> std::uint64_t

Estimate the byte size occupied by the given parsed JSON instance (not its stringified representation). Keep in mind that as the method name implies, this is just a rough estimate. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON value =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
 
// Byte length of "foo" (3) + byte length of 1 (8)
assert(value.estimated_byte_size() == 11);

fast_hash()

auto sourcemeta::jsontoolkit::JSON::fast_hash

(

)

const -> std::uint64_t

Produce a simple hash for the JSON value. Note the hash is fast to produce but might have a higher chance of collisions. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON value_1 =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
 
const sourcemeta::jsontoolkit::JSON value_2 =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
 
assert(value_1.fast_hash() == value_2.fast_hash());

front() [1/2]

auto sourcemeta::jsontoolkit::JSON::front

(

)

-> JSON &

This method retrieves a reference to the first element of a JSON array. This method is undefined if the input JSON instance is an empty array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.front().to_integer() == 1);

front() [2/2]

auto sourcemeta::jsontoolkit::JSON::front

(

)

const -> const JSON &

This method retrieves a reference to the first element of a JSON array. This method is undefined if the input JSON instance is an empty array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.front().to_integer() == 1);

into() [1/2]

auto sourcemeta::jsontoolkit::JSON::into

(

const JSON &

other

)

-> void

This method sets a value to another JSON value by copying it. For example, the member of a JSON document can be transformed from a boolean to an integer as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
const sourcemeta::jsontoolkit::JSON value{2};
document.at("foo").into(value);
assert(document.at("foo").is_integer());

into() [2/2]

auto sourcemeta::jsontoolkit::JSON::into ( JSON &&  other ) -> void

noexcept

This method sets a value to another JSON value. For example, the member of a JSON document can be transformed from a boolean to an integer as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": true }");
document.at("foo").into(sourcemeta::jsontoolkit::JSON{2});
assert(document.at("foo").is_integer());

into_array()

auto sourcemeta::jsontoolkit::JSON::into_array

(

)

-> void

This method converts an existing JSON instance into an empty array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document{true};
assert(document.is_boolean());
document.into_array();
assert(document.is_array());
assert(document.empty());

into_object()

auto sourcemeta::jsontoolkit::JSON::into_object

(

)

-> void

This method converts an existing JSON instance into an empty object. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document{true};
assert(document.is_boolean());
document.into_object();
assert(document.is_object());
assert(document.empty());

is_array()

auto sourcemeta::jsontoolkit::JSON::is_array ( ) const -> bool

noexcept

Check if the input JSON document is an array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON
document=sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.is_array());

is_boolean()

auto sourcemeta::jsontoolkit::JSON::is_boolean ( ) const -> bool

noexcept

Check if the input JSON document is a boolean. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{true};
assert(document.is_boolean());

is_integer()

auto sourcemeta::jsontoolkit::JSON::is_integer ( ) const -> bool

noexcept

Check if the input JSON document is an integer. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{5};
assert(document.is_integer());

is_integer_real()

auto sourcemeta::jsontoolkit::JSON::is_integer_real ( ) const -> bool

noexcept

Check if the input JSON document is a real number that represents an integer. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{5.0};
assert(document.is_integer_real());

is_null()

auto sourcemeta::jsontoolkit::JSON::is_null ( ) const -> bool

noexcept

Check if the input JSON document is null. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{nullptr};
assert(document.is_null());

is_number()

auto sourcemeta::jsontoolkit::JSON::is_number ( ) const -> bool

noexcept

Check if the input JSON document is either an integer or a real type. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON real{3.14};
const sourcemeta::jsontoolkit::JSON integer{5};
assert(real.is_number());
assert(integer.is_number());

is_object()

auto sourcemeta::jsontoolkit::JSON::is_object ( ) const -> bool

noexcept

Check if the input JSON document is an object. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON
document=sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
assert(document.is_object());

is_positive()

auto sourcemeta::jsontoolkit::JSON::is_positive ( ) const -> bool

noexcept

Check if the input JSON document is either a positive integer or a positive real number. Zero is considered to be positive. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON real{3.14};
const sourcemeta::jsontoolkit::JSON integer{-5};
assert(real.is_positive());
assert(!integer.is_positive());

is_real()

auto sourcemeta::jsontoolkit::JSON::is_real ( ) const -> bool

noexcept

Check if the input JSON document is a real type. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{3.14};
assert(document.is_real());

is_string()

auto sourcemeta::jsontoolkit::JSON::is_string ( ) const -> bool

noexcept

Check if the input JSON document is a string. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{"foo"};
assert(document.is_string());

make_array()

static auto sourcemeta::jsontoolkit::JSON::make_array ( ) -> JSON

static

This function creates an empty JSON array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_array();
assert(document.is_array());
assert(document.empty());

This function is particularly handy for programatically constructing arrays.

make_object()

static auto sourcemeta::jsontoolkit::JSON::make_object ( ) -> JSON

static

This function creates an empty JSON object. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::JSON::make_object();
assert(document.is_object());
assert(document.empty());

This function is particularly handy for programatically constructing objects.

object_size()

auto sourcemeta::jsontoolkit::JSON::object_size

(

)

const -> std::size_t

If the input JSON instance is an object, return its number of pairs.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
assert(my_object.object_size() == 1);

operator+()

auto sourcemeta::jsontoolkit::JSON::operator+

(

const JSON &

other

)

const -> JSON

Add two numeric JSON instances and get a new instance with the result. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON left{5};
const sourcemeta::jsontoolkit::JSON right{3};
const sourcemeta::jsontoolkit::JSON result{left + right};
assert(result.is_integer());
assert(document.to_integer() == 8);

operator+=()

auto sourcemeta::jsontoolkit::JSON::operator+=

(

const JSON &

additive

)

-> JSON &

This operator adds a numeric JSON instance to another numeric JSON instance. For example, a numeric JSON instance 3.2 can be added to a numeric JSON instance 5 as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document{5};
const sourcemeta::jsontoolkit::JSON additive{3.2};
document += additive;
assert(document.is_real());
assert(document.to_real() == 8.2);

operator-()

auto sourcemeta::jsontoolkit::JSON::operator-

(

const JSON &

other

)

const -> JSON

Substract two numeric JSON instances and get a new instance with the result. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON left{5};
const sourcemeta::jsontoolkit::JSON right{3};
const sourcemeta::jsontoolkit::JSON result{left - right};
assert(result.is_integer());
assert(document.to_integer() == 2);

operator-=()

auto sourcemeta::jsontoolkit::JSON::operator-=

(

const JSON &

substractive

)

-> JSON &

This operator substracts a numeric JSON instance from another numeric JSON instance. For example, a numeric JSON instance 3.2 can be substracted from a numeric JSON instance 5 as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document{5};
const sourcemeta::jsontoolkit::JSON substractive{3.2};
document -= substractive;
assert(document.is_real());
assert(document.to_real() == 1.8);

push_back() [1/2]

auto sourcemeta::jsontoolkit::JSON::push_back

(

const JSON &

value

)

-> void

This method inserts a new element to the end of the given array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
const sourcemeta::jsontoolkit::JSON value{4};
document.push_back(value);
assert(document.size() == 4);
assert(document.back().to_integer() == 4);

push_back() [2/2]

auto sourcemeta::jsontoolkit::JSON::push_back

(

JSON &&

value

)

-> void

This method inserts a new element to the end of the given array. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
document.push_back(sourcemeta::jsontoolkit::JSON{4});
assert(document.size() == 4);
assert(document.back().to_integer() == 4);

push_back_if_unique() [1/2]

auto sourcemeta::jsontoolkit::JSON::push_back_if_unique

(

const JSON &

value

)

-> std::pair< std::reference_wrapper< const JSON >, bool >

This method inserts a new element to the end of the given array if an equal element is not already present in the array. The return value is a pair consisting of a reference to the element in question and whether the element was inserted or not. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
const sourcemeta::jsontoolkit::JSON new_element{3};
const auto result{document.push_back_if_unique(new_element)};
assert(result.first.get().to_integer() == 3);
assert(!result.second);

push_back_if_unique() [2/2]

auto sourcemeta::jsontoolkit::JSON::push_back_if_unique

(

JSON &&

value

)

-> std::pair< std::reference_wrapper< const JSON >, bool >

This method inserts a new element to the end of the given array if an equal element is not already present in the array. The return value is a pair consisting of a reference to the element in question and whether the element was inserted or not. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <utility>
 
sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
sourcemeta::jsontoolkit::JSON new_element{3};
const auto result{document.push_back_if_unique(std::move(new_element)};
assert(result.first.get().to_integer() == 3);
assert(!result.second);

size() [1/2]

auto sourcemeta::jsontoolkit::JSON::size

(

)

const -> std::size_t

If the input JSON instance is an object, return its number of pairs. If the input JSON instance is an array, return its number of elements. If the input JSON instance is a string, return its logical length.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_object =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }");
const sourcemeta::jsontoolkit::JSON my_array =
  sourcemeta::jsontoolkit::parse("[ 1, 2 ]");
const sourcemeta::jsontoolkit::JSON my_string{"foo"};
 
assert(my_object.size() == 1);
assert(my_array.size() == 2);
assert(my_string.size() == 3);

size() [2/2]

static auto sourcemeta::jsontoolkit::JSON::size ( const String &  value ) -> std::size_t

staticnoexcept

This function calculates the logical size of a string according to the JSON specification. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON::String value{"foo"};
assert(sourcemeta::jsontoolkit::JSON::size(value) == 3);

string_size()

auto sourcemeta::jsontoolkit::JSON::string_size

(

)

const -> std::size_t

If the input JSON instance is a string, return its logical length.

For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON my_string{"foo"};
assert(my_string.string_size() == 3);

to_boolean()

auto sourcemeta::jsontoolkit::JSON::to_boolean ( ) const -> bool

noexcept

Convert a JSON instance into a boolean value. The result of this method is undefined unless the JSON instance holds a boolean value. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{true};
assert(document.is_boolean());
assert(document.to_boolean());

to_integer()

auto sourcemeta::jsontoolkit::JSON::to_integer ( ) const -> Integer

noexcept

Convert a JSON instance into a signed integer value. The result of this method is undefined unless the JSON instance holds an integer value. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{5};
assert(document.is_integer());
assert(document.to_integer() == 5);

to_real()

auto sourcemeta::jsontoolkit::JSON::to_real ( ) const -> Real

noexcept

Convert a JSON instance into an IEEE 64-bit floating-point value. The result of this method is undefined unless the JSON instance holds a real value. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{3.14};
assert(document.is_real());
assert(document.to_real() == 3.14);

to_string()

auto sourcemeta::jsontoolkit::JSON::to_string ( ) const -> const String &

noexcept

Convert a JSON instance into a standard string value. The result of this method is undefined unless the JSON instance holds a string value. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{"foo"};
assert(document.is_string());
assert(document.to_string() == "foo");

to_stringstream()

auto sourcemeta::jsontoolkit::JSON::to_stringstream

(

)

const -> std::basic_istringstream< Char, CharTraits, Allocator< Char > >

Get a standard input string stream from a JSON string. The result of this method is undefined unless the JSON instance holds a string value. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{"foo"};
assert(document.is_string());
auto stream{document.to_stringstream()};
assert(stream.get() == 'f');

try_at()

auto sourcemeta::jsontoolkit::JSON::try_at	(	const String &	key,
		const typename Object::Container::hash_type	hash
	)		const -> const JSON *

This method checks whether an input JSON object defines a specific key and returns the value if it does. For example:

```cpp #include <sourcemeta/jsontoolkit/json.h> #include <cassert>

const sourcemeta::jsontoolkit::JSON document = sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }"); EXPECT_TRUE(document.is_object()); const auto result = document.try_at("foo"); EXPECT_TRUE(result); EXPECT_EQ(result->to_integer(), 1); */ [[nodiscard]] auto try_at(const String &key) const -> const JSON *;

/** This method checks, given a pre-calculated hash, whether an input JSON object defines a specific key and returns the value if it does. For example:

```cpp #include <sourcemeta/jsontoolkit/json.h> #include <cassert>

const sourcemeta::jsontoolkit::JSON document = sourcemeta::jsontoolkit::parse("{ \"foo\": 1 }"); EXPECT_TRUE(document.is_object()); const sourcemeta::jsontoolkit::Hash hasher; const auto result = document.try_at("foo", hasher("foo")); EXPECT_TRUE(result); EXPECT_EQ(result->to_integer(), 1);

type()

auto sourcemeta::jsontoolkit::JSON::type ( ) const -> Type

noexcept

Get the type of the JSON document. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document{true};
assert(document.type() == sourcemeta::jsontoolkit::JSON::Type::Boolean);

unique()

auto sourcemeta::jsontoolkit::JSON::unique

(

)

const -> bool

This method checks if an JSON array does not contain duplicated items. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.unique());

Typedef Documentation

Callback

using sourcemeta::jsontoolkit::Callback = typedef std::function<void( const CallbackPhase phase, const JSON::Type type, const std::uint64_t line, const std::uint64_t column, const JSON &value)>

An optional callback that can be passed to parsing functions to obtain metadata during the parsing process. Each subdocument will emit 2 events: a "pre" and a "post". When parsing object and arrays, during the "pre" event, the value corresponds to the property name or index, respectively.

KeyComparison

using sourcemeta::jsontoolkit::KeyComparison = typedef std::function<bool(const JSON::String &, const JSON::String &)>

A comparison function between object property keys. See https://en.cppreference.com/w/cpp/named_req/Compare

Function Documentation

from_file()

auto sourcemeta::jsontoolkit::from_file

(

const std::filesystem::path &

path

)

-> JSON

A convenience function to create a JSON document from a file. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <iostream>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::from_file("/tmp/foo.json");
sourcemeta::jsontoolkit::stringify(document, std::cout);
std::cout << std::endl;

If parsing fails, sourcemeta::jsontoolkit::ParseError will be thrown.

operator<<() [1/2]

auto sourcemeta::jsontoolkit::operator<<	(	std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream,
		const JSON &	document
	)		-> std::basic_ostream< JSON::Char, JSON::CharTraits > &

Encode the input JSON document into a given standard output stream. The JSON document is stringified or prettified depending on the presence of the NDEBUG define (for debugging purposes). For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <iostream>
#include <sstream>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
std::ostringstream stream;
stream << document;
std::cout << stream.str() << std::endl;

operator<<() [2/2]

auto sourcemeta::jsontoolkit::operator<<	(	std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream,
		const JSON::Type	type
	)		-> std::basic_ostream< JSON::Char, JSON::CharTraits > &

Encode the input JSON type as a string into a given standard output stream. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <iostream>
#include <sstream>
 
std::ostringstream stream;
stream << sourcemeta::jsontoolkit::JSON::Type::String;
// Will print "string"
std::cout << stream.str() << std::endl;

parse() [1/4]

auto sourcemeta::jsontoolkit::parse	(	const std::basic_string< JSON::Char, JSON::CharTraits > &	input,
		const Callback &	callback = nullptr
	)		-> JSON

Create a JSON document from a JSON string. For example, a JSON document that represents an array can be parsed as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
assert(document.is_array());

If parsing fails, sourcemeta::jsontoolkit::ParseError will be thrown.

parse() [2/4]

auto sourcemeta::jsontoolkit::parse	(	const std::basic_string< JSON::Char, JSON::CharTraits > &	input,
		std::uint64_t &	line,
		std::uint64_t &	column,
		const Callback &	callback = nullptr
	)		-> JSON

Create a JSON document from a JSON string, passing your own line and column read/write position indicators. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
 
std::uint64_t line{1};
std::uint64_t column{0};
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]", line, column);
assert(document.is_array());

parse() [3/4]

auto sourcemeta::jsontoolkit::parse	(	std::basic_istream< JSON::Char, JSON::CharTraits > &	stream,
		const Callback &	callback = nullptr
	)		-> JSON

Create a JSON document from a C++ standard input stream. For example, a JSON document that represents an array can be parsed as follows:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ 1, 2, 3 ]"};
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse(stream);
assert(document.is_array());

If parsing fails, sourcemeta::jsontoolkit::ParseError will be thrown.

parse() [4/4]

auto sourcemeta::jsontoolkit::parse	(	std::basic_istream< JSON::Char, JSON::CharTraits > &	stream,
		std::uint64_t &	line,
		std::uint64_t &	column,
		const Callback &	callback = nullptr
	)		-> JSON

Create a JSON document from a C++ standard input stream, passing your own line and column read/write position indicators. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ 1, 2, 3 ]"};
std::uint64_t line{1};
std::uint64_t column{0};
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse(stream, line, column);
assert(document.is_array());

prettify() [1/2]

auto sourcemeta::jsontoolkit::prettify	(	const JSON &	document,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream
	)		-> void

Stringify the input JSON document into a given C++ standard output stream in pretty mode, indenting the output using 4 spaces. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <iostream>
#include <sstream>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
std::ostringstream stream;
sourcemeta::jsontoolkit::prettify(document, stream);
std::cout << stream.str() << std::endl;

prettify() [2/2]

auto sourcemeta::jsontoolkit::prettify	(	const JSON &	document,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream,
		const KeyComparison &	compare
	)		-> void

Stringify the input JSON document into a given C++ standard output stream in pretty mode, indenting the output using 4 spaces and sorting object properties on a specific criteria. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <iostream>
#include <sstream>
 
auto key_compare(const sourcemeta::jsontoolkit::JSON::String &left,
                 const sourcemeta::jsontoolkit::JSON::String &right)
  -> bool {
  return left < right;
}
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1, \"bar\": 2, \"baz\": 3 }");
std::ostringstream stream;
sourcemeta::jsontoolkit::prettify(document, stream, key_compare);
std::cout << stream.str() << std::endl;

read_file()

auto sourcemeta::jsontoolkit::read_file

(

const std::filesystem::path &

path

)

-> std::basic_ifstream< JSON::Char, JSON::CharTraits >

A convenience function to read a document from a file. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <cassert>
#include <iostream>
 
auto stream = sourcemeta::jsontoolkit::read_file("/tmp/foo.json");
const auto document = sourcemeta::jsontoolkit::parse(stream);
sourcemeta::jsontoolkit::stringify(document, std::cout);
std::cout << std::endl;

If parsing fails, sourcemeta::jsontoolkit::ParseError will be thrown.

stringify() [1/2]

auto sourcemeta::jsontoolkit::stringify	(	const JSON &	document,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream
	)		-> void

Stringify the input JSON document into a given C++ standard output stream in compact mode. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <iostream>
#include <sstream>
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("[ 1, 2, 3 ]");
std::ostringstream stream;
sourcemeta::jsontoolkit::stringify(document, stream);
std::cout << stream.str() << std::endl;

stringify() [2/2]

auto sourcemeta::jsontoolkit::stringify	(	const JSON &	document,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream,
		const KeyComparison &	compare
	)		-> void

Stringify the input JSON document into a given C++ standard output stream in compact mode, sorting object properties on a specific criteria. For example:

#include <sourcemeta/jsontoolkit/json.h>
#include <iostream>
#include <sstream>
 
auto key_compare(const sourcemeta::jsontoolkit::JSON::String &left,
                 const sourcemeta::jsontoolkit::JSON::String &right)
  -> bool {
  return left < right;
}
 
const sourcemeta::jsontoolkit::JSON document =
  sourcemeta::jsontoolkit::parse("{ \"foo\": 1, \"bar\": 2, \"baz\": 3 }");
std::ostringstream stream;
sourcemeta::jsontoolkit::stringify(document, stream, key_compare);
std::cout << stream.str() << std::endl;