json/docs/mkdocs/docs/api/basic_json_document/erase.md

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 (#!cpp view_mode::editable, e.g. json_editable_document) has erase; calling it on a read-only basic_json_document fails to compile (#!cpp static_assert).

1. Removes every member of object whose key is key (see Notes on duplicate keys) and returns how many were removed; #!cpp 0 if object has no member with this key.
2. Removes the element at index idx of array, which must already exist (#!cpp 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, #!cpp 0 or more) and as in 2. if it is an array (always returns #!cpp 1).

Template parameters

I

an integral type other than #!cpp bool, deduced (overloads taking a #!cpp 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 (#!cpp 0 if object had none with this key)
2. (nothing)
3. the number of removed values (#!cpp 0 or more for an object member, always #!cpp 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 #!cpp 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 #!cpp '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

!!! info "Duplicate keys"

Overload 1. removes *every* member with `key`, not just the first — unlike [`set`](set.md), which assigns the
first occurrence and drops the rest. This is why it returns a count rather than a single view: there may be
more than one member removed, or none.

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

??? example

The example below drops a deprecated field and a decommissioned entry from a configuration document — using all
three overloads — and shows what stays intact that would not with a plain `json`/`ordered_json` value: the order
of the fields around the ones removed, and the exact spelling of a number that was never touched.

```cpp
--8<-- "examples/basic_json_document__erase.cpp"
```

Output:

```json
--8<-- "examples/basic_json_document__erase.output"
```

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
• Zero-copy JSON views - what an edit guarantees and costs

Version history

• Added in version 3.13.0.