Niels Lohmann
a496c709f4
Add API reference pages for basic_json_document::insert and basic_json_document::erase, matching the style of set.md and push_back.md: signatures, parameters, return values, exception safety, exceptions with their exact ids and messages, complexity, notes on duplicate keys and view/iterator validity, and an example. Add example programs basic_json_document__insert.cpp and basic_json_document__erase.cpp with their expected output, each comparing an edit on an editable document with the same edit on a plain json value to show what is preserved: member order, the spelling of untouched numbers, and, for insert, that a view taken before the insert keeps referring to the same element after its index shifts. Register both new pages in mkdocs.yml, docSet.sql, and the member list of basic_json_document/index.md, add cross-references to them from set.md and push_back.md, and mention insert/erase in the "Editing a document" section of features/json_view.md. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
5.6 KiB
nlohmann::basic_json_document::insert
template<typename I, typename V>
view_type insert(view_type array, I idx, V&& value);
Only an editable document (#!cpp Editable == true, e.g. json_editable_document)
has insert; calling it on a read-only basic_json_document fails to compile (#!cpp static_assert).
Inserts value into array as a new element before position idx, which must not be past the end
(#!cpp idx <= array.size(); #!cpp idx == array.size() appends, like push_back). Unlike
push_back, a null array does not first become an empty array:
array must already be an array.
value is accepted three ways: a basic_json_view of any document -- read-only or
editable, and it does not have to be array's own document -- which is copied so that nothing is shared with the
source document afterward; a BasicJsonType value; or anything BasicJsonType can be constructed from (numbers,
strings, #!cpp bool, #!cpp nullptr, containers, ...).
Template parameters
I- an integral type other than
#!cpp bool, deduced (overloads taking a#!cpp boolor a non-integral type foridxdo not participate in overload resolution). V- the type of
value, deduced; see above for what is accepted.
Parameters
array(in)- the array to insert into
idx(in)- the position to insert
valuebefore; a negative value throws (see Exceptions) value(in)- the value to insert
Return value
a view of the new element, now holding value
Exception safety
Basic exception safety: value is fully encoded -- including the checks below -- into storage owned by the document
before anything already reachable from root() is touched, so a failure while encoding value (an
invalid argument, or #!cpp std::bad_alloc) leaves the document completely unchanged, other than memory allocated
for the encoding that is not reclaimed. A failure of a later allocation -- while array switches from its parsed
layout to a growable block, or while that block grows, see Notes -- can still leave array already
switched to that layout even though value itself was not inserted.
Exceptions
Throws type_error.309 if array is not an array -- the same
message BasicJsonType::insert throws for the same type; a null array throws this too
(see above). Throws out_of_range.401 if idx is negative,
or if #!cpp idx > array.size(). Throws
invalid_iterator.202 ("view does not belong to this
document") if array is a discarded view or a view of a different document.
Throws type_error.302 if value is a
discarded view or a discarded BasicJsonType
value, and type_error.319 if value is (or contains) a
binary value -- BasicJsonType can hold one, but a json_document cannot. Throws
type_error.316 if value is (or contains) a string that is
not valid UTF-8, with the same message BasicJsonType::dump() gives for that string.
Complexity
Linear in the number of elements of array at or after idx (they move one slot over), plus time linear in the
size of value to encode it into the document's storage (constant for a scalar, linear in the number of nested
values for an array or object): like push_back, the elements of array move to a growable block
of links the first time it is inserted into (or set/push_back on), and that block
grows in amortized constant time; inserting before the end within that block still shifts every later element.
Notes
Like set on a member or an element, insert never moves an existing element's value -- only where
array's links to its elements live -- so a view of an existing element of array stays valid across an
insert, and keeps referring to the same element even though its index shifts. Any iterator already taken over
array is invalidated, since it was walking the old layout. See Edits for what stays valid across
an edit in general.
Examples
??? example
The example below inserts a step into the middle of a deployment plan, without touching the steps that come
after it, and shows that a view taken before the insert keeps referring to the same element even though its
index shifts -- something a plain `json`/`ordered_json` array, or its `std::vector`-based storage, has no
equivalent for.
```cpp
--8<-- "examples/basic_json_document__insert.cpp"
```
Output:
```json
--8<-- "examples/basic_json_document__insert.output"
```
See also
- push_back - append to an array
- erase - remove an object member, an array element, or the value a JSON pointer refers to
- set - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
BasicJsonType::insert- the corresponding function ofbasic_json- Edits - what an edit guarantees, for every overload
Version history
- Added in version 3.13.0.