274be40921
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.0 KiB
nlohmann::basic_json_document::push_back
template<typename V>
view_type push_back(view_type array, V&& value);
Appends value as a new last element of array. A null array first becomes an
empty array, the same way set turns a null object into an empty object.
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, ...).
Only an editable document (#!cpp Editable == true, e.g. json_editable_document)
has push_back; calling it on a read-only basic_json_document fails to compile (#!cpp static_assert).
Template parameters
V- the type of
value, deduced; see above for what is accepted.
Parameters
array(in)- the array (or null value) to append to
value(in)- the value to append
Return value
a view of the new last element of array, 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 a partial effect, such
as a null array argument already turned into an empty array even though value itself was not appended.
Exceptions
Throws type_error.308 if array is neither an array nor
null -- the same message BasicJsonType::push_back throws for the same type. 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
Amortized constant, 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): the elements of array move to a growable
block of links the first time it is appended to (or set on), and that block itself grows -- doubling its
capacity, so the cost of growing it amortizes to constant per element -- only once it runs out of room. See
Notes.
Notes
Like set on a member or an element, push_back never moves an existing element itself -- only where
array's links to its elements live -- so a view of an existing element of array stays valid across a
push_back, but 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 appends records to an array one at a time, as they might arrive from a stream of events,
without ever building a `BasicJsonType` value for the array or for the records already in it, and shows that a
view taken from an earlier `push_back` still refers to the same element once later ones have run.
```cpp
--8<-- "examples/basic_json_document__push_back.cpp"
```
Output:
```json
--8<-- "examples/basic_json_document__push_back.output"
```
See also
- set - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
- insert - insert an element into an array before a given position
- erase - remove an object member, an array element, or the value a JSON pointer refers to
- root - the view of the root value
BasicJsonType::push_back- the corresponding function ofbasic_json- Edits - what an edit guarantees, for every overload
Version history
- Added in version 3.13.0.