102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# Checked access: at
|
|
|
|
## Overview
|
|
|
|
The [`at`](../../api/basic_json/at.md) 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](../../home/exceptions.md#out-of-range)
|
|
otherwise.
|
|
|
|
??? example "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 "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 "Example: access 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 |
|
|
|
|
<p class="nj-table-caption" markdown>Result of [`at`](../../api/basic_json/at.md) in each scenario, for a non-const and a const value.</p>
|
|
|
|
## See also
|
|
|
|
- [Element Access](index.md) - overview of all ways to access elements
|
|
- [Unchecked access: operator[]](unchecked_access.md) - access without range checking
|
|
- [Access with default value: value](default_value.md) - fall back to a default instead of throwing
|
|
- [`at`](../../api/basic_json/at.md) - checked access by reference
|
|
- [JSON Pointer](../json_pointer.md) - access nested values with `at` and a pointer
|