• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Checked access: at
2
3## Overview
4
5The `#!cpp 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](../../home/exceptions.md#out-of-range) otherwise.
6
7??? example
8
9    Consider the following JSON value:
10
11    ```json
12    {
13        "name": "Mary Smith",
14        "age": 42,
15        "hobbies": ["hiking", "reading"]
16    }
17    ```
18
19    Assume the value is parsed to a `json` variable `j`.
20
21    | expression | value |
22    | ---------- | ----- |
23    | `#!cpp j`  | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
24    | `#!cpp j.at("name")`  | `#!json "Mary Smith"` |
25    | `#!cpp j.at("age")`  | `#!json 42` |
26    | `#!cpp j.at("hobbies")`  | `#!json ["hiking", "reading"]` |
27    | `#!cpp j.at("hobbies").at(0)`  | `#!json "hiking"` |
28    | `#!cpp j.at("hobbies").at(1)`  | `#!json "reading"` |
29
30The return value is a reference, so it can be modify the original value.
31
32??? example
33
34    ```cpp
35    j.at("name") = "John Smith";
36    ```
37
38    This code produces the following JSON value:
39
40    ```json
41    {
42        "name": "John Smith",
43        "age": 42,
44        "hobbies": ["hiking", "reading"]
45    }
46    ```
47
48When accessing an invalid index (i.e., and index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.
49
50??? example
51
52    ```cpp
53    j.at("hobbies").at(3) = "cooking";
54    ```
55
56    This code produces the following exception:
57
58    ```
59    [json.exception.out_of_range.401] array index 3 is out of range
60    ```
61
62## Notes
63
64
65!!! failure "Exceptions"
66
67    - `at` 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.
68    - [`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.
69
70## Summary
71
72| scenario | non-const value | const value |
73| -------- | ------------- | ----------- |
74| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
75| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
76| access to non-existing object key | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
77| access to invalid array index | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
78