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:21:49 +02:00
parent 15a779cde7
commit 7dfe09f7ac
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
5 changed files with 44 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -164,6 +164,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at_json_pointer_const.output" --8<-- "examples/at_json_pointer_const.output"
``` ```
## See also
- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
- see [`value`](value.md) for access with default value
## Version history ## Version history
1. Added in version 1.0.0. 1. Added in version 1.0.0.

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

@ -184,6 +184,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorjson_pointer_const.output" --8<-- "examples/operatorjson_pointer_const.output"
``` ```
## See also
- see [`at`](at.md) for access by reference with range checking
- see [`value`](value.md) for access with default value
## Version history ## Version history
1. Added in version 1.0.0. 1. Added in version 1.0.0.

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

@ -36,8 +36,11 @@ ValueType value(const json_pointer& ptr,
} }
``` ```
Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by !!! note
`key`/`ptr` key. This function is furthermore also applicable to const objects.
- Unlike [`at`](at.md), this function does not throw if the given `key`/`ptr` was not found.
- Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
`key`/`ptr` key. This function is furthermore also applicable to const objects.
## Template parameters ## Template parameters
@ -87,7 +90,7 @@ changes to any JSON value.
## Example ## Example
??? example ??? example "Example (1): access specified object element with default value"
The example below shows how object elements can be queried with a default value. The example below shows how object elements can be queried with a default value.
@ -101,7 +104,7 @@ changes to any JSON value.
--8<-- "examples/basic_json__value.output" --8<-- "examples/basic_json__value.output"
``` ```
??? example ??? example "Example (2): access specified object element via JSON Pointer with default value"
The example below shows how object elements can be queried with a default value. The example below shows how object elements can be queried with a default value.
@ -115,6 +118,11 @@ changes to any JSON value.
--8<-- "examples/basic_json__value_ptr.output" --8<-- "examples/basic_json__value_ptr.output"
``` ```
## See also
- see [`at`](at.md) for access by reference with range checking
- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
## Version history ## Version history
1. Added in version 1.0.0. 1. Added in version 1.0.0.

113
include/nlohmann/json.hpp
View File

@ -2292,57 +2292,9 @@ 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 with default value
@brief access specified object element with default value /// @sa https://json.nlohmann.me/api/basic_json/value/
/// using std::is_convertible in a std::enable_if will fail when using explicit conversions
Returns either a copy of an object's element at the specified key @a key
or a given default value if no element with key @a key exists.
The function is basically equivalent to executing
@code {.cpp}
try {
return at(key);
} catch(out_of_range) {
return default_value;
}
@endcode
@note Unlike @ref at(const typename object_t::key_type&), this function
does not throw if the given key @a key was not found.
@note Unlike @ref operator[](const typename object_t::key_type& key), this
function does not implicitly add an element to the position defined by @a
key. This function is furthermore also applicable to const objects.
@param[in] key key of the element to access
@param[in] default_value the value to return if @a key is not found
@tparam ValueType type compatible to JSON values, for instance `int` for
JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
JSON arrays. Note the type of the expected value at @a key and the default
value @a default_value must be compatible.
@return copy of the element at key @a key or @a default_value if @a key
is not found
@throw type_error.302 if @a default_value does not match the type of the
value at @a key
@throw type_error.306 if the JSON value is not an object; in that case,
using `value()` with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be queried
with a default value.,basic_json__value}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref operator[](const typename object_t::key_type&) for unchecked
access by reference
@since version 1.0.0
*/
// using std::is_convertible in a std::enable_if will fail when using explicit conversions
template < class ValueType, typename std::enable_if < template < class ValueType, typename std::enable_if <
detail::is_getable<basic_json_t, ValueType>::value detail::is_getable<basic_json_t, ValueType>::value
&& !std::is_same<value_t, ValueType>::value, int >::type = 0 > && !std::is_same<value_t, ValueType>::value, int >::type = 0 >
@ -2364,58 +2316,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element with default value
@brief overload for a default value of type const char* /// @sa https://json.nlohmann.me/api/basic_json/value/
@copydoc basic_json::value(const typename object_t::key_type&, const ValueType&) const /// overload for a default value of type const char*
*/
string_t value(const typename object_t::key_type& key, const char* default_value) const string_t value(const typename object_t::key_type& key, const char* default_value) const
{ {
return value(key, string_t(default_value)); return value(key, string_t(default_value));
} }
/*! /// @brief access specified object element via JSON Pointer with default value
@brief access specified object element via JSON Pointer with default value /// @sa https://json.nlohmann.me/api/basic_json/value/
Returns either a copy of an object's element at the specified key @a key
or a given default value if no element with key @a key exists.
The function is basically equivalent to executing
@code {.cpp}
try {
return at(ptr);
} catch(out_of_range) {
return default_value;
}
@endcode
@note Unlike @ref at(const json_pointer&), this function does not throw
if the given key @a key was not found.
@param[in] ptr a JSON pointer to the element to access
@param[in] default_value the value to return if @a ptr found no value
@tparam ValueType type compatible to JSON values, for instance `int` for
JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
JSON arrays. Note the type of the expected value at @a key and the default
value @a default_value must be compatible.
@return copy of the element at key @a key or @a default_value if @a key
is not found
@throw type_error.302 if @a default_value does not match the type of the
value at @a ptr
@throw type_error.306 if the JSON value is not an object; in that case,
using `value()` with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be queried
with a default value.,basic_json__value_ptr}
@sa see @ref operator[](const json_pointer&) for unchecked access by reference
@since version 2.0.2
*/
template<class ValueType, typename std::enable_if< template<class ValueType, typename std::enable_if<
detail::is_getable<basic_json_t, ValueType>::value, int>::type = 0> detail::is_getable<basic_json_t, ValueType>::value, int>::type = 0>
ValueType value(const json_pointer& ptr, const ValueType& default_value) const ValueType value(const json_pointer& ptr, const ValueType& default_value) const
@ -2437,10 +2347,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element via JSON Pointer with default value
@brief overload for a default value of type const char* /// @sa https://json.nlohmann.me/api/basic_json/value/
@copydoc basic_json::value(const json_pointer&, ValueType) const /// overload for a default value of type const char*
*/
JSON_HEDLEY_NON_NULL(3) JSON_HEDLEY_NON_NULL(3)
string_t value(const json_pointer& ptr, const char* default_value) const string_t value(const json_pointer& ptr, const char* default_value) const
{ {

113
single_include/nlohmann/json.hpp
View File

@ -19793,57 +19793,9 @@ 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 with default value
@brief access specified object element with default value /// @sa https://json.nlohmann.me/api/basic_json/value/
/// using std::is_convertible in a std::enable_if will fail when using explicit conversions
Returns either a copy of an object's element at the specified key @a key
or a given default value if no element with key @a key exists.
The function is basically equivalent to executing
@code {.cpp}
try {
return at(key);
} catch(out_of_range) {
return default_value;
}
@endcode
@note Unlike @ref at(const typename object_t::key_type&), this function
does not throw if the given key @a key was not found.
@note Unlike @ref operator[](const typename object_t::key_type& key), this
function does not implicitly add an element to the position defined by @a
key. This function is furthermore also applicable to const objects.
@param[in] key key of the element to access
@param[in] default_value the value to return if @a key is not found
@tparam ValueType type compatible to JSON values, for instance `int` for
JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
JSON arrays. Note the type of the expected value at @a key and the default
value @a default_value must be compatible.
@return copy of the element at key @a key or @a default_value if @a key
is not found
@throw type_error.302 if @a default_value does not match the type of the
value at @a key
@throw type_error.306 if the JSON value is not an object; in that case,
using `value()` with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be queried
with a default value.,basic_json__value}
@sa see @ref at(const typename object_t::key_type&) for access by reference
with range checking
@sa see @ref operator[](const typename object_t::key_type&) for unchecked
access by reference
@since version 1.0.0
*/
// using std::is_convertible in a std::enable_if will fail when using explicit conversions
template < class ValueType, typename std::enable_if < template < class ValueType, typename std::enable_if <
detail::is_getable<basic_json_t, ValueType>::value detail::is_getable<basic_json_t, ValueType>::value
&& !std::is_same<value_t, ValueType>::value, int >::type = 0 > && !std::is_same<value_t, ValueType>::value, int >::type = 0 >
@ -19865,58 +19817,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element with default value
@brief overload for a default value of type const char* /// @sa https://json.nlohmann.me/api/basic_json/value/
@copydoc basic_json::value(const typename object_t::key_type&, const ValueType&) const /// overload for a default value of type const char*
*/
string_t value(const typename object_t::key_type& key, const char* default_value) const string_t value(const typename object_t::key_type& key, const char* default_value) const
{ {
return value(key, string_t(default_value)); return value(key, string_t(default_value));
} }
/*! /// @brief access specified object element via JSON Pointer with default value
@brief access specified object element via JSON Pointer with default value /// @sa https://json.nlohmann.me/api/basic_json/value/
Returns either a copy of an object's element at the specified key @a key
or a given default value if no element with key @a key exists.
The function is basically equivalent to executing
@code {.cpp}
try {
return at(ptr);
} catch(out_of_range) {
return default_value;
}
@endcode
@note Unlike @ref at(const json_pointer&), this function does not throw
if the given key @a key was not found.
@param[in] ptr a JSON pointer to the element to access
@param[in] default_value the value to return if @a ptr found no value
@tparam ValueType type compatible to JSON values, for instance `int` for
JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
JSON arrays. Note the type of the expected value at @a key and the default
value @a default_value must be compatible.
@return copy of the element at key @a key or @a default_value if @a key
is not found
@throw type_error.302 if @a default_value does not match the type of the
value at @a ptr
@throw type_error.306 if the JSON value is not an object; in that case,
using `value()` with a key makes no sense.
@complexity Logarithmic in the size of the container.
@liveexample{The example below shows how object elements can be queried
with a default value.,basic_json__value_ptr}
@sa see @ref operator[](const json_pointer&) for unchecked access by reference
@since version 2.0.2
*/
template<class ValueType, typename std::enable_if< template<class ValueType, typename std::enable_if<
detail::is_getable<basic_json_t, ValueType>::value, int>::type = 0> detail::is_getable<basic_json_t, ValueType>::value, int>::type = 0>
ValueType value(const json_pointer& ptr, const ValueType& default_value) const ValueType value(const json_pointer& ptr, const ValueType& default_value) const
@ -19938,10 +19848,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this)); JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
} }
/*! /// @brief access specified object element via JSON Pointer with default value
@brief overload for a default value of type const char* /// @sa https://json.nlohmann.me/api/basic_json/value/
@copydoc basic_json::value(const json_pointer&, ValueType) const /// overload for a default value of type const char*
*/
JSON_HEDLEY_NON_NULL(3) JSON_HEDLEY_NON_NULL(3)
string_t value(const json_pointer& ptr, const char* default_value) const string_t value(const json_pointer& ptr, const char* default_value) const
{ {