| # <small>nlohmann::basic_json_view::</small>value | |
| ```cpp | |
| // (1) | |
| template<typename T> | |
| T value(string_view_t key, const T& default_value) const; | |
| string_t value(string_view_t key, const char* default_value) const; | |
| // (2) | |
| template<typename T> | |
| T value(const json_pointer& ptr, const T& default_value) const; | |
| string_t value(const json_pointer& ptr, const char* default_value) const; | |
| ``` | |
| 1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see | |
| [Notes on duplicate keys](operator[].md#notes)) -- converted to `T`, or `default_value` if there is no such member. | |
| 2. Returns the value a JSON pointer `ptr` refers to, starting at this value, converted to `T`, or `default_value` if | |
| `ptr` cannot be resolved. | |
| Both overloads have a dedicated `#!cpp const char*` overload, so `#!cpp v.value(key, "default")` (and the JSON pointer | |
| equivalent) deduce `string_t`, not `const char*`, for their return type and for the comparison used to pick between | |
| `key` and `default_value`. | |
| ## Template parameters | |
| `T` | |
| : the type to convert the found value to; also the type of `default_value` | |
| ## Parameters | |
| `key` (in) | |
| : object key of the element to access | |
| `ptr` (in) | |
| : JSON pointer to the element to access | |
| `default_value` (in) | |
| : the value to return if `key`/`ptr` resolves to no value | |
| ## Return value | |
| 1. the first member with key `key`, converted to `T`, or `default_value` | |
| 2. the value `ptr` resolves to, converted to `T`, or `default_value` | |
| ## Exception safety | |
| Strong guarantee: there are no changes to the view or the document it refers to. | |
| ## Exceptions | |
| 1. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the value is not an object -- | |
| the same exception, with the same message, that [`BasicJsonType::value`](../basic_json/value.md) throws for the | |
| same call. If a member with key `key` is found, throws whatever converting it to `T` throws (typically | |
| [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302), with the same message | |
| [`BasicJsonType::value`](../basic_json/value.md) throws for the same mismatch); a missing member never throws. | |
| 2. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if this value -- not the value `ptr` | |
| resolves to -- is neither an object nor an array. Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) | |
| or [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if `ptr` contains a malformed array | |
| index. If `ptr` resolves to a value, throws whatever converting it to `T` throws. Every other way `ptr` can fail to | |
| resolve -- a missing key, an out-of-range or "`-`" array index, an unresolvable token on a primitive -- yields | |
| `default_value` instead of throwing, exactly as [`BasicJsonType::value`](../basic_json/value.md) catches | |
| `out_of_range` and returns `default_value`. | |
| None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no | |
| `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with | |
| `JSON_DIAGNOSTICS` enabled. | |
| ## Complexity | |
| 1. Linear in the number of members: as for [`operator[]`](operator[].md#complexity), members are compared one after | |
| another, in document order, stopping at the first match. Plus the complexity of converting | |
| the found member to `T` (see [`get`](get.md)). | |
| Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes | |
| constant time on average. | |
| 2. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at | |
| that level or the index into the array -- as for the [`operator[]`](operator[].md#complexity) and | |
| [`at`](at.md#complexity) overloads that take a JSON pointer. Plus the complexity of converting the resolved value | |
| to `T`. | |
| ## Notes | |
| !!! warning "Duplicate keys: the first member wins" | |
| If the source text repeats a key, this resolves to the *first* member with it, not to the last one that | |
| [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of | |
| `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get | |
| the last value. | |
| !!! info "Differences to `at` and `operator[]`" | |
| Unlike [`at`](at.md), this function does not throw if `key`/`ptr` resolves to no value. Unlike | |
| [`operator[]`](operator[].md), it never returns a [discarded](is_discarded.md) view -- it always returns a `T` -- | |
| and it is available on any view, since it never needs to insert a missing element the way the non-const | |
| `BasicJsonType::operator[]` would. | |
| !!! info "Which values can be asked" | |
| As for [`BasicJsonType::value`](../basic_json/value.md), the key overload (1) requires an object, and the JSON | |
| pointer overload (2) an object or an array. | |
| ## Examples | |
| ??? example "Example: (1) access specified object element with default value" | |
| The example below reads a couple of optional configuration fields with a default, so that a missing key never | |
| needs a `#!cpp try`/`#!cpp catch` of its own. | |
| ```cpp | |
| #include <iostream> | |
| #include <nlohmann/json_view.hpp> | |
| #include <string> | |
| using json_document = nlohmann::json_document; | |
| using json_view = nlohmann::json_view; | |
| int main() | |
| { | |
| json_document doc = json_document::parse(R"({"server": {"host": "localhost"}})"); | |
| const json_view server = doc.root()["server"]; | |
| // "port" is missing -- value() returns the default instead of | |
| // throwing, so optional configuration fields never need their own | |
| // try/catch | |
| std::cout << server.value("host", std::string("0.0.0.0")) << '\n'; | |
| std::cout << server.value("port", 8080) << '\n'; | |
| // a present but wrong-typed default still throws -- value() only | |
| // replaces "not found", not "wrong type", exactly as basic_json::value | |
| try | |
| { | |
| static_cast<void>(server.value("host", 0)); | |
| } | |
| catch (const nlohmann::json::type_error& e) | |
| { | |
| std::cout << e.what() << '\n'; | |
| } | |
| } | |
| ``` | |
| Output: | |
| ```json | |
| localhost | |
| 8080 | |
| [json.exception.type_error.302] type must be number, but is string | |
| ``` | |
| ??? example "Example: (2) access specified element via JSON pointer with default value" | |
| The example below reads an optional, nested configuration value with a default, given as a JSON pointer. | |
| ```cpp | |
| #include <iostream> | |
| #include <nlohmann/json_view.hpp> | |
| using json_document = nlohmann::json_document; | |
| using json_view = nlohmann::json_view; | |
| using json_pointer = nlohmann::json::json_pointer; | |
| int main() | |
| { | |
| json_document doc = json_document::parse(R"({"server": {"host": "localhost", "limits": {"connections": 100}}})"); | |
| const json_view config = doc.root(); | |
| // a nested, optional setting read with a default -- no exception, even | |
| // though "timeout" is missing several levels down | |
| std::cout << config.value(json_pointer("/server/limits/connections"), 10) << '\n'; | |
| std::cout << config.value(json_pointer("/server/limits/timeout"), 30) << '\n'; | |
| // an out-of-range array index also falls back to the default | |
| json_document list_doc = json_document::parse(R"({"servers": ["a", "b"]})"); | |
| std::cout << list_doc.root().value(json_pointer("/servers/5"), std::string("none")) << '\n'; | |
| } | |
| ``` | |
| Output: | |
| ```json | |
| 100 | |
| 30 | |
| none | |
| ``` | |
| ## See also | |
| - [at](at.md) - access specified element with bounds checking (throws instead of returning a default value) | |
| - [operator[]](operator[].md) - access specified element (returns a discarded view instead of a default value) | |
| - [`BasicJsonType::value`](../basic_json/value.md) - the corresponding function of `basic_json` | |
| ## Version history | |
| - Added in version 3.13.0. |