json/docs/mkdocs/docs/api/basic_json_document/push_back.md

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 view_mode::editable, 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 of basic_json
• Edits - what an edit guarantees, for every overload
• Zero-copy JSON views - what an edit guarantees and costs

Version history

• Added in version 3.13.0.