Skip to content

# 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.

Read access

Consider the following JSON value:

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

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

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

The return value is a reference, so it can be modified by the original value.

Write access

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

This code produces the following JSON value:

    {
        "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.

Accessing via invalid index or missing key

    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 you extended diagnostic messages are enabled by defining `JSON_DIAGNOSTICS`, 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

Exceptions

- `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` is thrown.
- `basic_json::out_of_range` exception 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

Last update: May 17, 2022
Back to top