// (1) template<class ValueType> ValueType value(const typename object_t::key_type& key, ValueType&& default_value) const; // (2) template<class KeyType, class ValueType> ValueType value(KeyType&& key, ValueType&& default_value) const; // (3) template<class ValueType> ValueType value(const json_pointer& ptr, const ValueType& default_value) const;
Returns either a copy of an object's element at the specified key key
or a given default value if no element with key key
exists.
The function is basically equivalent to executing
try { return at(key); } catch(out_of_range) { return default_value; }
See 1. This overload is only available if KeyType
is comparable with #!cpp typename object_t::key_type
and #!cpp typename object_comparator_t::is_transparent
denotes a type.
Returns either a copy of an object's element at the specified JSON pointer ptr
or a given default value if no value at ptr
exists.
The function is basically equivalent to executing
try { return at(ptr); } catch(out_of_range) { return default_value; }
!!! note “Differences to at
and operator[]
”
- 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.
KeyType
: A type for an object key other than json_pointer
that is comparable with string_t
using object_comparator_t
. This can also be a string view (C++17). ValueType
: type compatible to JSON values, for instance #!cpp int
for JSON integer numbers, #!cpp bool
for JSON booleans, or #!cpp std::vector
types for JSON arrays. Note the type of the expected value at key
/ptr
and the default value default_value
must be compatible.
key
(in) : key of the element to access
default_value
(in) : the value to return if key
/ptr
found no value
ptr
(in) : a JSON pointer to the element to access
key
or default_value
if key
is not foundkey
or default_value
if key
is not foundptr
or default_value
if no value for ptr
is foundStrong guarantee: if an exception is thrown, there are no changes to any JSON value.
type_error.302
if default_value
does not match the type of the value at key
type_error.306
if the JSON value is not an object; in that case, using value()
with a key makes no sense.type_error.302
if default_value
does not match the type of the value at ptr
type_error.306
if the JSON value is not an object; in that case, using value()
with a key makes no sense.??? example “Example: (1) access specified object element with default value”
The example below shows how object elements can be queried with a default value. ```cpp --8<-- "examples/value__object_t_key_type.cpp" ``` Output: ```json --8<-- "examples/value__object_t_key_type.output" ```
??? example “Example: (2) access specified object element using string_view with default value”
The example below shows how object elements can be queried with a default value. ```cpp --8<-- "examples/value__keytype.c++17.cpp" ``` Output: ```json --8<-- "examples/value__keytype.c++17.output" ```
??? example “Example: (3) access specified object element via JSON Pointer with default value”
The example below shows how object elements can be queried with a default value. ```cpp --8<-- "examples/value__json_ptr.cpp" ``` Output: ```json --8<-- "examples/value__json_ptr.output" ```
at
for access by reference with range checkingoperator[]
for unchecked access by referencedefault_value
type from const ValueType&
to ValueType&&
in version 3.11.0.