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 Editable == true, 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(), and returns how many values were removed: the parent of the target must already exist, and the target itself is removed as in 1. (an object member; #!cpp 0 or more) or 2. (an array element; always #!cpp 1). ptr must not be empty -- root() itself cannot be erased.

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.

Every overload also throws invalid_iterator.202 ("view does not belong to this document") if object/array is a discarded view or a view of a different document (overloads 1-2 only; overload 3 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. Removing an element of array (2.) does shift the links to the elements after it, the same way insert, set, or push_back on the same array would; any iterator already taken over array/object is invalidated by an erase, since it was walking the old layout.

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

Version history

• Added in version 3.13.0.