]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
1 | # Checked access: at |
2 | ||
3 | ## Overview | |
4 | ||
5 | The `#!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 | ||
30 | The return value is a reference, so it can be modified by 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 | ||
48 | 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. | |
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 | |