• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# <small>nlohmann::basic_json::</small>at
2
3```cpp
4// (1)
5reference at(size_type idx);
6const_reference at(size_type idx) const;
7
8// (2)
9reference at(const typename object_t::key_type& key);
10const_reference at(const typename object_t::key_type& key) const;
11
12// (3)
13template<typename KeyType>
14reference at(KeyType&& key);
15template<typename KeyType>
16const_reference at(KeyType&& key) const;
17
18// (4)
19reference at(const json_pointer& ptr);
20const_reference at(const json_pointer& ptr) const;
21```
22
231. Returns a reference to the array element at specified location `idx`, with bounds checking.
242. Returns a reference to the object element with specified key `key`, with bounds checking.
253. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
26   `#!cpp typename object_comparator_t::is_transparent` denotes a type.
274. Returns a reference to the element at specified JSON pointer `ptr`, with bounds checking.
28
29## Template parameters
30
31`KeyType`
32:   A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
33    [`string_t`](string_t.md) using  [`object_comparator_t`](object_comparator_t.md).
34    This can also be a string view (C++17).
35
36## Parameters
37
38`idx` (in)
39:   index of the element to access
40
41`key` (in)
42:   object key of the elements to access
43
44`ptr` (in)
45:   JSON pointer to the desired element
46
47## Return value
48
491. reference to the element at index `idx`
502. reference to the element at key `key`
513. reference to the element at key `key`
524. reference to the element pointed to by `ptr`
53
54## Exception safety
55
56Strong exception safety: if an exception occurs, the original value stays intact.
57
58## Exceptions
59
601. The function can throw the following exceptions:
61    - Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an array;
62      in this case, calling `at` with an index makes no sense. See example below.
63    - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if the index `idx` is out of
64      range of the array; that is, `idx >= size()`. See example below.
652. The function can throw the following exceptions:
66    - Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an object;
67      in this case, calling `at` with a key makes no sense. See example below.
68    - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is not
69      stored in the object; that is, `find(key) == end()`. See example below.
703. See 2.
714. The function can throw the following exceptions:
72    - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
73      JSON pointer `ptr` begins with '0'. See example below.
74    - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
75      JSON pointer `ptr` is not a number. See example below.
76    - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index in the passed
77      JSON pointer `ptr` is out of range. See example below.
78    - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
79      in the passed JSON pointer `ptr`. As `at` provides checked access (and no elements are implicitly inserted), the
80      index '-' is always invalid. See example below.
81    - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the JSON pointer describes a
82      key of an object which cannot be found. See example below.
83    - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
84      not be resolved. See example below.
85
86## Complexity
87
881. Constant.
892. Logarithmic in the size of the container.
903. Logarithmic in the size of the container.
914. Logarithmic in the size of the container.
92
93## Examples
94
95??? example "Example: (1) access specified array element with bounds checking"
96
97    The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
98    exceptions that can be thrown.
99
100    ```cpp
101    --8<-- "examples/at__size_type.cpp"
102    ```
103
104    Output:
105
106    ```json
107    --8<-- "examples/at__size_type.output"
108    ```
109
110??? example "Example: (1) access specified array element with bounds checking"
111
112    The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
113    that can be thrown.
114
115    ```cpp
116    --8<-- "examples/at__size_type_const.cpp"
117    ```
118
119    Output:
120
121    ```json
122    --8<-- "examples/at__size_type_const.output"
123    ```
124
125??? example "Example: (2) access specified object element with bounds checking"
126
127    The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
128    exceptions that can be thrown.
129
130    ```cpp
131    --8<-- "examples/at__object_t_key_type.cpp"
132    ```
133
134    Output:
135
136    ```json
137    --8<-- "examples/at__object_t_key_type.output"
138    ```
139
140??? example "Example: (2) access specified object element with bounds checking"
141
142    The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
143    that can be thrown.
144
145    ```cpp
146    --8<-- "examples/at__object_t_key_type_const.cpp"
147    ```
148
149    Output:
150
151    ```json
152    --8<-- "examples/at__object_t_key_type_const.output"
153    ```
154
155??? example "Example: (3) access specified object element using string_view with bounds checking"
156
157    The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
158    exceptions that can be thrown.
159
160    ```cpp
161    --8<-- "examples/at__keytype.c++17.cpp"
162    ```
163
164    Output:
165
166    ```json
167    --8<-- "examples/at__keytype.c++17.output"
168    ```
169
170??? example "Example: (3) access specified object element using string_view with bounds checking"
171
172    The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
173    that can be thrown.
174
175    ```cpp
176    --8<-- "examples/at__keytype_const.c++17.cpp"
177    ```
178
179    Output:
180
181    ```json
182    --8<-- "examples/at__keytype_const.c++17.output"
183    ```
184
185??? example "Example: (4) access specified element via JSON Pointer"
186
187    The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
188    exceptions that can be thrown.
189
190    ```cpp
191    --8<-- "examples/at__json_pointer.cpp"
192    ```
193
194    Output:
195
196    ```json
197    --8<-- "examples/at__json_pointer.output"
198    ```
199
200??? example "Example: (4) access specified element via JSON Pointer"
201
202    The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
203    that can be thrown.
204
205    ```cpp
206    --8<-- "examples/at__json_pointer_const.cpp"
207    ```
208
209    Output:
210
211    ```json
212    --8<-- "examples/at__json_pointer_const.output"
213    ```
214
215## See also
216
217- documentation on [checked access](../../features/element_access/checked_access.md)
218- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
219- see [`value`](value.md) for access with default value
220
221## Version history
222
2231. Added in version 1.0.0.
2242. Added in version 1.0.0.
2253. Added in version 3.11.0.
2264. Added in version 2.0.0.
227