• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# basic_json::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)
16void erase(const size_type idx);
17```
18
191. Removes an element from a JSON value specified by iterator `pos`. The iterator `pos` must be valid and
20   dereferenceable. Thus the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
21   `pos`.
22
23    If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`.
24
252. Remove an element range specified by `[first; last)` from a JSON value. The iterator `first` does not need to be
26   dereferenceable if `first == last`: erasing an empty range is a no-op.
27
28    If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`.
29
303. Removes an element from a JSON object by key.
31
324. Removes an element from a JSON array by index.
33
34## Parameters
35
36`pos` (in)
37:   iterator to the element to remove
38
39`first` (in)
40:   iterator to the beginning of the range to remove
41
42`last` (in)
43:   iterator past the end of the range to remove
44
45`key` (in)
46:   object key of the elements to remove
47
48`idx` (in)
49:   array index of the element to remove
50
51## Return value
52
531. Iterator following the last removed element. If the iterator `pos` refers to the last element, the `end()` iterator
54   is returned.
552. Iterator following the last removed element. If the iterator `last` refers to the last element, the `end()` iterator
56   is returned.
573. Number of elements removed. If `ObjectType` is the default `std::map` type, the return value will always be `0`
58   (`key` was not found) or `1` (`key` was found).
594. /
60
61## Exceptions
62
631. The function can throw the following exceptions:
64    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value;
65      example: `"cannot use erase() with null"`
66    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
67      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
68    - Throws [`invalid_iterator.205`](../../home/exceptions.md#jsonexceptioninvalid_iterator205) if called on a
69      primitive type with invalid iterator (i.e., any iterator which is not `begin()`); example: `"iterator out of
70      range"`
712. The function can throw thw following exceptions:
72    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value;
73      example: `"cannot use erase() with null"`
74    - Throws [`invalid_iterator.203`](../../home/exceptions.md#jsonexceptioninvalid_iterator203) if called on iterators
75      which does not belong to the current JSON value; example: `"iterators do not fit current value"`
76    - Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if called on a
77      primitive type with invalid iterators (i.e., if `first != begin()` and `last != end()`); example: `"iterators out
78      of range"`
793. The function can throw thw following exceptions:
80    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
81      JSON object; example: `"cannot use erase() with null"`
824. The function can throw thw following exceptions:
83    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
84      JSON object; example: `"cannot use erase() with null"`
85    - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
86      `"array index 17 is out of range"`
87
88## Exception safety
89
90Strong exception safety: if an exception occurs, the original value stays intact.
91
92## Complexity
93
941. The complexity depends on the type:
95       - objects: amortized constant
96       - arrays: linear in distance between `pos` and the end of the container
97       - strings and binary: linear in the length of the member
98       - other types: constant
992. The complexity depends on the type:
100       - objects: `log(size()) + std::distance(first, last)`
101       - arrays: linear in the distance between `first` and `last`, plus linear
102         in the distance between `last` and end of the container
103       - strings and binary: linear in the length of the member
104       - other types: constant
1053. `log(size()) + count(key)`
1064. Linear in distance between `idx` and the end of the container.
107
108## Notes
109
1101. Invalidates iterators and references at or after the point of the
111   erase, including the `end()` iterator.
1122. /
1133. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
1144. /
115
116## Example
117
118??? example
119
120    The example shows the effect of `erase()` for different JSON types using an iterator.
121
122    ```cpp
123    --8<-- "examples/erase__IteratorType.cpp"
124    ```
125
126    Output:
127
128    ```json
129    --8<-- "examples/erase__IteratorType.output"
130    ```
131
132??? example
133
134    The example shows the effect of `erase()` for different JSON types using an iterator range.
135
136    ```cpp
137    --8<-- "examples/erase__IteratorType_IteratorType.cpp"
138    ```
139
140    Output:
141
142    ```json
143    --8<-- "examples/erase__IteratorType_IteratorType.output"
144    ```
145
146??? example
147
148    The example shows the effect of `erase()` for different JSON types using an object key.
149
150    ```cpp
151    --8<-- "examples/erase__key_type.cpp"
152    ```
153
154    Output:
155
156    ```json
157    --8<-- "examples/erase__key_type.output"
158    ```
159
160??? example
161
162    The example shows the effect of `erase()` using an array index.
163
164    ```cpp
165    --8<-- "examples/erase__size_type.cpp"
166    ```
167
168    Output:
169
170    ```json
171    --8<-- "examples/erase__size_type.output"
172    ```
173
174## Version history
175
176- Added in version 1.0.0.
177- Added support for binary types in version 3.8.0.
178