External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

🔥 consolidate documentation

Browse Source
This commit is contained in:
Niels Lohmann 2021-10-16 14:10:09 +02:00
parent 17a31bf503
commit 15a779cde7
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
4 changed files with 72 additions and 820 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/mkdocs/docs/api/basic_json/at.md
View File

@ -14,8 +14,8 @@ reference at(const json_pointer& ptr);
const_reference at(const json_pointer& ptr) const; const_reference at(const json_pointer& ptr) const;
``` ```
1. Returns a reference to the element at specified location `idx`, with bounds checking. 1. Returns a reference to the array element at specified location `idx`, with bounds checking.
2. Returns a reference to the element at with specified key `key`, with bounds checking. 2. Returns a reference to the object element at with specified key `key`, with bounds checking.
3. Returns a reference to the element at with specified JSON pointer `ptr`, with bounds checking. 3. Returns a reference to the element at with specified JSON pointer `ptr`, with bounds checking.
## Parameters ## Parameters
@ -74,7 +74,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Example ## Example
??? example ??? example "Example: (1) access specified array element with bounds checking"
The example below shows how array elements can be read and written using `at()`. It also demonstrates the different The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown. exceptions that can be thrown.
@ -89,7 +89,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__size_type.output" --8<-- "examples/at__size_type.output"
``` ```
??? example ??? example "Example: (1) access specified array element with bounds checking"
The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown. that can be thrown.
@ -104,7 +104,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__size_type_const.output" --8<-- "examples/at__size_type_const.output"
``` ```
??? example ??? example "Example: (2) access specified object element with bounds checking"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown. exceptions that can be thrown.
@ -119,7 +119,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__object_t_key_type.output" --8<-- "examples/at__object_t_key_type.output"
``` ```
??? example ??? example "Example (2) access specified object element with bounds checking"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown. that can be thrown.
@ -134,7 +134,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__object_t_key_type_const.output" --8<-- "examples/at__object_t_key_type_const.output"
``` ```
??? example ??? example "Example (3) access specified element via JSON Pointer"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown. exceptions that can be thrown.
@ -149,7 +149,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at_json_pointer.output" --8<-- "examples/at_json_pointer.output"
``` ```
??? example ??? example "Example (3) access specified element via JSON Pointer"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown. that can be thrown.

16
doc/mkdocs/docs/api/basic_json/operator[].md
View File

@ -18,8 +18,8 @@ reference operator[](const json_pointer& ptr);
const_reference operator[](const json_pointer& ptr) const; const_reference operator[](const json_pointer& ptr) const;
``` ```
1. Returns a reference to the element at specified location `idx`. 1. Returns a reference to the array element at specified location `idx`.
2. Returns a reference to the element at with specified key `key`. 2. Returns a reference to the object element at with specified key `key`.
3. Returns a reference to the element at with specified JSON pointer `ptr`. 3. Returns a reference to the element at with specified JSON pointer `ptr`.
## Template parameters ## Template parameters
@ -99,7 +99,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Example ## Example
??? example ??? example "Example (1): access specified array element"
The example below shows how array elements can be read and written using `[]` operator. Note the addition of The example below shows how array elements can be read and written using `[]` operator. Note the addition of
`#!json null` values. `#!json null` values.
@ -114,7 +114,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__size_type.output" --8<-- "examples/operatorarray__size_type.output"
``` ```
??? example ??? example "Example (1): access specified array element"
The example below shows how array elements can be read using the `[]` operator. The example below shows how array elements can be read using the `[]` operator.
@ -128,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__size_type_const.output" --8<-- "examples/operatorarray__size_type_const.output"
``` ```
??? example ??? example "Example (2): access specified object element"
The example below shows how object elements can be read and written using the `[]` operator. The example below shows how object elements can be read and written using the `[]` operator.
@ -142,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__key_type.output" --8<-- "examples/operatorarray__key_type.output"
``` ```
??? example ??? example "Example (2): access specified object element"
The example below shows how object elements can be read using the `[]` operator. The example below shows how object elements can be read using the `[]` operator.
@ -156,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__key_type_const.output" --8<-- "examples/operatorarray__key_type_const.output"
``` ```
??? example ??? example "Example (3): access specified element via JSON Pointer"
The example below shows how values can be read and written using JSON Pointers. The example below shows how values can be read and written using JSON Pointers.
@ -170,7 +170,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorjson_pointer.output" --8<-- "examples/operatorjson_pointer.output"
``` ```
??? example ??? example "Example (3): access specified element via JSON Pointer"
The example below shows how values can be read using JSON Pointers. The example below shows how values can be read using JSON Pointers.

430
include/nlohmann/json.hpp
View File

@ -2067,32 +2067,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// Access to the JSON value. /// Access to the JSON value.
/// @{ /// @{
/*! /// @brief access specified array element with bounds checking
@brief access specified array element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a reference to the element at specified location @a idx, with
bounds checking.
@param[in] idx index of the element to access
@return reference to the element at index @a idx
@throw type_error.304 if the JSON value is not an array; in this case,
calling `at` with an index makes no sense. See example below.
@throw out_of_range.401 if the index @a idx is out of range of the array;
that is, `idx >= size()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 1.0.0
@liveexample{The example below shows how array elements can be read and
written using `at()`. It also demonstrates the different exceptions that
can be thrown.,at__size_type}
*/
reference at(size_type idx) reference at(size_type idx)
{ {
// at only works for arrays // at only works for arrays
@ -2114,32 +2090,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified array element with bounds checking
@brief access specified array element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a const reference to the element at specified location @a idx,
with bounds checking.
@param[in] idx index of the element to access
@return const reference to the element at index @a idx
@throw type_error.304 if the JSON value is not an array; in this case,
calling `at` with an index makes no sense. See example below.
@throw out_of_range.401 if the index @a idx is out of range of the array;
that is, `idx >= size()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 1.0.0
@liveexample{The example below shows how array elements can be read using
`at()`. It also demonstrates the different exceptions that can be thrown.,
at__size_type_const}
*/
const_reference at(size_type idx) const const_reference at(size_type idx) const
{ {
// at only works for arrays // at only works for arrays
@ -2161,36 +2113,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified object element with bounds checking
@brief access specified object element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a reference to the element at with specified key @a key, with
bounds checking.
@param[in] key key of the element to access
@return reference to the element at key @a key
@throw type_error.304 if the JSON value is not an object; in this case,
calling `at` with a key makes no sense. See example below.
@throw out_of_range.403 if the key @a key is is not stored in the object;
that is, `find(key) == end()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Logarithmic in the size of the container.
@sa see @ref operator[](const typename object_t::key_type&) for unchecked
access by reference
@sa see @ref value() for access by value with a default value
@since version 1.0.0
@liveexample{The example below shows how object elements can be read and
written using `at()`. It also demonstrates the different exceptions that
can be thrown.,at__object_t_key_type}
*/
reference at(const typename object_t::key_type& key) reference at(const typename object_t::key_type& key)
{ {
// at only works for objects // at only works for objects
@ -2212,36 +2136,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified object element with bounds checking
@brief access specified object element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a const reference to the element at with specified key @a key,
with bounds checking.
@param[in] key key of the element to access
@return const reference to the element at key @a key
@throw type_error.304 if the JSON value is not an object; in this case,
calling `at` with a key makes no sense. See example below.
@throw out_of_range.403 if the key @a key is is not stored in the object;
that is, `find(key) == end()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Logarithmic in the size of the container.
@sa see @ref operator[](const typename object_t::key_type&) for unchecked
access by reference
@sa see @ref value() for access by value with a default value
@since version 1.0.0
@liveexample{The example below shows how object elements can be read using
`at()`. It also demonstrates the different exceptions that can be thrown.,
at__object_t_key_type_const}
*/
const_reference at(const typename object_t::key_type& key) const const_reference at(const typename object_t::key_type& key) const
{ {
// at only works for objects // at only works for objects
@ -2263,31 +2159,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified array element
@brief access specified array element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a reference to the element at specified location @a idx.
@note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
then the array is silently filled up with `null` values to make `idx` a
valid reference to the last stored element.
@param[in] idx index of the element to access
@return reference to the element at index @a idx
@throw type_error.305 if the JSON value is not an array or null; in that
cases, using the [] operator with an index makes no sense.
@complexity Constant if @a idx is in the range of the array. Otherwise
linear in `idx - size()`.
@liveexample{The example below shows how array elements can be read and
written using `[]` operator. Note the addition of `null`
values.,operatorarray__size_type}
@since version 1.0.0
*/
reference operator[](size_type idx) reference operator[](size_type idx)
{ {
// implicitly convert null value to an empty array // implicitly convert null value to an empty array
@ -2332,25 +2205,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified array element
@brief access specified array element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a const reference to the element at specified location @a idx.
@param[in] idx index of the element to access
@return const reference to the element at index @a idx
@throw type_error.305 if the JSON value is not an array; in that case,
using the [] operator with an index makes no sense.
@complexity Constant.
@liveexample{The example below shows how array elements can be read using
the `[]` operator.,operatorarray__size_type_const}
@since version 1.0.0
*/
const_reference operator[](size_type idx) const const_reference operator[](size_type idx) const
{ {
// const operator[] only works for arrays // const operator[] only works for arrays
@ -2362,33 +2218,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a reference to the element at with specified key @a key.
@note If @a key is not found in the object, then it is silently added to
the object and filled with a `null` value to make `key` a valid reference.
In case the value was `null` before, it is converted to an object.
@param[in] key key of the element to access
@return reference to the element at key @a key
@throw type_error.305 if the JSON value is not an object or null; in that
cases, using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and
written using the `[]` operator.,operatorarray__key_type}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.0.0
*/
reference operator[](const typename object_t::key_type& key) reference operator[](const typename object_t::key_type& key)
{ {
// implicitly convert null value to an empty object // implicitly convert null value to an empty object
@ -2408,36 +2239,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief read-only access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a const reference to the element at with specified key @a key. No
bounds checking is performed.
@warning If the element with key @a key does not exist, the behavior is
undefined.
@param[in] key key of the element to access
@return const reference to the element at key @a key
@pre The element with key @a key must exist. **This precondition is
enforced with an assertion.**
@throw type_error.305 if the JSON value is not an object; in that case,
using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using
the `[]` operator.,operatorarray__key_type_const}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.0.0
*/
const_reference operator[](const typename object_t::key_type& key) const const_reference operator[](const typename object_t::key_type& key) const
{ {
// const operator[] only works for objects // const operator[] only works for objects
@ -2450,33 +2253,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a reference to the element at with specified key @a key.
@note If @a key is not found in the object, then it is silently added to
the object and filled with a `null` value to make `key` a valid reference.
In case the value was `null` before, it is converted to an object.
@param[in] key key of the element to access
@return reference to the element at key @a key
@throw type_error.305 if the JSON value is not an object or null; in that
cases, using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and
written using the `[]` operator.,operatorarray__key_type}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.1.0
*/
template<typename T> template<typename T>
JSON_HEDLEY_NON_NULL(2) JSON_HEDLEY_NON_NULL(2)
reference operator[](T* key) reference operator[](T* key)
@ -2498,36 +2276,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief read-only access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a const reference to the element at with specified key @a key. No
bounds checking is performed.
@warning If the element with key @a key does not exist, the behavior is
undefined.
@param[in] key key of the element to access
@return const reference to the element at key @a key
@pre The element with key @a key must exist. **This precondition is
enforced with an assertion.**
@throw type_error.305 if the JSON value is not an object; in that case,
using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using
the `[]` operator.,operatorarray__key_type_const}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.1.0
*/
template<typename T> template<typename T>
JSON_HEDLEY_NON_NULL(2) JSON_HEDLEY_NON_NULL(2)
const_reference operator[](T* key) const const_reference operator[](T* key) const
@ -5382,153 +5132,29 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// @name JSON Pointer functions /// @name JSON Pointer functions
/// @{ /// @{
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Uses a JSON pointer to retrieve a reference to the respective JSON value.
No bound checking is performed. Similar to @ref operator[](const typename
object_t::key_type&), `null` values are created in arrays and objects if
necessary.
In particular:
- If the JSON pointer points to an object key that does not exist, it
is created an filled with a `null` value before a reference to it
is returned.
- If the JSON pointer points to an array index that does not exist, it
is created an filled with a `null` value before a reference to it
is returned. All indices between the current maximum and the given
index are also filled with `null`.
- The special value `-` is treated as a synonym for the index past the
end.
@param[in] ptr a JSON pointer
@return reference to the element pointed to by @a ptr
@complexity Constant.
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer}
@since version 2.0.0
*/
reference operator[](const json_pointer& ptr) reference operator[](const json_pointer& ptr)
{ {
return ptr.get_unchecked(this); return ptr.get_unchecked(this);
} }
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Uses a JSON pointer to retrieve a reference to the respective JSON value.
No bound checking is performed. The function does not change the JSON
value; no `null` values are created. In particular, the special value
`-` yields an exception.
@param[in] ptr JSON pointer to the desired element
@return const reference to the element pointed to by @a ptr
@complexity Constant.
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
@since version 2.0.0
*/
const_reference operator[](const json_pointer& ptr) const const_reference operator[](const json_pointer& ptr) const
{ {
return ptr.get_unchecked(this); return ptr.get_unchecked(this);
} }
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a reference to the element at with specified JSON pointer @a ptr,
with bounds checking.
@param[in] ptr JSON pointer to the desired element
@return reference to the element pointed to by @a ptr
@throw parse_error.106 if an array index in the passed JSON pointer @a ptr
begins with '0'. See example below.
@throw parse_error.109 if an array index in the passed JSON pointer @a ptr
is not a number. See example below.
@throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
is out of range. See example below.
@throw out_of_range.402 if the array index '-' is used in the passed JSON
pointer @a ptr. As `at` provides checked access (and no elements are
implicitly inserted), the index '-' is always invalid. See example below.
@throw out_of_range.403 if the JSON pointer describes a key of an object
which cannot be found. See example below.
@throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 2.0.0
@liveexample{The behavior is shown in the example.,at_json_pointer}
*/
reference at(const json_pointer& ptr) reference at(const json_pointer& ptr)
{ {
return ptr.get_checked(this); return ptr.get_checked(this);
} }
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a const reference to the element at with specified JSON pointer @a
ptr, with bounds checking.
@param[in] ptr JSON pointer to the desired element
@return reference to the element pointed to by @a ptr
@throw parse_error.106 if an array index in the passed JSON pointer @a ptr
begins with '0'. See example below.
@throw parse_error.109 if an array index in the passed JSON pointer @a ptr
is not a number. See example below.
@throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
is out of range. See example below.
@throw out_of_range.402 if the array index '-' is used in the passed JSON
pointer @a ptr. As `at` provides checked access (and no elements are
implicitly inserted), the index '-' is always invalid. See example below.
@throw out_of_range.403 if the JSON pointer describes a key of an object
which cannot be found. See example below.
@throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 2.0.0
@liveexample{The behavior is shown in the example.,at_json_pointer_const}
*/
const_reference at(const json_pointer& ptr) const const_reference at(const json_pointer& ptr) const
{ {
return ptr.get_checked(this); return ptr.get_checked(this);

430
single_include/nlohmann/json.hpp
View File

@ -19568,32 +19568,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// Access to the JSON value. /// Access to the JSON value.
/// @{ /// @{
/*! /// @brief access specified array element with bounds checking
@brief access specified array element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a reference to the element at specified location @a idx, with
bounds checking.
@param[in] idx index of the element to access
@return reference to the element at index @a idx
@throw type_error.304 if the JSON value is not an array; in this case,
calling `at` with an index makes no sense. See example below.
@throw out_of_range.401 if the index @a idx is out of range of the array;
that is, `idx >= size()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 1.0.0
@liveexample{The example below shows how array elements can be read and
written using `at()`. It also demonstrates the different exceptions that
can be thrown.,at__size_type}
*/
reference at(size_type idx) reference at(size_type idx)
{ {
// at only works for arrays // at only works for arrays
@ -19615,32 +19591,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified array element with bounds checking
@brief access specified array element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a const reference to the element at specified location @a idx,
with bounds checking.
@param[in] idx index of the element to access
@return const reference to the element at index @a idx
@throw type_error.304 if the JSON value is not an array; in this case,
calling `at` with an index makes no sense. See example below.
@throw out_of_range.401 if the index @a idx is out of range of the array;
that is, `idx >= size()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 1.0.0
@liveexample{The example below shows how array elements can be read using
`at()`. It also demonstrates the different exceptions that can be thrown.,
at__size_type_const}
*/
const_reference at(size_type idx) const const_reference at(size_type idx) const
{ {
// at only works for arrays // at only works for arrays
@ -19662,36 +19614,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified object element with bounds checking
@brief access specified object element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a reference to the element at with specified key @a key, with
bounds checking.
@param[in] key key of the element to access
@return reference to the element at key @a key
@throw type_error.304 if the JSON value is not an object; in this case,
calling `at` with a key makes no sense. See example below.
@throw out_of_range.403 if the key @a key is is not stored in the object;
that is, `find(key) == end()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Logarithmic in the size of the container.
@sa see @ref operator[](const typename object_t::key_type&) for unchecked
access by reference
@sa see @ref value() for access by value with a default value
@since version 1.0.0
@liveexample{The example below shows how object elements can be read and
written using `at()`. It also demonstrates the different exceptions that
can be thrown.,at__object_t_key_type}
*/
reference at(const typename object_t::key_type& key) reference at(const typename object_t::key_type& key)
{ {
// at only works for objects // at only works for objects
@ -19713,36 +19637,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified object element with bounds checking
@brief access specified object element with bounds checking /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a const reference to the element at with specified key @a key,
with bounds checking.
@param[in] key key of the element to access
@return const reference to the element at key @a key
@throw type_error.304 if the JSON value is not an object; in this case,
calling `at` with a key makes no sense. See example below.
@throw out_of_range.403 if the key @a key is is not stored in the object;
that is, `find(key) == end()`. See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Logarithmic in the size of the container.
@sa see @ref operator[](const typename object_t::key_type&) for unchecked
access by reference
@sa see @ref value() for access by value with a default value
@since version 1.0.0
@liveexample{The example below shows how object elements can be read using
`at()`. It also demonstrates the different exceptions that can be thrown.,
at__object_t_key_type_const}
*/
const_reference at(const typename object_t::key_type& key) const const_reference at(const typename object_t::key_type& key) const
{ {
// at only works for objects // at only works for objects
@ -19764,31 +19660,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief access specified array element
@brief access specified array element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a reference to the element at specified location @a idx.
@note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
then the array is silently filled up with `null` values to make `idx` a
valid reference to the last stored element.
@param[in] idx index of the element to access
@return reference to the element at index @a idx
@throw type_error.305 if the JSON value is not an array or null; in that
cases, using the [] operator with an index makes no sense.
@complexity Constant if @a idx is in the range of the array. Otherwise
linear in `idx - size()`.
@liveexample{The example below shows how array elements can be read and
written using `[]` operator. Note the addition of `null`
values.,operatorarray__size_type}
@since version 1.0.0
*/
reference operator[](size_type idx) reference operator[](size_type idx)
{ {
// implicitly convert null value to an empty array // implicitly convert null value to an empty array
@ -19833,25 +19706,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified array element
@brief access specified array element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a const reference to the element at specified location @a idx.
@param[in] idx index of the element to access
@return const reference to the element at index @a idx
@throw type_error.305 if the JSON value is not an array; in that case,
using the [] operator with an index makes no sense.
@complexity Constant.
@liveexample{The example below shows how array elements can be read using
the `[]` operator.,operatorarray__size_type_const}
@since version 1.0.0
*/
const_reference operator[](size_type idx) const const_reference operator[](size_type idx) const
{ {
// const operator[] only works for arrays // const operator[] only works for arrays
@ -19863,33 +19719,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a reference to the element at with specified key @a key.
@note If @a key is not found in the object, then it is silently added to
the object and filled with a `null` value to make `key` a valid reference.
In case the value was `null` before, it is converted to an object.
@param[in] key key of the element to access
@return reference to the element at key @a key
@throw type_error.305 if the JSON value is not an object or null; in that
cases, using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and
written using the `[]` operator.,operatorarray__key_type}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.0.0
*/
reference operator[](const typename object_t::key_type& key) reference operator[](const typename object_t::key_type& key)
{ {
// implicitly convert null value to an empty object // implicitly convert null value to an empty object
@ -19909,36 +19740,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief read-only access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a const reference to the element at with specified key @a key. No
bounds checking is performed.
@warning If the element with key @a key does not exist, the behavior is
undefined.
@param[in] key key of the element to access
@return const reference to the element at key @a key
@pre The element with key @a key must exist. **This precondition is
enforced with an assertion.**
@throw type_error.305 if the JSON value is not an object; in that case,
using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using
the `[]` operator.,operatorarray__key_type_const}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.0.0
*/
const_reference operator[](const typename object_t::key_type& key) const const_reference operator[](const typename object_t::key_type& key) const
{ {
// const operator[] only works for objects // const operator[] only works for objects
@ -19951,33 +19754,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a reference to the element at with specified key @a key.
@note If @a key is not found in the object, then it is silently added to
the object and filled with a `null` value to make `key` a valid reference.
In case the value was `null` before, it is converted to an object.
@param[in] key key of the element to access
@return reference to the element at key @a key
@throw type_error.305 if the JSON value is not an object or null; in that
cases, using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read and
written using the `[]` operator.,operatorarray__key_type}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.1.0
*/
template<typename T> template<typename T>
JSON_HEDLEY_NON_NULL(2) JSON_HEDLEY_NON_NULL(2)
reference operator[](T* key) reference operator[](T* key)
@ -19999,36 +19777,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element
@brief read-only access specified object element /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Returns a const reference to the element at with specified key @a key. No
bounds checking is performed.
@warning If the element with key @a key does not exist, the behavior is
undefined.
@param[in] key key of the element to access
@return const reference to the element at key @a key
@pre The element with key @a key must exist. **This precondition is
enforced with an assertion.**
@throw type_error.305 if the JSON value is not an object; in that case,
using the [] operator with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be read using
the `[]` operator.,operatorarray__key_type_const}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref value() for access by value with a default value
@since version 1.1.0
*/
template<typename T> template<typename T>
JSON_HEDLEY_NON_NULL(2) JSON_HEDLEY_NON_NULL(2)
const_reference operator[](T* key) const const_reference operator[](T* key) const
@ -22883,153 +22633,29 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// @name JSON Pointer functions /// @name JSON Pointer functions
/// @{ /// @{
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Uses a JSON pointer to retrieve a reference to the respective JSON value.
No bound checking is performed. Similar to @ref operator[](const typename
object_t::key_type&), `null` values are created in arrays and objects if
necessary.
In particular:
- If the JSON pointer points to an object key that does not exist, it
is created an filled with a `null` value before a reference to it
is returned.
- If the JSON pointer points to an array index that does not exist, it
is created an filled with a `null` value before a reference to it
is returned. All indices between the current maximum and the given
index are also filled with `null`.
- The special value `-` is treated as a synonym for the index past the
end.
@param[in] ptr a JSON pointer
@return reference to the element pointed to by @a ptr
@complexity Constant.
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer}
@since version 2.0.0
*/
reference operator[](const json_pointer& ptr) reference operator[](const json_pointer& ptr)
{ {
return ptr.get_unchecked(this); return ptr.get_unchecked(this);
} }
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
Uses a JSON pointer to retrieve a reference to the respective JSON value.
No bound checking is performed. The function does not change the JSON
value; no `null` values are created. In particular, the special value
`-` yields an exception.
@param[in] ptr JSON pointer to the desired element
@return const reference to the element pointed to by @a ptr
@complexity Constant.
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
@since version 2.0.0
*/
const_reference operator[](const json_pointer& ptr) const const_reference operator[](const json_pointer& ptr) const
{ {
return ptr.get_unchecked(this); return ptr.get_unchecked(this);
} }
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a reference to the element at with specified JSON pointer @a ptr,
with bounds checking.
@param[in] ptr JSON pointer to the desired element
@return reference to the element pointed to by @a ptr
@throw parse_error.106 if an array index in the passed JSON pointer @a ptr
begins with '0'. See example below.
@throw parse_error.109 if an array index in the passed JSON pointer @a ptr
is not a number. See example below.
@throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
is out of range. See example below.
@throw out_of_range.402 if the array index '-' is used in the passed JSON
pointer @a ptr. As `at` provides checked access (and no elements are
implicitly inserted), the index '-' is always invalid. See example below.
@throw out_of_range.403 if the JSON pointer describes a key of an object
which cannot be found. See example below.
@throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 2.0.0
@liveexample{The behavior is shown in the example.,at_json_pointer}
*/
reference at(const json_pointer& ptr) reference at(const json_pointer& ptr)
{ {
return ptr.get_checked(this); return ptr.get_checked(this);
} }
/*! /// @brief access specified element via JSON Pointer
@brief access specified element via JSON Pointer /// @sa https://json.nlohmann.me/api/basic_json/at/
Returns a const reference to the element at with specified JSON pointer @a
ptr, with bounds checking.
@param[in] ptr JSON pointer to the desired element
@return reference to the element pointed to by @a ptr
@throw parse_error.106 if an array index in the passed JSON pointer @a ptr
begins with '0'. See example below.
@throw parse_error.109 if an array index in the passed JSON pointer @a ptr
is not a number. See example below.
@throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
is out of range. See example below.
@throw out_of_range.402 if the array index '-' is used in the passed JSON
pointer @a ptr. As `at` provides checked access (and no elements are
implicitly inserted), the index '-' is always invalid. See example below.
@throw out_of_range.403 if the JSON pointer describes a key of an object
which cannot be found. See example below.
@throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
See example below.
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 2.0.0
@liveexample{The behavior is shown in the example.,at_json_pointer_const}
*/
const_reference at(const json_pointer& ptr) const const_reference at(const json_pointer& ptr) const
{ {
return ptr.get_checked(this); return ptr.get_checked(this);