1# <small>nlohmann::basic_json::</small>erase 2 3```cpp 4// (1) 5iterator erase(iterator pos); 6const_iterator erase(const_iterator pos); 7 8// (2) 9iterator erase(iterator first, iterator last); 10const_iterator erase(const_iterator first, const_iterator last); 11 12// (3) 13size_type erase(const typename object_t::key_type& key); 14 15// (4) 16template<typename KeyType> 17size_type erase(KeyType&& key); 18 19// (5) 20void erase(const size_type idx); 21``` 22 231. Removes an element from a JSON value specified by iterator `pos`. The iterator `pos` must be valid and 24 dereferenceable. Thus, the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for 25 `pos`. 26 27 If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`. 28 292. Remove an element range specified by `[first; last)` from a JSON value. The iterator `first` does not need to be 30 dereferenceable if `first == last`: erasing an empty range is a no-op. 31 32 If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`. 33 343. Removes an element from a JSON object by key. 35 364. See 3. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and 37 `#!cpp typename object_comparator_t::is_transparent` denotes a type. 38 395. Removes an element from a JSON array by index. 40 41## Template parameters 42 43`KeyType` 44: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with 45 [`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md). 46 This can also be a string view (C++17). 47 48## Parameters 49 50`pos` (in) 51: iterator to the element to remove 52 53`first` (in) 54: iterator to the beginning of the range to remove 55 56`last` (in) 57: iterator past the end of the range to remove 58 59`key` (in) 60: object key of the elements to remove 61 62`idx` (in) 63: array index of the element to remove 64 65## Return value 66 671. Iterator following the last removed element. If the iterator `pos` refers to the last element, the `end()` iterator 68 is returned. 692. Iterator following the last removed element. If the iterator `last` refers to the last element, the `end()` iterator 70 is returned. 713. Number of elements removed. If `ObjectType` is the default `std::map` type, the return value will always be `0` 72 (`key` was not found) or `1` (`key` was found). 734. See 3. 745. (none) 75 76## Exception safety 77 78Strong exception safety: if an exception occurs, the original value stays intact. 79 80## Exceptions 81 821. The function can throw the following exceptions: 83 - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value; 84 example: `"cannot use erase() with null"` 85 - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an 86 iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"` 87 - Throws [`invalid_iterator.205`](../../home/exceptions.md#jsonexceptioninvalid_iterator205) if called on a 88 primitive type with invalid iterator (i.e., any iterator which is not `begin()`); example: `"iterator out of 89 range"` 902. The function can throw the following exceptions: 91 - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value; 92 example: `"cannot use erase() with null"` 93 - Throws [`invalid_iterator.203`](../../home/exceptions.md#jsonexceptioninvalid_iterator203) if called on iterators 94 which does not belong to the current JSON value; example: `"iterators do not fit current value"` 95 - Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if called on a 96 primitive type with invalid iterators (i.e., if `first != begin()` and `last != end()`); example: `"iterators out 97 of range"` 983. The function can throw the following exceptions: 99 - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than 100 JSON object; example: `"cannot use erase() with null"` 1014. See 3. 1025. The function can throw the following exceptions: 103 - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than 104 JSON object; example: `"cannot use erase() with null"` 105 - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example: 106 `"array index 17 is out of range"` 107 108## Complexity 109 1101. The complexity depends on the type: 111 - objects: amortized constant 112 - arrays: linear in distance between `pos` and the end of the container 113 - strings and binary: linear in the length of the member 114 - other types: constant 1152. The complexity depends on the type: 116 - objects: `log(size()) + std::distance(first, last)` 117 - arrays: linear in the distance between `first` and `last`, plus linear 118 in the distance between `last` and end of the container 119 - strings and binary: linear in the length of the member 120 - other types: constant 1213. `log(size()) + count(key)` 1224. `log(size()) + count(key)` 1235. Linear in distance between `idx` and the end of the container. 124 125## Notes 126 1271. Invalidates iterators and references at or after the point of the `erase`, including the `end()` iterator. 1282. (none) 1293. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. 1304. See 3. 1315. (none) 132 133## Examples 134 135??? example "Example: (1) remove element given an iterator" 136 137 The example shows the effect of `erase()` for different JSON types using an iterator. 138 139 ```cpp 140 --8<-- "examples/erase__IteratorType.cpp" 141 ``` 142 143 Output: 144 145 ```json 146 --8<-- "examples/erase__IteratorType.output" 147 ``` 148 149??? example "Example: (2) remove elements given an iterator range" 150 151 The example shows the effect of `erase()` for different JSON types using an iterator range. 152 153 ```cpp 154 --8<-- "examples/erase__IteratorType_IteratorType.cpp" 155 ``` 156 157 Output: 158 159 ```json 160 --8<-- "examples/erase__IteratorType_IteratorType.output" 161 ``` 162 163??? example "Example: (3) remove element from a JSON object given a key" 164 165 The example shows the effect of `erase()` for different JSON types using an object key. 166 167 ```cpp 168 --8<-- "examples/erase__object_t_key_type.cpp" 169 ``` 170 171 Output: 172 173 ```json 174 --8<-- "examples/erase__object_t_key_type.output" 175 ``` 176 177??? example "Example: (4) remove element from a JSON object given a key using string_view" 178 179 The example shows the effect of `erase()` for different JSON types using an object key. 180 181 ```cpp 182 --8<-- "examples/erase__keytype.c++17.cpp" 183 ``` 184 185 Output: 186 187 ```json 188 --8<-- "examples/erase__keytype.c++17.output" 189 ``` 190 191??? example "Example: (5) remove element from a JSON array given an index" 192 193 The example shows the effect of `erase()` using an array index. 194 195 ```cpp 196 --8<-- "examples/erase__size_type.cpp" 197 ``` 198 199 Output: 200 201 ```json 202 --8<-- "examples/erase__size_type.output" 203 ``` 204 205## Version history 206 2071. Added in version 1.0.0. Added support for binary types in version 3.8.0. 2082. Added in version 1.0.0. Added support for binary types in version 3.8.0. 2093. Added in version 1.0.0. 2104. Added in version 3.11.0. 2115. Added in version 1.0.0. 212