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.
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.
The function can throw the following exceptions:
- Throws parse_error.106 if an array index in the passed JSON pointer ptr begins with '0'.
- Throws parse_error.109 if an array index in the passed JSON pointer ptr is not a number.
- Throws out_of_range.402 if the array index '-' is used in the passed JSON pointer ptr for the const version.
- Throws out_of_range.404 if the JSON pointer ptr can not be resolved.

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 with null values to make idx a valid reference to the last stored element. In case the value was null 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 a null value to make key a valid reference. In case the value was null 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 with null.
- The special value - is treated as a synonym for the index past the end.

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 in idx - 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:

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.