Skip to content

# nlohmann::basic_json::erase

    // (1)
    iterator erase(iterator pos);
    const_iterator erase(const_iterator pos);

    // (2)
    iterator erase(iterator first, iterator last);
    const_iterator erase(const_iterator first, const_iterator last);

    // (3)
    size_type erase(const typename object_t::key_type& key);

    // (4)
    void erase(const size_type idx);

1. Removes an element from a JSON value specified by iterator `pos`. The iterator `pos` must be valid and dereferenceable. Thus, the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for `pos`.

   If called on a primitive type other than `null`, the resulting JSON value will be `null`.

2. Remove an element range specified by `[first; last)` from a JSON value. The iterator `first` does not need to be dereferenceable if `first == last`: erasing an empty range is a no-op.

   If called on a primitive type other than `null`, the resulting JSON value will be `null`.

3. Removes an element from a JSON object by key.

4. Removes an element from a JSON array by index.

## Parameters

`pos` (in)
  iterator to the element to remove
`first` (in)
  iterator to the beginning of the range to remove
`last` (in)
  iterator past the end of the range to remove
`key` (in)
  object key of the elements to remove
`idx` (in)
  array index of the element to remove

## Return value

1. Iterator following the last removed element. If the iterator `pos` refers to the last element, the `end()` iterator is returned.
2. Iterator following the last removed element. If the iterator `last` refers to the last element, the `end()` iterator is returned.
3. Number of elements removed. If `ObjectType` is the default `std::map` type, the return value will always be `0` (`key` was not found) or `1` (`key` was found).
4. /

## 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.307` if called on a `null` value; example: `"cannot use erase() with null"`
   - Throws `invalid_iterator.202` if called on an iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
   - Throws `invalid_iterator.205` if called on a primitive type with invalid iterator (i.e., any iterator which is not `begin()`); example: `"iterator out of range"`
2. The function can throw the following exceptions:
   - Throws `type_error.307` if called on a `null` value; example: `"cannot use erase() with null"`
   - Throws `invalid_iterator.203` if called on iterators which does not belong to the current JSON value; example: `"iterators do not fit current value"`
   - Throws `invalid_iterator.204` if called on a primitive type with invalid iterators (i.e., if `first != begin()` and `last != end()`); example: `"iterators out of range"`
3. The function can throw the following exceptions:
   - Throws `type_error.307` when called on a type other than JSON object; example: `"cannot use erase() with null"`
4. The function can throw the following exceptions:
   - Throws `type_error.307` when called on a type other than JSON object; example: `"cannot use erase() with null"`
   - Throws `out_of_range.401` when `idx >= size()`; example: `"array index 17 is out of range"`

## Complexity

1. The complexity depends on the type:
   - objects: amortized constant
   - arrays: linear in distance between `pos` and the end of the container
   - strings and binary: linear in the length of the member
   - other types: constant
2. The complexity depends on the type:
   - objects: `log(size()) + std::distance(first, last)`
   - arrays: linear in the distance between `first` and `last`, plus linear in the distance between `last` and end of the container
   - strings and binary: linear in the length of the member
   - other types: constant
3. `log(size()) + count(key)`
4. Linear in distance between `idx` and the end of the container.

## Notes

1. Invalidates iterators and references at or after the point of the `erase`, including the `end()` iterator.
2. /
3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
4. /

## Examples

Example: (1) remove element given an iterator

The example shows the effect of `erase()` for different JSON types using an iterator.

    #include <iostream>
    #include <nlohmann/json.hpp>

    using json = nlohmann::json;

    int main()
    {
        // create JSON values
        json j_boolean = true;
        json j_number_integer = 17;
        json j_number_float = 23.42;
        json j_object = {{"one", 1}, {"two", 2}};
        json j_array = {1, 2, 4, 8, 16};
        json j_string = "Hello, world";

        // call erase()
        j_boolean.erase(j_boolean.begin());
        j_number_integer.erase(j_number_integer.begin());
        j_number_float.erase(j_number_float.begin());
        j_object.erase(j_object.find("two"));
        j_array.erase(j_array.begin() + 2);
        j_string.erase(j_string.begin());

        // print values
        std::cout << j_boolean << '\n';
        std::cout << j_number_integer << '\n';
        std::cout << j_number_float << '\n';
        std::cout << j_object << '\n';
        std::cout << j_array << '\n';
        std::cout << j_string << '\n';
    }

Output:

    null
    null
    null
    {"one":1}
    [1,2,8,16]
    null

Example: (2) remove elements given an iterator range

The example shows the effect of `erase()` for different JSON types using an iterator range.

    #include <iostream>
    #include <nlohmann/json.hpp>

    using json = nlohmann::json;

    int main()
    {
        // create JSON values
        json j_boolean = true;
        json j_number_integer = 17;
        json j_number_float = 23.42;
        json j_object = {{"one", 1}, {"two", 2}};
        json j_array = {1, 2, 4, 8, 16};
        json j_string = "Hello, world";

        // call erase()
        j_boolean.erase(j_boolean.begin(), j_boolean.end());
        j_number_integer.erase(j_number_integer.begin(), j_number_integer.end());
        j_number_float.erase(j_number_float.begin(), j_number_float.end());
        j_object.erase(j_object.find("two"), j_object.end());
        j_array.erase(j_array.begin() + 1, j_array.begin() + 3);
        j_string.erase(j_string.begin(), j_string.end());

        // print values
        std::cout << j_boolean << '\n';
        std::cout << j_number_integer << '\n';
        std::cout << j_number_float << '\n';
        std::cout << j_object << '\n';
        std::cout << j_array << '\n';
        std::cout << j_string << '\n';
    }

Output:

    null
    null
    null
    {"one":1}
    [1,8,16]
    null

Example: (3) remove element from a JSON object given a key

The example shows the effect of `erase()` for different JSON types using an object key.

    #include <iostream>
    #include <nlohmann/json.hpp>

    using json = nlohmann::json;

    int main()
    {
        // create a JSON object
        json j_object = {{"one", 1}, {"two", 2}};

        // call erase()
        auto count_one = j_object.erase("one");
        auto count_three = j_object.erase("three");

        // print values
        std::cout << j_object << '\n';
        std::cout << count_one << " " << count_three << '\n';
    }

Output:

    {"two":2}
    1 0

Example: (4) remove element from a JSON array given an index

The example shows the effect of `erase()` using an array index.

    #include <iostream>
    #include <nlohmann/json.hpp>

    using json = nlohmann::json;

    int main()
    {
        // create a JSON array
        json j_array = {0, 1, 2, 3, 4, 5};

        // call erase()
        j_array.erase(2);

        // print values
        std::cout << j_array << '\n';
    }

Output:

    [0,1,3,4,5]

## Version history

- Added in version 1.0.0.
- Added support for binary types in version 3.8.0.

Back to top