mirror of
https://github.com/nlohmann/json.git
synced 2026-11-12 15:10:47 +00:00
Split the json_view feature page into sub-pages (#6018)
* Split the json_view feature page into sub-pages
The single features/json_view.md page grew to ~600 lines covering eight
topics. Split it into features/json_view/ with an overview page and
pages for ownership and lifetime, differences from basic_json, reading
values, generic code, editing, and images.
The new differences page collects what was spread over several sections
("What is the same", "What is different", "Duplicate keys", and notes in
the conversion and serialization sections) under one summary table, and
adds the parts of the basic_json interface a view does not have. The
other pages now link to it instead of restating the rules.
Internal links across the documentation point to the new pages.
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
* Docs: fix stale comments and trim repeated text in json_view pages
- fig-jsonview.js/.css: point the header comments at the new pages
- reading.md: views' strings are valid as long as the document (and a
borrowed source text), as lifetime.md says
- reading.md, generic_code.md: link to differences.md instead of
restating the member-order and repeated-key rules
- differences.md: drop the third mention of ordering comparisons, name
rbegin()/rend() in the iterator row
- exceptions.md: link editable documents to editing.md
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---------
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and 
GitHub committed
1 parent
7757de3a58
commit
6a852ab96d
73 files changed
+880
-686
No files matched your search
@@ -77,7 +77,7 @@ compile; see [`parse`](parse.md#notes).
|
||||
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/differences.md#what-is-the-same) - how parsing a document differs from, and matches, basic_json::parse
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -52,7 +52,7 @@ Constant.
|
||||
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/lifetime.md) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -123,7 +123,7 @@ by an erase, not only those at or after the removed element, since the container
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/editing.md) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -109,7 +109,7 @@ points apply to every edit:
|
||||
anything `BasicJsonType` can be constructed from (numbers, strings, `#!cpp bool`, `#!cpp nullptr`, containers, ...).
|
||||
- [`dump()`](../basic_json_view/dump.md) writes an edited document with members in document order, new members at
|
||||
the end, and, with [`number_format::source`](../basic_json_view/number_format.md), keeps the spelling of every
|
||||
number that was not itself edited — see [Editing a document](../../features/json_view.md#editing-a-document) for
|
||||
number that was not itself edited — see [Editing a document](../../features/json_view/editing.md) for
|
||||
why this matters.
|
||||
- [`read()`](read.md) discards all edits, [`shrink_to_fit()`](shrink_to_fit.md) does not move the node index once
|
||||
there are edits, and [`memory_usage()`](memory_usage.md) includes the memory edits use.
|
||||
@@ -118,7 +118,7 @@ points apply to every edit:
|
||||
|
||||
## See also
|
||||
|
||||
- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
|
||||
- [Zero-copy JSON views](../../features/json_view/index.md) - guide to documents and views
|
||||
- [`basic_json_view`](../basic_json_view/index.md) - the non-owning handle to a value in a document
|
||||
- [`json_document`](../json_document.md) - and [`json_editable_document`](../json_editable_document.md) - the default specializations
|
||||
- [`materialize`](../basic_json_view/materialize.md) - build a `basic_json` value from a view
|
||||
|
||||
@@ -108,7 +108,7 @@ an edit in general.
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/editing.md) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ When the document is discarded, [`root()`](root.md) returns a discarded view (it
|
||||
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/differences.md#what-is-the-same) - how a discarded document arises
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ static basic_json_document load(std::vector<std::uint8_t>&& image,
|
||||
|
||||
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
|
||||
`image`. The hash indexes [large objects](../../features/json_view/index.md) use for lookup are rebuilt, exactly as after
|
||||
parsing.
|
||||
|
||||
## Parameters
|
||||
@@ -172,7 +172,7 @@ returned document, and any [view](../basic_json_view/index.md) taken from it, is
|
||||
- [`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
|
||||
- [Images](../../features/json_view/images.md) - why and when to use images
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ to observe the effect of [`shrink_to_fit()`](shrink_to_fit.md).
|
||||
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/index.md#the-idea) - the flat node index and its memory
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ strings and, for an owned document, the text).
|
||||
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/index.md#the-idea) - the flat node index and its memory
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ document (`#!cpp owns_source() == false`) is only valid while the buffer it was
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/lifetime.md) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -112,7 +112,7 @@ told apart from other class-type iterators, so their range is read into an owned
|
||||
range (e.g. of a `#!cpp std::list<char>`).
|
||||
|
||||
See [`owns_source`](owns_source.md) to check which happened after a call, and the
|
||||
[feature page](../../features/json_view.md) for the reasoning.
|
||||
[feature page](../../features/json_view/index.md) for the reasoning.
|
||||
|
||||
**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.
|
||||
|
||||
@@ -74,7 +74,7 @@ compile; see [`parse`](parse.md#notes).
|
||||
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/lifetime.md) - borrowing or copying the source text
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -96,7 +96,7 @@ Like [`set`](set.md) on a member or an element, `push_back` never moves an exist
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/editing.md) - what an edit guarantees and costs
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -81,7 +81,7 @@ compile; see [`parse`](parse.md#notes).
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/lifetime.md) - reusing a document and what it invalidates
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ auto v = doc.root();
|
||||
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).
|
||||
`#!cpp std::string_view`; see [Ownership and lifetime](../../features/json_view/lifetime.md).
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -91,7 +91,7 @@ big-endian reader could not interpret correctly.
|
||||
- [`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
|
||||
- [Images](../../features/json_view/images.md) - why and when to use images
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -195,7 +195,7 @@ one-node scalar.
|
||||
- [`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
|
||||
- [Editing a document](../../features/json_view.md#editing-a-document) - why editable documents keep the source
|
||||
- [Editing a document](../../features/json_view/editing.md) - why editable documents keep the source
|
||||
text's order and number spelling
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -56,7 +56,7 @@ possible would be an internal optimization only, not a guarantee to rely on.
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/lifetime.md) - what releasing memory invalidates
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ is; see [`owns_source`](owns_source.md).
|
||||
|
||||
- [`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
|
||||
- [Zero-copy JSON views](../../features/json_view/lifetime.md) - who owns the source text and for how long
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
Reference in new issue
Block a user