basic_json::operator[]¶
// (1)
reference operator[](size_type idx);
const_reference operator[](size_type idx) const;
// (2)
reference operator[](const typename object_t::key_type& key);
const_reference operator[](const typename object_t::key_type& key) const;
template<typename T>
reference operator[](T* key);
template<typename T>
const_reference operator[](T* key) const;
// (3)
reference operator[](const json_pointer& ptr);
const_reference operator[](const json_pointer& ptr) const;
- Returns a reference to the element at specified location
idx
. - Returns a reference to the element at with specified key
key
. - Returns a reference to the element at with specified JSON pointer
ptr
.
Template parameters¶
T
- string literal convertible to
object_t::key_type
Parameters¶
idx
(in)- index of the element to access
key
(in)- object key of the elements to remove
ptr
(in)- JSON pointer to the desired element
Return value¶
- reference to the element at index
idx
- reference to the element at key
key
- reference to the element pointed to by
ptr
Exceptions¶
- The function can throw the following exceptions:
- Throws
type_error.305
if the JSON value is not an array or null; in that cases, using the[]
operator with an index makes no sense.
- Throws
- The function can throw the following exceptions:
- Throws
type_error.305
if the JSON value is not an array or null; in that cases, using the[]
operator with an index makes no sense.
- Throws
- The function can throw the following exceptions:
- Throws
parse_error.106
if an array index in the passed JSON pointerptr
begins with '0'. - Throws
parse_error.109
if an array index in the passed JSON pointerptr
is not a number. - Throws
out_of_range.402
if the array index '-' is used in the passed JSON pointerptr
for the const version. - Throws
out_of_range.404
if the JSON pointerptr
can not be resolved.
- Throws
Notes¶
Danger
- If the element with key
idx
does not exist, the behavior is undefined. - If the element with key
key
does not exist, the behavior is undefined and is guarded by an assertion!
-
The non-const version may add values: If
idx
is beyond the range of the array (i.e.,idx >= size()
), then the array is silently filled up withnull
values to makeidx
a valid reference to the last stored element. In case the value wasnull
before, it is converted to an array. -
If
key
is not found in the object, then it is silently added to the object and filled with anull
value to makekey
a valid reference. In case the value wasnull
before, it is converted to an object. -
null
values are created in arrays and objects if necessary.In particular:
- If the JSON pointer points to an object key that does not exist, it is created an filled with a
null
value before a reference to it is returned. - If the JSON pointer points to an array index that does not exist, it is created an filled with a
null
value before a reference to it is returned. All indices between the current maximum and the given index are also filled withnull
. - The special value
-
is treated as a synonym for the index past the end.
- If the JSON pointer points to an object key that does not exist, it is created an filled with a
Exception safety¶
Strong exception safety: if an exception occurs, the original value stays intact.
Complexity¶
- Constant if
idx
is in the range of the array. Otherwise linear inidx - size()
. - Logarithmic in the size of the container.
- Constant
Example¶
Example
The example below shows how array elements can be read and written using []
operator. Note the addition of null
values.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON array
json array = {1, 2, 3, 4, 5};
// output element at index 3 (fourth element)
std::cout << array[3] << '\n';
// change last element to 6
array[array.size() - 1] = 6;
// output changed array
std::cout << array << '\n';
// write beyond array limit
array[10] = 11;
// output changed array
std::cout << array << '\n';
}
Output:
4
[1,2,3,4,6]
[1,2,3,4,6,null,null,null,null,null,11]
Example
The example below shows how array elements can be read using the []
operator.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON array
const json array = {"first", "2nd", "third", "fourth"};
// output element at index 2 (third element)
std::cout << array.at(2) << '\n';
}
Output:
"third"
Example
The example below shows how object elements can be read and written using the []
operator.
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON object
json object =
{
{"one", 1}, {"two", 2}, {"three", 2.9}
};
// output element with key "two"
std::cout << object["two"] << "\n\n";
// change element with key "three"
object["three"] = 3;
// output changed array
std::cout << std::setw(4) << object << "\n\n";
// mention nonexisting key
object["four"];
// write to nonexisting key
object["five"]["really"]["nested"] = true;
// output changed object
std::cout << std::setw(4) << object << '\n';
}
Output:
2
{
"one": 1,
"three": 3,
"two": 2
}
{
"five": {
"really": {
"nested": true
}
},
"four": null,
"one": 1,
"three": 3,
"two": 2
}
Example
The example below shows how object elements can be read using the []
operator.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON object
const json object =
{
{"one", 1}, {"two", 2}, {"three", 2.9}
};
// output element with key "two"
std::cout << object["two"] << '\n';
}
Output:
2
Example
The example below shows how values can be read and written using JSON Pointers.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON value
json j =
{
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout << j["/number"_json_pointer] << '\n';
// output element with JSON pointer "/string"
std::cout << j["/string"_json_pointer] << '\n';
// output element with JSON pointer "/array"
std::cout << j["/array"_json_pointer] << '\n';
// output element with JSON pointer "/array/1"
std::cout << j["/array/1"_json_pointer] << '\n';
// writing access
// change the string
j["/string"_json_pointer] = "bar";
// output the changed string
std::cout << j["string"] << '\n';
// "change" a nonexisting object entry
j["/boolean"_json_pointer] = true;
// output the changed object
std::cout << j << '\n';
// change an array element
j["/array/1"_json_pointer] = 21;
// "change" an array element with nonexisting index
j["/array/4"_json_pointer] = 44;
// output the changed array
std::cout << j["array"] << '\n';
// "change" the array element past the end
j["/array/-"_json_pointer] = 55;
// output the changed array
std::cout << j["array"] << '\n';
}
Output:
1
"foo"
[1,2]
2
"bar"
{"array":[1,2],"boolean":true,"number":1,"string":"bar"}
[1,21,null,null,44]
[1,21,null,null,44,55]
Example
The example below shows how values can be read using JSON Pointers.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON value
const json j =
{
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout << j["/number"_json_pointer] << '\n';
// output element with JSON pointer "/string"
std::cout << j["/string"_json_pointer] << '\n';
// output element with JSON pointer "/array"
std::cout << j["/array"_json_pointer] << '\n';
// output element with JSON pointer "/array/1"
std::cout << j["/array/1"_json_pointer] << '\n';
}
Output:
1
"foo"
[1,2]
2
Version history¶
- Added in version 1.0.0.
- Added in version 1.0.0. Overloads for
T* key
added in version 1.1.0. - Added in version 2.0.0.