nlohmann::basic_json_document::erase¶

// (1)
std::size_t erase(view_type object, string_view_t key);

// (2)
template<typename I>
void erase(view_type array, I idx);

// (3)
std::size_t erase(const json_pointer& ptr);

Only an editable document (Editable == true, e.g. json_editable_document) has erase; calling it on a read-only basic_json_document fails to compile (static_assert).

1. Removes every member of object whose key is key (see Notes on duplicate keys) and returns how many were removed; 0 if object has no member with this key.
2. Removes the element at index idx of array, which must already exist (idx < array.size()).
3. Removes the value the JSON pointer ptr refers to, relative to root(). ptr must not be empty (root() itself cannot be erased), and the parent of the target must already exist. The target is removed as in 1. if the parent is an object (returns the number of removed members, 0 or more) and as in 2. if it is an array (always returns 1).

Template parameters¶

I

an integral type other than bool, deduced (overloads taking a bool or a non-integral type for idx do not participate in overload resolution).

Parameters¶

object (in)

the object to remove a member of

array (in)

the array to remove an element of

key (in)

the key of the member(s) to remove

idx (in)

the index of the element to remove; a negative value throws (see Exceptions)

ptr (in)

a JSON pointer to the value to remove, relative to root()

Return value¶

1. the number of removed members (0 if object had none with this key)
2. (nothing)
3. the number of removed values (0 or more for an object member, always 1 for an array element)

Exceptions¶

1. Throws type_error.307 if object is not an object -- the same message BasicJsonType::erase throws for the same type.
2. Throws type_error.307 if array is not an array. Throws out_of_range.401 if idx is negative, or if idx >= array.size().
3. Throws out_of_range.405 ("JSON pointer has no parent") if ptr is empty. Throws what at throws (overload 3) for resolving ptr's parent. For the last reference token itself: if the parent is an array, throws what 2. throws for an index that is out of range, or, for a token that is not a valid array index, parse_error.106 (a leading '0'), parse_error.109 (not a number), out_of_range.410 (too large for size_type), or out_of_range.404 (an empty token); otherwise (an object, or a primitive value the pointer's parent resolves to) throws what 1. throws.

Overloads 1. and 2. also throw invalid_iterator.202 ("view does not belong to this document") if object/array is a discarded view or a view of a different document. Overload 3. never throws invalid_iterator.202: it takes no view, and it always starts from this document's own root().

Complexity¶

1. Linear in the number of members of object.
2. Linear in the number of elements of array at or after idx (they move one slot over).
3. Linear in the number of reference tokens of ptr and, for each token, in the number of members of the object at that level or the index into the array (as at), plus the complexity of 1. or 2. for the last token.

Notes¶

Like set and push_back, erase never moves an element's value: a view still referring to a removed member or element keeps showing what it last held (see Edits) -- it just no longer appears when array/object is read, dumped, or iterated. What does change is the container's sequence of links to its elements: removing an element of array (2.) shifts the links to the elements after it by one, as insert does in the other direction. Every iterator already taken over array/object is invalidated by an erase, not only those at or after the removed element, since the container may now use a different sequence.

Examples¶

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

using json = nlohmann::json;
using json_editable_document = nlohmann::json_editable_document;
using json_editable_view = nlohmann::json_editable_view;

int main()
{
    // a deprecated field is dropped from a configuration file, and a
    // decommissioned replica is removed from the list -- "price" keeps its
    // trailing zero, and the fields around the removed ones keep their order
    const std::string text = R"({
  "name": "cache",
  "legacy_host": "db0",
  "host": "db1",
  "price": 19.90,
  "replicas": ["db2", "db3", "db4"]
})";

    json_editable_document doc = json_editable_document::parse(text);

    doc.erase(doc.root(), "legacy_host");                                      // (1) an object member
    doc.erase(doc.root()["replicas"], 1);                                      // (2) an array element ("db3")
    const std::size_t removed = doc.erase(json::json_pointer("/replicas/0"));  // (3) via a JSON pointer

    std::cout << removed << '\n';
    std::cout << doc.root().dump(2, ' ', false, json_editable_view::number_format::source) << "\n\n";

    // the same edits on a plain json value: object_t is a std::map, so
    // parsing already sorted the keys, and dump() rewrites every number to
    // its shortest form, even "price", which was never touched
    json plain = json::parse(text);
    plain.erase("legacy_host");
    plain["replicas"].erase(1);
    plain["replicas"].erase(0);
    std::cout << plain.dump(2) << '\n';
}

1
{
  "name": "cache",
  "host": "db1",
  "price": 19.90,
  "replicas": [
    "db4"
  ]
}

{
  "host": "db1",
  "name": "cache",
  "price": 19.9,
  "replicas": [
    "db4"
  ]
}

See also¶

• insert - insert an element into an array
• set - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
• push_back - append to an array
• root - the view of the root value, the starting point of overload 3
• BasicJsonType::erase - the corresponding function of basic_json
• Edits - what an edit guarantees, for every overload

Version history¶

• Added in version 3.13.0 unreleased.