Skip to content

nlohmann::basic_json::at 

// (1)
referenceat(size_typeidx);
const_referenceat(size_typeidx)const;
// (2)
referenceat(consttypenameobject_t::key_type&key);
const_referenceat(consttypenameobject_t::key_type&key)const;
// (3)
template<typenameKeyType>
referenceat(KeyType&&key);
template<typenameKeyType>
const_referenceat(KeyType&&key)const;
// (4)
referenceat(constjson_pointer&ptr);
const_referenceat(constjson_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 typenameobject_t::key_type and typenameobject_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.

Examples

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.

#include<iostream>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
intmain()
{
// create JSON array
jsonarray={"first","2nd","third","fourth"};
// output element at index 2 (third element)
std::cout<<array.at(2)<<'\n';
// change element at index 1 (second element) to "second"
array.at(1)="second";
// output changed array
std::cout<<array<<'\n';
// exception type_error.304
try
{
// use at() on a non-array type
jsonstr="I am a string";
str.at(0)="Another string";
}
catch(constjson::type_error&e)
{
std::cout<<e.what()<<'\n';
}
// exception out_of_range.401
try
{
// try to write beyond the array limit
array.at(5)="sixth";
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
}

Output:

"third"
["first","second","third","fourth"]
[json.exception.type_error.304]cannotuseat()withstring
[json.exception.out_of_range.401]arrayindex5isoutofrange
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.

#include<iostream>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
intmain()
{
// create JSON array
constjsonarray={"first","2nd","third","fourth"};
// output element at index 2 (third element)
std::cout<<array.at(2)<<'\n';
// exception type_error.304
try
{
// use at() on a non-array type
constjsonstr="I am a string";
std::cout<<str.at(0)<<'\n';
}
catch(constjson::type_error&e)
{
std::cout<<e.what()<<'\n';
}
// exception out_of_range.401
try
{
// try to read beyond the array limit
std::cout<<array.at(5)<<'\n';
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
}

Output:

"third"
[json.exception.type_error.304]cannotuseat()withstring
[json.exception.out_of_range.401]arrayindex5isoutofrange
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.

#include<iostream>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
intmain()
{
// create JSON object
jsonobject=
{
{"the good","il buono"},
{"the bad","il cattivo"},
{"the ugly","il brutto"}
};
// output element with key "the ugly"
std::cout<<object.at("the ugly")<<'\n';
// change element with key "the bad"
object.at("the bad")="il cattivo";
// output changed array
std::cout<<object<<'\n';
// exception type_error.304
try
{
// use at() on a non-object type
jsonstr="I am a string";
str.at("the good")="Another string";
}
catch(constjson::type_error&e)
{
std::cout<<e.what()<<'\n';
}
// exception out_of_range.401
try
{
// try to write at a nonexisting key
object.at("the fast")="il rapido";
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
}

Output:

"il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
[json.exception.type_error.304]cannotuseat()withstring
[json.exception.out_of_range.403]key'thefast'notfound
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.

#include<iostream>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
intmain()
{
// create JSON object
constjsonobject=
{
{"the good","il buono"},
{"the bad","il cattivo"},
{"the ugly","il brutto"}
};
// output element with key "the ugly"
std::cout<<object.at("the ugly")<<'\n';
// exception type_error.304
try
{
// use at() on a non-object type
constjsonstr="I am a string";
std::cout<<str.at("the good")<<'\n';
}
catch(constjson::type_error&e)
{
std::cout<<e.what()<<'\n';
}
// exception out_of_range.401
try
{
// try to read from a nonexisting key
std::cout<<object.at("the fast")<<'\n';
}
catch(constjson::out_of_range)
{
std::cout<<"out of range"<<'\n';
}
}

Output:

"il brutto"
[json.exception.type_error.304]cannotuseat()withstring
outofrange
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.

#include<iostream>
#include<string_view>
#include<nlohmann/json.hpp>
usingnamespacestd::string_view_literals;
usingjson=nlohmann::json;
intmain()
{
// create JSON object
jsonobject=
{
{"the good","il buono"},
{"the bad","il cattivo"},
{"the ugly","il brutto"}
};
// output element with key "the ugly" using string_view
std::cout<<object.at("the ugly"sv)<<'\n';
// change element with key "the bad" using string_view
object.at("the bad"sv)="il cattivo";
// output changed array
std::cout<<object<<'\n';
// exception type_error.304
try
{
// use at() with string_view on a non-object type
jsonstr="I am a string";
str.at("the good"sv)="Another string";
}
catch(constjson::type_error&e)
{
std::cout<<e.what()<<'\n';
}
// exception out_of_range.401
try
{
// try to write at a nonexisting key using string_view
object.at("the fast"sv)="il rapido";
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
}

Output:

"il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
[json.exception.type_error.304]cannotuseat()withstring
[json.exception.out_of_range.403]key'thefast'notfound
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.

#include<iostream>
#include<string_view>
#include<nlohmann/json.hpp>
usingnamespacestd::string_view_literals;
usingjson=nlohmann::json;
intmain()
{
// create JSON object
constjsonobject=
{
{"the good","il buono"},
{"the bad","il cattivo"},
{"the ugly","il brutto"}
};
// output element with key "the ugly" using string_view
std::cout<<object.at("the ugly"sv)<<'\n';
// exception type_error.304
try
{
// use at() with string_view on a non-object type
constjsonstr="I am a string";
std::cout<<str.at("the good"sv)<<'\n';
}
catch(constjson::type_error&e)
{
std::cout<<e.what()<<'\n';
}
// exception out_of_range.401
try
{
// try to read from a nonexisting key using string_view
std::cout<<object.at("the fast"sv)<<'\n';
}
catch(constjson::out_of_range&e)
{
std::cout<<"out of range"<<'\n';
}
}

Output:

"il brutto"
[json.exception.type_error.304]cannotuseat()withstring
outofrange
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.

#include<iostream>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
usingnamespacenlohmann::literals;
intmain()
{
// create a JSON value
jsonj=
{
{"number",1},{"string","foo"},{"array",{1,2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout<<j.at("/number"_json_pointer)<<'\n';
// output element with JSON pointer "/string"
std::cout<<j.at("/string"_json_pointer)<<'\n';
// output element with JSON pointer "/array"
std::cout<<j.at("/array"_json_pointer)<<'\n';
// output element with JSON pointer "/array/1"
std::cout<<j.at("/array/1"_json_pointer)<<'\n';
// writing access
// change the string
j.at("/string"_json_pointer)="bar";
// output the changed string
std::cout<<j["string"]<<'\n';
// change an array element
j.at("/array/1"_json_pointer)=21;
// output the changed array
std::cout<<j["array"]<<'\n';
// out_of_range.106
try
{
// try to use an array index with leading '0'
json::referenceref=j.at("/array/01"_json_pointer);
}
catch(constjson::parse_error&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.109
try
{
// try to use an array index that is not a number
json::referenceref=j.at("/array/one"_json_pointer);
}
catch(constjson::parse_error&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.401
try
{
// try to use an invalid array index
json::referenceref=j.at("/array/4"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.402
try
{
// try to use the array index '-'
json::referenceref=j.at("/array/-"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.403
try
{
// try to use a JSON pointer to a nonexistent object key
json::const_referenceref=j.at("/foo"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.404
try
{
// try to use a JSON pointer that cannot be resolved
json::referenceref=j.at("/number/foo"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
}

Output:

1
"foo"
[1,2]
2
"bar"
[1,21]
[json.exception.parse_error.106]parseerror:arrayindex'01'mustnotbeginwith'0'
[json.exception.parse_error.109]parseerror:arrayindex'one'isnotanumber
[json.exception.out_of_range.401]arrayindex4isoutofrange
[json.exception.out_of_range.402]arrayindex'-'(2)isoutofrange
[json.exception.out_of_range.403]key'foo'notfound
[json.exception.out_of_range.404]unresolvedreferencetoken'foo'
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.

#include<iostream>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
usingnamespacenlohmann::literals;
intmain()
{
// create a JSON value
constjsonj=
{
{"number",1},{"string","foo"},{"array",{1,2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout<<j.at("/number"_json_pointer)<<'\n';
// output element with JSON pointer "/string"
std::cout<<j.at("/string"_json_pointer)<<'\n';
// output element with JSON pointer "/array"
std::cout<<j.at("/array"_json_pointer)<<'\n';
// output element with JSON pointer "/array/1"
std::cout<<j.at("/array/1"_json_pointer)<<'\n';
// out_of_range.109
try
{
// try to use an array index that is not a number
json::const_referenceref=j.at("/array/one"_json_pointer);
}
catch(constjson::parse_error&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.401
try
{
// try to use an invalid array index
json::const_referenceref=j.at("/array/4"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.402
try
{
// try to use the array index '-'
json::const_referenceref=j.at("/array/-"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.403
try
{
// try to use a JSON pointer to a nonexistent object key
json::const_referenceref=j.at("/foo"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
// out_of_range.404
try
{
// try to use a JSON pointer that cannot be resolved
json::const_referenceref=j.at("/number/foo"_json_pointer);
}
catch(constjson::out_of_range&e)
{
std::cout<<e.what()<<'\n';
}
}

Output:

1
"foo"
[1,2]
2
[json.exception.parse_error.109]parseerror:arrayindex'one'isnotanumber
[json.exception.out_of_range.401]arrayindex4isoutofrange
[json.exception.out_of_range.402]arrayindex'-'(2)isoutofrange
[json.exception.out_of_range.403]key'foo'notfound
[json.exception.out_of_range.404]unresolvedreferencetoken'foo'

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.
Copyright © 2013-2026 Niels Lohmann

AltStyle によって変換されたページ (->オリジナル) /