basic_json.md

jsoncons::basic_json

#include <jsoncons/json.hpp>

template< 
    class CharT,
    class ImplementationPolicy = sorted_policy,
    class Allocator = std::allocator<char>
> class basic_json;

The class basic_json resembles a union. A basic_json holds a data item of one of its alternative types: null, bool, int64_t, uint64_t, double, text string, byte string, array, and object. The data item may be tagged with a semantic_tag that provides additional information about the data item.

When assigned a new basic_json value, the old value is overwritten. The type of the new value may be different from the old value.

The definition of the character type of text strings is supplied via the CharT template parameter. Implementation policies for arrays and objects are provided via the ImplementationPolicy template parameter. A custom allocator may be supplied with the Allocator template parameter, which a basic_json will rebind to internal data structures.

Several typedefs for common character types and policies for ordering an object's name/value pairs are provided:

Type	Definition
json	basic_json<char,sorted_policy,std::allocator<char>>
ojson	basic_json<char, preserve_order_policy, std::allocator<char>>
wjson	basic_json<wchar_t,sorted_policy,std::allocator<char>>
wojson	basic_json<wchar_t, preserve_order_policy, std::allocator<char>>

Member type	Definition
char_type	CharT
`implementation_policy'	ImplementationPolicy
allocator_type	Allocator
char_traits_type	std::char_traits<char_type>
char_allocator_type	allocator_type rebound to char_type
reference	basic_json&
const_reference	const basic_json&
pointer	basic_json*
const_pointer	const basic_json*
string_view_type	basic_string_view<char_type>
key_type	std::basic_string<char_type,char_traits_type,char_allocator_type>
key_value_type	key_value<key_type,basic_json>
object	json_object<key_type,basic_json>
array	json_array<basic_json>
object_iterator	A RandomAccessIterator to key_value_type
const_object_iterator	A const RandomAccessIterator to const key_value_type
array_iterator	A RandomAccessIterator to basic_json
const_array_iterator	A const RandomAccessIterator to const basic_json
proxy_type	proxy<basic_json>. The proxy_type class supports conversion to basic_json&.

Static member functions

parse	Parses JSON.
make_array	Makes a multidimensional basic_json array.
const basic_json& null()	Returns a null value

Member functions

(constructor)	constructs the basic_json value
(destructor)	destructs the basic_json value
operator=	assigns values

allocator_type get_allocator() const

Returns the allocator associated with the basic_json value.

Ranges and Iterators

array_range	Returns a "range" that supports a range-based for loop over the elements of a `basic_json` array.
obect_range	Returns a "range" that supports a range-based for loop over the key-value pairs of a `basic_json` object.

Capacity

size_t size() const noexcept	Returns the number of elements in a basic_json array, or the number of members in a basic_json object, or `zero`
bool empty() const noexcept	Returns true if a basic_json string, object or array has no elements, otherwise false
size_t capacity() const	Returns the size of the storage space currently allocated for a basic_json object or array
void reserve(size_t n)	Increases the capacity of a basic_json object or array to allow at least `n` members or elements
void resize(size_t n)	Resizes a basic_json array so that it contains `n` elements
void resize(size_t n, const basic_json& val)	Resizes a basic_json array so that it contains `n` elements that are initialized to `val`
void shrink_to_fit()	Requests the removal of unused capacity

Accessors

bool contains(const string_view_type& key) const noexcept	Returns true if an object has a member with the given `key`, otherwise false
is	Checks if a basic_json value matches a type.
as	Attempts to convert a basic_json value to a value of a type.
operator[]	Access or insert specified element.
at	Access specified element.

semantic_tag tag() const

Returns the semantic_tag associated with this value

object_iterator find(const string_view_type& name)
const_object_iterator find(const string_view_type& name) const

Returns an object iterator to a member whose name compares equal to name. If there is no such member, returns object_range.end(). Throws std::runtime_error if not an object.

const basic_json& get_with_default(const string_view_type& name) const

If name matches the name of a member in the basic_json object, returns the member value converted to the default's data type, otherwise returns null. Throws std::runtime_error if not an object or null value.

template <class T>
T get_with_default(const string_view_type& name, 
                   const T& default_val) const

If name matches the name of a member in the basic_json object, returns the member value converted to the default's data type, otherwise returns default_val. Throws std::runtime_error if not an object or null value.

template <class T = std::string>
T get_with_default(const string_view_type& name, 
                   const char_type* default_val) const

Make get_with_default do the right thing for string literals. Throws std::runtime_error if not an object or null value.

Modifiers

void clear()	Remove all elements from an array or members from an object, otherwise do nothing
erase	Erases array elements and object members
push_back	Adds a value to the end of a basic_json array
insert	Inserts elements
emplace_back	Constructs a value in place at the end of a basic_json array
emplace	Constructs a value in place before a specified position in a basic_json array
try_emplace	Constructs a key-value pair in place in a basic_json object if the key does not exist, does nothing if the key exists
insert_or_assign	Inserts a key-value pair in a basic_json object if the key does not exist, or assigns a new value if the key already exists
merge	Inserts another basic_json object's key-value pairs into a basic_json object, if they don't already exist.
merge_or_update	Inserts another basic_json object's key-value pairs into a basic_json object, or assigns them if they already exist.
void swap(basic_json& val) noexcept	Exchanges the content of the basic_json value with the content of val, which is another basic_json value

Serialization

dump	Serializes basic_json value to a string, stream, or output handler.

Non member functions

bool operator==(const basic_json& lhs, const basic_json& rhs)	Returns true if two basic_json objects compare equal, false otherwise.
bool operator!=(const basic_json& lhs, const basic_json& rhs)	Returns true if two basic_json objects do not compare equal, false otherwise.
bool operator<(const basic_json& lhs, const basic_json& rhs)	Compares the contents of lhs and rhs lexicographically.
bool operator<=(const basic_json& lhs, const basic_json& rhs)	Compares the contents of lhs and rhs lexicographically.
bool operator>(const basic_json& lhs, const basic_json& rhs)	Compares the contents of lhs and rhs lexicographically.
bool operator>=(const basic_json& lhs, const basic_json& rhs)	Compares the contents of lhs and rhs lexicographically.

std::basic_istream<char_type>& operator>>(std::basic_istream<char_type>& is, basic_json& o)

Reads a basic_json value from a stream.

std::basic_ostream<char_type>& operator<<(std::basic_ostream<char_type>& os, const basic_json& o)

Inserts basic_json value into stream.

std::basic_ostream<char_type>& print(const basic_json& val)  
std::basic_ostream<char_type>& print(const basic_json& val, const basic_json_options<CharT>& options)  

Inserts basic_json value into stream using the specified basic_json_options if supplied.

std::basic_ostream<char_type>& pretty_print(const basic_json& val)  
std::basic_ostream<char_type>& pretty_print(const basic_json& val, const basic_json_options<CharT>& options)  

Inserts basic_json value into stream using the specified basic_json_options if supplied.

void swap(basic_json& a, basic_json& b) noexcept

Exchanges the values of a and b