// (1) template<class ValueType> ValueType value(const typename object_t::key_type& key, ValueType&& default_value) const; // (2) template<class ValueType, class KeyType> ValueType value(KeyType&& key, ValueType&& default_value) const; // (3) template<class ValueType> ValueType value(const json_pointer& ptr, const ValueType& default_value) const;
This is equivalent to Python's dict.get(key, default).
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.
!!! note “Integer keys”
Calling this function with an integer `key` argument (for example, `#!cpp value(0, 1)`) does not compile in C++11, where `object_comparator_t` is not transparent: such an argument would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when constructing a `#!cpp std::string` for the object key. To access an array element with a default value, use [`at`](at.md) together with a `#!cpp try`/`#!cpp catch` block, or compare against [`size`](size.md) instead.
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 keytype_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 ptrtype_error.306 if the JSON value is not an array or object; in that case, using value() with a JSON pointer makes no sense.parse_error.106 if an array index in the passed JSON pointer ptr begins with ‘0’.parse_error.109 if an array index in the passed JSON pointer ptr is not a number.!!! warning “null members are not missing”
The default value is used only if the key (or JSON Pointer) does not exist. A member that exists but is
`#!json null` is converted like any other value, so `#!cpp j.value("k", 0)` throws a
[`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `"k"` is `#!json null`. See
[Access with default value](../../features/element_access/default_value.md)
for alternatives.
!!! warning “Return type”
The value function is a template, and the return type of the function is determined by the type of the provided
default value unless otherwise specified. This can have unexpected effects. In the example below, we store a 64-bit
unsigned integer. We get exactly that value when using [`operator[]`](operator[].md). However, when we call `value`
and provide `#!c 0` as default value, then `#!c -1` is returned. This occurs, because `#!c 0` has type `#!c int`
which overflows when handling the value `#!c 18446744073709551615`.
To address this issue, either provide a correctly typed default value or use the template parameter to specify the
desired return type. Note that this issue occurs even when a value is stored at the provided key, and the default
value is not used as the return value.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
json j = json::parse(R"({"uint64": 18446744073709551615})");
std::cout << "operator[]: " << j["uint64"] << '\n'
<< "default value (int): " << j.value("uint64", 0) << '\n'
<< "default value (uint64_t): " << j.value("uint64", std::uint64_t(0)) << '\n'
<< "explicit return value type: " << j.value<std::uint64_t>("uint64", 0) << '\n';
}
```
Output:
```json
operator[]: 18446744073709551615
default value (int): -1
default value (uint64_t): 18446744073709551615
explicit return value type: 18446744073709551615
```
!!! warning “Deprecation”
Overload (3) also accepts a [`json_pointer`](../json_pointer/index.md) whose template argument is a `basic_json` specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`, `nlohmann::json_pointer<std::string>`) instead. You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function. See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
??? 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
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON object with different entry types
json j =
{
{"integer", 1},
{"floating", 42.23},
{"string", "hello world"},
{"boolean", true},
{"object", {{"key1", 1}, {"key2", 2}}},
{"array", {1, 2, 3}}
};
// access existing values
int v_integer = j.value("integer", 0);
double v_floating = j.value("floating", 47.11);
// access nonexisting values and rely on default value
std::string v_string = j.value("nonexisting", "oops");
bool v_boolean = j.value("nonexisting", false);
// output values
std::cout << std::boolalpha << v_integer << " " << v_floating
<< " " << v_string << " " << v_boolean << "\n";
}
```
Output:
```json
1 42.23 oops false
```
??? 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
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
int main()
{
// create a JSON object with different entry types
json j =
{
{"integer", 1},
{"floating", 42.23},
{"string", "hello world"},
{"boolean", true},
{"object", {{"key1", 1}, {"key2", 2}}},
{"array", {1, 2, 3}}
};
// access existing values
int v_integer = j.value("integer"sv, 0);
double v_floating = j.value("floating"sv, 47.11);
// access nonexisting values and rely on default value
std::string v_string = j.value("nonexisting"sv, "oops");
bool v_boolean = j.value("nonexisting"sv, false);
// output values
std::cout << std::boolalpha << v_integer << " " << v_floating
<< " " << v_string << " " << v_boolean << "\n";
}
```
Output:
```json
1 42.23 oops false
```
??? 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
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create a JSON object with different entry types
json j =
{
{"integer", 1},
{"floating", 42.23},
{"string", "hello world"},
{"boolean", true},
{"object", {{"key1", 1}, {"key2", 2}}},
{"array", {1, 2, 3}}
};
// access existing values
int v_integer = j.value("/integer"_json_pointer, 0);
double v_floating = j.value("/floating"_json_pointer, 47.11);
// access nonexisting values and rely on default value
std::string v_string = j.value("/nonexisting"_json_pointer, "oops");
bool v_boolean = j.value("/nonexisting"_json_pointer, false);
// output values
std::cout << std::boolalpha << v_integer << " " << v_floating
<< " " << v_string << " " << v_boolean << "\n";
}
```
Output:
```json
1 42.23 oops false
```
??? example “Example: (1) type_error.302 and type_error.306 exceptions”
The example below shows how `value()` throws `type_error.302` when the default value's type does not match the type
of the stored value, and `type_error.306` when `value()` is called on a JSON value that is not an object.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON object with a string value
json j = {{"name", "the good"}};
// exception type_error.302
try
{
int v = j.value("name", 0);
std::cout << v << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception type_error.306
try
{
json str = "I am a string";
auto v = str.value("name", 0);
std::cout << v << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```json
[json.exception.type_error.302] type must be number, but is string
[json.exception.type_error.306] cannot use value() with string
```
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. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime.ValueType the first template parameter in version 3.11.2. Fixed in version 3.13.0 to consistently accept std::string_view-convertible keys, as already supported by operator[], at, find, and other lookup functions.ptr through an array unexpectedly threw out_of_range instead of returning the resolved element (or default_value, as documented). Throws parse_error.109 instead of returning default_value for a one-character array index that is not a digit (e.g., /x) in version 3.13.0, as it already did for longer ones.