amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-10-02 20:50:32 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
3f672f036da9f8ca0b3a06044f3127e000b023f2
json/docs/mkdocs/docs/api/basic_json/at.md
T
Niels Lohmann 63c10a51fc Review and extend the documentation, and check it in CI (#5638) 
* Review and extend the documentation, and check it in CI

A review of all documentation pages found factual errors, dead links,
missing cross-references, and gaps in examples. This fixes them and adds
checks so the same problems are caught automatically.

Fixes:
- wrong signatures and version histories (operator!= C++20 member,
  binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...)
- stale descriptions (number parsing since #5283, UBJSON table, SAX
  example that no longer compiled, tsl::ordered_map advice)
- dead internal and external links; repology.org badges (the domain is
  suspended) replaced by badges that query the registries directly
- deprecation notes link the migration guide; the guide itself fixed

Additions:
- "See also" sections, cross-references, 25 runnable examples, 12
  Mermaid diagrams, new API pages for json_pointer::operator<=> and
  byte_container_with_subtype::operator==/!=
- landing page, guides for untrusted input and performance
- "unreleased" badge after versions newer than the latest release

Checks:
- strict documentation build (broken links/anchors fail it); CI and
  the publish workflow fetch the full history the build needs
- weekly external link check, Mermaid syntax check in CI
- check_structure.py: example titles, heading levels, alt texts,
  header links, docset index coverage; its unused-example check works
  again
- all examples produce the same output on every platform

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Keep the customer links that could not be fixed

A dead link on the customers page is still the evidence of where the
use of the library was documented. Keep the original URLs of the entries
without a working replacement (Marne, Cisco Webex Desk Camera, Philips
Hue, CyberArk) and exclude exactly these URLs from the link check.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Correct the duplicate-key recipe's claim about SAX positions

The SAX interface's key() receives no position either; only parse_error()
does. Also note that the recipe does not report the path to the repeated
key (see discussion #5085).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Say the library is available as a single header and mention json_fwd.hpp

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Correct documentation errors found while hunting for bugs

- patch/patch_inplace: list the JSON pointer errors parse_error.106-109
  and out_of_range.402/404, and quote the actual parse_error.105 message.
- unflatten: list parse_error.106/107/108 and out_of_range.404.
- to_bson: list out_of_range.415 (binary subtype above 255) and note
  that 412 and 415 are new in 3.13.0.
- to_string: state that string_t must be convertible to std::string, also
  in the StringType requirements table.
- JSON Lines: a `while (input >> j)` loop also throws after the last value
  for concatenated JSON values; show a loop that works for both.
- BON8: a string gets 0xFF only if nothing follows it in the message; a
  string at the end of an array or object is ended by 0xFE.
- custom_string_type.hpp: add operator+=(char), which the "Always
  required" list asks for (json_pointer::to_string, flatten, unflatten,
  and diff did not compile), and an ADL int_to_string for diff and items.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Cache the release headers with functools.lru_cache

Codacy (Pylint) flagged the mutable default argument that header() used
as its cache. functools.lru_cache keeps the same memoization without it.
The script's output is unchanged.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-02 11:32:15 +02:00

8.3 KiB
Raw Blame History

nlohmann::basic_json::at

// (1)
reference at(size_type idx);
const_reference at(size_type idx) const;

// (2)
reference at(const typename object_t::key_type& key);
const_reference at(const typename object_t::key_type& key) const;

// (3)
template<typename KeyType>
reference at(KeyType&& key);
template<typename KeyType>
const_reference at(KeyType&& key) const;

// (4)
reference at(const json_pointer& ptr);
const_reference at(const json_pointer& ptr) const;
  1. Returns a reference to the array element at specified location idx, with bounds checking.
  2. Returns a reference to the object element with specified key key, with bounds checking.
  3. See 2. This overload is only available if KeyType is comparable with #!cpp typename object_t::key_type and #!cpp typename object_comparator_t::is_transparent denotes a type.
  4. Returns a reference to the element at specified JSON pointer ptr, with bounds checking.

Template parameters

KeyType
A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17).

Parameters

idx (in)
index of the element to access
key (in)
object key of the elements to access
ptr (in)
JSON pointer to the desired element

Return value

  1. reference to the element at index idx
  2. reference to the element at key key
  3. reference to the element at key key
  4. reference to the element pointed to by ptr

Exception safety

Strong exception safety: if an exception occurs, the original value stays intact.

Exceptions

  1. The function can throw the following exceptions:
    • Throws type_error.304 if the JSON value is not an array; in this case, calling at with an index makes no sense. See the example below.
    • Throws out_of_range.401 if the index idx is out of range of the array; that is, idx >= size(). See the example below.
  2. The function can throw the following exceptions:
    • Throws type_error.304 if the JSON value is not an object; in this case, calling at with a key makes no sense. See the example below.
    • Throws out_of_range.403 if the key key is not stored in the object; that is, find(key) == end(). See the example below.
  3. See 2.
  4. The function can throw the following exceptions:
    • Throws parse_error.106 if an array index in the passed JSON pointer ptr begins with '0'. See the example below.
    • Throws parse_error.109 if an array index in the passed JSON pointer ptr is not a number. See the example below.
    • Throws out_of_range.401 if an array index in the passed JSON pointer ptr is out of range. See the example below.
    • Throws out_of_range.402 if the array index '-' is used in the passed JSON pointer ptr. As at provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See the example below.
    • Throws out_of_range.403 if the JSON pointer describes a key of an object which cannot be found. See the example below.
    • Throws out_of_range.404 if the JSON pointer ptr can not be resolved. See the example below.
    • Throws out_of_range.410 if an array index in the passed JSON pointer ptr exceeds the range of size_type (e.g., on 32-bit platforms).

Complexity

  1. Constant.
  2. Logarithmic in the size of the container.
  3. Logarithmic in the size of the container.
  4. Logarithmic in the size of the container.

Notes

!!! warning "Deprecation"

Overload (4) also accepts a [`json_pointer`](../json_pointer/index.md) whose template argument is a `basic_json`
specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since
version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`,
`nlohmann::json_pointer<std::string>`) instead.

You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.

Examples

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

The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.

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

Output:

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

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

The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
    
```cpp
--8<-- "examples/at__size_type_const.cpp"
```

Output:

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

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

The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
    
```cpp
--8<-- "examples/at__object_t_key_type.cpp"
```

Output:

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

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

The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.

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

Output:

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

??? example "Example: (3) access specified object element using string_view with bounds checking"

The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.

```cpp
--8<-- "examples/at__keytype.c++17.cpp"
```

Output:

```json
--8<-- "examples/at__keytype.c++17.output"
```

??? example "Example: (3) access specified object element using string_view with bounds checking"

The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.

```cpp
--8<-- "examples/at__keytype_const.c++17.cpp"
```

Output:

```json
--8<-- "examples/at__keytype_const.c++17.output"
```

??? example "Example: (4) access specified element via JSON Pointer"

The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
    
```cpp
--8<-- "examples/at__json_pointer.cpp"
```

Output:

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

??? example "Example: (4) access specified element via JSON Pointer"

The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
    
```cpp
--8<-- "examples/at__json_pointer_const.cpp"
```

Output:

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

See also

Version history

  1. Added in version 1.0.0.
  2. Added in version 1.0.0.
  3. Added in version 3.11.0.
  4. Added in version 2.0.0.
Reference in New Issue View Git Blame Copy Permalink