mirror of
https://github.com/nlohmann/json.git
synced 2026-10-29 03:55:21 +00:00
deploy: a47170346a
This commit is contained in:
nlohmann
@@ -9,7 +9,7 @@ static bool accept(InputType&& input,
|
||||
|
||||
Checks whether the input is valid JSON, accepting and rejecting exactly what
|
||||
[`BasicJsonType::accept()`](../basic_json/accept.md) does, with the same options. Unlike [`parse()`](parse.md), this
|
||||
function never throws an exception for invalid input, and the returned `#!cpp bool` is the only result -- no document
|
||||
function never throws an exception for invalid input, and the returned `#!cpp bool` is the only result — no document
|
||||
is returned.
|
||||
|
||||
The result is the same as that of `BasicJsonType::accept()` by design; the difference is how the check is made. This
|
||||
@@ -92,8 +92,9 @@ compile; see [`parse`](parse.md#notes).
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](parse.md) - deserialize from a compatible input
|
||||
- [`parse`](parse.md) - deserialize from a compatible input
|
||||
- [`BasicJsonType::accept`](../basic_json/accept.md) - the corresponding function of `basic_json`
|
||||
- [Zero-copy JSON views](../../features/json_view.md#what-is-the-same-as-parse) - how parsing a document differs from, and matches, basic_json::parse
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -7,7 +7,7 @@ static bool accept(InputType&& input,
|
||||
const bool ignore_trailing_commas = false);
|
||||
```
|
||||
|
||||
Checks whether the input is valid JSON, accepting and rejecting exactly what [`BasicJsonType::accept()`](https://json.nlohmann.me/api/basic_json/accept/index.md) does, with the same options. Unlike [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md), this function never throws an exception for invalid input, and the returned `bool` is the only result -- no document is returned.
|
||||
Checks whether the input is valid JSON, accepting and rejecting exactly what [`BasicJsonType::accept()`](https://json.nlohmann.me/api/basic_json/accept/index.md) does, with the same options. Unlike [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md), this function never throws an exception for invalid input, and the returned `bool` is the only result — no document is returned.
|
||||
|
||||
The result is the same as that of `BasicJsonType::accept()` by design; the difference is how the check is made. This function runs the document's index builder (and discards the index), while `BasicJsonType::accept()` runs the SAX parser with a handler that ignores every event. Use this one if you go on to parse the same input with [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) anyway, so that both use the same code; either is fine for a plain yes/no answer.
|
||||
|
||||
@@ -76,8 +76,9 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [`BasicJsonType::accept`](https://json.nlohmann.me/api/basic_json/accept/index.md) - the corresponding function of `basic_json`
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#what-is-the-same-as-parse) - how parsing a document differs from, and matches, basic_json::parse
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -75,8 +75,9 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](parse.md) - deserialize from a compatible input
|
||||
- [is_discarded](is_discarded.md) - return whether the last parse failed
|
||||
- [`parse`](parse.md) - deserialize from a compatible input
|
||||
- [`is_discarded`](is_discarded.md) - return whether the last parse failed
|
||||
- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -68,8 +68,9 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [is_discarded](https://json.nlohmann.me/api/basic_json_document/is_discarded/index.md) - return whether the last parse failed
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [`is_discarded`](https://json.nlohmann.me/api/basic_json_document/is_discarded/index.md) - return whether the last parse failed
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -54,7 +54,7 @@ has `erase`; calling it on a read-only `basic_json_document` fails to compile (`
|
||||
|
||||
## Exceptions
|
||||
|
||||
1. Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if `object` is not an object -- the
|
||||
1. Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if `object` is not an object — the
|
||||
same message [`BasicJsonType::erase`](../basic_json/erase.md) throws for the same type.
|
||||
2. Throws `type_error.307` if `array` is not an array. Throws
|
||||
[`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if `idx` is negative, or if
|
||||
@@ -86,12 +86,12 @@ always starts from this document's own [`root()`](root.md).
|
||||
|
||||
!!! info "Duplicate keys"
|
||||
|
||||
Overload 1. removes *every* member with `key`, not just the first -- unlike [`set`](set.md), which assigns the
|
||||
Overload 1. removes *every* member with `key`, not just the first — unlike [`set`](set.md), which assigns the
|
||||
first occurrence and drops the rest. This is why it returns a count rather than a single view: there may be
|
||||
more than one member removed, or none.
|
||||
|
||||
Like [`set`](set.md) and [`push_back`](push_back.md), `erase` never moves an element's *value*: a view still
|
||||
referring to a removed member or element keeps showing what it last held (see [Edits](index.md#edits)) -- it just no
|
||||
referring to a removed member or element keeps showing what it last held (see [Edits](index.md#edits)) — it just no
|
||||
longer appears when `array`/`object` is read, dumped, or iterated. What does change is the container's sequence of
|
||||
*links* to its elements: removing an element of `array` (2.) shifts the links to the elements after it by one, as
|
||||
[`insert`](insert.md) does in the other direction. *Every* iterator already taken over `array`/`object` is invalidated
|
||||
@@ -101,8 +101,8 @@ by an erase, not only those at or after the removed element, since the container
|
||||
|
||||
??? example
|
||||
|
||||
The example below drops a deprecated field and a decommissioned entry from a configuration document -- using all
|
||||
three overloads -- and shows what stays intact that would not with a plain `json`/`ordered_json` value: the order
|
||||
The example below drops a deprecated field and a decommissioned entry from a configuration document — using all
|
||||
three overloads — and shows what stays intact that would not with a plain `json`/`ordered_json` value: the order
|
||||
of the fields around the ones removed, and the exact spelling of a number that was never touched.
|
||||
|
||||
```cpp
|
||||
@@ -173,12 +173,13 @@ by an erase, not only those at or after the removed element, since the container
|
||||
|
||||
## See also
|
||||
|
||||
- [insert](insert.md) - insert an element into an array
|
||||
- [set](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [push_back](push_back.md) - append to an array
|
||||
- [root](root.md) - the view of the root value, the starting point of overload 3
|
||||
- [`insert`](insert.md) - insert an element into an array
|
||||
- [`set`](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`push_back`](push_back.md) - append to an array
|
||||
- [`root`](root.md) - the view of the root value, the starting point of overload 3
|
||||
- [`BasicJsonType::erase`](../basic_json/erase.md) - the corresponding function of `basic_json`
|
||||
- [Edits](index.md#edits) - what an edit guarantees, for every overload
|
||||
- [Zero-copy JSON views](../../features/json_view.md#editing-a-document) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -42,7 +42,7 @@ Only an **editable** document (`view_mode::editable`, e.g. [`json_editable_docum
|
||||
|
||||
## Exceptions
|
||||
|
||||
1. Throws [`type_error.307`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error307) if `object` is not an object -- the same message [`BasicJsonType::erase`](https://json.nlohmann.me/api/basic_json/erase/index.md) throws for the same type.
|
||||
1. Throws [`type_error.307`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error307) if `object` is not an object — the same message [`BasicJsonType::erase`](https://json.nlohmann.me/api/basic_json/erase/index.md) throws for the same type.
|
||||
1. Throws `type_error.307` if `array` is not an array. Throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if `idx` is negative, or if `idx >= array.size()`.
|
||||
1. Throws [`out_of_range.405`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range405) ("JSON pointer has no parent") if `ptr` is empty. Throws what [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md) throws (overload 3) for resolving `ptr`'s parent. For the last reference token itself: if the parent is an array, throws what 2. throws for an index that is out of range, or, for a token that is not a valid array index, [`parse_error.106`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error106) (a leading `'0'`), [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) (not a number), [`out_of_range.410`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range410) (too large for `size_type`), or [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) (an empty token); otherwise (an object, or a primitive value the pointer's parent resolves to) throws what 1. throws.
|
||||
|
||||
@@ -58,15 +58,15 @@ Overloads 1. and 2. also throw [`invalid_iterator.202`](https://json.nlohmann.me
|
||||
|
||||
Duplicate keys
|
||||
|
||||
Overload 1. removes *every* member with `key`, not just the first -- unlike [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md), which assigns the first occurrence and drops the rest. This is why it returns a count rather than a single view: there may be more than one member removed, or none.
|
||||
Overload 1. removes *every* member with `key`, not just the first — unlike [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md), which assigns the first occurrence and drops the rest. This is why it returns a count rather than a single view: there may be more than one member removed, or none.
|
||||
|
||||
Like [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) and [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md), `erase` never moves an element's *value*: a view still referring to a removed member or element keeps showing what it last held (see [Edits](https://json.nlohmann.me/api/basic_json_document/#edits)) -- it just no longer appears when `array`/`object` is read, dumped, or iterated. What does change is the container's sequence of *links* to its elements: removing an element of `array` (2.) shifts the links to the elements after it by one, as [`insert`](https://json.nlohmann.me/api/basic_json_document/insert/index.md) does in the other direction. *Every* iterator already taken over `array`/`object` is invalidated by an erase, not only those at or after the removed element, since the container may now use a different sequence.
|
||||
Like [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) and [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md), `erase` never moves an element's *value*: a view still referring to a removed member or element keeps showing what it last held (see [Edits](https://json.nlohmann.me/api/basic_json_document/#edits)) — it just no longer appears when `array`/`object` is read, dumped, or iterated. What does change is the container's sequence of *links* to its elements: removing an element of `array` (2.) shifts the links to the elements after it by one, as [`insert`](https://json.nlohmann.me/api/basic_json_document/insert/index.md) does in the other direction. *Every* iterator already taken over `array`/`object` is invalidated by an erase, not only those at or after the removed element, since the container may now use a different sequence.
|
||||
|
||||
## Examples
|
||||
|
||||
Example
|
||||
|
||||
The example below drops a deprecated field and a decommissioned entry from a configuration document -- using all three overloads -- and shows what stays intact that would not with a plain `json`/`ordered_json` value: the order of the fields around the ones removed, and the exact spelling of a number that was never touched.
|
||||
The example below drops a deprecated field and a decommissioned entry from a configuration document — using all three overloads — and shows what stays intact that would not with a plain `json`/`ordered_json` value: the order of the fields around the ones removed, and the exact spelling of a number that was never touched.
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
@@ -134,12 +134,13 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [insert](https://json.nlohmann.me/api/basic_json_document/insert/index.md) - insert an element into an array
|
||||
- [set](https://json.nlohmann.me/api/basic_json_document/set/index.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [push_back](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) - append to an array
|
||||
- [root](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value, the starting point of overload 3
|
||||
- [`insert`](https://json.nlohmann.me/api/basic_json_document/insert/index.md) - insert an element into an array
|
||||
- [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) - append to an array
|
||||
- [`root`](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value, the starting point of overload 3
|
||||
- [`BasicJsonType::erase`](https://json.nlohmann.me/api/basic_json/erase/index.md) - the corresponding function of `basic_json`
|
||||
- [Edits](https://json.nlohmann.me/api/basic_json_document/#edits) - what an edit guarantees, for every overload
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#editing-a-document) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -72,15 +72,15 @@ An editable document (`view_mode::editable`) can be changed after parsing, with
|
||||
- **The source text is never written**, and the parsed index never moves: every value keeps the node it was parsed into, so [views](https://json.nlohmann.me/api/basic_json_view/index.md) taken before an edit stay valid, including [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md). New values (and the element sequences of an edited array/object) go to storage owned by the document, allocated on demand.
|
||||
- **A view keeps referring to the same value.** After [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) replaces the value a view refers to, that view sees the new value; a view of a value that a later edit replaces or drops keeps showing what it last held. An edit of an array or object, however, **invalidates the iterators taken over it** (its members may now live in a different sequence), and a string obtained with [`get_string()`](https://json.nlohmann.me/api/basic_json_view/get_string/index.md) stays valid even as further edits happen (earlier buffers of edited text are kept alive, not overwritten).
|
||||
- **Values are accepted three ways:** a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) of *any* document (read-only or editable; it is copied, nothing is shared with the source document), a `BasicJsonType` value, or anything `BasicJsonType` can be constructed from (numbers, strings, `bool`, `nullptr`, containers, ...).
|
||||
- [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) writes an edited document with members in document order, new members at the end, and, with [`number_format::source`](https://json.nlohmann.me/api/basic_json_view/number_format/index.md), keeps the spelling of every number that was not itself edited -- see [Editing a document](https://json.nlohmann.me/features/json_view/#editing-a-document) for why this matters.
|
||||
- [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) writes an edited document with members in document order, new members at the end, and, with [`number_format::source`](https://json.nlohmann.me/api/basic_json_view/number_format/index.md), keeps the spelling of every number that was not itself edited — see [Editing a document](https://json.nlohmann.me/features/json_view/#editing-a-document) for why this matters.
|
||||
- [`read()`](https://json.nlohmann.me/api/basic_json_document/read/index.md) discards all edits, [`shrink_to_fit()`](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md) does not move the node index once there are edits, and [`memory_usage()`](https://json.nlohmann.me/api/basic_json_document/memory_usage/index.md) includes the memory edits use. [`source_offset()`](https://json.nlohmann.me/api/basic_json_view/source_offset/index.md) of a value introduced by an edit is `static_cast<std::size_t>(-1)`, the same value it reports for a decoded string.
|
||||
|
||||
## See also
|
||||
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) - guide to documents and views
|
||||
- [**basic_json_view**](https://json.nlohmann.me/api/basic_json_view/index.md) - the non-owning handle to a value in a document
|
||||
- [**json_document**](https://json.nlohmann.me/api/json_document/index.md) and [**json_editable_document**](https://json.nlohmann.me/api/json_editable_document/index.md) - the default specializations
|
||||
- [**materialize**](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) - build a `basic_json` value from a view
|
||||
- [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) - the non-owning handle to a value in a document
|
||||
- [`json_document`](https://json.nlohmann.me/api/json_document/index.md) - and [`json_editable_document`](https://json.nlohmann.me/api/json_editable_document/index.md) - the default specializations
|
||||
- [`materialize`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) - build a `basic_json` value from a view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -13,8 +13,8 @@ Inserts `value` into `array` as a new element before position `idx`, which must
|
||||
[`push_back`](push_back.md), a [null](../basic_json_view/is_null.md) `array` does *not* first become an empty array:
|
||||
`array` must already be an array.
|
||||
|
||||
`value` is accepted three ways: a [`basic_json_view`](../basic_json_view/index.md) 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
|
||||
`value` is accepted three ways: a [`basic_json_view`](../basic_json_view/index.md) 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, ...).
|
||||
|
||||
@@ -44,16 +44,16 @@ 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
|
||||
Basic exception safety: `value` is fully encoded — including the checks below — into storage owned by the document
|
||||
before anything already reachable from [`root()`](root.md) 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](#notes) -- can still leave `array` already
|
||||
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](#notes) — can still leave `array` already
|
||||
switched to that layout even though `value` itself was not inserted.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if `array` is not an array -- the same
|
||||
Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if `array` is not an array — the same
|
||||
message [`BasicJsonType::insert`](../basic_json/insert.md) throws for the same type; a null `array` throws this too
|
||||
(see above). Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if `idx` is negative,
|
||||
or if `#!cpp idx > array.size()`. Throws
|
||||
@@ -62,7 +62,7 @@ document") if `array` is a [discarded](../basic_json_view/is_discarded.md) view
|
||||
Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `value` is a
|
||||
[discarded](../basic_json_view/is_discarded.md) view or a [discarded](../basic_json/is_discarded.md) `BasicJsonType`
|
||||
value, and [`type_error.319`](../../home/exceptions.md#jsonexceptiontype_error319) if `value` is (or contains) a
|
||||
binary value -- `BasicJsonType` can hold one, but a `json_document` cannot. Throws
|
||||
binary value — `BasicJsonType` can hold one, but a `json_document` cannot. Throws
|
||||
[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if `value` is (or contains) a string that is
|
||||
not valid UTF-8, with the same message [`BasicJsonType::dump()`](../basic_json/dump.md) gives for that string.
|
||||
|
||||
@@ -76,8 +76,8 @@ grows in amortized constant time; inserting before the end within that block sti
|
||||
|
||||
## Notes
|
||||
|
||||
Like [`set`](set.md) 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
|
||||
Like [`set`](set.md) 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](index.md#edits) for what stays valid across
|
||||
an edit in general.
|
||||
@@ -88,7 +88,7 @@ an edit in general.
|
||||
|
||||
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
|
||||
index shifts — something a plain `json`/`ordered_json` array, or its `std::vector`-based storage, has no
|
||||
equivalent for.
|
||||
|
||||
```cpp
|
||||
@@ -164,11 +164,12 @@ an edit in general.
|
||||
|
||||
## See also
|
||||
|
||||
- [push_back](push_back.md) - append to an array
|
||||
- [erase](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [set](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`push_back`](push_back.md) - append to an array
|
||||
- [`erase`](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`set`](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`BasicJsonType::insert`](../basic_json/insert.md) - the corresponding function of `basic_json`
|
||||
- [Edits](index.md#edits) - what an edit guarantees, for every overload
|
||||
- [Zero-copy JSON views](../../features/json_view.md#editing-a-document) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -9,7 +9,7 @@ Only an **editable** document (`view_mode::editable`, e.g. [`json_editable_docum
|
||||
|
||||
Inserts `value` into `array` as a new element before position `idx`, which must not be past the end (`idx <= array.size()`; `idx == array.size()` appends, like [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md)). Unlike [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md), a [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) `array` does *not* first become an empty array: `array` must already be an array.
|
||||
|
||||
`value` is accepted three ways: a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) 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, `bool`, `nullptr`, containers, ...).
|
||||
`value` is accepted three ways: a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) 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, `bool`, `nullptr`, containers, ...).
|
||||
|
||||
## Template parameters
|
||||
|
||||
@@ -31,11 +31,11 @@ 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()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) is touched, so a failure while encoding `value` (an invalid argument, or `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](#notes) -- can still leave `array` already switched to that layout even though `value` itself was not inserted.
|
||||
Basic exception safety: `value` is fully encoded — including the checks below — into storage owned by the document before anything already reachable from [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) is touched, so a failure while encoding `value` (an invalid argument, or `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](#notes) — can still leave `array` already switched to that layout even though `value` itself was not inserted.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [`type_error.309`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error309) if `array` is not an array -- the same message [`BasicJsonType::insert`](https://json.nlohmann.me/api/basic_json/insert/index.md) throws for the same type; a null `array` throws this too (see above). Throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if `idx` is negative, or if `idx > array.size()`. Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) ("view does not belong to this document") if `array` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a view of a *different* document. Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if `value` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) `BasicJsonType` value, and [`type_error.319`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error319) if `value` is (or contains) a binary value -- `BasicJsonType` can hold one, but a `json_document` cannot. Throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `value` is (or contains) a string that is not valid UTF-8, with the same message [`BasicJsonType::dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) gives for that string.
|
||||
Throws [`type_error.309`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error309) if `array` is not an array — the same message [`BasicJsonType::insert`](https://json.nlohmann.me/api/basic_json/insert/index.md) throws for the same type; a null `array` throws this too (see above). Throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if `idx` is negative, or if `idx > array.size()`. Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) ("view does not belong to this document") if `array` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a view of a *different* document. Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if `value` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) `BasicJsonType` value, and [`type_error.319`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error319) if `value` is (or contains) a binary value — `BasicJsonType` can hold one, but a `json_document` cannot. Throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `value` is (or contains) a string that is not valid UTF-8, with the same message [`BasicJsonType::dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) gives for that string.
|
||||
|
||||
## Complexity
|
||||
|
||||
@@ -43,13 +43,13 @@ Linear in the number of elements of `array` at or after `idx` (they move one slo
|
||||
|
||||
## Notes
|
||||
|
||||
Like [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) 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](https://json.nlohmann.me/api/basic_json_document/#edits) for what stays valid across an edit in general.
|
||||
Like [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) 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](https://json.nlohmann.me/api/basic_json_document/#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.
|
||||
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.
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
@@ -122,11 +122,12 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [push_back](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) - append to an array
|
||||
- [erase](https://json.nlohmann.me/api/basic_json_document/erase/index.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [set](https://json.nlohmann.me/api/basic_json_document/set/index.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) - append to an array
|
||||
- [`erase`](https://json.nlohmann.me/api/basic_json_document/erase/index.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`BasicJsonType::insert`](https://json.nlohmann.me/api/basic_json/insert/index.md) - the corresponding function of `basic_json`
|
||||
- [Edits](https://json.nlohmann.me/api/basic_json_document/#edits) - what an edit guarantees, for every overload
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#editing-a-document) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -63,8 +63,9 @@ When the document is discarded, [`root()`](root.md) returns a discarded view (it
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](parse.md) - deserialize from a compatible input
|
||||
- [is_discarded (basic_json_view)](../basic_json_view/is_discarded.md) - return whether a view is invalid
|
||||
- [`parse`](parse.md) - deserialize from a compatible input
|
||||
- [`basic_json_view::is_discarded`](../basic_json_view/is_discarded.md) - return whether a view is invalid
|
||||
- [Zero-copy JSON views](../../features/json_view.md#what-is-the-same-as-parse) - how a discarded document arises
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -58,8 +58,9 @@ false
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [is_discarded (basic_json_view)](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) - return whether a view is invalid
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [`basic_json_view::is_discarded`](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) - return whether a view is invalid
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#what-is-the-same-as-parse) - how a discarded document arises
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -16,14 +16,14 @@ static basic_json_document load(std::vector<std::uint8_t>&& image,
|
||||
|
||||
1. Reads an image [`save()`](save.md) wrote, from a pointer and a byte count. The image is **borrowed**: `image`
|
||||
must stay alive and unchanged for as long as the returned document, and any view taken from it, is used.
|
||||
2. Reads an image from a `#!cpp std::vector`. Also **borrowed** -- equivalent to overload 1 called with
|
||||
2. Reads an image from a `#!cpp std::vector`. Also **borrowed** — equivalent to overload 1 called with
|
||||
`#!cpp image.data()` and `#!cpp image.size()`.
|
||||
3. Reads an image, keeping the vector instead of copying it: `image` is moved into the document (no copy), which
|
||||
then owns it for as long as it needs the text and the decoded strings. [`owns_source()`](owns_source.md) is
|
||||
`#!cpp true` afterward.
|
||||
|
||||
In every overload, the node index is copied into storage the document itself owns -- so that it is properly aligned,
|
||||
and, for an [editable](index.md#edits) document, can be edited -- while the text and the decoded strings stay in
|
||||
In every overload, the node index is copied into storage the document itself owns — so that it is properly aligned,
|
||||
and, for an [editable](index.md#edits) document, can be edited — while the text and the decoded strings stay in
|
||||
`image`. The hash indexes [large objects](../../features/json_view.md) use for lookup are rebuilt, exactly as after
|
||||
parsing.
|
||||
|
||||
@@ -49,7 +49,7 @@ Overloads 1 and 2 give the strong guarantee: `image` is only read, never written
|
||||
caller's buffer untouched.
|
||||
|
||||
Overload 3 moves `image` into the document *before* validating it, so that a good image is kept without a copy. If
|
||||
loading then fails, the partially built document -- and the vector now inside it -- is discarded along with the
|
||||
loading then fails, the partially built document — and the vector now inside it — is discarded along with the
|
||||
exception, and `image` itself is left **empty**, not restored to what was passed in. Move a copy in instead, or
|
||||
validate with overload 2 first, if the original vector must survive a failed load.
|
||||
|
||||
@@ -63,7 +63,7 @@ Throws [`parse_error.116`](../../home/exceptions.md#jsonexceptionparse_error116)
|
||||
| `too short` | `image` is `#!cpp nullptr`, or `size` is smaller than the 64-byte header |
|
||||
| `unknown format` | the header's magic bytes or version do not match, or a reserved header field is not zero |
|
||||
| `sizes out of range` | the node count, text size, or decoded-string size the header describes does not fit `size`, or the `#!cpp '\0'` after the text or after the decoded strings is missing |
|
||||
| `the check failed` | `check` is not `#!cpp image_check::none`, and the image fails it -- see [`image_check`](#image_check) |
|
||||
| `the check failed` | `check` is not `#!cpp image_check::none`, and the image fails it — see [`image_check`](#image_check) |
|
||||
|
||||
!!! failure "Example messages"
|
||||
|
||||
@@ -116,7 +116,7 @@ How thoroughly `load()` validates `image` before trusting it.
|
||||
token is well-formed and matches the value stored for it. Strings and float tokens may share a range only if the
|
||||
ranges are identical (as nodes that share a value do), and never overlap otherwise. Reading and serializing a
|
||||
checked image is safe and always produces valid JSON, exactly as for a parsed document. This is the right choice for
|
||||
an image from anything you do not fully control -- a file, a cache shared with other processes, a peer on the
|
||||
an image from anything you do not fully control — a file, a cache shared with other processes, a peer on the
|
||||
network.
|
||||
|
||||
`bounds`
|
||||
@@ -136,7 +136,7 @@ How thoroughly `load()` validates `image` before trusting it.
|
||||
your own memory.
|
||||
|
||||
**Lifetime.** Overloads 1 and 2 borrow `image`: it must stay alive and byte-for-byte unchanged for as long as the
|
||||
returned document, and any [view](../basic_json_view/index.md) taken from it, is used -- exactly like a document
|
||||
returned document, and any [view](../basic_json_view/index.md) taken from it, is used — exactly like a document
|
||||
[`parse()`](parse.md) borrowed its input for. Overload 3 avoids this by keeping the vector itself; see
|
||||
[`owns_source`](owns_source.md).
|
||||
|
||||
@@ -145,7 +145,7 @@ returned document, and any [view](../basic_json_view/index.md) taken from it, is
|
||||
The image format is versioned but not yet stable, and may change in an incompatible way before it is declared
|
||||
stable; `load()` already rejects an image written by a different format version with `parse_error.116`
|
||||
("unknown format"). Use images to cache a document within one build of the library, or to hand one to another
|
||||
process running the *same* build on the *same* (little-endian) machine -- not as a long-term storage format.
|
||||
process running the *same* build on the *same* (little-endian) machine — not as a long-term storage format.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -154,8 +154,8 @@ returned document, and any [view](../basic_json_view/index.md) taken from it, is
|
||||
The example below saves a parsed document as an image, checks that `load()` reproduces the original
|
||||
[`dump()`](../basic_json_view/dump.md) without parsing, and shows the difference between
|
||||
`load(std::move(image))` (owned) and `load(image)` (borrowed). It then damages one byte of the image and shows
|
||||
`image_check::full` rejecting it with `parse_error.116`, while `image_check::bounds` -- meant for a cache the
|
||||
process already trusts -- still reads it without going out of bounds.
|
||||
`image_check::full` rejecting it with `parse_error.116`, while `image_check::bounds` — meant for a cache the
|
||||
process already trusts — still reads it without going out of bounds.
|
||||
|
||||
```cpp
|
||||
#include <cstdint>
|
||||
@@ -226,9 +226,9 @@ returned document, and any [view](../basic_json_view/index.md) taken from it, is
|
||||
|
||||
## See also
|
||||
|
||||
- [save](save.md) - write the document as an image
|
||||
- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [parse](parse.md) - deserialize from JSON text instead of an image
|
||||
- [`save`](save.md) - write the document as an image
|
||||
- [`owns_source`](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [`parse`](parse.md) - deserialize from JSON text instead of an image
|
||||
- [Images](../../features/json_view.md#images) - why and when to use images
|
||||
|
||||
## Version history
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -15,10 +15,10 @@ static basic_json_document load(std::vector<std::uint8_t>&& image,
|
||||
```
|
||||
|
||||
1. Reads an image [`save()`](https://json.nlohmann.me/api/basic_json_document/save/index.md) wrote, from a pointer and a byte count. The image is **borrowed**: `image` must stay alive and unchanged for as long as the returned document, and any view taken from it, is used.
|
||||
1. Reads an image from a `std::vector`. Also **borrowed** -- equivalent to overload 1 called with `image.data()` and `image.size()`.
|
||||
1. Reads an image from a `std::vector`. Also **borrowed** — equivalent to overload 1 called with `image.data()` and `image.size()`.
|
||||
1. Reads an image, keeping the vector instead of copying it: `image` is moved into the document (no copy), which then owns it for as long as it needs the text and the decoded strings. [`owns_source()`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) is `true` afterward.
|
||||
|
||||
In every overload, the node index is copied into storage the document itself owns -- so that it is properly aligned, and, for an [editable](https://json.nlohmann.me/api/basic_json_document/#edits) document, can be edited -- while the text and the decoded strings stay in `image`. The hash indexes [large objects](https://json.nlohmann.me/features/json_view/index.md) use for lookup are rebuilt, exactly as after parsing.
|
||||
In every overload, the node index is copied into storage the document itself owns — so that it is properly aligned, and, for an [editable](https://json.nlohmann.me/api/basic_json_document/#edits) document, can be edited — while the text and the decoded strings stay in `image`. The hash indexes [large objects](https://json.nlohmann.me/features/json_view/index.md) use for lookup are rebuilt, exactly as after parsing.
|
||||
|
||||
## Parameters
|
||||
|
||||
@@ -36,7 +36,7 @@ The document read from the image.
|
||||
|
||||
Overloads 1 and 2 give the strong guarantee: `image` is only read, never written, so a thrown exception leaves the caller's buffer untouched.
|
||||
|
||||
Overload 3 moves `image` into the document *before* validating it, so that a good image is kept without a copy. If loading then fails, the partially built document -- and the vector now inside it -- is discarded along with the exception, and `image` itself is left **empty**, not restored to what was passed in. Move a copy in instead, or validate with overload 2 first, if the original vector must survive a failed load.
|
||||
Overload 3 moves `image` into the document *before* validating it, so that a good image is kept without a copy. If loading then fails, the partially built document — and the vector now inside it — is discarded along with the exception, and `image` itself is left **empty**, not restored to what was passed in. Move a copy in instead, or validate with overload 2 first, if the original vector must survive a failed load.
|
||||
|
||||
## Exceptions
|
||||
|
||||
@@ -47,7 +47,7 @@ Throws [`parse_error.116`](https://json.nlohmann.me/home/exceptions/#jsonexcepti
|
||||
| `too short` | `image` is `nullptr`, or `size` is smaller than the 64-byte header |
|
||||
| `unknown format` | the header's magic bytes or version do not match, or a reserved header field is not zero |
|
||||
| `sizes out of range` | the node count, text size, or decoded-string size the header describes does not fit `size`, or the `'\0'` after the text or after the decoded strings is missing |
|
||||
| `the check failed` | `check` is not `image_check::none`, and the image fails it -- see [`image_check`](#image_check) |
|
||||
| `the check failed` | `check` is not `image_check::none`, and the image fails it — see [`image_check`](#image_check) |
|
||||
|
||||
Example messages
|
||||
|
||||
@@ -92,23 +92,23 @@ enum class image_check
|
||||
|
||||
How thoroughly `load()` validates `image` before trusting it.
|
||||
|
||||
`full` (the default) : Checks everything the parser itself guarantees: structure and bounds; that every string is valid UTF-8 (and, for a string still in the source text, that it contains no quote, backslash, or control character); and that every number token is well-formed and matches the value stored for it. Strings and float tokens may share a range only if the ranges are identical (as nodes that share a value do), and never overlap otherwise. Reading and serializing a checked image is safe and always produces valid JSON, exactly as for a parsed document. This is the right choice for an image from anything you do not fully control -- a file, a cache shared with other processes, a peer on the network.
|
||||
`full` (the default) : Checks everything the parser itself guarantees: structure and bounds; that every string is valid UTF-8 (and, for a string still in the source text, that it contains no quote, backslash, or control character); and that every number token is well-formed and matches the value stored for it. Strings and float tokens may share a range only if the ranges are identical (as nodes that share a value do), and never overlap otherwise. Reading and serializing a checked image is safe and always produces valid JSON, exactly as for a parsed document. This is the right choice for an image from anything you do not fully control — a file, a cache shared with other processes, a peer on the network.
|
||||
|
||||
`bounds` : Checks structure and bounds only: that every offset and count in the node index stays inside the image. So `load()`, [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md), element access, and [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) can never read outside the image, even on a damaged one. It does *not* guarantee that the image describes valid JSON: a string that a `full` check would have rejected can make [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) write invalid UTF-8 or invalid JSON, or throw [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316), and a number can read back with a value that does not match how it is spelled. An [editable document](https://json.nlohmann.me/api/json_editable_document/index.md) does not take such a string over: [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md), [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) and [`insert`](https://json.nlohmann.me/api/basic_json_document/insert/index.md) throw `type_error.316` when they copy it from a view of the loaded document, and leave the editable document unchanged. `bounds` skips scanning the text and the decoded strings, so it fits a cache your own process just wrote and reads straight back, where damage would mean a bug or a hardware fault rather than adversarial input.
|
||||
|
||||
`none` : Checks nothing. Reading a damaged image is undefined behavior, so use it only for an image you trust as much as your own memory.
|
||||
|
||||
**Lifetime.** Overloads 1 and 2 borrow `image`: it must stay alive and byte-for-byte unchanged for as long as the returned document, and any [view](https://json.nlohmann.me/api/basic_json_view/index.md) taken from it, is used -- exactly like a document [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) borrowed its input for. Overload 3 avoids this by keeping the vector itself; see [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md).
|
||||
**Lifetime.** Overloads 1 and 2 borrow `image`: it must stay alive and byte-for-byte unchanged for as long as the returned document, and any [view](https://json.nlohmann.me/api/basic_json_view/index.md) taken from it, is used — exactly like a document [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) borrowed its input for. Overload 3 avoids this by keeping the vector itself; see [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md).
|
||||
|
||||
Experimental
|
||||
|
||||
The image format is versioned but not yet stable, and may change in an incompatible way before it is declared stable; `load()` already rejects an image written by a different format version with `parse_error.116` ("unknown format"). Use images to cache a document within one build of the library, or to hand one to another process running the *same* build on the *same* (little-endian) machine -- not as a long-term storage format.
|
||||
The image format is versioned but not yet stable, and may change in an incompatible way before it is declared stable; `load()` already rejects an image written by a different format version with `parse_error.116` ("unknown format"). Use images to cache a document within one build of the library, or to hand one to another process running the *same* build on the *same* (little-endian) machine — not as a long-term storage format.
|
||||
|
||||
## Examples
|
||||
|
||||
Caching a document, ownership, and a rejected image
|
||||
|
||||
The example below saves a parsed document as an image, checks that `load()` reproduces the original [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) without parsing, and shows the difference between `load(std::move(image))` (owned) and `load(image)` (borrowed). It then damages one byte of the image and shows `image_check::full` rejecting it with `parse_error.116`, while `image_check::bounds` -- meant for a cache the process already trusts -- still reads it without going out of bounds.
|
||||
The example below saves a parsed document as an image, checks that `load()` reproduces the original [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) without parsing, and shows the difference between `load(std::move(image))` (owned) and `load(image)` (borrowed). It then damages one byte of the image and shows `image_check::full` rejecting it with `parse_error.116`, while `image_check::bounds` — meant for a cache the process already trusts — still reads it without going out of bounds.
|
||||
|
||||
```
|
||||
#include <cstdint>
|
||||
@@ -177,9 +177,9 @@ cache
|
||||
|
||||
## See also
|
||||
|
||||
- [save](https://json.nlohmann.me/api/basic_json_document/save/index.md) - write the document as an image
|
||||
- [owns_source](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [parse](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from JSON text instead of an image
|
||||
- [`save`](https://json.nlohmann.me/api/basic_json_document/save/index.md) - write the document as an image
|
||||
- [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from JSON text instead of an image
|
||||
- [Images](https://json.nlohmann.me/features/json_view/#images) - why and when to use images
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -23,7 +23,7 @@ Constant.
|
||||
|
||||
The exact value depends on the platform, the allocator, and the library's own layout, and may change between
|
||||
versions; do not rely on it being a specific number, and do not compare it across different builds or platforms.
|
||||
Compare it for the same document over time, or between documents built with the same binary, instead -- for instance
|
||||
Compare it for the same document over time, or between documents built with the same binary, instead — for instance
|
||||
to observe the effect of [`shrink_to_fit()`](shrink_to_fit.md).
|
||||
|
||||
## Examples
|
||||
@@ -72,8 +72,9 @@ to observe the effect of [`shrink_to_fit()`](shrink_to_fit.md).
|
||||
|
||||
## See also
|
||||
|
||||
- [node_count](node_count.md) - the number of index entries
|
||||
- [shrink_to_fit](shrink_to_fit.md) - release unused index capacity
|
||||
- [`node_count`](node_count.md) - the number of index entries
|
||||
- [`shrink_to_fit`](shrink_to_fit.md) - release unused index capacity
|
||||
- [Zero-copy JSON views](../../features/json_view.md#the-idea) - the flat node index and its memory
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -20,7 +20,7 @@ Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
The exact value depends on the platform, the allocator, and the library's own layout, and may change between versions; do not rely on it being a specific number, and do not compare it across different builds or platforms. Compare it for the same document over time, or between documents built with the same binary, instead -- for instance to observe the effect of [`shrink_to_fit()`](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md).
|
||||
The exact value depends on the platform, the allocator, and the library's own layout, and may change between versions; do not rely on it being a specific number, and do not compare it across different builds or platforms. Compare it for the same document over time, or between documents built with the same binary, instead — for instance to observe the effect of [`shrink_to_fit()`](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -66,8 +66,9 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [node_count](https://json.nlohmann.me/api/basic_json_document/node_count/index.md) - the number of index entries
|
||||
- [shrink_to_fit](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md) - release unused index capacity
|
||||
- [`node_count`](https://json.nlohmann.me/api/basic_json_document/node_count/index.md) - the number of index entries
|
||||
- [`shrink_to_fit`](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md) - release unused index capacity
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#the-idea) - the flat node index and its memory
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -58,8 +58,9 @@ strings and, for an owned document, the text).
|
||||
|
||||
## See also
|
||||
|
||||
- [memory_usage](memory_usage.md) - the number of bytes held by the document
|
||||
- [shrink_to_fit](shrink_to_fit.md) - release unused index capacity
|
||||
- [`memory_usage`](memory_usage.md) - the number of bytes held by the document
|
||||
- [`shrink_to_fit`](shrink_to_fit.md) - release unused index capacity
|
||||
- [Zero-copy JSON views](../../features/json_view.md#the-idea) - the flat node index and its memory
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -53,8 +53,9 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [memory_usage](https://json.nlohmann.me/api/basic_json_document/memory_usage/index.md) - the number of bytes held by the document
|
||||
- [shrink_to_fit](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md) - release unused index capacity
|
||||
- [`memory_usage`](https://json.nlohmann.me/api/basic_json_document/memory_usage/index.md) - the number of bytes held by the document
|
||||
- [`shrink_to_fit`](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md) - release unused index capacity
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#the-idea) - the flat node index and its memory
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -67,9 +67,10 @@ document (`#!cpp owns_source() == false`) is only valid while the buffer it was
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](parse.md) - deserialize from a compatible input
|
||||
- [parse_copy](parse_copy.md) - deserialize a copy of a compatible input, always owned
|
||||
- [source](source.md) - the parsed text
|
||||
- [`parse`](parse.md) - deserialize from a compatible input
|
||||
- [`parse_copy`](parse_copy.md) - deserialize a copy of a compatible input, always owned
|
||||
- [`source`](source.md) - the parsed text
|
||||
- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -63,9 +63,10 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [parse_copy](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) - deserialize a copy of a compatible input, always owned
|
||||
- [source](https://json.nlohmann.me/api/basic_json_document/source/index.md) - the parsed text
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [`parse_copy`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) - deserialize a copy of a compatible input, always owned
|
||||
- [`source`](https://json.nlohmann.me/api/basic_json_document/source/index.md) - the parsed text
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ Both overloads accept the same JSON text as [`BasicJsonType::parse()`](../basic_
|
||||
the input) instead of a tree of `BasicJsonType` values. They accept every input `BasicJsonType::parse()` takes, and in
|
||||
addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of
|
||||
single-byte characters that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, which
|
||||
must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns -- see the
|
||||
must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns — see the
|
||||
Notes. Use [`parse_copy()`](parse_copy.md) to get an owned copy of a borrowable input
|
||||
as well.
|
||||
|
||||
@@ -82,8 +82,8 @@ discarded; see [`is_discarded`](is_discarded.md).
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws the same exception [`BasicJsonType::parse()`](../basic_json/parse.md) throws for the same input and options --
|
||||
the same exception id, message, and position -- because on a failing input the library's own parser is run on the
|
||||
Throws the same exception [`BasicJsonType::parse()`](../basic_json/parse.md) throws for the same input and options —
|
||||
the same exception id, message, and position — because on a failing input the library's own parser is run on the
|
||||
same bytes to produce the diagnostic. This replay runs only for a failing input, and costs about a lexing pass up to
|
||||
the error (its SAX handler builds no values); with `allow_exceptions` set to `#!cpp false`, it is skipped and a
|
||||
discarded document is returned instead. Additionally throws
|
||||
@@ -100,7 +100,7 @@ Linear in the length of the input.
|
||||
|
||||
| `input` | ownership |
|
||||
|--------------------------------------------------------------------------------------|--------------------------------------------------------------|
|
||||
| lvalue byte container (`std::string`, `std::vector<char>`, ...), `std::string_view`, C string, character array | **borrowed** -- `input` must outlive the document |
|
||||
| lvalue byte container (`std::string`, `std::vector<char>`, ...), `std::string_view`, C string, character array | **borrowed** — `input` must outlive the document |
|
||||
| non-const rvalue `#!cpp std::string` | **owned**, moved in without a copy |
|
||||
| other rvalue byte container (including a `#!cpp const` rvalue `#!cpp std::string`) | **owned**, copied |
|
||||
| stream, `#!cpp FILE*`, wide characters, or anything else read through the general input adapter | **owned**, read into a buffer (a stream is read to its end) |
|
||||
@@ -117,8 +117,8 @@ See [`owns_source`](owns_source.md) to check which happened after a call, and th
|
||||
**Numbers.** As for [`BasicJsonType::parse()`](../basic_json/parse.md), an integer literal too large for the 64-bit
|
||||
integer type becomes a floating-point value.
|
||||
|
||||
**No lengths.** An integer argument that is not a `#!cpp bool` where the flags are expected -- for example
|
||||
`#!cpp parse(ptr, len)` -- does not compile (the overload is deleted). Such a call would convert `len` to
|
||||
**No lengths.** An integer argument that is not a `#!cpp bool` where the flags are expected — for example
|
||||
`#!cpp parse(ptr, len)` — does not compile (the overload is deleted). Such a call would convert `len` to
|
||||
`allow_exceptions` and read `ptr` as a null-terminated string, past the end of a buffer that has none. To parse a
|
||||
buffer of a given length, pass a pair of pointers: `#!cpp parse(ptr, ptr + len)`. The same holds for
|
||||
[`parse_copy`](parse_copy.md), [`accept`](accept.md), and [`read`](read.md).
|
||||
@@ -211,11 +211,11 @@ buffer of a given length, pass a pair of pointers: `#!cpp parse(ptr, ptr + len)`
|
||||
|
||||
## See also
|
||||
|
||||
- [parse_copy](parse_copy.md) - deserialize a copy of a compatible input
|
||||
- [accept](accept.md) - check whether the input is valid JSON
|
||||
- [read](read.md) - (re-)parse into this document, reusing its memory
|
||||
- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [load](load.md) - read a document from an image instead of parsing JSON text
|
||||
- [`parse_copy`](parse_copy.md) - deserialize a copy of a compatible input
|
||||
- [`accept`](accept.md) - check whether the input is valid JSON
|
||||
- [`read`](read.md) - (re-)parse into this document, reusing its memory
|
||||
- [`owns_source`](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [`load`](load.md) - read a document from an image instead of parsing JSON text
|
||||
- [`BasicJsonType::parse`](../basic_json/parse.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -19,7 +19,7 @@ static basic_json_document parse(IteratorType first, IteratorType last,
|
||||
1. Deserialize from a compatible input, borrowing or owning it depending on its value category and type (see Notes).
|
||||
1. Deserialize from a pair of input iterators.
|
||||
|
||||
Both overloads accept the same JSON text as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md), with the same `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) (a flat index into the input) instead of a tree of `BasicJsonType` values. They accept every input `BasicJsonType::parse()` takes, and in addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of single-byte characters that stay alive can be borrowed; all others (streams, `FILE*`, wide characters, which must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns -- see the Notes. Use [`parse_copy()`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) to get an owned copy of a borrowable input as well.
|
||||
Both overloads accept the same JSON text as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md), with the same `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) (a flat index into the input) instead of a tree of `BasicJsonType` values. They accept every input `BasicJsonType::parse()` takes, and in addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of single-byte characters that stay alive can be borrowed; all others (streams, `FILE*`, wide characters, which must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns — see the Notes. Use [`parse_copy()`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) to get an owned copy of a borrowable input as well.
|
||||
|
||||
## Template parameters
|
||||
|
||||
@@ -62,7 +62,7 @@ The parsed document. If `allow_exceptions` is `false` and the input is not valid
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws the same exception [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) throws for the same input and options -- the same exception id, message, and position -- because on a failing input the library's own parser is run on the same bytes to produce the diagnostic. This replay runs only for a failing input, and costs about a lexing pass up to the error (its SAX handler builds no values); with `allow_exceptions` set to `false`, it is skipped and a discarded document is returned instead. Additionally throws [`out_of_range.416`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range416) if the input is 4294967280 bytes (4 GiB minus 16 bytes) or larger, a size [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) does not reject.
|
||||
Throws the same exception [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) throws for the same input and options — the same exception id, message, and position — because on a failing input the library's own parser is run on the same bytes to produce the diagnostic. This replay runs only for a failing input, and costs about a lexing pass up to the error (its SAX handler builds no values); with `allow_exceptions` set to `false`, it is skipped and a discarded document is returned instead. Additionally throws [`out_of_range.416`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range416) if the input is 4294967280 bytes (4 GiB minus 16 bytes) or larger, a size [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) does not reject.
|
||||
|
||||
## Complexity
|
||||
|
||||
@@ -74,7 +74,7 @@ Linear in the length of the input.
|
||||
|
||||
| `input` | ownership |
|
||||
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
|
||||
| lvalue byte container (`std::string`, `std::vector<char>`, ...), `std::string_view`, C string, character array | **borrowed** -- `input` must outlive the document |
|
||||
| lvalue byte container (`std::string`, `std::vector<char>`, ...), `std::string_view`, C string, character array | **borrowed** — `input` must outlive the document |
|
||||
| non-const rvalue `std::string` | **owned**, moved in without a copy |
|
||||
| other rvalue byte container (including a `const` rvalue `std::string`) | **owned**, copied |
|
||||
| stream, `FILE*`, wide characters, or anything else read through the general input adapter | **owned**, read into a buffer (a stream is read to its end) |
|
||||
@@ -85,7 +85,7 @@ See [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source
|
||||
|
||||
**Numbers.** As for [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md), an integer literal too large for the 64-bit integer type becomes a floating-point value.
|
||||
|
||||
**No lengths.** An integer argument that is not a `bool` where the flags are expected -- for example `parse(ptr, len)` -- does not compile (the overload is deleted). Such a call would convert `len` to `allow_exceptions` and read `ptr` as a null-terminated string, past the end of a buffer that has none. To parse a buffer of a given length, pass a pair of pointers: `parse(ptr, ptr + len)`. The same holds for [`parse_copy`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md), [`accept`](https://json.nlohmann.me/api/basic_json_document/accept/index.md), and [`read`](https://json.nlohmann.me/api/basic_json_document/read/index.md).
|
||||
**No lengths.** An integer argument that is not a `bool` where the flags are expected — for example `parse(ptr, len)` — does not compile (the overload is deleted). Such a call would convert `len` to `allow_exceptions` and read `ptr` as a null-terminated string, past the end of a buffer that has none. To parse a buffer of a given length, pass a pair of pointers: `parse(ptr, ptr + len)`. The same holds for [`parse_copy`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md), [`accept`](https://json.nlohmann.me/api/basic_json_document/accept/index.md), and [`read`](https://json.nlohmann.me/api/basic_json_document/read/index.md).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -171,11 +171,11 @@ false
|
||||
|
||||
## See also
|
||||
|
||||
- [parse_copy](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) - deserialize a copy of a compatible input
|
||||
- [accept](https://json.nlohmann.me/api/basic_json_document/accept/index.md) - check whether the input is valid JSON
|
||||
- [read](https://json.nlohmann.me/api/basic_json_document/read/index.md) - (re-)parse into this document, reusing its memory
|
||||
- [owns_source](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [load](https://json.nlohmann.me/api/basic_json_document/load/index.md) - read a document from an image instead of parsing JSON text
|
||||
- [`parse_copy`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) - deserialize a copy of a compatible input
|
||||
- [`accept`](https://json.nlohmann.me/api/basic_json_document/accept/index.md) - check whether the input is valid JSON
|
||||
- [`read`](https://json.nlohmann.me/api/basic_json_document/read/index.md) - (re-)parse into this document, reusing its memory
|
||||
- [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) - read a document from an image instead of parsing JSON text
|
||||
- [`BasicJsonType::parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -96,8 +96,9 @@ compile; see [`parse`](parse.md#notes).
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](parse.md) - deserialize from a compatible input, borrowing it where possible
|
||||
- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [`parse`](parse.md) - deserialize from a compatible input, borrowing it where possible
|
||||
- [`owns_source`](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - borrowing or copying the source text
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -82,8 +82,9 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input, borrowing it where possible
|
||||
- [owns_source](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input, borrowing it where possible
|
||||
- [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime) - borrowing or copying the source text
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@ view_type push_back(view_type array, V&& value);
|
||||
Appends `value` as a new last element of `array`. A [null](../basic_json_view/is_null.md) `array` first becomes an
|
||||
empty array, the same way [`set`](set.md) turns a null `object` into an empty object.
|
||||
|
||||
`value` is accepted three ways: a [`basic_json_view`](../basic_json_view/index.md) 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
|
||||
`value` is accepted three ways: a [`basic_json_view`](../basic_json_view/index.md) 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, ...).
|
||||
|
||||
@@ -35,23 +35,23 @@ 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
|
||||
Basic exception safety: `value` is fully encoded — including the checks below — into storage owned by the document
|
||||
before anything already reachable from [`root()`](root.md) 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](#notes) -- can still leave a partial effect, such
|
||||
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](#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`](../../home/exceptions.md#jsonexceptiontype_error308) if `array` is neither an array nor
|
||||
null -- the same message [`BasicJsonType::push_back`](../basic_json/push_back.md) throws for the same type. Throws
|
||||
null — the same message [`BasicJsonType::push_back`](../basic_json/push_back.md) throws for the same type. Throws
|
||||
[`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) ("view does not belong to this
|
||||
document") if `array` is a [discarded](../basic_json_view/is_discarded.md) view or a view of a *different* document.
|
||||
Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `value` is a
|
||||
[discarded](../basic_json_view/is_discarded.md) view or a [discarded](../basic_json/is_discarded.md) `BasicJsonType`
|
||||
value, and [`type_error.319`](../../home/exceptions.md#jsonexceptiontype_error319) if `value` is (or contains) a
|
||||
binary value -- `BasicJsonType` can hold one, but a `json_document` cannot. Throws
|
||||
binary value — `BasicJsonType` can hold one, but a `json_document` cannot. Throws
|
||||
[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if `value` is (or contains) a string that is
|
||||
not valid UTF-8, with the same message [`BasicJsonType::dump()`](../basic_json/dump.md) gives for that string.
|
||||
|
||||
@@ -59,14 +59,14 @@ not valid UTF-8, with the same message [`BasicJsonType::dump()`](../basic_json/d
|
||||
|
||||
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`](set.md) 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
|
||||
block of links the first time it is appended to (or [`set`](set.md) 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).
|
||||
|
||||
## Notes
|
||||
|
||||
Like [`set`](set.md) 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
|
||||
Like [`set`](set.md) 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](index.md#edits) for what stays valid across an edit in general.
|
||||
|
||||
@@ -137,12 +137,13 @@ Like [`set`](set.md) on a member or an element, `push_back` never moves an exist
|
||||
|
||||
## See also
|
||||
|
||||
- [set](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [insert](insert.md) - insert an element into an array before a given position
|
||||
- [erase](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [root](root.md) - the view of the root value
|
||||
- [`set`](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`insert`](insert.md) - insert an element into an array before a given position
|
||||
- [`erase`](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`root`](root.md) - the view of the root value
|
||||
- [`BasicJsonType::push_back`](../basic_json/push_back.md) - the corresponding function of `basic_json`
|
||||
- [Edits](index.md#edits) - what an edit guarantees, for every overload
|
||||
- [Zero-copy JSON views](../../features/json_view.md#editing-a-document) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -7,7 +7,7 @@ view_type push_back(view_type array, V&& value);
|
||||
|
||||
Appends `value` as a new last element of `array`. A [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) `array` first becomes an empty array, the same way [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) turns a null `object` into an empty object.
|
||||
|
||||
`value` is accepted three ways: a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) 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, `bool`, `nullptr`, containers, ...).
|
||||
`value` is accepted three ways: a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) 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, `bool`, `nullptr`, containers, ...).
|
||||
|
||||
Only an **editable** document (`view_mode::editable`, e.g. [`json_editable_document`](https://json.nlohmann.me/api/json_editable_document/index.md)) has `push_back`; calling it on a read-only `basic_json_document` fails to compile (`static_assert`).
|
||||
|
||||
@@ -27,19 +27,19 @@ 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()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) is touched, so a failure while encoding `value` (an invalid argument, or `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](#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.
|
||||
Basic exception safety: `value` is fully encoded — including the checks below — into storage owned by the document before anything already reachable from [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) is touched, so a failure while encoding `value` (an invalid argument, or `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](#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`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error308) if `array` is neither an array nor null -- the same message [`BasicJsonType::push_back`](https://json.nlohmann.me/api/basic_json/push_back/index.md) throws for the same type. Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) ("view does not belong to this document") if `array` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a view of a *different* document. Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if `value` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) `BasicJsonType` value, and [`type_error.319`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error319) if `value` is (or contains) a binary value -- `BasicJsonType` can hold one, but a `json_document` cannot. Throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `value` is (or contains) a string that is not valid UTF-8, with the same message [`BasicJsonType::dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) gives for that string.
|
||||
Throws [`type_error.308`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error308) if `array` is neither an array nor null — the same message [`BasicJsonType::push_back`](https://json.nlohmann.me/api/basic_json/push_back/index.md) throws for the same type. Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) ("view does not belong to this document") if `array` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a view of a *different* document. Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if `value` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) `BasicJsonType` value, and [`type_error.319`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error319) if `value` is (or contains) a binary value — `BasicJsonType` can hold one, but a `json_document` cannot. Throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `value` is (or contains) a string that is not valid UTF-8, with the same message [`BasicJsonType::dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) 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`](https://json.nlohmann.me/api/basic_json_document/set/index.md) 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).
|
||||
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`](https://json.nlohmann.me/api/basic_json_document/set/index.md) 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).
|
||||
|
||||
## Notes
|
||||
|
||||
Like [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) 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](https://json.nlohmann.me/api/basic_json_document/#edits) for what stays valid across an edit in general.
|
||||
Like [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) 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](https://json.nlohmann.me/api/basic_json_document/#edits) for what stays valid across an edit in general.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -104,12 +104,13 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [set](https://json.nlohmann.me/api/basic_json_document/set/index.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [insert](https://json.nlohmann.me/api/basic_json_document/insert/index.md) - insert an element into an array before a given position
|
||||
- [erase](https://json.nlohmann.me/api/basic_json_document/erase/index.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [root](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value
|
||||
- [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`insert`](https://json.nlohmann.me/api/basic_json_document/insert/index.md) - insert an element into an array before a given position
|
||||
- [`erase`](https://json.nlohmann.me/api/basic_json_document/erase/index.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`root`](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value
|
||||
- [`BasicJsonType::push_back`](https://json.nlohmann.me/api/basic_json/push_back/index.md) - the corresponding function of `basic_json`
|
||||
- [Edits](https://json.nlohmann.me/api/basic_json_document/#edits) - what an edit guarantees, for every overload
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#editing-a-document) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ Linear in the length of the input.
|
||||
|
||||
## Notes
|
||||
|
||||
Every view taken from `#!cpp *this` before the call -- including the previous [`root()`](root.md) -- is invalidated,
|
||||
Every view taken from `#!cpp *this` before the call — including the previous [`root()`](root.md) — is invalidated,
|
||||
whether or not the new parse succeeds; take fresh views from [`root()`](root.md) afterward.
|
||||
|
||||
`input` is borrowed or owned by the same rules as [`parse()`](parse.md#notes); a document can borrow on one call and
|
||||
@@ -111,9 +111,10 @@ compile; see [`parse`](parse.md#notes).
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](parse.md) - deserialize from a compatible input
|
||||
- [root](root.md) - the view of the root value
|
||||
- [load](load.md) - read a document from an image instead of parsing JSON text
|
||||
- [`parse`](parse.md) - deserialize from a compatible input
|
||||
- [`root`](root.md) - the view of the root value
|
||||
- [`load`](load.md) - read a document from an image instead of parsing JSON text
|
||||
- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - reusing a document and what it invalidates
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -34,7 +34,7 @@ Linear in the length of the input.
|
||||
|
||||
## Notes
|
||||
|
||||
Every view taken from `*this` before the call -- including the previous [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) -- is invalidated, whether or not the new parse succeeds; take fresh views from [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) afterward.
|
||||
Every view taken from `*this` before the call — including the previous [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) — is invalidated, whether or not the new parse succeeds; take fresh views from [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) afterward.
|
||||
|
||||
`input` is borrowed or owned by the same rules as [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/#notes); a document can borrow on one call and own on the next, since ownership is decided freshly each time. An input that is copied (see the table in [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/#notes)) is written into the document's previous owned copy, reusing its memory; a moved-in `std::string` replaces it.
|
||||
|
||||
@@ -91,9 +91,10 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [root](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value
|
||||
- [load](https://json.nlohmann.me/api/basic_json_document/load/index.md) - read a document from an image instead of parsing JSON text
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize from a compatible input
|
||||
- [`root`](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value
|
||||
- [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) - read a document from an image instead of parsing JSON text
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime) - reusing a document and what it invalidates
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -37,8 +37,8 @@ auto v = doc.root();
|
||||
```
|
||||
|
||||
`root()` is a cheap handle into the document's index, not a copy of anything; call it as often as needed. The
|
||||
returned view is valid under the same conditions as any other view of the document -- see
|
||||
[Object inspection](../basic_json_view/index.md) -- in particular, it is invalidated by the next
|
||||
returned view is valid under the same conditions as any other view of the document — see
|
||||
[Object inspection](../basic_json_view/index.md) — in particular, it is invalidated by the next
|
||||
[`read()`](read.md) or [`shrink_to_fit()`](shrink_to_fit.md) on this document. A view can dangle, like a
|
||||
`#!cpp std::string_view`; see [Ownership and lifetime](../../features/json_view.md#ownership-and-lifetime).
|
||||
|
||||
@@ -80,8 +80,8 @@ returned view is valid under the same conditions as any other view of the docume
|
||||
|
||||
## See also
|
||||
|
||||
- [is_discarded](is_discarded.md) - return whether the last parse failed
|
||||
- [materialize](../basic_json_view/materialize.md) - build the `BasicJsonType` value of a subtree
|
||||
- [`is_discarded`](is_discarded.md) - return whether the last parse failed
|
||||
- [`materialize`](../basic_json_view/materialize.md) - build the `BasicJsonType` value of a subtree
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -34,7 +34,7 @@ auto doc = json_document::parse(text); // OK: keep the document alive
|
||||
auto v = doc.root();
|
||||
```
|
||||
|
||||
`root()` is a cheap handle into the document's index, not a copy of anything; call it as often as needed. The returned view is valid under the same conditions as any other view of the document -- see [Object inspection](https://json.nlohmann.me/api/basic_json_view/index.md) -- in particular, it is invalidated by the next [`read()`](https://json.nlohmann.me/api/basic_json_document/read/index.md) or [`shrink_to_fit()`](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md) on this document. A view can dangle, like a `std::string_view`; see [Ownership and lifetime](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime).
|
||||
`root()` is a cheap handle into the document's index, not a copy of anything; call it as often as needed. The returned view is valid under the same conditions as any other view of the document — see [Object inspection](https://json.nlohmann.me/api/basic_json_view/index.md) — in particular, it is invalidated by the next [`read()`](https://json.nlohmann.me/api/basic_json_document/read/index.md) or [`shrink_to_fit()`](https://json.nlohmann.me/api/basic_json_document/shrink_to_fit/index.md) on this document. A view can dangle, like a `std::string_view`; see [Ownership and lifetime](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -72,8 +72,8 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [is_discarded](https://json.nlohmann.me/api/basic_json_document/is_discarded/index.md) - return whether the last parse failed
|
||||
- [materialize](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) - build the `BasicJsonType` value of a subtree
|
||||
- [`is_discarded`](https://json.nlohmann.me/api/basic_json_document/is_discarded/index.md) - return whether the last parse failed
|
||||
- [`materialize`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) - build the `BasicJsonType` value of a subtree
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -6,13 +6,13 @@ std::vector<std::uint8_t> save() const;
|
||||
|
||||
Writes the document as an *image*: a byte buffer that [`load`](load.md) reads back without parsing. The image holds
|
||||
the node index, the source text (plus, for an edited document, the number tokens edits wrote), and the decoded
|
||||
strings (plus the strings edits wrote) -- everything [`root()`](root.md) needs, with nothing left to parse.
|
||||
strings (plus the strings edits wrote) — everything [`root()`](root.md) needs, with nothing left to parse.
|
||||
|
||||
An edited document is written in its *current* state, with its values in document order, the way the library's own
|
||||
parser would have produced them for that JSON text: a member [`set`](set.md) added goes at the end, an
|
||||
[`erase`](erase.md)d member leaves no trace, and a float that is not finite (NaN or positive/negative infinity)
|
||||
becomes null, the same substitution [`dump()`](../basic_json_view/dump.md) makes. The same document always saves to
|
||||
the same bytes -- also across `BasicJsonType` and the [`view_mode`](../view_mode.md), since the image reflects document order and
|
||||
the same bytes — also across `BasicJsonType` and the [`view_mode`](../view_mode.md), since the image reflects document order and
|
||||
values only, not which specialization produced them.
|
||||
|
||||
## Return value
|
||||
@@ -28,11 +28,11 @@ exactly as it was, and the partially built image is discarded with the exception
|
||||
## Exceptions
|
||||
|
||||
Throws [`type_error.320`](../../home/exceptions.md#jsonexceptiontype_error320) if the document is
|
||||
[discarded](is_discarded.md) -- a default-constructed document, or one a failed [`parse()`](parse.md)/
|
||||
[discarded](is_discarded.md) — a default-constructed document, or one a failed [`parse()`](parse.md)/
|
||||
[`read()`](read.md) with `allow_exceptions == false` left discarded.
|
||||
|
||||
Throws [`out_of_range.416`](../../home/exceptions.md#jsonexceptionout_of_range416) if the node count, the text, or
|
||||
the decoded strings of the image would individually reach 4 GiB -- the same 32-bit offsets
|
||||
the decoded strings of the image would individually reach 4 GiB — the same 32-bit offsets
|
||||
[`parse()`](parse.md#exceptions) and, for edits, [`set`](set.md)/[`push_back`](push_back.md) are already limited to.
|
||||
|
||||
!!! failure "Example messages"
|
||||
@@ -55,13 +55,13 @@ up in the image.
|
||||
and the sizes of the text and the decoded strings, all little-endian), followed by the nodes
|
||||
([16 bytes each](../../home/architecture.md#node-index-of-json-views)), the text and a `#!cpp '\0'`, and the decoded
|
||||
strings and a `#!cpp '\0'`. [`load`](load.md) checks the header, and the sizes it describes, before reading anything
|
||||
else -- see [`load`'s Exceptions](load.md#exceptions).
|
||||
else — see [`load`'s Exceptions](load.md#exceptions).
|
||||
|
||||
!!! warning "Experimental"
|
||||
|
||||
The image format is versioned but not yet stable: it may change in an incompatible way before it is declared
|
||||
stable. Use images to cache a document within one build of the library, or to hand one to another process running
|
||||
the *same* build on the *same* (little-endian) machine -- not as a long-term storage format. Keep the original
|
||||
the *same* build on the *same* (little-endian) machine — not as a long-term storage format. Keep the original
|
||||
JSON text if you need to read a saved document back with a future library version.
|
||||
|
||||
**Little-endian targets only.** The image is written as raw little-endian bytes, with no byte-swapping. On a
|
||||
@@ -72,8 +72,8 @@ big-endian reader could not interpret correctly.
|
||||
|
||||
??? example "Caching a parsed document as an image"
|
||||
|
||||
The example below saves a parsed configuration as an image -- the way a service might cache one to answer later
|
||||
requests without parsing the text again -- and confirms that loading it back gives exactly the same result as
|
||||
The example below saves a parsed configuration as an image — the way a service might cache one to answer later
|
||||
requests without parsing the text again — and confirms that loading it back gives exactly the same result as
|
||||
parsing did, and that saving is deterministic.
|
||||
|
||||
```cpp
|
||||
@@ -121,8 +121,8 @@ big-endian reader could not interpret correctly.
|
||||
|
||||
## See also
|
||||
|
||||
- [load](load.md) - read an image written by `save()`
|
||||
- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [`load`](load.md) - read an image written by `save()`
|
||||
- [`owns_source`](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [`basic_json_view::dump`](../basic_json_view/dump.md) - serialize the document to JSON text instead of an image
|
||||
- [Images](../../features/json_view.md#images) - why and when to use images
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -4,9 +4,9 @@
|
||||
std::vector<std::uint8_t> save() const;
|
||||
```
|
||||
|
||||
Writes the document as an *image*: a byte buffer that [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) reads back without parsing. The image holds the node index, the source text (plus, for an edited document, the number tokens edits wrote), and the decoded strings (plus the strings edits wrote) -- everything [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) needs, with nothing left to parse.
|
||||
Writes the document as an *image*: a byte buffer that [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) reads back without parsing. The image holds the node index, the source text (plus, for an edited document, the number tokens edits wrote), and the decoded strings (plus the strings edits wrote) — everything [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) needs, with nothing left to parse.
|
||||
|
||||
An edited document is written in its *current* state, with its values in document order, the way the library's own parser would have produced them for that JSON text: a member [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) added goes at the end, an [`erase`](https://json.nlohmann.me/api/basic_json_document/erase/index.md)d member leaves no trace, and a float that is not finite (NaN or positive/negative infinity) becomes null, the same substitution [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) makes. The same document always saves to the same bytes -- also across `BasicJsonType` and the [`view_mode`](https://json.nlohmann.me/api/view_mode/index.md), since the image reflects document order and values only, not which specialization produced them.
|
||||
An edited document is written in its *current* state, with its values in document order, the way the library's own parser would have produced them for that JSON text: a member [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) added goes at the end, an [`erase`](https://json.nlohmann.me/api/basic_json_document/erase/index.md)d member leaves no trace, and a float that is not finite (NaN or positive/negative infinity) becomes null, the same substitution [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) makes. The same document always saves to the same bytes — also across `BasicJsonType` and the [`view_mode`](https://json.nlohmann.me/api/view_mode/index.md), since the image reflects document order and values only, not which specialization produced them.
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -18,9 +18,9 @@ Strong guarantee: `save()` does not modify `*this` (it is `const`), so if it thr
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [`type_error.320`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error320) if the document is [discarded](https://json.nlohmann.me/api/basic_json_document/is_discarded/index.md) -- a default-constructed document, or one a failed [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md)/ [`read()`](https://json.nlohmann.me/api/basic_json_document/read/index.md) with `allow_exceptions == false` left discarded.
|
||||
Throws [`type_error.320`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error320) if the document is [discarded](https://json.nlohmann.me/api/basic_json_document/is_discarded/index.md) — a default-constructed document, or one a failed [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md)/ [`read()`](https://json.nlohmann.me/api/basic_json_document/read/index.md) with `allow_exceptions == false` left discarded.
|
||||
|
||||
Throws [`out_of_range.416`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range416) if the node count, the text, or the decoded strings of the image would individually reach 4 GiB -- the same 32-bit offsets [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/#exceptions) and, for edits, [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md)/[`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) are already limited to.
|
||||
Throws [`out_of_range.416`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range416) if the node count, the text, or the decoded strings of the image would individually reach 4 GiB — the same 32-bit offsets [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/#exceptions) and, for edits, [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md)/[`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) are already limited to.
|
||||
|
||||
Example messages
|
||||
|
||||
@@ -38,11 +38,11 @@ Linear in the size of the document: the number of nodes, plus the length of the
|
||||
|
||||
## Notes
|
||||
|
||||
**Format.** The image begins with a 64-byte header (the magic bytes `"NJVI"`, a version number, the node count, and the sizes of the text and the decoded strings, all little-endian), followed by the nodes ([16 bytes each](https://json.nlohmann.me/home/architecture/#node-index-of-json-views)), the text and a `'\0'`, and the decoded strings and a `'\0'`. [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) checks the header, and the sizes it describes, before reading anything else -- see [`load`'s Exceptions](https://json.nlohmann.me/api/basic_json_document/load/#exceptions).
|
||||
**Format.** The image begins with a 64-byte header (the magic bytes `"NJVI"`, a version number, the node count, and the sizes of the text and the decoded strings, all little-endian), followed by the nodes ([16 bytes each](https://json.nlohmann.me/home/architecture/#node-index-of-json-views)), the text and a `'\0'`, and the decoded strings and a `'\0'`. [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) checks the header, and the sizes it describes, before reading anything else — see [`load`'s Exceptions](https://json.nlohmann.me/api/basic_json_document/load/#exceptions).
|
||||
|
||||
Experimental
|
||||
|
||||
The image format is versioned but not yet stable: it may change in an incompatible way before it is declared stable. Use images to cache a document within one build of the library, or to hand one to another process running the *same* build on the *same* (little-endian) machine -- not as a long-term storage format. Keep the original JSON text if you need to read a saved document back with a future library version.
|
||||
The image format is versioned but not yet stable: it may change in an incompatible way before it is declared stable. Use images to cache a document within one build of the library, or to hand one to another process running the *same* build on the *same* (little-endian) machine — not as a long-term storage format. Keep the original JSON text if you need to read a saved document back with a future library version.
|
||||
|
||||
**Little-endian targets only.** The image is written as raw little-endian bytes, with no byte-swapping. On a big-endian target, `save()` and [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) do not exist: a call fails to compile rather than produce bytes a big-endian reader could not interpret correctly.
|
||||
|
||||
@@ -50,7 +50,7 @@ The image format is versioned but not yet stable: it may change in an incompatib
|
||||
|
||||
Caching a parsed document as an image
|
||||
|
||||
The example below saves a parsed configuration as an image -- the way a service might cache one to answer later requests without parsing the text again -- and confirms that loading it back gives exactly the same result as parsing did, and that saving is deterministic.
|
||||
The example below saves a parsed configuration as an image — the way a service might cache one to answer later requests without parsing the text again — and confirms that loading it back gives exactly the same result as parsing did, and that saving is deterministic.
|
||||
|
||||
```
|
||||
#include <cstdint>
|
||||
@@ -95,8 +95,8 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [load](https://json.nlohmann.me/api/basic_json_document/load/index.md) - read an image written by `save()`
|
||||
- [owns_source](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md) - read an image written by `save()`
|
||||
- [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [`basic_json_view::dump`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) - serialize the document to JSON text instead of an image
|
||||
- [Images](https://json.nlohmann.me/features/json_view/#images) - why and when to use images
|
||||
|
||||
|
||||
@@ -23,8 +23,8 @@ has `set`; calling it on a read-only `basic_json_document` fails to compile (`#!
|
||||
|
||||
1. Replaces the value `target` refers to with `value`.
|
||||
2. Sets the member `key` of the object `object` to `value`: assigns it if `object` already has a member with this
|
||||
key -- the first one, should the key occur more than once, and the later duplicates are then dropped (see the
|
||||
[Notes](#notes) below) -- or appends a new member at the end otherwise. A [null](../basic_json_view/is_null.md)
|
||||
key — the first one, should the key occur more than once, and the later duplicates are then dropped (see the
|
||||
[Notes](#notes) below) — or appends a new member at the end otherwise. A [null](../basic_json_view/is_null.md)
|
||||
`object` first becomes an empty object.
|
||||
3. Assigns `value` to the element at index `idx` of the array `array`, which must already exist (`#!cpp idx <
|
||||
array.size()`).
|
||||
@@ -37,7 +37,7 @@ has `set`; calling it on a read-only `basic_json_document` fails to compile (`#!
|
||||
null values up to that index), an object otherwise. An empty `ptr` sets [`root()`](root.md) itself, as in 1.
|
||||
|
||||
In every overload, `value` is accepted three ways: a [`basic_json_view`](../basic_json_view/index.md) of *any*
|
||||
document -- read-only or editable, and it does not have to be `target`'s/`object`'s/`array`'s own document -- which
|
||||
document — read-only or editable, and it does not have to be `target`'s/`object`'s/`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, ...).
|
||||
|
||||
@@ -82,11 +82,11 @@ is copied so that nothing is shared with the source document afterward; a `Basic
|
||||
|
||||
## Exception safety
|
||||
|
||||
Basic exception safety: `value` is fully encoded -- including the checks below -- into storage owned by the document
|
||||
Basic exception safety: `value` is fully encoded — including the checks below — into storage owned by the document
|
||||
before anything already reachable from [`root()`](root.md) 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 an edited array or object switches
|
||||
from its parsed layout to a growable block, see [Notes](#notes) -- can still leave a partial effect, such as a
|
||||
for the encoding that is not reclaimed. A failure of a later allocation — while an edited array or object switches
|
||||
from its parsed layout to a growable block, see [Notes](#notes) — can still leave a partial effect, such as a
|
||||
[null](../basic_json_view/is_null.md) `object`/`array` argument already turned into an empty object/array even
|
||||
though `value` itself was not linked in. Likewise, a failure of `value` in 4. leaves a null parent that is set with an
|
||||
index beyond 0 already filled with the null values before the index.
|
||||
@@ -95,14 +95,14 @@ index beyond 0 already filled with the null values before the index.
|
||||
|
||||
1. Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `value` is a
|
||||
[discarded](../basic_json_view/is_discarded.md) view, or a [discarded](../basic_json/is_discarded.md)
|
||||
`BasicJsonType` value (e.g. `#!cpp BasicJsonType(value_t::discarded)`) -- an object or array `value`, of either
|
||||
`BasicJsonType` value (e.g. `#!cpp BasicJsonType(value_t::discarded)`) — an object or array `value`, of either
|
||||
kind, is fine and is encoded as a whole subtree.
|
||||
2. Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if `object` is neither an object
|
||||
nor null -- the same message [`operator[]`](../basic_json_view/operator%5B%5D.md) throws for a string argument on
|
||||
nor null — the same message [`operator[]`](../basic_json_view/operator%5B%5D.md) throws for a string argument on
|
||||
such a value. Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if `key` is not
|
||||
valid UTF-8, with the same message [`BasicJsonType::dump()`](../basic_json/dump.md) gives for that string.
|
||||
Also throws what 1. throws for `value`.
|
||||
3. Throws `type_error.305` if `array` is not an array -- the same message `operator[]` throws for a numeric argument
|
||||
3. Throws `type_error.305` if `array` is not an array — the same message `operator[]` throws for a numeric argument
|
||||
on such a value. Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if `idx` is
|
||||
negative, or if `#!cpp idx >= array.size()`. Also throws what 1. throws for `value`.
|
||||
4. Throws what [`at`](../basic_json_view/at.md) throws (overload 3) for resolving `ptr`'s parent, except that a
|
||||
@@ -121,7 +121,7 @@ index beyond 0 already filled with the null values before the index.
|
||||
Also throws what 1. throws for `value`.
|
||||
|
||||
Every overload also throws [`type_error.319`](../../home/exceptions.md#jsonexceptiontype_error319) if `value` is (or
|
||||
contains) a binary value -- `BasicJsonType` can hold one, but a `json_document` cannot -- and
|
||||
contains) a binary value — `BasicJsonType` can hold one, but a `json_document` cannot — and
|
||||
[`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) ("view does not belong to this
|
||||
document") if `target`/`object`/`array` is a [discarded](../basic_json_view/is_discarded.md) view or a view of a
|
||||
*different* document (overloads 1-3 only; overload 4 always starts from this document's own [`root()`](root.md)).
|
||||
@@ -132,7 +132,7 @@ document") if `target`/`object`/`array` is a [discarded](../basic_json_view/is_d
|
||||
number of nested values for an array or object. If `target` is itself an array or object that spans more than one
|
||||
node in its parent's original, unedited layout, and `value` is a scalar, replacing it additionally costs time
|
||||
linear in the size of the document, the *first* time (the parent of `target` is looked up from
|
||||
[`root()`](root.md), and then switches to links) -- see [Notes](#notes). Once the parent has links, `target` is
|
||||
[`root()`](root.md), and then switches to links) — see [Notes](#notes). Once the parent has links, `target` is
|
||||
replaced in constant time: setting every element of a large array one after the other is linear overall. To avoid
|
||||
the lookup altogether, use 3. (or 2. for an object), which know the parent.
|
||||
2. Linear in the number of members of `object`, to find an existing member with `key`, plus the complexity of 1. for
|
||||
@@ -147,7 +147,7 @@ document") if `target`/`object`/`array` is a [discarded](../basic_json_view/is_d
|
||||
!!! info "Duplicate keys"
|
||||
|
||||
If `object` already has more than one member with `key` (2.), the *first* one is assigned `value` and every
|
||||
later member with the same key is removed -- so that a lookup, an iteration, and
|
||||
later member with the same key is removed — so that a lookup, an iteration, and
|
||||
[`materialize()`](../basic_json_view/materialize.md) of `object` afterward all agree on a single value for
|
||||
`key`, the same way [`operator[]`](../basic_json_view/operator%5B%5D.md) already picks the first occurrence of a
|
||||
duplicate key for reading. See the [Notes on duplicate keys](../basic_json_view/operator%5B%5D.md#notes) of
|
||||
@@ -156,8 +156,8 @@ document") if `target`/`object`/`array` is a [discarded](../basic_json_view/is_d
|
||||
Setting a member (2.) or an element (3., through 4.) of an array or object whose elements have not been edited
|
||||
before switches it from its parsed layout to a growable block holding links to its elements; a later
|
||||
[`push_back`](push_back.md) or `set` on the same container reuses that block, growing it (amortized constant time)
|
||||
only once it runs out of room. This never moves an element itself -- only where the container's *links* to its
|
||||
elements live -- so a view of an element stays valid, but any iterator already taken over the container is
|
||||
only once it runs out of room. This never moves an element itself — only where the container's *links* to its
|
||||
elements live — so a view of an element stays valid, but any iterator already taken over the container is
|
||||
invalidated, since it was walking the old layout. See [Edits](index.md#edits) for what stays valid across an edit in
|
||||
general.
|
||||
|
||||
@@ -170,8 +170,8 @@ one-node scalar.
|
||||
|
||||
??? example "Example: (1)/(2)/(3)/(4) replace a value, set a member, assign an element, set via a JSON pointer"
|
||||
|
||||
The example below edits a small configuration document -- replacing a value, adding an object member, assigning
|
||||
an array element, and reaching a field through a JSON pointer -- and shows what
|
||||
The example below edits a small configuration document — replacing a value, adding an object member, assigning
|
||||
an array element, and reaching a field through a JSON pointer — and shows what
|
||||
[`dump()`](../basic_json_view/dump.md) preserves that is lost once the same edits are made on a `BasicJsonType`
|
||||
value instead: the order object members were written in, and the exact spelling of a number that was never
|
||||
touched.
|
||||
@@ -254,10 +254,10 @@ one-node scalar.
|
||||
|
||||
## See also
|
||||
|
||||
- [push_back](push_back.md) - append to an array
|
||||
- [insert](insert.md) - insert an element into an array
|
||||
- [erase](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [root](root.md) - the view of the root value, the starting point of overload 4
|
||||
- [`push_back`](push_back.md) - append to an array
|
||||
- [`insert`](insert.md) - insert an element into an array
|
||||
- [`erase`](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`root`](root.md) - the view of the root value, the starting point of overload 4
|
||||
- [`basic_json_view::dump`](../basic_json_view/dump.md) - serialize the document, keeping an untouched number's
|
||||
spelling with `#!cpp number_format::source`
|
||||
- [Edits](index.md#edits) - what an edit guarantees, for every overload
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -21,11 +21,11 @@ view_type set(const json_pointer& ptr, V&& value);
|
||||
Only an **editable** document (`view_mode::editable`, e.g. [`json_editable_document`](https://json.nlohmann.me/api/json_editable_document/index.md)) has `set`; calling it on a read-only `basic_json_document` fails to compile (`static_assert`).
|
||||
|
||||
1. Replaces the value `target` refers to with `value`.
|
||||
1. Sets the member `key` of the object `object` to `value`: assigns it if `object` already has a member with this key -- the first one, should the key occur more than once, and the later duplicates are then dropped (see the [Notes](#notes) below) -- or appends a new member at the end otherwise. A [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) `object` first becomes an empty object.
|
||||
1. Sets the member `key` of the object `object` to `value`: assigns it if `object` already has a member with this key — the first one, should the key occur more than once, and the later duplicates are then dropped (see the [Notes](#notes) below) — or appends a new member at the end otherwise. A [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) `object` first becomes an empty object.
|
||||
1. Assigns `value` to the element at index `idx` of the array `array`, which must already exist (`idx < array.size()`).
|
||||
1. Sets the value the JSON pointer `ptr` refers to, relative to [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md), to `value`. The *parent* of the target must already exist: an object member is set as in 2. (added if it does not exist yet), an array element is assigned as in 3., and a last reference token of `"-"`, or equal to the size of the array, appends `value` instead, exactly as [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) would. A [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) parent becomes what [`basic_json::operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) with a JSON pointer makes of it: an array if the last reference token is `"-"` or consists of digits only (for an index beyond 0, the array is first filled with null values up to that index), an object otherwise. An empty `ptr` sets [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) itself, as in 1.
|
||||
|
||||
In every overload, `value` is accepted three ways: a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) of *any* document -- read-only or editable, and it does not have to be `target`'s/`object`'s/`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, `bool`, `nullptr`, containers, ...).
|
||||
In every overload, `value` is accepted three ways: a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) of *any* document — read-only or editable, and it does not have to be `target`'s/`object`'s/`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, `bool`, `nullptr`, containers, ...).
|
||||
|
||||
## Template parameters
|
||||
|
||||
@@ -58,20 +58,20 @@ In every overload, `value` is accepted three ways: a [`basic_json_view`](https:/
|
||||
|
||||
## 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()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) is touched, so a failure while encoding `value` (an invalid argument, or `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 an edited array or object switches from its parsed layout to a growable block, see [Notes](#notes) -- can still leave a partial effect, such as a [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) `object`/`array` argument already turned into an empty object/array even though `value` itself was not linked in. Likewise, a failure of `value` in 4. leaves a null parent that is set with an index beyond 0 already filled with the null values before the index.
|
||||
Basic exception safety: `value` is fully encoded — including the checks below — into storage owned by the document before anything already reachable from [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) is touched, so a failure while encoding `value` (an invalid argument, or `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 an edited array or object switches from its parsed layout to a growable block, see [Notes](#notes) — can still leave a partial effect, such as a [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) `object`/`array` argument already turned into an empty object/array even though `value` itself was not linked in. Likewise, a failure of `value` in 4. leaves a null parent that is set with an index beyond 0 already filled with the null values before the index.
|
||||
|
||||
## Exceptions
|
||||
|
||||
1. Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if `value` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view, or a [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) `BasicJsonType` value (e.g. `BasicJsonType(value_t::discarded)`) -- an object or array `value`, of either kind, is fine and is encoded as a whole subtree.
|
||||
1. Throws [`type_error.305`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error305) if `object` is neither an object nor null -- the same message [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md) throws for a string argument on such a value. Throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `key` is not valid UTF-8, with the same message [`BasicJsonType::dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) gives for that string. Also throws what 1. throws for `value`.
|
||||
1. Throws `type_error.305` if `array` is not an array -- the same message `operator[]` throws for a numeric argument on such a value. Throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if `idx` is negative, or if `idx >= array.size()`. Also throws what 1. throws for `value`.
|
||||
1. Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if `value` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view, or a [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) `BasicJsonType` value (e.g. `BasicJsonType(value_t::discarded)`) — an object or array `value`, of either kind, is fine and is encoded as a whole subtree.
|
||||
1. Throws [`type_error.305`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error305) if `object` is neither an object nor null — the same message [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md) throws for a string argument on such a value. Throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `key` is not valid UTF-8, with the same message [`BasicJsonType::dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) gives for that string. Also throws what 1. throws for `value`.
|
||||
1. Throws `type_error.305` if `array` is not an array — the same message `operator[]` throws for a numeric argument on such a value. Throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if `idx` is negative, or if `idx >= array.size()`. Also throws what 1. throws for `value`.
|
||||
1. Throws what [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md) throws (overload 3) for resolving `ptr`'s parent, except that a missing object member or an array index equal to the array's size at the very last reference token is not an error there (it becomes a new member or an appended element) instead of [`out_of_range.403`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range403)/[`out_of_range.402`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range402). For the last reference token itself: if the parent is an object (or a primitive value, where it throws `type_error.305`), throws what 2. throws; if the parent is an array, throws what 3. throws for an index that is out of range, or, for a token that is not a valid array index, [`parse_error.106`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error106) (a leading `'0'`), [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) (not a number), [`out_of_range.410`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range410) (too large for `size_type`), or [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) (an empty token); the same errors are thrown for a null parent and a token of digits (the parent is not changed then), and [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if the index is 4294967295 or more. Also throws what 1. throws for `value`.
|
||||
|
||||
Every overload also throws [`type_error.319`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error319) if `value` is (or contains) a binary value -- `BasicJsonType` can hold one, but a `json_document` cannot -- and [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) ("view does not belong to this document") if `target`/`object`/`array` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a view of a *different* document (overloads 1-3 only; overload 4 always starts from this document's own [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md)).
|
||||
Every overload also throws [`type_error.319`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error319) if `value` is (or contains) a binary value — `BasicJsonType` can hold one, but a `json_document` cannot — and [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) ("view does not belong to this document") if `target`/`object`/`array` is a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view or a view of a *different* document (overloads 1-3 only; overload 4 always starts from this document's own [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md)).
|
||||
|
||||
## Complexity
|
||||
|
||||
1. Linear in the size of `value` (encoding it into the document's storage): constant for a scalar, linear in the number of nested values for an array or object. If `target` is itself an array or object that spans more than one node in its parent's original, unedited layout, and `value` is a scalar, replacing it additionally costs time linear in the size of the document, the *first* time (the parent of `target` is looked up from [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md), and then switches to links) -- see [Notes](#notes). Once the parent has links, `target` is replaced in constant time: setting every element of a large array one after the other is linear overall. To avoid the lookup altogether, use 3. (or 2. for an object), which know the parent.
|
||||
1. Linear in the size of `value` (encoding it into the document's storage): constant for a scalar, linear in the number of nested values for an array or object. If `target` is itself an array or object that spans more than one node in its parent's original, unedited layout, and `value` is a scalar, replacing it additionally costs time linear in the size of the document, the *first* time (the parent of `target` is looked up from [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md), and then switches to links) — see [Notes](#notes). Once the parent has links, `target` is replaced in constant time: setting every element of a large array one after the other is linear overall. To avoid the lookup altogether, use 3. (or 2. for an object), which know the parent.
|
||||
1. Linear in the number of members of `object`, to find an existing member with `key`, plus the complexity of 1. for `value`.
|
||||
1. Constant, plus the complexity of 1. for `value`.
|
||||
1. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at that level or the index into the array (as [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md)), plus the complexity of 2. or 3. for the last token; for a null parent and an index, linear in the index.
|
||||
@@ -80,9 +80,9 @@ Every overload also throws [`type_error.319`](https://json.nlohmann.me/home/exce
|
||||
|
||||
Duplicate keys
|
||||
|
||||
If `object` already has more than one member with `key` (2.), the *first* one is assigned `value` and every later member with the same key is removed -- so that a lookup, an iteration, and [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) of `object` afterward all agree on a single value for `key`, the same way [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md) already picks the first occurrence of a duplicate key for reading. See the [Notes on duplicate keys](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/#notes) of `operator[]`.
|
||||
If `object` already has more than one member with `key` (2.), the *first* one is assigned `value` and every later member with the same key is removed — so that a lookup, an iteration, and [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) of `object` afterward all agree on a single value for `key`, the same way [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md) already picks the first occurrence of a duplicate key for reading. See the [Notes on duplicate keys](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/#notes) of `operator[]`.
|
||||
|
||||
Setting a member (2.) or an element (3., through 4.) of an array or object whose elements have not been edited before switches it from its parsed layout to a growable block holding links to its elements; a later [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) or `set` on the same container reuses that block, growing it (amortized constant time) only once it runs out of room. This never moves an element itself -- only where the container's *links* to its elements live -- so a view of an element stays valid, but any iterator already taken over the container is invalidated, since it was walking the old layout. See [Edits](https://json.nlohmann.me/api/basic_json_document/#edits) for what stays valid across an edit in general.
|
||||
Setting a member (2.) or an element (3., through 4.) of an array or object whose elements have not been edited before switches it from its parsed layout to a growable block holding links to its elements; a later [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) or `set` on the same container reuses that block, growing it (amortized constant time) only once it runs out of room. This never moves an element itself — only where the container's *links* to its elements live — so a view of an element stays valid, but any iterator already taken over the container is invalidated, since it was walking the old layout. See [Edits](https://json.nlohmann.me/api/basic_json_document/#edits) for what stays valid across an edit in general.
|
||||
|
||||
The same switch happens, for the same reason, when overload 1. replaces a multi-node array/object value with a scalar: the *parent's* element sequence is what has to switch to links, not `target` itself, because the parent originally stepped over `target`'s whole subtree by its node count, which no longer applies once `target` is a one-node scalar.
|
||||
|
||||
@@ -90,7 +90,7 @@ The same switch happens, for the same reason, when overload 1. replaces a multi-
|
||||
|
||||
Example: (1)/(2)/(3)/(4) replace a value, set a member, assign an element, set via a JSON pointer
|
||||
|
||||
The example below edits a small configuration document -- replacing a value, adding an object member, assigning an array element, and reaching a field through a JSON pointer -- and shows what [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) preserves that is lost once the same edits are made on a `BasicJsonType` value instead: the order object members were written in, and the exact spelling of a number that was never touched.
|
||||
The example below edits a small configuration document — replacing a value, adding an object member, assigning an array element, and reaching a field through a JSON pointer — and shows what [`dump()`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) preserves that is lost once the same edits are made on a `BasicJsonType` value instead: the order object members were written in, and the exact spelling of a number that was never touched.
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
@@ -168,10 +168,10 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [push_back](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) - append to an array
|
||||
- [insert](https://json.nlohmann.me/api/basic_json_document/insert/index.md) - insert an element into an array
|
||||
- [erase](https://json.nlohmann.me/api/basic_json_document/erase/index.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [root](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value, the starting point of overload 4
|
||||
- [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) - append to an array
|
||||
- [`insert`](https://json.nlohmann.me/api/basic_json_document/insert/index.md) - insert an element into an array
|
||||
- [`erase`](https://json.nlohmann.me/api/basic_json_document/erase/index.md) - remove an object member, an array element, or the value a JSON pointer refers to
|
||||
- [`root`](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value, the starting point of overload 4
|
||||
- [`basic_json_view::dump`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) - serialize the document, keeping an untouched number's spelling with `number_format::source`
|
||||
- [Edits](https://json.nlohmann.me/api/basic_json_document/#edits) - what an edit guarantees, for every overload
|
||||
- [Editing a document](https://json.nlohmann.me/features/json_view/#editing-a-document) - why editable documents keep the source text's order and number spelling
|
||||
|
||||
@@ -100,9 +100,10 @@ possible would be an internal optimization only, not a guarantee to rely on.
|
||||
|
||||
## See also
|
||||
|
||||
- [node_count](node_count.md) - the number of index entries
|
||||
- [memory_usage](memory_usage.md) - the number of bytes held by the document
|
||||
- [root](root.md) - the view of the root value
|
||||
- [`node_count`](node_count.md) - the number of index entries
|
||||
- [`memory_usage`](memory_usage.md) - the number of bytes held by the document
|
||||
- [`root`](root.md) - the view of the root value
|
||||
- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - what releasing memory invalidates
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -89,9 +89,10 @@ true 1
|
||||
|
||||
## See also
|
||||
|
||||
- [node_count](https://json.nlohmann.me/api/basic_json_document/node_count/index.md) - the number of index entries
|
||||
- [memory_usage](https://json.nlohmann.me/api/basic_json_document/memory_usage/index.md) - the number of bytes held by the document
|
||||
- [root](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value
|
||||
- [`node_count`](https://json.nlohmann.me/api/basic_json_document/node_count/index.md) - the number of index entries
|
||||
- [`memory_usage`](https://json.nlohmann.me/api/basic_json_document/memory_usage/index.md) - the number of bytes held by the document
|
||||
- [`root`](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of the root value
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime) - what releasing memory invalidates
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -63,8 +63,9 @@ is; see [`owns_source`](owns_source.md).
|
||||
|
||||
## See also
|
||||
|
||||
- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [source_offset](../basic_json_view/source_offset.md) - byte offset of a value in the source text
|
||||
- [`owns_source`](owns_source.md) - return whether the document holds its own copy of the text
|
||||
- [`source_offset`](../basic_json_view/source_offset.md) - byte offset of a value in the source text
|
||||
- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -59,8 +59,9 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [owns_source](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [source_offset](https://json.nlohmann.me/api/basic_json_view/source_offset/index.md) - byte offset of a value in the source text
|
||||
- [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md) - return whether the document holds its own copy of the text
|
||||
- [`source_offset`](https://json.nlohmann.me/api/basic_json_view/source_offset/index.md) - byte offset of a value in the source text
|
||||
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#ownership-and-lifetime) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
Reference in New Issue
Block a user