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