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-10 15:32:59 +02:00
parent cb60de9e69
commit 5e04a6a2ba
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
5 changed files with 82 additions and 276 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/mkdocs/docs/api/basic_json/back.md
View File

@ -55,6 +55,10 @@ Constant.
--8<-- "examples/back.output"
```
## See also
- [front](front.md) to access the first element
## Version history
- Added in version 1.0.0.

54
doc/mkdocs/docs/api/basic_json/contains.md
View File

@ -1,12 +1,17 @@
# basic_json::contains
```cpp
// (1)
template<typename KeyT>
bool contains(KeyT && key) const;
// (2)
bool contains(const json_pointer& ptr) const
```
Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the JSON
value is not an object, `#!cpp false` is returned.
1. Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the
JSON value is not an object, `#!cpp false` is returned.
2. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
## Template parameters
@ -17,27 +22,45 @@ value is not an object, `#!cpp false` is returned.
`key` (in)
: key value to check its existence.
`ptr` (in)
: JSON pointer to check its existence.
## Return value
`#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value is
not an object, `#!cpp false` is returned.
1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value
is not an object, `#!cpp false` is returned.
2. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. The function does not throw exceptions.
2. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index begins with
`0`.
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index was not a
number.
## Complexity
Logarithmic in the size of the JSON object.
## Notes
This method always returns `#!cpp false` when executed on a JSON type that is not an object.
1. This method always returns `#!cpp false` when executed on a JSON type that is not an object.
2. This method can be executed on any JSON value type.
!!! info "Postconditions"
If `#!cpp j.contains(x)` returns `#!c true` for a key or JSON pointer `x`, then it is safe to call `j[x]`.
## Example
??? example
??? example "Example (1) check with key"
The example shows how `contains()` is used.
@ -51,6 +74,21 @@ This method always returns `#!cpp false` when executed on a JSON type that is no
--8<-- "examples/contains.output"
```
??? example "Example (1) check with JSON pointer"
The example shows how `contains()` is used.
```cpp
--8<-- "examples/contains_json_pointer.cpp"
```
Output:
```json
--8<-- "examples/contains_json_pointer.output"
```
## Version history
- Added in version 3.6.0.
1. Added in version 3.6.0.
2. Added in version 3.7.0.

4
doc/mkdocs/docs/api/basic_json/front.md
View File

@ -48,6 +48,10 @@ Constant.
--8<-- "examples/front.output"
```
## See also
- [back](back.md) to access the last element
## Version history
- Added in version 1.0.0.

148
include/nlohmann/json.hpp
View File

@ -3188,75 +3188,22 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return value(ptr, string_t(default_value));
}
/*!
@brief access the first element
Returns a reference to the first element in the container. For a JSON
container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
@return In case of a structured type (array or object), a reference to the
first element is returned. In case of number, string, boolean, or binary
values, a reference to the value is returned.
@complexity Constant.
@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 invalid_iterator.214 when called on `null` value
@liveexample{The following code shows an example for `front()`.,front}
@sa see @ref back() -- access the last element
@since version 1.0.0
*/
/// @brief access the first element
/// @sa https://json.nlohmann.me/api/basic_json/front/
reference front()
{
return *begin();
}
/*!
@copydoc basic_json::front()
*/
/// @brief access the first element
/// @sa https://json.nlohmann.me/api/basic_json/front/
const_reference front() const
{
return *cbegin();
}
/*!
@brief access the last element
Returns a reference to the last element in the container. For a JSON
container `c`, the expression `c.back()` is equivalent to
@code {.cpp}
auto tmp = c.end();
--tmp;
return *tmp;
@endcode
@return In case of a structured type (array or object), a reference to the
last element is returned. In case of number, string, boolean, or binary
values, a reference to the value is returned.
@complexity Constant.
@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 invalid_iterator.214 when called on a `null` value. See example
below.
@liveexample{The following code shows an example for `back()`.,back}
@sa see @ref front() -- access the first element
@since version 1.0.0
*/
/// @brief access the last element
/// @sa https://json.nlohmann.me/api/basic_json/back/
reference back()
{
auto tmp = end();
@ -3264,9 +3211,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return *tmp;
}
/*!
@copydoc basic_json::back()
*/
/// @brief access the last element
/// @sa https://json.nlohmann.me/api/basic_json/back/
const_reference back() const
{
auto tmp = cend();
@ -3653,27 +3599,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result;
}
/*!
@brief returns the number of occurrences of a key in a JSON object
Returns the number of elements with key @a key. If ObjectType is the
default `std::map` type, the return value will always be `0` (@a key was
not found) or `1` (@a key was found).
@note This method always returns `0` when executed on a JSON type that is
not an object.
@param[in] key key value of the element to count
@return Number of elements with key @a key. If the JSON value is not an
object, the return value will be `0`.
@complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how `count()` is used.,count}
@since version 1.0.0
*/
/// @brief returns the number of occurrences of a key in a JSON object
/// @sa https://json.nlohmann.me/api/basic_json/count/
template<typename KeyT>
size_type count(KeyT&& key) const
{
@ -3681,31 +3608,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return is_object() ? m_value.object->count(std::forward<KeyT>(key)) : 0;
}
/*!
@brief check the existence of an element in a JSON object
Check whether an element exists in a JSON object with key equivalent to
@a key. If the element is not found or the JSON value is not an object,
false is returned.
@note This method always returns false when executed on a JSON type
that is not an object.
@param[in] key key value to check its existence.
@return true if an element with specified @a key exists. If no such
element with such key is found or the JSON value is not an object,
false is returned.
@complexity Logarithmic in the size of the JSON object.
@liveexample{The following code shows an example for `contains()`.,contains}
@sa see @ref find(KeyT&&) -- returns an iterator to an object element
@sa see @ref contains(const json_pointer&) const -- checks the existence for a JSON pointer
@since version 3.6.0
*/
/// @brief check the existence of an element in a JSON object
/// @sa https://json.nlohmann.me/api/basic_json/contains/
template < typename KeyT, typename std::enable_if <
!std::is_same<typename std::decay<KeyT>::type, json_pointer>::value, int >::type = 0 >
bool contains(KeyT && key) const
@ -3713,32 +3617,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return is_object() && m_value.object->find(std::forward<KeyT>(key)) != m_value.object->end();
}
/*!
@brief check the existence of an element in a JSON object given a JSON pointer
Check whether the given JSON pointer @a ptr can be resolved in the current
JSON value.
@note This method can be executed on any JSON value type.
@param[in] ptr JSON pointer to check its existence.
@return true if the JSON pointer can be resolved to a stored value, false
otherwise.
@post If `j.contains(ptr)` returns true, it is safe to call `j[ptr]`.
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@complexity Logarithmic in the size of the JSON object.
@liveexample{The following code shows an example for `contains()`.,contains_json_pointer}
@sa see @ref contains(KeyT &&) const -- checks the existence of a key
@since version 3.7.0
*/
/// @brief check the existence of an element in a JSON object given a JSON pointer
/// @sa https://json.nlohmann.me/api/basic_json/contains/
bool contains(const json_pointer& ptr) const
{
return ptr.contains(this);

148
single_include/nlohmann/json.hpp
View File

@ -20675,75 +20675,22 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return value(ptr, string_t(default_value));
}
/*!
@brief access the first element
Returns a reference to the first element in the container. For a JSON
container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
@return In case of a structured type (array or object), a reference to the
first element is returned. In case of number, string, boolean, or binary
values, a reference to the value is returned.
@complexity Constant.
@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 invalid_iterator.214 when called on `null` value
@liveexample{The following code shows an example for `front()`.,front}
@sa see @ref back() -- access the last element
@since version 1.0.0
*/
/// @brief access the first element
/// @sa https://json.nlohmann.me/api/basic_json/front/
reference front()
{
return *begin();
}
/*!
@copydoc basic_json::front()
*/
/// @brief access the first element
/// @sa https://json.nlohmann.me/api/basic_json/front/
const_reference front() const
{
return *cbegin();
}
/*!
@brief access the last element
Returns a reference to the last element in the container. For a JSON
container `c`, the expression `c.back()` is equivalent to
@code {.cpp}
auto tmp = c.end();
--tmp;
return *tmp;
@endcode
@return In case of a structured type (array or object), a reference to the
last element is returned. In case of number, string, boolean, or binary
values, a reference to the value is returned.
@complexity Constant.
@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 invalid_iterator.214 when called on a `null` value. See example
below.
@liveexample{The following code shows an example for `back()`.,back}
@sa see @ref front() -- access the first element
@since version 1.0.0
*/
/// @brief access the last element
/// @sa https://json.nlohmann.me/api/basic_json/back/
reference back()
{
auto tmp = end();
@ -20751,9 +20698,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return *tmp;
}
/*!
@copydoc basic_json::back()
*/
/// @brief access the last element
/// @sa https://json.nlohmann.me/api/basic_json/back/
const_reference back() const
{
auto tmp = cend();
@ -21140,27 +21086,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result;
}
/*!
@brief returns the number of occurrences of a key in a JSON object
Returns the number of elements with key @a key. If ObjectType is the
default `std::map` type, the return value will always be `0` (@a key was
not found) or `1` (@a key was found).
@note This method always returns `0` when executed on a JSON type that is
not an object.
@param[in] key key value of the element to count
@return Number of elements with key @a key. If the JSON value is not an
object, the return value will be `0`.
@complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how `count()` is used.,count}
@since version 1.0.0
*/
/// @brief returns the number of occurrences of a key in a JSON object
/// @sa https://json.nlohmann.me/api/basic_json/count/
template<typename KeyT>
size_type count(KeyT&& key) const
{
@ -21168,31 +21095,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return is_object() ? m_value.object->count(std::forward<KeyT>(key)) : 0;
}
/*!
@brief check the existence of an element in a JSON object
Check whether an element exists in a JSON object with key equivalent to
@a key. If the element is not found or the JSON value is not an object,
false is returned.
@note This method always returns false when executed on a JSON type
that is not an object.
@param[in] key key value to check its existence.
@return true if an element with specified @a key exists. If no such
element with such key is found or the JSON value is not an object,
false is returned.
@complexity Logarithmic in the size of the JSON object.
@liveexample{The following code shows an example for `contains()`.,contains}
@sa see @ref find(KeyT&&) -- returns an iterator to an object element
@sa see @ref contains(const json_pointer&) const -- checks the existence for a JSON pointer
@since version 3.6.0
*/
/// @brief check the existence of an element in a JSON object
/// @sa https://json.nlohmann.me/api/basic_json/contains/
template < typename KeyT, typename std::enable_if <
!std::is_same<typename std::decay<KeyT>::type, json_pointer>::value, int >::type = 0 >
bool contains(KeyT && key) const
@ -21200,32 +21104,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return is_object() && m_value.object->find(std::forward<KeyT>(key)) != m_value.object->end();
}
/*!
@brief check the existence of an element in a JSON object given a JSON pointer
Check whether the given JSON pointer @a ptr can be resolved in the current
JSON value.
@note This method can be executed on any JSON value type.
@param[in] ptr JSON pointer to check its existence.
@return true if the JSON pointer can be resolved to a stored value, false
otherwise.
@post If `j.contains(ptr)` returns true, it is safe to call `j[ptr]`.
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@complexity Logarithmic in the size of the JSON object.
@liveexample{The following code shows an example for `contains()`.,contains_json_pointer}
@sa see @ref contains(KeyT &&) const -- checks the existence of a key
@since version 3.7.0
*/
/// @brief check the existence of an element in a JSON object given a JSON pointer
/// @sa https://json.nlohmann.me/api/basic_json/contains/
bool contains(const json_pointer& ptr) const
{
return ptr.contains(this);