• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# basic_json::value
2
3```cpp
4// (1)
5template<class ValueType>
6ValueType value(const typename object_t::key_type& key,
7                const ValueType& default_value) const;
8
9// (2)
10template<class ValueType>
11ValueType value(const json_pointer& ptr,
12                const ValueType& default_value) const;
13```
14
151. Returns either a copy of an object's element at the specified key `key` or a given default value if no element with
16   key `key` exists.
17
18    The function is basically equivalent to executing
19    ```cpp
20    try {
21       return at(key);
22    } catch(out_of_range) {
23       return default_value;
24    }
25    ```
26
272. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value
28   at `ptr` exists.
29
30    The function is basically equivalent to executing
31    ```cpp
32    try {
33       return at(ptr);
34    } catch(out_of_range) {
35       return default_value;
36    }
37    ```
38
39Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
40`key`/`ptr` key. This function is furthermore also applicable to const objects.
41
42## Template parameters
43
44`ValueType`
45:   type compatible to JSON values, for instance `#!cpp int` for JSON integer numbers, `#!cpp bool` for JSON booleans,
46    or `#!cpp std::vector` types for JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
47    value `default_value` must be compatible.
48
49## Parameters
50
51`key` (in)
52:   key of the element to access
53
54`default_value` (in)
55:   the value to return if key/ptr found no value
56
57`ptr` (in)
58:   a JSON pointer to the element to access
59
60## Return value
61
621. copy of the element at key `key` or `default_value` if `key` is not found
631. copy of the element at JSON Pointer `ptr` or `default_value` if no value for `ptr` is found
64
65## Exception safety
66
67Strong guarantee: if an exception is thrown, there are no
68changes to any JSON value.
69
70## Exceptions
71
721. The function can throw thw following exceptions:
73    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
74      the type of the value at `key`
75    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
76      in that case, using `value()` with a key makes no sense.
772. The function can throw thw following exceptions:
78    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
79      the type of the value at `ptr`
80    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
81      in that case, using `value()` with a key makes no sense.
82
83## Complexity
84
851. Logarithmic in the size of the container.
862. Logarithmic in the size of the container.
87
88## Example
89
90??? example
91
92    The example below shows how object elements can be queried with a default value.
93
94    ```cpp
95    --8<-- "examples/basic_json__value.cpp"
96    ```
97
98    Output:
99
100    ```json
101    --8<-- "examples/basic_json__value.output"
102    ```
103
104??? example
105
106    The example below shows how object elements can be queried with a default value.
107
108    ```cpp
109    --8<-- "examples/basic_json__value_ptr.cpp"
110    ```
111
112    Output:
113
114    ```json
115    --8<-- "examples/basic_json__value_ptr.output"
116    ```
117
118## Version history
119
1201. Added in version 1.0.0.
1212. Added in version 2.0.2.
122