• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# <small>nlohmann::basic_json::</small>value
2
3```cpp
4// (1)
5template<class ValueType>
6ValueType value(const typename object_t::key_type& key,
7                ValueType&& default_value) const;
8
9// (2)
10template<class ValueType, class KeyType>
11ValueType value(KeyType&& key,
12                ValueType&& default_value) const;
13
14// (3)
15template<class ValueType>
16ValueType value(const json_pointer& ptr,
17                const ValueType& default_value) const;
18```
19
201. Returns either a copy of an object's element at the specified key `key` or a given default value if no element with
21   key `key` exists.
22
23    The function is basically equivalent to executing
24    ```cpp
25    try {
26       return at(key);
27    } catch(out_of_range) {
28       return default_value;
29    }
30    ```
31
322. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
33   `#!cpp typename object_comparator_t::is_transparent` denotes a type.
34
353. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value
36   at `ptr` exists.
37
38    The function is basically equivalent to executing
39    ```cpp
40    try {
41       return at(ptr);
42    } catch(out_of_range) {
43       return default_value;
44    }
45    ```
46
47!!! note "Differences to `at` and `operator[]`"
48
49    - Unlike [`at`](at.md), this function does not throw if the given `key`/`ptr` was not found.
50    - Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
51     `key`/`ptr` key. This function is furthermore also applicable to const objects.
52
53## Template parameters
54
55`KeyType`
56:   A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
57    [`string_t`](string_t.md) using  [`object_comparator_t`](object_comparator_t.md).
58    This can also be a string view (C++17).
59`ValueType`
60:   type compatible to JSON values, for instance `#!cpp int` for JSON integer numbers, `#!cpp bool` for JSON booleans,
61    or `#!cpp std::vector` types for JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
62    value `default_value` must be compatible.
63
64## Parameters
65
66`key` (in)
67:   key of the element to access
68
69`default_value` (in)
70:   the value to return if `key`/`ptr` found no value
71
72`ptr` (in)
73:   a JSON pointer to the element to access
74
75## Return value
76
771. copy of the element at key `key` or `default_value` if `key` is not found
782. copy of the element at key `key` or `default_value` if `key` is not found
793. copy of the element at JSON Pointer `ptr` or `default_value` if no value for `ptr` is found
80
81## Exception safety
82
83Strong guarantee: if an exception is thrown, there are no
84changes to any JSON value.
85
86## Exceptions
87
881. The function can throw the following exceptions:
89    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
90      the type of the value at `key`
91    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
92      in that case, using `value()` with a key makes no sense.
932. See 1.
943. The function can throw the following exceptions:
95    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
96      the type of the value at `ptr`
97    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
98      in that case, using `value()` with a key makes no sense.
99
100## Complexity
101
1021. Logarithmic in the size of the container.
1032. Logarithmic in the size of the container.
1043. Logarithmic in the size of the container.
105
106## Examples
107
108??? example "Example: (1) access specified object element with default value"
109
110    The example below shows how object elements can be queried with a default value.
111
112    ```cpp
113    --8<-- "examples/value__object_t_key_type.cpp"
114    ```
115
116    Output:
117
118    ```json
119    --8<-- "examples/value__object_t_key_type.output"
120    ```
121
122??? example "Example: (2) access specified object element using string_view with default value"
123
124    The example below shows how object elements can be queried with a default value.
125
126    ```cpp
127    --8<-- "examples/value__keytype.c++17.cpp"
128    ```
129
130    Output:
131
132    ```json
133    --8<-- "examples/value__keytype.c++17.output"
134    ```
135
136??? example "Example: (3) access specified object element via JSON Pointer with default value"
137
138    The example below shows how object elements can be queried with a default value.
139
140    ```cpp
141    --8<-- "examples/value__json_ptr.cpp"
142    ```
143
144    Output:
145
146    ```json
147    --8<-- "examples/value__json_ptr.output"
148    ```
149
150## See also
151
152- see [`at`](at.md) for access by reference with range checking
153- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
154
155## Version history
156
1571. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version 3.11.0.
1582. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2.
1593. Added in version 2.0.2.
160