j3d1/json
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

improved documentation

Browse source
This commit is contained in:
Niels 2016-01-31 13:05:39 +01:00
parent 22127a4b85
commit 6aa881988d
8 changed files with 514 additions and 330 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/Makefile
View file

@ -53,6 +53,7 @@ doxygen: create_output create_links
doxygen doxygen
gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html
gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html
gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType >@@g' html/*.html
upload: clean doxygen check_output upload: clean doxygen check_output
cd html ; ../scripts/git-update-ghpages nlohmann/json cd html ; ../scripts/git-update-ghpages nlohmann/json

4
doc/examples/back.cpp
View file

@ -21,8 +21,8 @@ int main()
std::cout << j_number_integer.back() << '\n'; std::cout << j_number_integer.back() << '\n';
std::cout << j_number_float.back() << '\n'; std::cout << j_number_float.back() << '\n';
std::cout << j_object.back() << '\n'; std::cout << j_object.back() << '\n';
//std::cout << j_object_empty.back() << '\n'; // would throw //std::cout << j_object_empty.back() << '\n'; // undefined behavior
std::cout << j_array.back() << '\n'; std::cout << j_array.back() << '\n';
//std::cout << j_array_empty.back() << '\n'; // would throw //std::cout << j_array_empty.back() << '\n'; // undefined behavior
std::cout << j_string.back() << '\n'; std::cout << j_string.back() << '\n';
} }

2
doc/examples/back.link
View file

@ -1 +1 @@
<a target="_blank" href="http://melpon.org/wandbox/permlink/M9xQVJJLTE1qvTtm"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/V7lUsd6LyndZDGoM"><b>online</b></a>

4
doc/examples/front.cpp
View file

@ -21,8 +21,8 @@ int main()
std::cout << j_number_integer.front() << '\n'; std::cout << j_number_integer.front() << '\n';
std::cout << j_number_float.front() << '\n'; std::cout << j_number_float.front() << '\n';
std::cout << j_object.front() << '\n'; std::cout << j_object.front() << '\n';
//std::cout << j_object_empty.front() << '\n'; // would throw //std::cout << j_object_empty.front() << '\n'; // undefined behavior
std::cout << j_array.front() << '\n'; std::cout << j_array.front() << '\n';
//std::cout << j_array_empty.front() << '\n'; // would throw //std::cout << j_array_empty.front() << '\n'; // undefined behavior
std::cout << j_string.front() << '\n'; std::cout << j_string.front() << '\n';
} }

2
doc/examples/front.link
View file

@ -1 +1 @@
<a target="_blank" href="http://melpon.org/wandbox/permlink/NH4F08xGiQfNT71r"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/HheeceJWHngZFhu2"><b>online</b></a>

1
doc/index.md
View file

@ -3,6 +3,7 @@
These pages contain the API documentation of JSON for Modern C++, a C++11 header-only JSON class. These pages contain the API documentation of JSON for Modern C++, a C++11 header-only JSON class.
- @link nlohmann::basic_json `basic_json` class @endlink - @link nlohmann::basic_json `basic_json` class @endlink
- [Function index](functions_func.html)
- Types - Types
- @link nlohmann::basic_json::array_t arrays @endlink - @link nlohmann::basic_json::array_t arrays @endlink
- @link nlohmann::basic_json::object_t objects @endlink - @link nlohmann::basic_json::object_t objects @endlink

365
src/json.hpp
View file

@ -87,21 +87,21 @@ struct has_mapped_type
/*! /*!
@brief a class to store JSON values @brief a class to store JSON values
@tparam ObjectType type for JSON objects (@c std::map by default; will be used @tparam ObjectType type for JSON objects (`std::map` by default; will be used
in @ref object_t) in @ref object_t)
@tparam ArrayType type for JSON arrays (@c std::vector by default; will be used @tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
in @ref array_t) in @ref array_t)
@tparam StringType type for JSON strings and object keys (@c std::string by @tparam StringType type for JSON strings and object keys (`std::string` by
default; will be used in @ref string_t) default; will be used in @ref string_t)
@tparam BooleanType type for JSON booleans (@c `bool` by default; will be used @tparam BooleanType type for JSON booleans (`bool` by default; will be used
in @ref boolean_t) in @ref boolean_t)
@tparam NumberIntegerType type for JSON integer numbers (@c `int64_t` by @tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
default; will be used in @ref number_integer_t) default; will be used in @ref number_integer_t)
@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c @tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
`uint64_t` by default; will be used in @ref number_unsigned_t) `uint64_t` by default; will be used in @ref number_unsigned_t)
@tparam NumberFloatType type for JSON floating-point numbers (@c `double` by @tparam NumberFloatType type for JSON floating-point numbers (`double` by
default; will be used in @ref number_float_t) default; will be used in @ref number_float_t)
@tparam AllocatorType type of the allocator to use (@c `std::allocator` by @tparam AllocatorType type of the allocator to use (`std::allocator` by
default) default)
@requirement The class satisfies the following concept requirements: @requirement The class satisfies the following concept requirements:
@ -682,7 +682,7 @@ class basic_json
string, ///< string value string, ///< string value
boolean, ///< boolean value boolean, ///< boolean value
number_integer, ///< number value (integer) number_integer, ///< number value (integer)
number_unsigned,///< number value (unsigned integer) number_unsigned, ///< number value (unsigned integer)
number_float, ///< number value (floating-point) number_float, ///< number value (floating-point)
discarded ///< discarded by the the parser callback function discarded ///< discarded by the the parser callback function
}; };
@ -954,7 +954,9 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- As postcondition, it holds: `basic_json().empty() == true`. - As postcondition, it holds: `basic_json().empty() == true`.
@ -972,7 +974,7 @@ class basic_json
Create a `null` JSON value. This is the explicitly version of the `null` Create a `null` JSON value. This is the explicitly version of the `null`
value constructor as it takes a null pointer as parameter. It allows to value constructor as it takes a null pointer as parameter. It allows to
create `null` values by explicitly assigning a @c nullptr to a JSON value. create `null` values by explicitly assigning a `nullptr` to a JSON value.
The passed null pointer itself is not read -- it is only used to choose the The passed null pointer itself is not read -- it is only used to choose the
right constructor. right constructor.
@ -1227,7 +1229,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of a JSON integer @liveexample{The example below shows the construction of an integer
number value.,basic_json__number_integer_t} number value.,basic_json__number_integer_t}
@sa @ref basic_json(const int) -- create a number value (integer) @sa @ref basic_json(const int) -- create a number value (integer)
@ -1261,7 +1263,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of a JSON integer @liveexample{The example below shows the construction of an integer
number value from an anonymous enum.,basic_json__const_int} number value from an anonymous enum.,basic_json__const_int}
@sa @ref basic_json(const number_integer_t) -- create a number value @sa @ref basic_json(const number_integer_t) -- create a number value
@ -1291,8 +1293,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of several JSON @liveexample{The example below shows the construction of several integer
integer number values from compatible number values from compatible
types.,basic_json__CompatibleIntegerNumberType} types.,basic_json__CompatibleIntegerNumberType}
@sa @ref basic_json(const number_integer_t) -- create a number value @sa @ref basic_json(const number_integer_t) -- create a number value
@ -1428,7 +1430,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of several JSON @liveexample{The example below shows the construction of several
floating-point number values from compatible floating-point number values from compatible
types.,basic_json__CompatibleNumberFloatType} types.,basic_json__CompatibleNumberFloatType}
@ -1506,7 +1508,7 @@ class basic_json
@complexity Linear in the size of the initializer list @a init. @complexity Linear in the size of the initializer list @a init.
@liveexample{The example below shows how JSON values are created from @liveexample{The example below shows how JSON values are created from
initializer lists,basic_json__list_init_t} initializer lists.,basic_json__list_init_t}
@sa @ref array(std::initializer_list<basic_json>) -- create a JSON array @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
value from an initializer list value from an initializer list
@ -1597,7 +1599,7 @@ class basic_json
@complexity Linear in the size of @a init. @complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref array @liveexample{The following code shows an example for the `array`
function.,array} function.,array}
@sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) -- @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
@ -1637,7 +1639,7 @@ class basic_json
@complexity Linear in the size of @a init. @complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref object @liveexample{The following code shows an example for the `object`
function.,object} function.,object}
@sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) -- @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
@ -1817,7 +1819,9 @@ class basic_json
@complexity Linear in the size of @a other. @complexity Linear in the size of @a other.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is linear. - The complexity is linear.
- As postcondition, it holds: `other == basic_json(other)`. - As postcondition, it holds: `other == basic_json(other)`.
@ -1923,7 +1927,9 @@ class basic_json
@complexity Linear. @complexity Linear.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is linear. - The complexity is linear.
@liveexample{The code below shows and example for the copy assignment. It @liveexample{The code below shows and example for the copy assignment. It
@ -1953,7 +1959,9 @@ class basic_json
@complexity Linear. @complexity Linear.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is linear. - The complexity is linear.
- All stored elements are destroyed and all memory is freed. - All stored elements are destroyed and all memory is freed.
@ -2054,7 +2062,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref type() for all JSON @liveexample{The following code exemplifies `type()` for all JSON
types.,type} types.,type}
@since version 1.0.0 @since version 1.0.0
@ -2075,9 +2083,15 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_primitive for all JSON @liveexample{The following code exemplifies `is_primitive()` for all JSON
types.,is_primitive} types.,is_primitive}
@sa @ref is_structured() -- returns whether JSON value is structured
@sa @ref is_null() -- returns whether JSON value is `null`
@sa @ref is_string() -- returns whether JSON value is a string
@sa @ref is_boolean() -- returns whether JSON value is a boolean
@sa @ref is_number() -- returns whether JSON value is a number
@since version 1.0.0 @since version 1.0.0
*/ */
bool is_primitive() const noexcept bool is_primitive() const noexcept
@ -2095,9 +2109,13 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_structured for all JSON @liveexample{The following code exemplifies `is_structured()` for all JSON
types.,is_structured} types.,is_structured}
@sa @ref is_primitive() -- returns whether value is primitive
@sa @ref is_array() -- returns whether value is an array
@sa @ref is_object() -- returns whether value is an object
@since version 1.0.0 @since version 1.0.0
*/ */
bool is_structured() const noexcept bool is_structured() const noexcept
@ -2114,7 +2132,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_null for all JSON @liveexample{The following code exemplifies `is_null()` for all JSON
types.,is_null} types.,is_null}
@since version 1.0.0 @since version 1.0.0
@ -2133,7 +2151,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_boolean for all JSON @liveexample{The following code exemplifies `is_boolean()` for all JSON
types.,is_boolean} types.,is_boolean}
@since version 1.0.0 @since version 1.0.0
@ -2154,7 +2172,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number for all JSON @liveexample{The following code exemplifies `is_number()` for all JSON
types.,is_number} types.,is_number}
@sa @ref is_number_integer() -- check if value is an integer or unsigned @sa @ref is_number_integer() -- check if value is an integer or unsigned
@ -2181,7 +2199,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number_integer for all @liveexample{The following code exemplifies `is_number_integer()` for all
JSON types.,is_number_integer} JSON types.,is_number_integer}
@sa @ref is_number() -- check if value is a number @sa @ref is_number() -- check if value is a number
@ -2206,7 +2224,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number_unsigned for all @liveexample{The following code exemplifies `is_number_unsigned()` for all
JSON types.,is_number_unsigned} JSON types.,is_number_unsigned}
@sa @ref is_number() -- check if value is a number @sa @ref is_number() -- check if value is a number
@ -2231,7 +2249,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number_float for all @liveexample{The following code exemplifies `is_number_float()` for all
JSON types.,is_number_float} JSON types.,is_number_float}
@sa @ref is_number() -- check if value is number @sa @ref is_number() -- check if value is number
@ -2255,7 +2273,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_object for all JSON @liveexample{The following code exemplifies `is_object()` for all JSON
types.,is_object} types.,is_object}
@since version 1.0.0 @since version 1.0.0
@ -2274,7 +2292,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_array for all JSON @liveexample{The following code exemplifies `is_array()` for all JSON
types.,is_array} types.,is_array}
@since version 1.0.0 @since version 1.0.0
@ -2293,7 +2311,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_string for all JSON @liveexample{The following code exemplifies `is_string()` for all JSON
types.,is_string} types.,is_string}
@since version 1.0.0 @since version 1.0.0
@ -2317,7 +2335,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_discarded for all JSON @liveexample{The following code exemplifies `is_discarded()` for all JSON
types.,is_discarded} types.,is_discarded}
@since version 1.0.0 @since version 1.0.0
@ -2337,8 +2355,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies the value_t operator for all @liveexample{The following code exemplifies the @ref value_t operator for
JSON types.,operator__value_t} all JSON types.,operator__value_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -2855,9 +2873,9 @@ class basic_json
@tparam ValueType non-pointer type compatible to the JSON value, for @tparam ValueType non-pointer type compatible to the JSON value, for
instance `int` for JSON integer numbers, `bool` for JSON booleans, or instance `int` for JSON integer numbers, `bool` for JSON booleans, or
`std::vector` types for JSON arrays. The character type of @ref string_t `std::vector` types for JSON arrays. The character type of @ref string_t as
as well as an initializer list of this type is excluded to avoid well as an initializer list of this type is excluded to avoid ambiguities
ambiguities as these types implicitly convert to `std::string`. as these types implicitly convert to `std::string`.
@return copy of the JSON value, converted to type @a ValueType @return copy of the JSON value, converted to type @a ValueType
@ -2917,7 +2935,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how array elements can be read and @liveexample{The example below shows how array elements can be read and
written using at.,at__size_type} written using `at()`.,at__size_type}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -2961,7 +2979,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how array elements can be read using @liveexample{The example below shows how array elements can be read using
at.,at__size_type_const} `at()`.,at__size_type_const}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3005,7 +3023,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using at.,at__object_t_key_type} written using `at()`.,at__object_t_key_type}
@sa @ref operator[](const typename object_t::key_type&) for unchecked @sa @ref operator[](const typename object_t::key_type&) for unchecked
access by reference access by reference
@ -3053,7 +3071,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
at.,at__object_t_key_type_const} `at()`.,at__object_t_key_type_const}
@sa @ref operator[](const typename object_t::key_type&) for unchecked @sa @ref operator[](const typename object_t::key_type&) for unchecked
access by reference access by reference
@ -3103,7 +3121,7 @@ class basic_json
linear in `idx - size()`. linear in `idx - size()`.
@liveexample{The example below shows how array elements can be read and @liveexample{The example below shows how array elements can be read and
written using [] operator. Note the addition of `null` written using `[]` operator. Note the addition of `null`
values.,operatorarray__size_type} values.,operatorarray__size_type}
@since version 1.0.0 @since version 1.0.0
@ -3149,7 +3167,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how array elements can be read using @liveexample{The example below shows how array elements can be read using
the [] operator.,operatorarray__size_type_const} the `[]` operator.,operatorarray__size_type_const}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3186,7 +3204,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using the [] operator.,operatorarray__key_type} written using the `[]` operator.,operatorarray__key_type}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3234,7 +3252,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
the [] operator.,operatorarray__key_type_const} the `[]` operator.,operatorarray__key_type_const}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3276,7 +3294,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using the [] operator.,operatorarray__key_type} written using the `[]` operator.,operatorarray__key_type}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3311,7 +3329,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
the [] operator.,operatorarray__key_type_const} the `[]` operator.,operatorarray__key_type_const}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3344,7 +3362,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using the [] operator.,operatorarray__key_type} written using the `[]` operator.,operatorarray__key_type}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3393,7 +3411,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
the [] operator.,operatorarray__key_type_const} the `[]` operator.,operatorarray__key_type_const}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3512,11 +3530,15 @@ class basic_json
@complexity Constant. @complexity Constant.
@note Calling `front` on an empty container is undefined. @pre The JSON value must not be `null` (would throw `std::out_of_range`) or
an empty array or object (undefined behavior, guarded by assertions).
@post The JSON value remains unchanged.
@throw std::out_of_range when called on null value @throw std::out_of_range when called on `null` value
@liveexample{The following code shows an example for @ref front.,front} @liveexample{The following code shows an example for `front()`.,front}
@sa @ref back() -- access the last element
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3546,11 +3568,15 @@ class basic_json
@complexity Constant. @complexity Constant.
@note Calling `back` on an empty container is undefined. @pre The JSON value must not be `null` (would throw `std::out_of_range`) or
an empty array or object (undefined behavior, guarded by assertions).
@post The JSON value remains unchanged.
@throw std::out_of_range when called on null value. @throw std::out_of_range when called on null value.
@liveexample{The following code shows an example for @ref back.,back} @liveexample{The following code shows an example for `back()`.,back}
@sa @ref front() -- access the first element
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3603,7 +3629,7 @@ class basic_json
- strings: linear in the length of the string - strings: linear in the length of the string
- other types: constant - other types: constant
@liveexample{The example shows the result of erase for different JSON @liveexample{The example shows the result of `erase()` for different JSON
types.,erase__IteratorType} types.,erase__IteratorType}
@sa @ref erase(InteratorType, InteratorType) -- removes the elements in the @sa @ref erase(InteratorType, InteratorType) -- removes the elements in the
@ -3710,7 +3736,7 @@ class basic_json
- strings: linear in the length of the string - strings: linear in the length of the string
- other types: constant - other types: constant
@liveexample{The example shows the result of erase for different JSON @liveexample{The example shows the result of `erase()` for different JSON
types.,erase__IteratorType_IteratorType} types.,erase__IteratorType_IteratorType}
@sa @ref erase(InteratorType) -- removes the element at a given position @sa @ref erase(InteratorType) -- removes the element at a given position
@ -3801,7 +3827,7 @@ class basic_json
@complexity `log(size()) + count(key)` @complexity `log(size()) + count(key)`
@liveexample{The example shows the effect of erase.,erase__key_type} @liveexample{The example shows the effect of `erase()`.,erase__key_type}
@sa @ref erase(InteratorType) -- removes the element at a given position @sa @ref erase(InteratorType) -- removes the element at a given position
@sa @ref erase(InteratorType, InteratorType) -- removes the elements in the @sa @ref erase(InteratorType, InteratorType) -- removes the elements in the
@ -3839,7 +3865,7 @@ class basic_json
@complexity Linear in distance between @a idx and the end of the container. @complexity Linear in distance between @a idx and the end of the container.
@liveexample{The example shows the effect of erase.,erase__size_type} @liveexample{The example shows the effect of `erase()`.,erase__size_type}
@sa @ref erase(InteratorType) -- removes the element at a given position @sa @ref erase(InteratorType) -- removes the element at a given position
@sa @ref erase(InteratorType, InteratorType) -- removes the elements in the @sa @ref erase(InteratorType, InteratorType) -- removes the elements in the
@ -3881,7 +3907,7 @@ class basic_json
@complexity Logarithmic in the size of the JSON object. @complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how find is used.,find__key_type} @liveexample{The example shows how `find()` is used.,find__key_type}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3929,7 +3955,7 @@ class basic_json
@complexity Logarithmic in the size of the JSON object. @complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how count is used.,count} @liveexample{The example shows how `count()` is used.,count}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3961,10 +3987,16 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
@liveexample{The following code shows an example for @ref begin.,begin} @liveexample{The following code shows an example for `begin()`.,begin}
@sa @ref cbegin() -- returns a const iterator to the beginning
@sa @ref end() -- returns an iterator to the end
@sa @ref cend() -- returns a const iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3994,11 +4026,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).begin()`. - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
@liveexample{The following code shows an example for @ref cbegin.,cbegin} @liveexample{The following code shows an example for `cbegin()`.,cbegin}
@sa @ref begin() -- returns an iterator to the beginning
@sa @ref end() -- returns an iterator to the end
@sa @ref cend() -- returns a const iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4020,10 +4058,16 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
@liveexample{The following code shows an example for @ref end.,end} @liveexample{The following code shows an example for `end()`.,end}
@sa @ref cend() -- returns a const iterator to the end
@sa @ref begin() -- returns an iterator to the beginning
@sa @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4053,11 +4097,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).end()`. - Has the semantics of `const_cast<const basic_json&>(*this).end()`.
@liveexample{The following code shows an example for @ref cend.,cend} @liveexample{The following code shows an example for `cend()`.,cend}
@sa @ref end() -- returns an iterator to the end
@sa @ref begin() -- returns an iterator to the beginning
@sa @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4077,11 +4127,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `reverse_iterator(end())`. - Has the semantics of `reverse_iterator(end())`.
@liveexample{The following code shows an example for @ref rbegin.,rbegin} @liveexample{The following code shows an example for `rbegin()`.,rbegin}
@sa @ref crbegin() -- returns a const reverse iterator to the beginning
@sa @ref rend() -- returns a reverse iterator to the end
@sa @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4108,11 +4164,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `reverse_iterator(begin())`. - Has the semantics of `reverse_iterator(begin())`.
@liveexample{The following code shows an example for @ref rend.,rend} @liveexample{The following code shows an example for `rend()`.,rend}
@sa @ref crend() -- returns a const reverse iterator to the end
@sa @ref rbegin() -- returns a reverse iterator to the beginning
@sa @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4139,11 +4201,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`. - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
@liveexample{The following code shows an example for @ref crbegin.,crbegin} @liveexample{The following code shows an example for `crbegin()`.,crbegin}
@sa @ref rbegin() -- returns a reverse iterator to the beginning
@sa @ref rend() -- returns a reverse iterator to the end
@sa @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4162,11 +4230,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rend()`. - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
@liveexample{The following code shows an example for @ref crend.,crend} @liveexample{The following code shows an example for `crend()`.,crend}
@sa @ref rend() -- returns a reverse iterator to the end
@sa @ref rbegin() -- returns a reverse iterator to the beginning
@sa @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4223,24 +4297,28 @@ class basic_json
defined as follows: defined as follows:
Value type | return value Value type | return value
----------- | ------------- ----------- | -------------
null | @c true null | `true`
boolean | @c false boolean | `false`
string | @c false string | `false`
number | @c false number | `false`
object | result of function object_t::empty() object | result of function `object_t::empty()`
array | result of function array_t::empty() array | result of function `array_t::empty()`
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their empty() functions have constant Container concept; that is, their `empty()` functions have constant
complexity. complexity.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `begin() == end()`. - Has the semantics of `begin() == end()`.
@liveexample{The following code uses @ref empty to check if a @ref json @liveexample{The following code uses `empty()` to check if a JSON
object contains any elements.,empty} object contains any elements.,empty}
@sa @ref size() -- returns the number of elements
@since version 1.0.0 @since version 1.0.0
*/ */
bool empty() const noexcept bool empty() const noexcept
@ -4282,23 +4360,28 @@ class basic_json
defined as follows: defined as follows:
Value type | return value Value type | return value
----------- | ------------- ----------- | -------------
null | @c 0 null | `0`
boolean | @c 1 boolean | `1`
string | @c 1 string | `1`
number | @c 1 number | `1`
object | result of function object_t::size() object | result of function object_t::size()
array | result of function array_t::size() array | result of function array_t::size()
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their size() functions have constant complexity. Container concept; that is, their size() functions have constant complexity.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `std::distance(begin(), end())`. - Has the semantics of `std::distance(begin(), end())`.
@liveexample{The following code calls @ref size on the different value @liveexample{The following code calls `size()` on the different value
types.,size} types.,size}
@sa @ref empty() -- checks whether the container is empty
@sa @ref max_size() -- returns the maximal number of elements
@since version 1.0.0 @since version 1.0.0
*/ */
size_type size() const noexcept size_type size() const noexcept
@ -4342,25 +4425,29 @@ class basic_json
defined as follows: defined as follows:
Value type | return value Value type | return value
----------- | ------------- ----------- | -------------
null | @c 0 (same as size()) null | `0` (same as `size()`)
boolean | @c 1 (same as size()) boolean | `1` (same as `size()`)
string | @c 1 (same as size()) string | `1` (same as `size()`)
number | @c 1 (same as size()) number | `1` (same as `size()`)
object | result of function object_t::max_size() object | result of function `object_t::max_size()`
array | result of function array_t::max_size() array | result of function `array_t::max_size()`
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their max_size() functions have constant Container concept; that is, their `max_size()` functions have constant
complexity. complexity.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of returning `b.size()` where `b` is the largest - Has the semantics of returning `b.size()` where `b` is the largest
possible JSON value. possible JSON value.
@liveexample{The following code calls @ref max_size on the different value @liveexample{The following code calls `max_size()` on the different value
types. Note the output is implementation specific.,max_size} types. Note the output is implementation specific.,max_size}
@sa @ref size() -- returns the number of elements
@since version 1.0.0 @since version 1.0.0
*/ */
size_type max_size() const noexcept size_type max_size() const noexcept
@ -4417,7 +4504,7 @@ class basic_json
@complexity Linear in the size of the JSON value. @complexity Linear in the size of the JSON value.
@liveexample{The example below shows the effect of @ref clear to different @liveexample{The example below shows the effect of `clear()` to different
JSON types.,clear} JSON types.,clear}
@since version 1.0.0 @since version 1.0.0
@ -4485,16 +4572,16 @@ class basic_json
function is called on a JSON null value, an empty array is created before function is called on a JSON null value, an empty array is created before
appending @a val. appending @a val.
@param val the value to add to the JSON array @param[in] val the value to add to the JSON array
@throw std::domain_error when called on a type other than JSON array or @throw std::domain_error when called on a type other than JSON array or
null; example: `"cannot use push_back() with number"` null; example: `"cannot use push_back() with number"`
@complexity Amortized constant. @complexity Amortized constant.
@liveexample{The example shows how `push_back` and `+=` can be used to add @liveexample{The example shows how `push_back()` and `+=` can be used to
elements to a JSON array. Note how the `null` value was silently converted add elements to a JSON array. Note how the `null` value was silently
to a JSON array.,push_back} converted to a JSON array.,push_back}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4578,9 +4665,9 @@ class basic_json
@complexity Logarithmic in the size of the container, O(log(`size()`)). @complexity Logarithmic in the size of the container, O(log(`size()`)).
@liveexample{The example shows how `push_back` and `+=` can be used to add @liveexample{The example shows how `push_back()` and `+=` can be used to
elements to a JSON object. Note how the `null` value was silently converted add elements to a JSON object. Note how the `null` value was silently
to a JSON object.,push_back__object_t__value} converted to a JSON object.,push_back__object_t__value}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4632,7 +4719,7 @@ class basic_json
@complexity Constant plus linear in the distance between pos and end of the @complexity Constant plus linear in the distance between pos and end of the
container. container.
@liveexample{The example shows how insert is used.,insert} @liveexample{The example shows how `insert()` is used.,insert}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4688,7 +4775,7 @@ class basic_json
@complexity Linear in @a cnt plus linear in the distance between @a pos @complexity Linear in @a cnt plus linear in the distance between @a pos
and end of the container. and end of the container.
@liveexample{The example shows how insert is used.,insert__count} @liveexample{The example shows how `insert()` is used.,insert__count}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4741,7 +4828,7 @@ class basic_json
@complexity Linear in `std::distance(first, last)` plus linear in the @complexity Linear in `std::distance(first, last)` plus linear in the
distance between @a pos and end of the container. distance between @a pos and end of the container.
@liveexample{The example shows how insert is used.,insert__range} @liveexample{The example shows how `insert()` is used.,insert__range}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4799,7 +4886,7 @@ class basic_json
@complexity Linear in `ilist.size()` plus linear in the distance between @a @complexity Linear in `ilist.size()` plus linear in the distance between @a
pos and end of the container. pos and end of the container.
@liveexample{The example shows how insert is used.,insert__ilist} @liveexample{The example shows how `insert()` is used.,insert__ilist}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4836,8 +4923,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON arrays can be @liveexample{The example below shows how JSON values can be swapped with
swapped.,swap__reference} `swap()`.,swap__reference}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4867,8 +4954,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON values can be @liveexample{The example below shows how arrays can be swapped with
swapped.,swap__array_t} `swap()`.,swap__array_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4901,8 +4988,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON values can be @liveexample{The example below shows how objects can be swapped with
swapped.,swap__object_t} `swap()`.,swap__object_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4935,8 +5022,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON values can be @liveexample{The example below shows how strings can be swapped with
swapped.,swap__string_t} `swap()`.,swap__string_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -5442,7 +5529,7 @@ class basic_json
@note A UTF-8 byte order mark is silently ignored. @note A UTF-8 byte order mark is silently ignored.
@liveexample{The example below demonstrates the parse function with and @liveexample{The example below demonstrates the `parse()` function with and
without callback function.,parse__string__parser_callback_t} without callback function.,parse__string__parser_callback_t}
@sa @ref parse(std::istream&, parser_callback_t) for a version that reads @sa @ref parse(std::istream&, parser_callback_t) for a version that reads
@ -5471,7 +5558,7 @@ class basic_json
@note A UTF-8 byte order mark is silently ignored. @note A UTF-8 byte order mark is silently ignored.
@liveexample{The example below demonstrates the parse function with and @liveexample{The example below demonstrates the `parse()` function with and
without callback function.,parse__istream__parser_callback_t} without callback function.,parse__istream__parser_callback_t}
@sa @ref parse(const string_t&, parser_callback_t) for a version that reads @sa @ref parse(const string_t&, parser_callback_t) for a version that reads
@ -5694,7 +5781,8 @@ class basic_json
{ {
if (c >= 0x00 and c <= 0x1f) if (c >= 0x00 and c <= 0x1f)
{ {
// convert a number 0..15 to its hex representation (0..f) // convert a number 0..15 to its hex representation
// (0..f)
auto hexify = [](const char v) -> char auto hexify = [](const char v) -> char
{ {
return (v < 10) ? ('0' + v) : ('a' + v - 10); return (v < 10) ? ('0' + v) : ('a' + v - 10);
@ -5731,9 +5819,9 @@ class basic_json
additional parameter. In case of arrays and objects, the function is called additional parameter. In case of arrays and objects, the function is called
recursively. Note that recursively. Note that
- strings and object keys are escaped using escape_string() - strings and object keys are escaped using `escape_string()`
- integer numbers are converted implicitly via operator<< - integer numbers are converted implicitly via `operator<<`
- floating-point numbers are converted to a string using "%g" format - floating-point numbers are converted to a string using `"%g"` format
@param[out] o stream to write to @param[out] o stream to write to
@param[in] pretty_print whether the output shall be pretty-printed @param[in] pretty_print whether the output shall be pretty-printed
@ -6744,6 +6832,7 @@ class basic_json
return result; return result;
} }
/// return difference
difference_type operator-(const iterator& other) const difference_type operator-(const iterator& other) const
{ {
return base_iterator::operator-(other); return base_iterator::operator-(other);
@ -6959,8 +7048,6 @@ class basic_json
static string_t to_unicode(const std::size_t codepoint1, static string_t to_unicode(const std::size_t codepoint1,
const std::size_t codepoint2 = 0) const std::size_t codepoint2 = 0)
{ {
string_t result;
// calculate the codepoint from the given code points // calculate the codepoint from the given code points
std::size_t codepoint = codepoint1; std::size_t codepoint = codepoint1;
@ -6986,6 +7073,8 @@ class basic_json
} }
} }
string_t result;
if (codepoint < 0x80) if (codepoint < 0x80)
{ {
// 1-byte characters: 0xxxxxxx (ASCII) // 1-byte characters: 0xxxxxxx (ASCII)
@ -7882,9 +7971,9 @@ basic_json_parser_63:
1. Escaped characters. In this case, a new character is constructed 1. Escaped characters. In this case, a new character is constructed
according to the nature of the escape. Some escapes create new according to the nature of the escape. Some escapes create new
characters (e.g., @c "\\n" is replaced by @c "\n"), some are copied characters (e.g., `"\\n"` is replaced by `"\n"`), some are copied as
as is (e.g., @c "\\\\"). Furthermore, Unicode escapes of the shape is (e.g., `"\\\\"`). Furthermore, Unicode escapes of the shape
@c "\\uxxxx" need special care. In this case, to_unicode takes care `"\\uxxxx"` need special care. In this case, to_unicode takes care
of the construction of the values. of the construction of the values.
2. Unescaped characters are copied as is. 2. Unescaped characters are copied as is.
@ -8027,9 +8116,10 @@ basic_json_parser_63:
supplied via the first parameter. Set this to supplied via the first parameter. Set this to
@a static_cast<number_float_t*>(nullptr). @a static_cast<number_float_t*>(nullptr).
@param type the @ref number_float_t in use @param[in] type the @ref number_float_t in use
@param endptr recieves a pointer to the first character after the number @param[in,out] endptr recieves a pointer to the first character after
the number
@return the floating point number @return the floating point number
*/ */
@ -8046,9 +8136,10 @@ basic_json_parser_63:
supplied via the first parameter. Set this to supplied via the first parameter. Set this to
@a static_cast<number_float_t*>(nullptr). @a static_cast<number_float_t*>(nullptr).
@param type the @ref number_float_t in use @param[in] type the @ref number_float_t in use
@param endptr recieves a pointer to the first character after the number @param[in,out] endptr recieves a pointer to the first character after
the number
@return the floating point number @return the floating point number
*/ */

365
src/json.hpp.re2c
View file

@ -87,21 +87,21 @@ struct has_mapped_type
/*! /*!
@brief a class to store JSON values @brief a class to store JSON values
@tparam ObjectType type for JSON objects (@c std::map by default; will be used @tparam ObjectType type for JSON objects (`std::map` by default; will be used
in @ref object_t) in @ref object_t)
@tparam ArrayType type for JSON arrays (@c std::vector by default; will be used @tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
in @ref array_t) in @ref array_t)
@tparam StringType type for JSON strings and object keys (@c std::string by @tparam StringType type for JSON strings and object keys (`std::string` by
default; will be used in @ref string_t) default; will be used in @ref string_t)
@tparam BooleanType type for JSON booleans (@c `bool` by default; will be used @tparam BooleanType type for JSON booleans (`bool` by default; will be used
in @ref boolean_t) in @ref boolean_t)
@tparam NumberIntegerType type for JSON integer numbers (@c `int64_t` by @tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
default; will be used in @ref number_integer_t) default; will be used in @ref number_integer_t)
@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c @tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
`uint64_t` by default; will be used in @ref number_unsigned_t) `uint64_t` by default; will be used in @ref number_unsigned_t)
@tparam NumberFloatType type for JSON floating-point numbers (@c `double` by @tparam NumberFloatType type for JSON floating-point numbers (`double` by
default; will be used in @ref number_float_t) default; will be used in @ref number_float_t)
@tparam AllocatorType type of the allocator to use (@c `std::allocator` by @tparam AllocatorType type of the allocator to use (`std::allocator` by
default) default)
@requirement The class satisfies the following concept requirements: @requirement The class satisfies the following concept requirements:
@ -682,7 +682,7 @@ class basic_json
string, ///< string value string, ///< string value
boolean, ///< boolean value boolean, ///< boolean value
number_integer, ///< number value (integer) number_integer, ///< number value (integer)
number_unsigned,///< number value (unsigned integer) number_unsigned, ///< number value (unsigned integer)
number_float, ///< number value (floating-point) number_float, ///< number value (floating-point)
discarded ///< discarded by the the parser callback function discarded ///< discarded by the the parser callback function
}; };
@ -954,7 +954,9 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- As postcondition, it holds: `basic_json().empty() == true`. - As postcondition, it holds: `basic_json().empty() == true`.
@ -972,7 +974,7 @@ class basic_json
Create a `null` JSON value. This is the explicitly version of the `null` Create a `null` JSON value. This is the explicitly version of the `null`
value constructor as it takes a null pointer as parameter. It allows to value constructor as it takes a null pointer as parameter. It allows to
create `null` values by explicitly assigning a @c nullptr to a JSON value. create `null` values by explicitly assigning a `nullptr` to a JSON value.
The passed null pointer itself is not read -- it is only used to choose the The passed null pointer itself is not read -- it is only used to choose the
right constructor. right constructor.
@ -1227,7 +1229,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of a JSON integer @liveexample{The example below shows the construction of an integer
number value.,basic_json__number_integer_t} number value.,basic_json__number_integer_t}
@sa @ref basic_json(const int) -- create a number value (integer) @sa @ref basic_json(const int) -- create a number value (integer)
@ -1261,7 +1263,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of a JSON integer @liveexample{The example below shows the construction of an integer
number value from an anonymous enum.,basic_json__const_int} number value from an anonymous enum.,basic_json__const_int}
@sa @ref basic_json(const number_integer_t) -- create a number value @sa @ref basic_json(const number_integer_t) -- create a number value
@ -1291,8 +1293,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of several JSON @liveexample{The example below shows the construction of several integer
integer number values from compatible number values from compatible
types.,basic_json__CompatibleIntegerNumberType} types.,basic_json__CompatibleIntegerNumberType}
@sa @ref basic_json(const number_integer_t) -- create a number value @sa @ref basic_json(const number_integer_t) -- create a number value
@ -1428,7 +1430,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows the construction of several JSON @liveexample{The example below shows the construction of several
floating-point number values from compatible floating-point number values from compatible
types.,basic_json__CompatibleNumberFloatType} types.,basic_json__CompatibleNumberFloatType}
@ -1506,7 +1508,7 @@ class basic_json
@complexity Linear in the size of the initializer list @a init. @complexity Linear in the size of the initializer list @a init.
@liveexample{The example below shows how JSON values are created from @liveexample{The example below shows how JSON values are created from
initializer lists,basic_json__list_init_t} initializer lists.,basic_json__list_init_t}
@sa @ref array(std::initializer_list<basic_json>) -- create a JSON array @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
value from an initializer list value from an initializer list
@ -1597,7 +1599,7 @@ class basic_json
@complexity Linear in the size of @a init. @complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref array @liveexample{The following code shows an example for the `array`
function.,array} function.,array}
@sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) -- @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
@ -1637,7 +1639,7 @@ class basic_json
@complexity Linear in the size of @a init. @complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref object @liveexample{The following code shows an example for the `object`
function.,object} function.,object}
@sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) -- @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
@ -1817,7 +1819,9 @@ class basic_json
@complexity Linear in the size of @a other. @complexity Linear in the size of @a other.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is linear. - The complexity is linear.
- As postcondition, it holds: `other == basic_json(other)`. - As postcondition, it holds: `other == basic_json(other)`.
@ -1923,7 +1927,9 @@ class basic_json
@complexity Linear. @complexity Linear.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is linear. - The complexity is linear.
@liveexample{The code below shows and example for the copy assignment. It @liveexample{The code below shows and example for the copy assignment. It
@ -1953,7 +1959,9 @@ class basic_json
@complexity Linear. @complexity Linear.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is linear. - The complexity is linear.
- All stored elements are destroyed and all memory is freed. - All stored elements are destroyed and all memory is freed.
@ -2054,7 +2062,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref type() for all JSON @liveexample{The following code exemplifies `type()` for all JSON
types.,type} types.,type}
@since version 1.0.0 @since version 1.0.0
@ -2075,9 +2083,15 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_primitive for all JSON @liveexample{The following code exemplifies `is_primitive()` for all JSON
types.,is_primitive} types.,is_primitive}
@sa @ref is_structured() -- returns whether JSON value is structured
@sa @ref is_null() -- returns whether JSON value is `null`
@sa @ref is_string() -- returns whether JSON value is a string
@sa @ref is_boolean() -- returns whether JSON value is a boolean
@sa @ref is_number() -- returns whether JSON value is a number
@since version 1.0.0 @since version 1.0.0
*/ */
bool is_primitive() const noexcept bool is_primitive() const noexcept
@ -2095,9 +2109,13 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_structured for all JSON @liveexample{The following code exemplifies `is_structured()` for all JSON
types.,is_structured} types.,is_structured}
@sa @ref is_primitive() -- returns whether value is primitive
@sa @ref is_array() -- returns whether value is an array
@sa @ref is_object() -- returns whether value is an object
@since version 1.0.0 @since version 1.0.0
*/ */
bool is_structured() const noexcept bool is_structured() const noexcept
@ -2114,7 +2132,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_null for all JSON @liveexample{The following code exemplifies `is_null()` for all JSON
types.,is_null} types.,is_null}
@since version 1.0.0 @since version 1.0.0
@ -2133,7 +2151,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_boolean for all JSON @liveexample{The following code exemplifies `is_boolean()` for all JSON
types.,is_boolean} types.,is_boolean}
@since version 1.0.0 @since version 1.0.0
@ -2154,7 +2172,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number for all JSON @liveexample{The following code exemplifies `is_number()` for all JSON
types.,is_number} types.,is_number}
@sa @ref is_number_integer() -- check if value is an integer or unsigned @sa @ref is_number_integer() -- check if value is an integer or unsigned
@ -2181,7 +2199,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number_integer for all @liveexample{The following code exemplifies `is_number_integer()` for all
JSON types.,is_number_integer} JSON types.,is_number_integer}
@sa @ref is_number() -- check if value is a number @sa @ref is_number() -- check if value is a number
@ -2206,7 +2224,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number_unsigned for all @liveexample{The following code exemplifies `is_number_unsigned()` for all
JSON types.,is_number_unsigned} JSON types.,is_number_unsigned}
@sa @ref is_number() -- check if value is a number @sa @ref is_number() -- check if value is a number
@ -2231,7 +2249,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_number_float for all @liveexample{The following code exemplifies `is_number_float()` for all
JSON types.,is_number_float} JSON types.,is_number_float}
@sa @ref is_number() -- check if value is number @sa @ref is_number() -- check if value is number
@ -2255,7 +2273,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_object for all JSON @liveexample{The following code exemplifies `is_object()` for all JSON
types.,is_object} types.,is_object}
@since version 1.0.0 @since version 1.0.0
@ -2274,7 +2292,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_array for all JSON @liveexample{The following code exemplifies `is_array()` for all JSON
types.,is_array} types.,is_array}
@since version 1.0.0 @since version 1.0.0
@ -2293,7 +2311,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_string for all JSON @liveexample{The following code exemplifies `is_string()` for all JSON
types.,is_string} types.,is_string}
@since version 1.0.0 @since version 1.0.0
@ -2317,7 +2335,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies @ref is_discarded for all JSON @liveexample{The following code exemplifies `is_discarded()` for all JSON
types.,is_discarded} types.,is_discarded}
@since version 1.0.0 @since version 1.0.0
@ -2337,8 +2355,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The following code exemplifies the value_t operator for all @liveexample{The following code exemplifies the @ref value_t operator for
JSON types.,operator__value_t} all JSON types.,operator__value_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -2855,9 +2873,9 @@ class basic_json
@tparam ValueType non-pointer type compatible to the JSON value, for @tparam ValueType non-pointer type compatible to the JSON value, for
instance `int` for JSON integer numbers, `bool` for JSON booleans, or instance `int` for JSON integer numbers, `bool` for JSON booleans, or
`std::vector` types for JSON arrays. The character type of @ref string_t `std::vector` types for JSON arrays. The character type of @ref string_t as
as well as an initializer list of this type is excluded to avoid well as an initializer list of this type is excluded to avoid ambiguities
ambiguities as these types implicitly convert to `std::string`. as these types implicitly convert to `std::string`.
@return copy of the JSON value, converted to type @a ValueType @return copy of the JSON value, converted to type @a ValueType
@ -2917,7 +2935,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how array elements can be read and @liveexample{The example below shows how array elements can be read and
written using at.,at__size_type} written using `at()`.,at__size_type}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -2961,7 +2979,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how array elements can be read using @liveexample{The example below shows how array elements can be read using
at.,at__size_type_const} `at()`.,at__size_type_const}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3005,7 +3023,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using at.,at__object_t_key_type} written using `at()`.,at__object_t_key_type}
@sa @ref operator[](const typename object_t::key_type&) for unchecked @sa @ref operator[](const typename object_t::key_type&) for unchecked
access by reference access by reference
@ -3053,7 +3071,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
at.,at__object_t_key_type_const} `at()`.,at__object_t_key_type_const}
@sa @ref operator[](const typename object_t::key_type&) for unchecked @sa @ref operator[](const typename object_t::key_type&) for unchecked
access by reference access by reference
@ -3103,7 +3121,7 @@ class basic_json
linear in `idx - size()`. linear in `idx - size()`.
@liveexample{The example below shows how array elements can be read and @liveexample{The example below shows how array elements can be read and
written using [] operator. Note the addition of `null` written using `[]` operator. Note the addition of `null`
values.,operatorarray__size_type} values.,operatorarray__size_type}
@since version 1.0.0 @since version 1.0.0
@ -3149,7 +3167,7 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how array elements can be read using @liveexample{The example below shows how array elements can be read using
the [] operator.,operatorarray__size_type_const} the `[]` operator.,operatorarray__size_type_const}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3186,7 +3204,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using the [] operator.,operatorarray__key_type} written using the `[]` operator.,operatorarray__key_type}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3234,7 +3252,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
the [] operator.,operatorarray__key_type_const} the `[]` operator.,operatorarray__key_type_const}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3276,7 +3294,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using the [] operator.,operatorarray__key_type} written using the `[]` operator.,operatorarray__key_type}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3311,7 +3329,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
the [] operator.,operatorarray__key_type_const} the `[]` operator.,operatorarray__key_type_const}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3344,7 +3362,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and @liveexample{The example below shows how object elements can be read and
written using the [] operator.,operatorarray__key_type} written using the `[]` operator.,operatorarray__key_type}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3393,7 +3411,7 @@ class basic_json
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using @liveexample{The example below shows how object elements can be read using
the [] operator.,operatorarray__key_type_const} the `[]` operator.,operatorarray__key_type_const}
@sa @ref at(const typename object_t::key_type&) for access by reference @sa @ref at(const typename object_t::key_type&) for access by reference
with range checking with range checking
@ -3512,11 +3530,15 @@ class basic_json
@complexity Constant. @complexity Constant.
@note Calling `front` on an empty container is undefined. @pre The JSON value must not be `null` (would throw `std::out_of_range`) or
an empty array or object (undefined behavior, guarded by assertions).
@post The JSON value remains unchanged.
@throw std::out_of_range when called on null value @throw std::out_of_range when called on `null` value
@liveexample{The following code shows an example for @ref front.,front} @liveexample{The following code shows an example for `front()`.,front}
@sa @ref back() -- access the last element
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3546,11 +3568,15 @@ class basic_json
@complexity Constant. @complexity Constant.
@note Calling `back` on an empty container is undefined. @pre The JSON value must not be `null` (would throw `std::out_of_range`) or
an empty array or object (undefined behavior, guarded by assertions).
@post The JSON value remains unchanged.
@throw std::out_of_range when called on null value. @throw std::out_of_range when called on null value.
@liveexample{The following code shows an example for @ref back.,back} @liveexample{The following code shows an example for `back()`.,back}
@sa @ref front() -- access the first element
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3603,7 +3629,7 @@ class basic_json
- strings: linear in the length of the string - strings: linear in the length of the string
- other types: constant - other types: constant
@liveexample{The example shows the result of erase for different JSON @liveexample{The example shows the result of `erase()` for different JSON
types.,erase__IteratorType} types.,erase__IteratorType}
@sa @ref erase(InteratorType, InteratorType) -- removes the elements in the @sa @ref erase(InteratorType, InteratorType) -- removes the elements in the
@ -3710,7 +3736,7 @@ class basic_json
- strings: linear in the length of the string - strings: linear in the length of the string
- other types: constant - other types: constant
@liveexample{The example shows the result of erase for different JSON @liveexample{The example shows the result of `erase()` for different JSON
types.,erase__IteratorType_IteratorType} types.,erase__IteratorType_IteratorType}
@sa @ref erase(InteratorType) -- removes the element at a given position @sa @ref erase(InteratorType) -- removes the element at a given position
@ -3801,7 +3827,7 @@ class basic_json
@complexity `log(size()) + count(key)` @complexity `log(size()) + count(key)`
@liveexample{The example shows the effect of erase.,erase__key_type} @liveexample{The example shows the effect of `erase()`.,erase__key_type}
@sa @ref erase(InteratorType) -- removes the element at a given position @sa @ref erase(InteratorType) -- removes the element at a given position
@sa @ref erase(InteratorType, InteratorType) -- removes the elements in the @sa @ref erase(InteratorType, InteratorType) -- removes the elements in the
@ -3839,7 +3865,7 @@ class basic_json
@complexity Linear in distance between @a idx and the end of the container. @complexity Linear in distance between @a idx and the end of the container.
@liveexample{The example shows the effect of erase.,erase__size_type} @liveexample{The example shows the effect of `erase()`.,erase__size_type}
@sa @ref erase(InteratorType) -- removes the element at a given position @sa @ref erase(InteratorType) -- removes the element at a given position
@sa @ref erase(InteratorType, InteratorType) -- removes the elements in the @sa @ref erase(InteratorType, InteratorType) -- removes the elements in the
@ -3881,7 +3907,7 @@ class basic_json
@complexity Logarithmic in the size of the JSON object. @complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how find is used.,find__key_type} @liveexample{The example shows how `find()` is used.,find__key_type}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3929,7 +3955,7 @@ class basic_json
@complexity Logarithmic in the size of the JSON object. @complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how count is used.,count} @liveexample{The example shows how `count()` is used.,count}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3961,10 +3987,16 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
@liveexample{The following code shows an example for @ref begin.,begin} @liveexample{The following code shows an example for `begin()`.,begin}
@sa @ref cbegin() -- returns a const iterator to the beginning
@sa @ref end() -- returns an iterator to the end
@sa @ref cend() -- returns a const iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -3994,11 +4026,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).begin()`. - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
@liveexample{The following code shows an example for @ref cbegin.,cbegin} @liveexample{The following code shows an example for `cbegin()`.,cbegin}
@sa @ref begin() -- returns an iterator to the beginning
@sa @ref end() -- returns an iterator to the end
@sa @ref cend() -- returns a const iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4020,10 +4058,16 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
@liveexample{The following code shows an example for @ref end.,end} @liveexample{The following code shows an example for `end()`.,end}
@sa @ref cend() -- returns a const iterator to the end
@sa @ref begin() -- returns an iterator to the beginning
@sa @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4053,11 +4097,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).end()`. - Has the semantics of `const_cast<const basic_json&>(*this).end()`.
@liveexample{The following code shows an example for @ref cend.,cend} @liveexample{The following code shows an example for `cend()`.,cend}
@sa @ref end() -- returns an iterator to the end
@sa @ref begin() -- returns an iterator to the beginning
@sa @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4077,11 +4127,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `reverse_iterator(end())`. - Has the semantics of `reverse_iterator(end())`.
@liveexample{The following code shows an example for @ref rbegin.,rbegin} @liveexample{The following code shows an example for `rbegin()`.,rbegin}
@sa @ref crbegin() -- returns a const reverse iterator to the beginning
@sa @ref rend() -- returns a reverse iterator to the end
@sa @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4108,11 +4164,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `reverse_iterator(begin())`. - Has the semantics of `reverse_iterator(begin())`.
@liveexample{The following code shows an example for @ref rend.,rend} @liveexample{The following code shows an example for `rend()`.,rend}
@sa @ref crend() -- returns a const reverse iterator to the end
@sa @ref rbegin() -- returns a reverse iterator to the beginning
@sa @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4139,11 +4201,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`. - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
@liveexample{The following code shows an example for @ref crbegin.,crbegin} @liveexample{The following code shows an example for `crbegin()`.,crbegin}
@sa @ref rbegin() -- returns a reverse iterator to the beginning
@sa @ref rend() -- returns a reverse iterator to the end
@sa @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4162,11 +4230,17 @@ class basic_json
@complexity Constant. @complexity Constant.
@requirement This function satisfies the ReversibleContainer requirements: @requirement This function helps `basic_json` satisfying the
[ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rend()`. - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
@liveexample{The following code shows an example for @ref crend.,crend} @liveexample{The following code shows an example for `crend()`.,crend}
@sa @ref rend() -- returns a reverse iterator to the end
@sa @ref rbegin() -- returns a reverse iterator to the beginning
@sa @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4223,24 +4297,28 @@ class basic_json
defined as follows: defined as follows:
Value type | return value Value type | return value
----------- | ------------- ----------- | -------------
null | @c true null | `true`
boolean | @c false boolean | `false`
string | @c false string | `false`
number | @c false number | `false`
object | result of function object_t::empty() object | result of function `object_t::empty()`
array | result of function array_t::empty() array | result of function `array_t::empty()`
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their empty() functions have constant Container concept; that is, their `empty()` functions have constant
complexity. complexity.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `begin() == end()`. - Has the semantics of `begin() == end()`.
@liveexample{The following code uses @ref empty to check if a @ref json @liveexample{The following code uses `empty()` to check if a JSON
object contains any elements.,empty} object contains any elements.,empty}
@sa @ref size() -- returns the number of elements
@since version 1.0.0 @since version 1.0.0
*/ */
bool empty() const noexcept bool empty() const noexcept
@ -4282,23 +4360,28 @@ class basic_json
defined as follows: defined as follows:
Value type | return value Value type | return value
----------- | ------------- ----------- | -------------
null | @c 0 null | `0`
boolean | @c 1 boolean | `1`
string | @c 1 string | `1`
number | @c 1 number | `1`
object | result of function object_t::size() object | result of function object_t::size()
array | result of function array_t::size() array | result of function array_t::size()
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their size() functions have constant complexity. Container concept; that is, their size() functions have constant complexity.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of `std::distance(begin(), end())`. - Has the semantics of `std::distance(begin(), end())`.
@liveexample{The following code calls @ref size on the different value @liveexample{The following code calls `size()` on the different value
types.,size} types.,size}
@sa @ref empty() -- checks whether the container is empty
@sa @ref max_size() -- returns the maximal number of elements
@since version 1.0.0 @since version 1.0.0
*/ */
size_type size() const noexcept size_type size() const noexcept
@ -4342,25 +4425,29 @@ class basic_json
defined as follows: defined as follows:
Value type | return value Value type | return value
----------- | ------------- ----------- | -------------
null | @c 0 (same as size()) null | `0` (same as `size()`)
boolean | @c 1 (same as size()) boolean | `1` (same as `size()`)
string | @c 1 (same as size()) string | `1` (same as `size()`)
number | @c 1 (same as size()) number | `1` (same as `size()`)
object | result of function object_t::max_size() object | result of function `object_t::max_size()`
array | result of function array_t::max_size() array | result of function `array_t::max_size()`
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their max_size() functions have constant Container concept; that is, their `max_size()` functions have constant
complexity. complexity.
@requirement This function satisfies the Container requirements: @requirement This function helps `basic_json` satisfying the
[Container](http://en.cppreference.com/w/cpp/concept/Container)
requirements:
- The complexity is constant. - The complexity is constant.
- Has the semantics of returning `b.size()` where `b` is the largest - Has the semantics of returning `b.size()` where `b` is the largest
possible JSON value. possible JSON value.
@liveexample{The following code calls @ref max_size on the different value @liveexample{The following code calls `max_size()` on the different value
types. Note the output is implementation specific.,max_size} types. Note the output is implementation specific.,max_size}
@sa @ref size() -- returns the number of elements
@since version 1.0.0 @since version 1.0.0
*/ */
size_type max_size() const noexcept size_type max_size() const noexcept
@ -4417,7 +4504,7 @@ class basic_json
@complexity Linear in the size of the JSON value. @complexity Linear in the size of the JSON value.
@liveexample{The example below shows the effect of @ref clear to different @liveexample{The example below shows the effect of `clear()` to different
JSON types.,clear} JSON types.,clear}
@since version 1.0.0 @since version 1.0.0
@ -4485,16 +4572,16 @@ class basic_json
function is called on a JSON null value, an empty array is created before function is called on a JSON null value, an empty array is created before
appending @a val. appending @a val.
@param val the value to add to the JSON array @param[in] val the value to add to the JSON array
@throw std::domain_error when called on a type other than JSON array or @throw std::domain_error when called on a type other than JSON array or
null; example: `"cannot use push_back() with number"` null; example: `"cannot use push_back() with number"`
@complexity Amortized constant. @complexity Amortized constant.
@liveexample{The example shows how `push_back` and `+=` can be used to add @liveexample{The example shows how `push_back()` and `+=` can be used to
elements to a JSON array. Note how the `null` value was silently converted add elements to a JSON array. Note how the `null` value was silently
to a JSON array.,push_back} converted to a JSON array.,push_back}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4578,9 +4665,9 @@ class basic_json
@complexity Logarithmic in the size of the container, O(log(`size()`)). @complexity Logarithmic in the size of the container, O(log(`size()`)).
@liveexample{The example shows how `push_back` and `+=` can be used to add @liveexample{The example shows how `push_back()` and `+=` can be used to
elements to a JSON object. Note how the `null` value was silently converted add elements to a JSON object. Note how the `null` value was silently
to a JSON object.,push_back__object_t__value} converted to a JSON object.,push_back__object_t__value}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4632,7 +4719,7 @@ class basic_json
@complexity Constant plus linear in the distance between pos and end of the @complexity Constant plus linear in the distance between pos and end of the
container. container.
@liveexample{The example shows how insert is used.,insert} @liveexample{The example shows how `insert()` is used.,insert}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4688,7 +4775,7 @@ class basic_json
@complexity Linear in @a cnt plus linear in the distance between @a pos @complexity Linear in @a cnt plus linear in the distance between @a pos
and end of the container. and end of the container.
@liveexample{The example shows how insert is used.,insert__count} @liveexample{The example shows how `insert()` is used.,insert__count}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4741,7 +4828,7 @@ class basic_json
@complexity Linear in `std::distance(first, last)` plus linear in the @complexity Linear in `std::distance(first, last)` plus linear in the
distance between @a pos and end of the container. distance between @a pos and end of the container.
@liveexample{The example shows how insert is used.,insert__range} @liveexample{The example shows how `insert()` is used.,insert__range}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4799,7 +4886,7 @@ class basic_json
@complexity Linear in `ilist.size()` plus linear in the distance between @a @complexity Linear in `ilist.size()` plus linear in the distance between @a
pos and end of the container. pos and end of the container.
@liveexample{The example shows how insert is used.,insert__ilist} @liveexample{The example shows how `insert()` is used.,insert__ilist}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4836,8 +4923,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON arrays can be @liveexample{The example below shows how JSON values can be swapped with
swapped.,swap__reference} `swap()`.,swap__reference}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4867,8 +4954,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON values can be @liveexample{The example below shows how arrays can be swapped with
swapped.,swap__array_t} `swap()`.,swap__array_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4901,8 +4988,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON values can be @liveexample{The example below shows how objects can be swapped with
swapped.,swap__object_t} `swap()`.,swap__object_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -4935,8 +5022,8 @@ class basic_json
@complexity Constant. @complexity Constant.
@liveexample{The example below shows how JSON values can be @liveexample{The example below shows how strings can be swapped with
swapped.,swap__string_t} `swap()`.,swap__string_t}
@since version 1.0.0 @since version 1.0.0
*/ */
@ -5442,7 +5529,7 @@ class basic_json
@note A UTF-8 byte order mark is silently ignored. @note A UTF-8 byte order mark is silently ignored.
@liveexample{The example below demonstrates the parse function with and @liveexample{The example below demonstrates the `parse()` function with and
without callback function.,parse__string__parser_callback_t} without callback function.,parse__string__parser_callback_t}
@sa @ref parse(std::istream&, parser_callback_t) for a version that reads @sa @ref parse(std::istream&, parser_callback_t) for a version that reads
@ -5471,7 +5558,7 @@ class basic_json
@note A UTF-8 byte order mark is silently ignored. @note A UTF-8 byte order mark is silently ignored.
@liveexample{The example below demonstrates the parse function with and @liveexample{The example below demonstrates the `parse()` function with and
without callback function.,parse__istream__parser_callback_t} without callback function.,parse__istream__parser_callback_t}
@sa @ref parse(const string_t&, parser_callback_t) for a version that reads @sa @ref parse(const string_t&, parser_callback_t) for a version that reads
@ -5694,7 +5781,8 @@ class basic_json
{ {
if (c >= 0x00 and c <= 0x1f) if (c >= 0x00 and c <= 0x1f)
{ {
// convert a number 0..15 to its hex representation (0..f) // convert a number 0..15 to its hex representation
// (0..f)
auto hexify = [](const char v) -> char auto hexify = [](const char v) -> char
{ {
return (v < 10) ? ('0' + v) : ('a' + v - 10); return (v < 10) ? ('0' + v) : ('a' + v - 10);
@ -5731,9 +5819,9 @@ class basic_json
additional parameter. In case of arrays and objects, the function is called additional parameter. In case of arrays and objects, the function is called
recursively. Note that recursively. Note that
- strings and object keys are escaped using escape_string() - strings and object keys are escaped using `escape_string()`
- integer numbers are converted implicitly via operator<< - integer numbers are converted implicitly via `operator<<`
- floating-point numbers are converted to a string using "%g" format - floating-point numbers are converted to a string using `"%g"` format
@param[out] o stream to write to @param[out] o stream to write to
@param[in] pretty_print whether the output shall be pretty-printed @param[in] pretty_print whether the output shall be pretty-printed
@ -6744,6 +6832,7 @@ class basic_json
return result; return result;
} }
/// return difference
difference_type operator-(const iterator& other) const difference_type operator-(const iterator& other) const
{ {
return base_iterator::operator-(other); return base_iterator::operator-(other);
@ -6959,8 +7048,6 @@ class basic_json
static string_t to_unicode(const std::size_t codepoint1, static string_t to_unicode(const std::size_t codepoint1,
const std::size_t codepoint2 = 0) const std::size_t codepoint2 = 0)
{ {
string_t result;
// calculate the codepoint from the given code points // calculate the codepoint from the given code points
std::size_t codepoint = codepoint1; std::size_t codepoint = codepoint1;
@ -6986,6 +7073,8 @@ class basic_json
} }
} }
string_t result;
if (codepoint < 0x80) if (codepoint < 0x80)
{ {
// 1-byte characters: 0xxxxxxx (ASCII) // 1-byte characters: 0xxxxxxx (ASCII)
@ -7192,9 +7281,9 @@ class basic_json
1. Escaped characters. In this case, a new character is constructed 1. Escaped characters. In this case, a new character is constructed
according to the nature of the escape. Some escapes create new according to the nature of the escape. Some escapes create new
characters (e.g., @c "\\n" is replaced by @c "\n"), some are copied characters (e.g., `"\\n"` is replaced by `"\n"`), some are copied as
as is (e.g., @c "\\\\"). Furthermore, Unicode escapes of the shape is (e.g., `"\\\\"`). Furthermore, Unicode escapes of the shape
@c "\\uxxxx" need special care. In this case, to_unicode takes care `"\\uxxxx"` need special care. In this case, to_unicode takes care
of the construction of the values. of the construction of the values.
2. Unescaped characters are copied as is. 2. Unescaped characters are copied as is.
@ -7337,9 +7426,10 @@ class basic_json
supplied via the first parameter. Set this to supplied via the first parameter. Set this to
@a static_cast<number_float_t*>(nullptr). @a static_cast<number_float_t*>(nullptr).
@param type the @ref number_float_t in use @param[in] type the @ref number_float_t in use
@param endptr recieves a pointer to the first character after the number @param[in,out] endptr recieves a pointer to the first character after
the number
@return the floating point number @return the floating point number
*/ */
@ -7356,9 +7446,10 @@ class basic_json
supplied via the first parameter. Set this to supplied via the first parameter. Set this to
@a static_cast<number_float_t*>(nullptr). @a static_cast<number_float_t*>(nullptr).
@param type the @ref number_float_t in use @param[in] type the @ref number_float_t in use
@param endptr recieves a pointer to the first character after the number @param[in,out] endptr recieves a pointer to the first character after
the number
@return the floating point number @return the floating point number
*/ */