| # <small>nlohmann::basic_json::</small>value | |
| ```cpp | |
| // (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)`. | |
| 1. 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 | |
| ```cpp | |
| try { | |
| return at(key); | |
| } catch(out_of_range) { | |
| return default_value; | |
| } | |
| ``` | |
| 2. 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. | |
| 3. 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 | |
| ```cpp | |
| 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. | |
| ## Template parameters | |
| `KeyType` | |
| : A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with | |
| [`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md). | |
| 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. | |
| ## Parameters | |
| `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 | |
| ## Return value | |
| 1. copy of the element at key `key` or `default_value` if `key` is not found | |
| 2. copy of the element at key `key` or `default_value` if `key` is not found | |
| 3. copy of the element at JSON Pointer `ptr` or `default_value` if no value for `ptr` is found | |
| ## Exception safety | |
| Strong guarantee: if an exception is thrown, there are no | |
| changes to any JSON value. | |
| ## Exceptions | |
| 1. The function can throw the following exceptions: | |
| - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match | |
| the type of the value at `key` | |
| - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object; | |
| in that case, using `value()` with a key makes no sense. | |
| 2. See 1. | |
| 3. The function can throw the following exceptions: | |
| - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match | |
| the type of the value at `ptr` | |
| - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an array | |
| or object; in that case, using `value()` with a JSON pointer makes no sense. | |
| - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed | |
| JSON pointer `ptr` begins with '0'. | |
| - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed | |
| JSON pointer `ptr` is not a number. | |
| ## Complexity | |
| 1. Logarithmic in the size of the container. | |
| 2. Logarithmic in the size of the container. | |
| 3. Logarithmic in the size of the container. | |
| ## Notes | |
| !!! 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. | |
| ## Examples | |
| ??? 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 | |
| ``` | |
| ## See also | |
| - see [`at`](at.md) for access by reference with range checking | |
| - see [`operator[]`](operator%5B%5D.md) for unchecked access by reference | |
| - [basic_json_view::value](../basic_json_view/value.md) - the same access on a zero-copy view | |
| ## Version history | |
| 1. Added in version 1.0.0. Changed parameter `default_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. | |
| 2. Added in version 3.11.0. Made `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[]`](operator[].md), [`at`](at.md), [`find`](find.md), and other lookup functions. | |
| 3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving | |
| `ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or | |
| `default_value`, as documented). Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) | |
| 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. |