json/features/element_access/checked_access.md

Checked access: at

Overview

The at member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a basic_json::out_of_range exception otherwise.

??? example "Read access"

Consider the following JSON value:

```json
{
    "name": "Mary Smith",
    "age": 42,
    "hobbies": ["hiking", "reading"]
}
```

Assume the value is parsed to a `json` variable `j`.

| expression                    | value                                                                        |
|-------------------------------|------------------------------------------------------------------------------|
| `#!cpp j`                     | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
| `#!cpp j.at("name")`          | `#!json "Mary Smith"`                                                        |
| `#!cpp j.at("age")`           | `#!json 42`                                                                  |
| `#!cpp j.at("hobbies")`       | `#!json ["hiking", "reading"]`                                               |
| `#!cpp j.at("hobbies").at(0)` | `#!json "hiking"`                                                            |
| `#!cpp j.at("hobbies").at(1)` | `#!json "reading"`                                                           |

The return value is a reference, so it can be used to modify the original value.

??? example "Write access"

```cpp
j.at("name") = "John Smith";
```

This code produces the following JSON value:

```json
{
    "name": "John Smith",
    "age": 42,
    "hobbies": ["hiking", "reading"]
}
```

When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.

??? example "Accessing via invalid index or missing key"

```cpp
j.at("hobbies").at(3) = "cooking";
```

This code produces the following exception:

```
[json.exception.out_of_range.401] array index 3 is out of range
```

When [extended diagnostic messages](../../home/exceptions.md#extended-diagnostic-messages) are enabled by
defining [`JSON_DIAGNOSTICS`](../../api/macros/json_diagnostics.md), the exception further gives information where
the key or index is missing or out of range.

```
[json.exception.out_of_range.401] (/hobbies) array index 3 is out of range
```

Notes

!!! failure "Exceptions"

- [`at`](../../api/basic_json/at.md) can only be used with objects (with a string argument) or with arrays (with a
  numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error304)
  is thrown.
- [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) exceptions are thrown if the
  provided key is not found in an object or the provided index is invalid.

Summary

scenario	non-const value	const value
access to existing object key	reference to existing value is returned	const reference to existing value is returned
access to valid array index	reference to existing value is returned	const reference to existing value is returned
access to non-existing object key	basic_json::out_of_range exception is thrown	basic_json::out_of_range exception is thrown
access to invalid array index	basic_json::out_of_range exception is thrown	basic_json::out_of_range exception is thrown