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.

Example

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 modify the original value.

Example

    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., and index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.

Example

    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

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