at() [3/6]

template<template< typename U, typename V, typename... Args > class ObjectType = std::map, template< typename U, typename... Args > class ArrayType = std::vector, class StringType = std::string, class BooleanType = bool, class NumberIntegerType = std::int64_t, class NumberUnsignedType = std::uint64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator, template< typename T, typename SFINAE=void > class JSONSerializer = adl_serializer, class BinaryType = std::vector<std::uint8_t>>

reference nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::at ( const typename object_t::key_type &  key )

inline

access specified object element with bounds checking

Returns a reference to the element at with specified key key, with bounds checking.

Parameters

[in]

key

key of the element to access

Returns

reference to the element at key key

Exceptions

type_error.304	if the JSON value is not an object; in this case, calling at with a key makes no sense. See example below.
out_of_range.403	if the key key is is not stored in the object; that is, find(key) == end(). See example below.

@exceptionsafety Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

@complexity Logarithmic in the size of the container.

See also

see operator[](const typename object_t::key_type&) for unchecked access by reference

see value() for access by value with a default value

Since

version 1.0.0

@liveexample{The example below shows how object elements can be read and written using at(). It also demonstrates the different exceptions that can be thrown.,at__object_t_key_type}

Definition at line 21286 of file json.hpp.

    {
        // at only works for objects
        if (JSON_HEDLEY_LIKELY(is_object()))
        {
            JSON_TRY
            {
                return set_parent(m_value.object->at(key));
            }
            JSON_CATCH (std::out_of_range &)
            {
                // create better exception explanation
                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found", *this));
            }
        }
 
        else
        {
            JSON_THROW(type_error::create(304, "cannot use at() with " + std::string(type_name()), *this));
        }
    }