ceph/src/jaegertracing/opentelemetry-cpp/third_party/nlohmann-json/doc/mkdocs/docs/api/basic_json/erase.md

   1 # <small>nlohmann::basic_json::</small>erase
   2
   3 ```cpp
   4 // (1)
   5 iterator erase(iterator pos);
   6 const_iterator erase(const_iterator pos);
   7
   8 // (2)
   9 iterator erase(iterator first, iterator last);
  10 const_iterator erase(const_iterator first, const_iterator last);
  11
  12 // (3)
  13 size_type erase(const typename object_t::key_type& key);
  14
  15 // (4)
  16 void erase(const size_type idx);
  17 ```
  18
  19 1. 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
  25 2. 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
  30 3. Removes an element from a JSON object by key.
  31
  32 4. 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
  53 1. Iterator following the last removed element. If the iterator `pos` refers to the last element, the `end()` iterator
  54    is returned.
  55 2. Iterator following the last removed element. If the iterator `last` refers to the last element, the `end()` iterator
  56    is returned.
  57 3. 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).
  59 4. /
  60
  61 ## Exception safety
  62
  63 Strong exception safety: if an exception occurs, the original value stays intact.
  64
  65 ## Exceptions
  66
  67 1. The function can throw the following exceptions:
  68     - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value;
  69       example: `"cannot use erase() with null"`
  70     - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
  71       iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
  72     - Throws [`invalid_iterator.205`](../../home/exceptions.md#jsonexceptioninvalid_iterator205) if called on a
  73       primitive type with invalid iterator (i.e., any iterator which is not `begin()`); example: `"iterator out of
  74       range"`
  75 2. The function can throw the following exceptions:
  76     - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value;
  77       example: `"cannot use erase() with null"`
  78     - Throws [`invalid_iterator.203`](../../home/exceptions.md#jsonexceptioninvalid_iterator203) if called on iterators
  79       which does not belong to the current JSON value; example: `"iterators do not fit current value"`
  80     - Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if called on a
  81       primitive type with invalid iterators (i.e., if `first != begin()` and `last != end()`); example: `"iterators out
  82       of range"`
  83 3. The function can throw the following exceptions:
  84     - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
  85       JSON object; example: `"cannot use erase() with null"`
  86 4. The function can throw the following exceptions:
  87     - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
  88       JSON object; example: `"cannot use erase() with null"`
  89     - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
  90       `"array index 17 is out of range"`
  91
  92 ## Complexity
  93
  94 1. 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
  99 2. 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
 105 3. `log(size()) + count(key)`
 106 4. Linear in distance between `idx` and the end of the container.
 107
 108 ## Notes
 109
 110 1. Invalidates iterators and references at or after the point of the `erase`, including the `end()` iterator.
 111 2. /
 112 3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
 113 4. /
 114
 115 ## Examples
 116
 117 ??? example "Example: (1) remove element given an iterator"
 118
 119     The example shows the effect of `erase()` for different JSON types using an iterator.
 120
 121     ```cpp
 122     --8<-- "examples/erase__IteratorType.cpp"
 123     ```
 124
 125     Output:
 126
 127     ```json
 128     --8<-- "examples/erase__IteratorType.output"
 129     ```
 130
 131 ??? example "Example: (2) remove elements given an iterator range"
 132
 133     The example shows the effect of `erase()` for different JSON types using an iterator range.
 134
 135     ```cpp
 136     --8<-- "examples/erase__IteratorType_IteratorType.cpp"
 137     ```
 138
 139     Output:
 140
 141     ```json
 142     --8<-- "examples/erase__IteratorType_IteratorType.output"
 143     ```
 144
 145 ??? example "Example: (3) remove element from a JSON object given a key"
 146
 147     The example shows the effect of `erase()` for different JSON types using an object key.
 148
 149     ```cpp
 150     --8<-- "examples/erase__key_type.cpp"
 151     ```
 152
 153     Output:
 154
 155     ```json
 156     --8<-- "examples/erase__key_type.output"
 157     ```
 158
 159 ??? example "Example: (4) remove element from a JSON array given an index"
 160
 161     The example shows the effect of `erase()` using an array index.
 162
 163     ```cpp
 164     --8<-- "examples/erase__size_type.cpp"
 165     ```
 166
 167     Output:
 168
 169     ```json
 170     --8<-- "examples/erase__size_type.output"
 171     ```
 172
 173 ## Version history
 174
 175 - Added in version 1.0.0.
 176 - Added support for binary types in version 3.8.0.