json/docs/mkdocs/docs/api/basic_json_view/at.md

nlohmann::basic_json_view::at

// (1)
basic_json_view at(string_view_t key) const;
basic_json_view at(const char* key) const;
basic_json_view at(const string_t& key) const;

// (2)
basic_json_view at(size_type idx) const;
template<typename IntegerType>
basic_json_view at(IntegerType idx) const;

// (3)
basic_json_view at(const json_pointer& ptr) const;

1. Returns the value of the object member with key key — the first one, should the key occur more than once (see Notes on duplicate keys).
2. Returns the array element at index idx. The template accepts every integer type except #!cpp bool and #!cpp std::size_t and forwards to the size_type overload, as for operator[]; a negative idx is out of range.
3. Returns the value a JSON pointer ptr refers to, starting at this value.

Parameters

key (in)

object key of the element to access

idx (in)

index of the element to access

ptr (in)

JSON pointer to the element to access

Return value

1. the value of the first member with key key
2. the element at index idx
3. the value ptr resolves to, starting at this value

Exception safety

Strong guarantee: there are no changes to the view or the document it refers to.

Exceptions

1. The function can throw the following exceptions, both with the same message as the corresponding call to BasicJsonType::at:
   • Throws type_error.304 if the value is not an object.
   • Throws out_of_range.403 if no member has key key.
2. The function can throw the following exceptions, both with the same message as the corresponding call to BasicJsonType::at:
   • Throws type_error.304 if the value is not an array.
   • Throws out_of_range.401 if #!cpp idx >= size().
3. The function can throw the following exceptions, all with the same message as the corresponding call to BasicJsonType::at:
   • Throws parse_error.106 if an array index in ptr begins with #!cpp '0'.
   • Throws parse_error.109 if an array index in ptr is not a number.
   • Throws out_of_range.401 if an array index in ptr is out of range.
   • Throws out_of_range.402 if a reference token is #!cpp "-" at an array — at never inserts an element, so #!cpp "-" is always invalid.
   • Throws out_of_range.403 if a reference token names an object member that does not exist.
   • Throws out_of_range.404 if ptr cannot be resolved because a reference token is used on a primitive value.

As for BasicJsonType, with JSON_DIAGNOSTICS these exceptions name the JSON Pointer path of the value within the document, and with JSON_DIAGNOSTIC_POSITIONS its bytes in the source text (when materialize() sets them).

Complexity

1. Linear in the number of members: as for ordered_json, members are compared one after another, in document order, stopping at the first match. Each comparison first checks the key's length — already known from the index, without reading the key bytes — before comparing its content. Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes constant time on average.
2. Linear in idx: elements are skipped one at a time from the first one, since they are not a fixed size in the index (unlike BasicJsonType's array, which is random-access). Constant if no element of the array is an array or object, since the elements are then adjacent in the index.
3. Linear in the number of reference tokens of ptr and, for each token, in the number of members of the object at that level (as 1.) or the index into the array (as 2.).

Notes

!!! warning "Duplicate keys: the first member wins"

If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
[`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
`operator[]` and [Duplicate keys](../../features/json_view/differences.md#duplicate-keys) for the reasons and for how to get
the last value.

Unlike operator[], which returns a discarded view for a missing key or an out-of-range index, at always throws — exactly as BasicJsonType::at does, and with the same messages, so existing error handling written against BasicJsonType::at keeps working unchanged when switched to a view. This also holds for overload 3: unlike operator[] with a JSON pointer, which returns a discarded view for a missing key or an out-of-range index, at throws for those too (out_of_range.403/out_of_range.401).

Examples

??? example "Example: (1)/(2) access specified element with bounds checking"

The example below reads required fields out of a service configuration with `at`, and shows that the exceptions
it throws — for a wrong type and for a missing key — carry the same messages
[`BasicJsonType::at`](../basic_json/at.md) would produce for the same JSON text.

```cpp
--8<-- "examples/basic_json_view__at.cpp"
```

Output:

```json
--8<-- "examples/basic_json_view__at.output"
```

??? example "Example: (3) access specified element via JSON pointer with bounds checking"

The example below shows that `at` with a JSON pointer throws exactly the exceptions, with exactly the messages,
that [`BasicJsonType::at`](../basic_json/at.md) throws for the same pointer and the same document.

```cpp
--8<-- "examples/basic_json_view__at_json_pointer.cpp"
```

Output:

```json
--8<-- "examples/basic_json_view__at_json_pointer.output"
```

See also

• operator[] - access specified element (returns a discarded view instead of throwing)
• front, back - access the first or last element
• BasicJsonType::at - the corresponding function of basic_json
• json_pointer - JSON pointer type used by overload 3

Version history

• Added in version 3.13.0.