• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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