docs: new design for the documentation site (#5934)
* docs: new design for the documentation site Apply the brand to the Material for MkDocs site: Inter and JetBrains Mono served by the site (upright and real italic), brand colours, blue header band with the syntax pattern, wordmark in the header, new home page (hero, cards, animated feature tour), 404 page, polish for tabs, search, footer, focus rings, tables and code blocks, and theme features (code copy, previous/next footer, TOC follow, search suggestions). Draw the number railroad diagram, the parser callback events and the iterator illustrations as inline SVGs that follow the light and dark scheme. The generator scripts are in docs/mkdocs/scripts/figures; the feature slideshow (json-light.svg, json-dark.svg, replacing json.gif on the home page) is built by docs/mkdocs/scripts/slideshow. Decision nodes in five flowcharts become hexagons, which need far less room. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: add figures, table captions and a macro chooser - Figures with numbered captions: SAX stepper, json_view layout and edit stepper, exception map, JSON pointer and patch walkers, QA pipeline, scaling and binary size charts, roadmap lanes, release timeline, integration decision tree and namespace builder - Table captions (nj-table-caption) on 9 pages - Compile times: modules and PCH charts, filesystem section, re-measured Figure 1, links between features/modules.md and compile_times.md - Interactive macro chooser for features/arbitrary_types.md - Link check: exclude URLs that answer the plugin with 400/401/419 or are dead (customers.md) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: macro chooser generates adl_serializer for non-default-constructible types Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: cross-link concept pages and API pages in See also sections Add See also links in both directions between the concept pages (features, home, integration) and the API pages, write API links in code font, give every entry a comment after a dash, and show the callback event figure on the parser callbacks page. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: address review comments on the new design - Home: add a "Latest release" button - Sponsors: update the list and group it by tier - Features: list all feature pages on the index page - Releases: add highlights per release, link the 4.0 roadmap, add the first commit to the timeline - Exceptions: prefix all example messages with the exception name - API: no code font for format names in the See also links of the to_/from_ pages - Merge Patch: show the document before, the patch, and the result - Replace "--" with typographic dashes, mark external links with an icon, center Mermaid diagrams 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
2bb2feeef4
commit
a47170346a
417 files changed
+11100
-3041
No files matched your search
@@ -15,7 +15,7 @@ basic_json_view at(IntegerType idx) const;
|
||||
basic_json_view at(const json_pointer& ptr) const;
|
||||
```
|
||||
|
||||
1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see
|
||||
1. Returns the value of the object member with key `key` — the first one, should the key occur more than once (see
|
||||
[Notes on duplicate keys](operator[].md#notes)).
|
||||
2. Returns the array element at index `idx`. The template accepts every integer type except `#!cpp bool` and
|
||||
`#!cpp std::size_t` and forwards to the `size_type` overload, as for [`operator[]`](operator[].md); a negative
|
||||
@@ -62,7 +62,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
|
||||
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index in `ptr`
|
||||
is out of range.
|
||||
- Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if a reference token is
|
||||
`#!cpp "-"` at an array -- `at` never inserts an element, so `#!cpp "-"` is always invalid.
|
||||
`#!cpp "-"` at an array — `at` never inserts an element, so `#!cpp "-"` is always invalid.
|
||||
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a reference token names
|
||||
an object member that does not exist.
|
||||
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if `ptr` cannot be resolved
|
||||
@@ -76,7 +76,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
|
||||
|
||||
1. Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after
|
||||
another, in document order, stopping at the first match. Each comparison first checks the
|
||||
key's length -- already known from the index, without reading the key bytes -- before comparing its content.
|
||||
key's length — already known from the index, without reading the key bytes — before comparing its content.
|
||||
Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
|
||||
constant time on average.
|
||||
2. Linear in `idx`: elements are skipped one at a time from the first one, since they are not a fixed size in the
|
||||
@@ -95,7 +95,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
|
||||
the last value.
|
||||
|
||||
Unlike [`operator[]`](operator[].md), which returns a [discarded](is_discarded.md) view for a missing key or an
|
||||
out-of-range index, `at` always throws -- exactly as `BasicJsonType::at` does, and with the same messages, so
|
||||
out-of-range index, `at` always throws — exactly as `BasicJsonType::at` does, and with the same messages, so
|
||||
existing error handling written against `BasicJsonType::at` keeps working unchanged when switched to a view. This
|
||||
also holds for overload 3: unlike [`operator[]`](operator[].md) with a JSON pointer, which returns a discarded view
|
||||
for a missing key or an out-of-range index, `at` throws for those too (`out_of_range.403`/`out_of_range.401`).
|
||||
@@ -105,7 +105,7 @@ for a missing key or an out-of-range index, `at` throws for those too (`out_of_r
|
||||
??? example "Example: (1)/(2) access specified element with bounds checking"
|
||||
|
||||
The example below reads required fields out of a service configuration with `at`, and shows that the exceptions
|
||||
it throws -- for a wrong type and for a missing key -- carry the same messages
|
||||
it throws — for a wrong type and for a missing key — carry the same messages
|
||||
[`BasicJsonType::at`](../basic_json/at.md) would produce for the same JSON text.
|
||||
|
||||
```cpp
|
||||
@@ -135,8 +135,8 @@ for a missing key or an out-of-range index, `at` throws for those too (`out_of_r
|
||||
|
||||
## See also
|
||||
|
||||
- [operator[]](operator[].md) - access specified element (returns a discarded view instead of throwing)
|
||||
- [front](front.md), [back](back.md) - access the first or last element
|
||||
- [`operator[]`](operator[].md) - access specified element (returns a discarded view instead of throwing)
|
||||
- [`front`](front.md), [`back`](back.md) - access the first or last element
|
||||
- [`BasicJsonType::at`](../basic_json/at.md) - the corresponding function of `basic_json`
|
||||
- [`json_pointer`](../json_pointer/index.md) - JSON pointer type used by overload 3
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ Unlike [`BasicJsonType::back()`](../basic_json/back.md), which has undefined beh
|
||||
|
||||
## See also
|
||||
|
||||
- [front](front.md) - access the first element
|
||||
- [`front`](front.md) - access the first element
|
||||
- [`BasicJsonType::back`](../basic_json/back.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -55,9 +55,10 @@ placeholder for "no value yet" and later be assigned a real view.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_discarded](is_discarded.md) - return whether the view is invalid
|
||||
- [root](../basic_json_document/root.md) - the view of a document's root value
|
||||
- [view_mode](../view_mode.md) - whether a document and its views can be edited
|
||||
- [`is_discarded`](is_discarded.md) - return whether the view is invalid
|
||||
- [`root`](../basic_json_document/root.md) - the view of a document's root value
|
||||
- [`view_mode`](../view_mode.md) - whether a document and its views can be edited
|
||||
- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - how long a view stays valid
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ iterator begin() const noexcept;
|
||||
```
|
||||
|
||||
Returns an iterator to the first element of an array, or the first member value of an object, in **document order**
|
||||
-- the order the values appear in the source text, not sorted by key. A primitive value iterates as a range of one
|
||||
— the order the values appear in the source text, not sorted by key. A primitive value iterates as a range of one
|
||||
element (itself), and a `#!json null` value or a [discarded](is_discarded.md) view iterates as an empty range.
|
||||
|
||||
## Return value
|
||||
@@ -22,7 +22,7 @@ Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
For an object, iteration visits **every** member, including all occurrences of a duplicate key -- unlike
|
||||
For an object, iteration visits **every** member, including all occurrences of a duplicate key — unlike
|
||||
[`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md), and [`contains`](contains.md),
|
||||
which all resolve to the *first* member with a given key. See the
|
||||
[Notes on duplicate keys](operator[].md#notes) of `operator[]`.
|
||||
@@ -55,9 +55,9 @@ the duplicates.
|
||||
|
||||
## See also
|
||||
|
||||
- [end](end.md) - returns an iterator to one past the last element
|
||||
- [cbegin](cbegin.md) - returns a const iterator to the first element
|
||||
- [items](items.md) - access iterator member functions in range-based for
|
||||
- [`end`](end.md) - returns an iterator to one past the last element
|
||||
- [`cbegin`](cbegin.md) - returns a const iterator to the first element
|
||||
- [`items`](items.md) - access iterator member functions in range-based for
|
||||
- [`BasicJsonType::begin`](../basic_json/begin.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -25,7 +25,7 @@ Constant.
|
||||
??? example
|
||||
|
||||
The example below sums many measurements with `std::accumulate`, using `cbegin()`/[`cend()`](cend.md) as the
|
||||
range -- the same way it would for any standard container -- without ever materializing the whole array into a
|
||||
range — the same way it would for any standard container — without ever materializing the whole array into a
|
||||
`BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
@@ -40,8 +40,8 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [begin](begin.md) - returns an iterator to the first element
|
||||
- [cend](cend.md) - returns a const iterator to one past the last element
|
||||
- [`begin`](begin.md) - returns an iterator to the first element
|
||||
- [`cend`](cend.md) - returns a const iterator to one past the last element
|
||||
- [`BasicJsonType::cbegin`](../basic_json/cbegin.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -25,7 +25,7 @@ Constant.
|
||||
??? example
|
||||
|
||||
The example below checks that every record of a batch is an object with `std::all_of`, using
|
||||
[`cbegin()`](cbegin.md)/`cend()` as the range -- the same way it would for any standard container -- before
|
||||
[`cbegin()`](cbegin.md)/`cend()` as the range — the same way it would for any standard container — before
|
||||
materializing any record of the batch.
|
||||
|
||||
```cpp
|
||||
@@ -40,8 +40,8 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [end](end.md) - returns an iterator to one past the last element
|
||||
- [cbegin](cbegin.md) - returns a const iterator to the first element
|
||||
- [`end`](end.md) - returns an iterator to one past the last element
|
||||
- [`cbegin`](cbegin.md) - returns a const iterator to the first element
|
||||
- [`BasicJsonType::cend`](../basic_json/cend.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -34,11 +34,11 @@ No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
1. Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after
|
||||
another, in document order, stopping at the first match. Each comparison first checks the
|
||||
key's length -- already known from the index, without reading the key bytes -- before comparing its content.
|
||||
key's length — already known from the index, without reading the key bytes — before comparing its content.
|
||||
Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
|
||||
constant time on average.
|
||||
2. 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 for [`operator[]`](operator[].md#complexity) and
|
||||
that level or the index into the array — as for [`operator[]`](operator[].md#complexity) and
|
||||
[`at`](at.md#complexity) with a JSON pointer.
|
||||
|
||||
## Notes
|
||||
@@ -50,7 +50,7 @@ No-throw guarantee: this function never throws exceptions.
|
||||
`operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
|
||||
the last value.
|
||||
|
||||
Overload 1 always returns `#!cpp false` when the value is not an object -- including a [discarded](is_discarded.md)
|
||||
Overload 1 always returns `#!cpp false` when the value is not an object — including a [discarded](is_discarded.md)
|
||||
view.
|
||||
|
||||
!!! info "Postconditions"
|
||||
@@ -101,9 +101,9 @@ view.
|
||||
|
||||
## See also
|
||||
|
||||
- [find](find.md) - find a value in an object
|
||||
- [count](count.md) - returns the number of occurrences of a key
|
||||
- [at](at.md), [operator[]](operator[].md) - resolve a JSON pointer and throw, or return a discarded view
|
||||
- [`find`](find.md) - find a value in an object
|
||||
- [`count`](count.md) - returns the number of occurrences of a key
|
||||
- [`at`](at.md), [`operator[]`](operator[].md) - resolve a JSON pointer and throw, or return a discarded view
|
||||
- [`BasicJsonType::contains`](../basic_json/contains.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -27,13 +27,13 @@ No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
Linear in the number of members: unlike the lookup functions, `count()` does not stop at the first match, because it
|
||||
has to count every member with the key. Members are compared one after another, in document order. Each comparison
|
||||
first checks the key's length -- already known from the index, without reading the key bytes -- before comparing its
|
||||
first checks the key's length — already known from the index, without reading the key bytes — before comparing its
|
||||
content. The hash index of the keys of objects with 128 or more members does not help here, since every member
|
||||
is visited.
|
||||
|
||||
## Notes
|
||||
|
||||
This method always returns `#!cpp 0` when the value is not an object -- including a [discarded](is_discarded.md)
|
||||
This method always returns `#!cpp 0` when the value is not an object — including a [discarded](is_discarded.md)
|
||||
view.
|
||||
|
||||
If the source text repeats a key, `count()` returns more than `#!cpp 1` for it, even though the
|
||||
@@ -62,8 +62,8 @@ If the source text repeats a key, `count()` returns more than `#!cpp 1` for it,
|
||||
|
||||
## See also
|
||||
|
||||
- [find](find.md) - find a value in an object
|
||||
- [contains](contains.md) - checks whether a key exists
|
||||
- [`find`](find.md) - find a value in an object
|
||||
- [`contains`](contains.md) - checks whether a key exists
|
||||
- [`BasicJsonType::count`](../basic_json/count.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -11,7 +11,7 @@ Serializes this value (and its subtree) directly from the flat index, without ev
|
||||
first. With the default `#!cpp numbers == number_format::shortest`, the result is the same string
|
||||
[`BasicJsonType::dump`](../basic_json/dump.md) would produce for the value
|
||||
[`BasicJsonType::parse()`](../basic_json/parse.md) builds from the same source text, called with the same `indent`,
|
||||
`indent_char`, and `ensure_ascii` -- except that members of an object appear in document order rather than sorted by
|
||||
`indent_char`, and `ensure_ascii` — except that members of an object appear in document order rather than sorted by
|
||||
key, and *every* occurrence of a repeated key is written rather than only the last one (see
|
||||
[Notes on duplicate keys](operator[].md#notes)). For a `json_view` (whose `BasicJsonType` is not ordered), this means
|
||||
`dump()` can print an object's members in a different order than [`materialize()`](materialize.md)`.dump()` of the
|
||||
@@ -58,19 +58,19 @@ Linear in the size of the output text.
|
||||
## Notes
|
||||
|
||||
The walk over the subtree is iterative, so the nesting depth it can write is limited by available memory only, not by
|
||||
the call stack -- as for [`materialize()`](materialize.md).
|
||||
the call stack — as for [`materialize()`](materialize.md).
|
||||
|
||||
Strings are escaped by the same rules as [`BasicJsonType::dump`](../basic_json/dump.md).
|
||||
|
||||
With `#!cpp numbers == number_format::shortest`, floats are written with the library's shortest round-trip conversion,
|
||||
exactly as [`BasicJsonType::dump`](../basic_json/dump.md) would (e.g. `#!cpp 1.5`, `#!cpp 100.0`, `#!cpp 1e+100`), and
|
||||
integers are copied from the source text -- already canonical in JSON, so this matches their shortest form too --
|
||||
integers are copied from the source text — already canonical in JSON, so this matches their shortest form too —
|
||||
except that `#!cpp -0` is written as `#!cpp 0`, the way [`BasicJsonType::parse()`](../basic_json/parse.md) reads it.
|
||||
|
||||
`#!cpp number_format::source` copies every number exactly as written in the source text instead, with no exception
|
||||
for `#!cpp -0` -- `#!cpp 1.50`, `#!cpp 1E2`, `#!cpp -0.0`, `#!cpp -0`, or all digits of an integer literal with more
|
||||
for `#!cpp -0` — `#!cpp 1.50`, `#!cpp 1E2`, `#!cpp -0.0`, `#!cpp -0`, or all digits of an integer literal with more
|
||||
digits than any number type holds (such a literal is itself classified as a float, see
|
||||
[What is different](../../features/json_view.md#what-is-different)) -- something `BasicJsonType` cannot do, since
|
||||
[What is different](../../features/json_view.md#what-is-different)) — something `BasicJsonType` cannot do, since
|
||||
parsing already reduces every number to its parsed value.
|
||||
|
||||
## Examples
|
||||
@@ -95,9 +95,10 @@ parsing already reduces every number to its parsed value.
|
||||
## See also
|
||||
|
||||
- [`number_format`](number_format.md) - how `dump()` writes numbers
|
||||
- [operator<<](operator_ltlt.md) - serialize this value to a stream
|
||||
- [materialize](materialize.md) - build a `BasicJsonType` value, e.g. to use `BasicJsonType::dump`'s `error_handler`
|
||||
- [`operator<<`](operator_ltlt.md) - serialize this value to a stream
|
||||
- [`materialize`](materialize.md) - build a `BasicJsonType` value, e.g. to use `BasicJsonType::dump`'s `error_handler`
|
||||
- [`BasicJsonType::dump`](../basic_json/dump.md) - the corresponding function of `basic_json`
|
||||
- [Zero-copy JSON views](../../features/json_view.md#writing-a-view-back) - writing a view back without building a tree
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
As for [`BasicJsonType::empty()`](../basic_json/empty.md), this does not return whether a string value is empty -- it
|
||||
As for [`BasicJsonType::empty()`](../basic_json/empty.md), this does not return whether a string value is empty — it
|
||||
is `#!cpp false` for any string, regardless of its length.
|
||||
|
||||
## Examples
|
||||
@@ -53,7 +53,7 @@ is `#!cpp false` for any string, regardless of its length.
|
||||
|
||||
## See also
|
||||
|
||||
- [size](size.md) - return the number of elements
|
||||
- [`size`](size.md) - return the number of elements
|
||||
- [`BasicJsonType::empty`](../basic_json/empty.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -5,7 +5,7 @@ iterator end() const noexcept;
|
||||
```
|
||||
|
||||
Returns an iterator to one past the last element of an array, one past the last member value of an object, in
|
||||
**document order** -- see [`begin()`](begin.md). A primitive value iterates as a range of one element (itself), and a
|
||||
**document order** — see [`begin()`](begin.md). A primitive value iterates as a range of one element (itself), and a
|
||||
`#!json null` value or a [discarded](is_discarded.md) view iterates as an empty range (`#!cpp begin() == end()`).
|
||||
|
||||
## Return value
|
||||
@@ -44,8 +44,8 @@ way to reach the last element by stepping back from `end()`. Use [`back()`](back
|
||||
|
||||
## See also
|
||||
|
||||
- [begin](begin.md) - returns an iterator to the first element
|
||||
- [cend](cend.md) - returns a const iterator to one past the last element
|
||||
- [`begin`](begin.md) - returns an iterator to the first element
|
||||
- [`cend`](cend.md) - returns a const iterator to one past the last element
|
||||
- [`BasicJsonType::end`](../basic_json/end.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -6,7 +6,7 @@ iterator find(const char* key) const;
|
||||
iterator find(const string_t& key) const;
|
||||
```
|
||||
|
||||
Finds a member with key `key` -- the first one, should the key occur more than once (see
|
||||
Finds a member with key `key` — the first one, should the key occur more than once (see
|
||||
[Notes on duplicate keys](operator[].md#notes)). If the value is not an object, or no member has this key,
|
||||
[`end()`](end.md) is returned.
|
||||
|
||||
@@ -27,7 +27,7 @@ No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after another,
|
||||
in document order, stopping at the first match. Each comparison first checks the key's length
|
||||
-- already known from the index, without reading the key bytes -- before comparing its content.
|
||||
— already known from the index, without reading the key bytes — before comparing its content.
|
||||
Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
|
||||
constant time on average.
|
||||
|
||||
@@ -41,7 +41,7 @@ constant time on average.
|
||||
the last value.
|
||||
|
||||
Unlike [`BasicJsonType::find`](../basic_json/find.md), which always returns `#!cpp end()` for a non-object type, this
|
||||
also does so for a [discarded](is_discarded.md) view -- there is no separate "invalid" iterator to return.
|
||||
also does so for a [discarded](is_discarded.md) view — there is no separate "invalid" iterator to return.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -63,8 +63,8 @@ also does so for a [discarded](is_discarded.md) view -- there is no separate "in
|
||||
|
||||
## See also
|
||||
|
||||
- [count](count.md) - returns the number of occurrences of a key
|
||||
- [contains](contains.md) - checks whether a key exists
|
||||
- [`count`](count.md) - returns the number of occurrences of a key
|
||||
- [`contains`](contains.md) - checks whether a key exists
|
||||
- [`BasicJsonType::find`](../basic_json/find.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -53,7 +53,7 @@ view.
|
||||
|
||||
## See also
|
||||
|
||||
- [back](back.md) - access the last element
|
||||
- [`back`](back.md) - access the last element
|
||||
- [`BasicJsonType::front`](../basic_json/front.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -7,26 +7,26 @@ T get() const;
|
||||
|
||||
Converts the value to `T`.
|
||||
|
||||
For the types below, the conversion works directly on the flat index -- no `BasicJsonType` value is built for it:
|
||||
For the types below, the conversion works directly on the flat index — no `BasicJsonType` value is built for it:
|
||||
|
||||
- `#!cpp bool`
|
||||
- arithmetic types other than `#!cpp bool` (for a boolean, `#!cpp 0`/`#!cpp 1`, exactly as for
|
||||
[`BasicJsonType::get<T>()`](../basic_json/get.md))
|
||||
- `#!cpp std::nullptr_t`
|
||||
- `#!cpp std::basic_string<char, Traits, Alloc>` (including `string_t`) -- a copy of the string
|
||||
- [`string_view_t`](index.md#member-types) -- **no copy**: the returned view points into the document's
|
||||
- `#!cpp std::basic_string<char, Traits, Alloc>` (including `string_t`) — a copy of the string
|
||||
- [`string_view_t`](index.md#member-types) — **no copy**: the returned view points into the document's
|
||||
[`source()`](../basic_json_document/source.md) text, or, for a string that contains escape sequences, into the
|
||||
document's own buffer of decoded strings (see [`get_string()`](get_string.md))
|
||||
- `BasicJsonType` -- equivalent to [`materialize()`](materialize.md)
|
||||
- `basic_json_view` -- returns `#!cpp *this`
|
||||
- `#!cpp std::vector<U, A>` of the types above -- from an array, element by element, each converted with
|
||||
- `BasicJsonType` — equivalent to [`materialize()`](materialize.md)
|
||||
- `basic_json_view` — returns `#!cpp *this`
|
||||
- `#!cpp std::vector<U, A>` of the types above — from an array, element by element, each converted with
|
||||
`#!cpp get<U>()`; `#!cpp std::vector<basic_json_view>` keeps a view of every element instead of a value
|
||||
- `#!cpp std::map<K, basic_json_view, C, A>` and `#!cpp std::unordered_map<K, basic_json_view, H, E, A>`, if `K` is
|
||||
constructible from a `#!cpp (const char*, std::size_t)` pair -- views of the members of an object; with a repeated
|
||||
constructible from a `#!cpp (const char*, std::size_t)` pair — views of the members of an object; with a repeated
|
||||
key, the view of the *last* member is kept, as [`BasicJsonType::parse()`](../basic_json/parse.md) keeps its value
|
||||
|
||||
A default-constructible `T` whose `from_json()` accepts views reads the view directly as well, without building a
|
||||
`BasicJsonType` value. This covers the library's own conversions of the standard library types -- all other
|
||||
`BasicJsonType` value. This covers the library's own conversions of the standard library types — all other
|
||||
`#!cpp std::vector`s, `#!cpp std::map`/`#!cpp std::unordered_map` (also with other key types), `#!cpp std::list`,
|
||||
`#!cpp std::deque`, `#!cpp std::set`, `#!cpp std::forward_list`, `#!cpp std::valarray`, `#!cpp std::array`, C arrays,
|
||||
`#!cpp std::pair`, `#!cpp std::tuple`, `#!cpp std::optional`, enumerations, `#!cpp std::filesystem::path`, ... --
|
||||
@@ -47,8 +47,8 @@ T&)` of [arbitrary type conversions](../../features/arbitrary_types.md), is not
|
||||
keeps it: for `#!cpp {"x":1,"x":2}`, `#!cpp get<point>()` reads `#!cpp x == 1`. See
|
||||
[Duplicate keys](../../features/json_view.md#duplicate-keys).
|
||||
|
||||
Every other `T` -- user types whose `from_json()` is written for `BasicJsonType` only, types without a default
|
||||
constructor, `#!cpp std::tuple`s holding references, ... -- is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
|
||||
Every other `T` — user types whose `from_json()` is written for `BasicJsonType` only, types without a default
|
||||
constructor, `#!cpp std::tuple`s holding references, ... — is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
|
||||
value first (as [`BasicJsonType::parse()`](../basic_json/parse.md) would), and converted from there exactly as
|
||||
[`BasicJsonType::get<T>()`](../basic_json/get.md) would convert it.
|
||||
|
||||
@@ -69,7 +69,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
|
||||
|
||||
- For the directly-converted types listed above (other than `BasicJsonType` and `basic_json_view`, which never
|
||||
throw): throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if the value's type does not
|
||||
match `T` -- the same exception, with the same message, that [`BasicJsonType::get<T>()`](../basic_json/get.md)
|
||||
match `T` — the same exception, with the same message, that [`BasicJsonType::get<T>()`](../basic_json/get.md)
|
||||
throws for the same JSON type and `T`.
|
||||
- For `#!cpp std::vector<U, A>`: throws `type_error.302` if the value is not an array; otherwise, whatever converting
|
||||
an element to `U` throws.
|
||||
@@ -77,7 +77,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
|
||||
- For a `T` whose `from_json()` reads the view: whatever that `from_json()` throws; for the library's conversions and
|
||||
the macros, the same exceptions with the same messages as [`BasicJsonType::get<T>()`](../basic_json/get.md) of the
|
||||
same value.
|
||||
- For every other `T`: whatever [`materialize().get<T>()`](../basic_json/get.md) throws -- typically `type_error.302`,
|
||||
- For every other `T`: whatever [`materialize().get<T>()`](../basic_json/get.md) throws — typically `type_error.302`,
|
||||
or whatever a user-provided `from_json()` throws.
|
||||
|
||||
None of the exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four
|
||||
@@ -132,7 +132,7 @@ document.
|
||||
|
||||
The example below reads typed fields straight into C++ variables, collects a view of every array element with
|
||||
`#!cpp get<std::vector<basic_json_view>>()` instead of a value, and converts a nested object into a user type
|
||||
through its `from_json()` -- which runs on a `BasicJsonType` value `materialize()` builds for just that one
|
||||
through its `from_json()` — which runs on a `BasicJsonType` value `materialize()` builds for just that one
|
||||
member.
|
||||
|
||||
```cpp
|
||||
@@ -147,11 +147,12 @@ document.
|
||||
|
||||
## See also
|
||||
|
||||
- [get_to](get_to.md) - convert and write into a passed value
|
||||
- [get_string](get_string.md) - the string, without a copy
|
||||
- [number_token](number_token.md) - a number's token text, without a copy
|
||||
- [materialize](materialize.md) - build the `BasicJsonType` value of this subtree
|
||||
- [`get_to`](get_to.md) - convert and write into a passed value
|
||||
- [`get_string`](get_string.md) - the string, without a copy
|
||||
- [`number_token`](number_token.md) - a number's token text, without a copy
|
||||
- [`materialize`](materialize.md) - build the `BasicJsonType` value of this subtree
|
||||
- [`BasicJsonType::get`](../basic_json/get.md) - the corresponding function of `basic_json`
|
||||
- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - which conversions avoid building a basic_json value
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -41,8 +41,8 @@ counterpart, except that it returns a view instead of a reference to a value tha
|
||||
document, the returned [`string_view_t`](index.md#member-types) is valid as long as the caller's buffer; for an owned
|
||||
one, as long as the document.
|
||||
|
||||
The returned [`string_view_t`](index.md#member-types) is valid exactly as long as the view that produced it -- see the
|
||||
[validity rules](index.md) of `basic_json_view` -- and, for a string with no escapes, for as long as the document's
|
||||
The returned [`string_view_t`](index.md#member-types) is valid exactly as long as the view that produced it — see the
|
||||
[validity rules](index.md) of `basic_json_view` — and, for a string with no escapes, for as long as the document's
|
||||
source text, which for a borrowed document must remain valid **and unmodified** for as long as the document exists,
|
||||
since floating-point values and unescaped strings are read from the source lazily.
|
||||
|
||||
@@ -52,8 +52,8 @@ since floating-point values and unescaped strings are read from the source lazil
|
||||
|
||||
The example below pulls one field out of a JSON text that stands in for a large API response, and shows that no
|
||||
`#!cpp std::string` was allocated for it: the returned view still points inside the original buffer. A field that
|
||||
contains an escape sequence cannot point into the original text -- it was decoded once into the document's own
|
||||
buffer instead -- but still avoids a per-field allocation.
|
||||
contains an escape sequence cannot point into the original text — it was decoded once into the document's own
|
||||
buffer instead — but still avoids a per-field allocation.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__get_string.cpp"
|
||||
@@ -67,9 +67,10 @@ since floating-point values and unescaped strings are read from the source lazil
|
||||
|
||||
## See also
|
||||
|
||||
- [get](get.md) - convert the value to a given type (`#!cpp get<string_view_t>()` is equivalent to this function)
|
||||
- [number_token](number_token.md) - a number's token text, without a copy
|
||||
- [`get`](get.md) - convert the value to a given type (`#!cpp get<string_view_t>()` is equivalent to this function)
|
||||
- [`number_token`](number_token.md) - a number's token text, without a copy
|
||||
- [`BasicJsonType::get_ref`](../basic_json/get_ref.md) - the closest counterpart of `basic_json`
|
||||
- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - borrowing strings instead of copying them
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -7,9 +7,9 @@ T& get_to(T& v) const;
|
||||
|
||||
Converts the value to `T` and stores it in `v`, in one of three ways:
|
||||
|
||||
- For the types that [`get<T>()`](get.md) converts directly -- arithmetic types, `#!cpp bool`,
|
||||
- For the types that [`get<T>()`](get.md) converts directly — arithmetic types, `#!cpp bool`,
|
||||
`#!cpp std::nullptr_t`, [`string_view_t`](index.md#member-types), `#!cpp std::basic_string`, `BasicJsonType`,
|
||||
`basic_json_view`, vectors of these, and maps of views -- `v` is assigned: `#!cpp v = get<T>()`.
|
||||
`basic_json_view`, vectors of these, and maps of views — `v` is assigned: `#!cpp v = get<T>()`.
|
||||
- For a type whose `from_json()` accepts views (see [`get<T>()`](get.md)), that `from_json()` is called with the
|
||||
view and the existing `v`, without building a `BasicJsonType` value.
|
||||
- For every other type, the subtree is built into a `BasicJsonType` value and `#!cpp materialize().get_to(v)` is
|
||||
@@ -73,8 +73,9 @@ them with those of a default-constructed `T`.
|
||||
|
||||
## See also
|
||||
|
||||
- [get](get.md) - convert the value to a given type
|
||||
- [`get`](get.md) - convert the value to a given type
|
||||
- [`BasicJsonType::get_to`](../basic_json/get_to.md) - the corresponding function of `basic_json`
|
||||
- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - which conversions avoid building a basic_json value
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -36,11 +36,11 @@ Moving the document itself does not invalidate its views: the index is heap-allo
|
||||
[`json_pointer`](../json_pointer/index.md). Unlike `basic_json`, there are no implicit conversion operators (no
|
||||
`#!cpp operator ValueType()`), and no `#!cpp get_ptr()` or `#!cpp get_ref()`; see [`get`](get.md).
|
||||
|
||||
`basic_json_view` itself is always read-only -- it never has a `set` or `push_back` of its own. A view of an
|
||||
`basic_json_view` itself is always read-only — it never has a `set` or `push_back` of its own. A view of an
|
||||
**editable** document (`#!cpp view_mode::editable`) sees every edit made through
|
||||
[`basic_json_document::set`](../basic_json_document/set.md) and
|
||||
[`basic_json_document::push_back`](../basic_json_document/push_back.md): once a value is changed, every view that
|
||||
still refers to it -- including ones taken before the change -- reads the new value. See
|
||||
still refers to it — including ones taken before the change — reads the new value. See
|
||||
[Edits](../basic_json_document/index.md#edits).
|
||||
|
||||
## Template parameters
|
||||
@@ -148,9 +148,9 @@ still refers to it -- including ones taken before the change -- reads the new va
|
||||
## See also
|
||||
|
||||
- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
|
||||
- [**basic_json_document**](../basic_json_document/index.md) - the document that owns the parsed data
|
||||
- [**json_view**](../json_view.md) and [**json_editable_view**](../json_editable_view.md) - the default specializations
|
||||
- [**materialize**](materialize.md) - build a `basic_json` value from a view
|
||||
- [`basic_json_document`](../basic_json_document/index.md) - the document that owns the parsed data
|
||||
- [`json_view`](../json_view.md) - and [`json_editable_view`](../json_editable_view.md) - the default specializations
|
||||
- [`materialize`](materialize.md) - build a `basic_json` value from a view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -37,9 +37,9 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_structured](is_structured.md) - return whether the type is structured
|
||||
- [size](size.md) - the number of elements
|
||||
- [empty](empty.md) - whether there are no elements
|
||||
- [`is_structured`](is_structured.md) - return whether the type is structured
|
||||
- [`size`](size.md) - the number of elements
|
||||
- [`empty`](empty.md) - whether there are no elements
|
||||
- [`BasicJsonType::is_array`](../basic_json/is_array.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -39,7 +39,7 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [type](type.md) - return the type of the value
|
||||
- [`type`](type.md) - return the type of the value
|
||||
- [`BasicJsonType::is_binary`](../basic_json/is_binary.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -37,7 +37,7 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [type](type.md) - return the type of the value
|
||||
- [`type`](type.md) - return the type of the value
|
||||
- [`BasicJsonType::is_boolean`](../basic_json/is_boolean.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -6,7 +6,7 @@ bool is_discarded() const noexcept;
|
||||
|
||||
Returns whether this view is invalid, i.e. does not refer to a value. This is the case for a default-constructed
|
||||
view (see [(constructor)](basic_json_view.md)), and for [`root()`](../basic_json_document/root.md) of a document
|
||||
that is itself [discarded](../basic_json_document/is_discarded.md) -- in particular, the root of a failed
|
||||
that is itself [discarded](../basic_json_document/is_discarded.md) — in particular, the root of a failed
|
||||
[`parse()`](../basic_json_document/parse.md) with `allow_exceptions` set to `#!cpp false`.
|
||||
|
||||
A discarded view is also what [`operator[]`](operator[].md) returns for a missing key, an index out of range, or a
|
||||
@@ -50,10 +50,11 @@ A `basic_json_view` is not convertible to `#!cpp bool`: such a conversion would
|
||||
|
||||
## See also
|
||||
|
||||
- [operator[]](operator[].md) - access specified element; yields a discarded view where an element is missing
|
||||
- [(constructor)](basic_json_view.md) - the default constructor creates a discarded view
|
||||
- [is_discarded (basic_json_document)](../basic_json_document/is_discarded.md) - return whether the last parse failed
|
||||
- [`operator[]`](operator[].md) - access specified element; yields a discarded view where an element is missing
|
||||
- [`(constructor)`](basic_json_view.md) - the default constructor creates a discarded view
|
||||
- [`basic_json_document::is_discarded`](../basic_json_document/is_discarded.md) - return whether the last parse failed
|
||||
- [`BasicJsonType::is_discarded`](../basic_json/is_discarded.md) - the corresponding function of `basic_json`
|
||||
- [Zero-copy JSON views](../../features/json_view.md#what-is-different) - how views differ from basic_json
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [type](type.md) - return the type of the value
|
||||
- [`type`](type.md) - return the type of the value
|
||||
- [`BasicJsonType::is_null`](../basic_json/is_null.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -37,9 +37,9 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number_integer](is_number_integer.md) - return whether the value is an integer or unsigned integer number
|
||||
- [is_number_unsigned](is_number_unsigned.md) - return whether the value is an unsigned integer number
|
||||
- [is_number_float](is_number_float.md) - return whether the value is a floating-point number
|
||||
- [`is_number_integer`](is_number_integer.md) - return whether the value is an integer or unsigned integer number
|
||||
- [`is_number_unsigned`](is_number_unsigned.md) - return whether the value is an unsigned integer number
|
||||
- [`is_number_float`](is_number_float.md) - return whether the value is a floating-point number
|
||||
- [`BasicJsonType::is_number`](../basic_json/is_number.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -43,7 +43,7 @@ integer-looking token in the source text.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number](is_number.md) - return whether the value is a number
|
||||
- [`is_number`](is_number.md) - return whether the value is a number
|
||||
- [`BasicJsonType::is_number_float`](../basic_json/is_number_float.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -42,8 +42,8 @@ values; use [`is_number_unsigned`](is_number_unsigned.md) to test for those spec
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number](is_number.md) - return whether the value is a number
|
||||
- [is_number_unsigned](is_number_unsigned.md) - return whether the value is an unsigned integer number
|
||||
- [`is_number`](is_number.md) - return whether the value is a number
|
||||
- [`is_number_unsigned`](is_number_unsigned.md) - return whether the value is an unsigned integer number
|
||||
- [`BasicJsonType::is_number_integer`](../basic_json/is_number_integer.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -37,7 +37,7 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number_integer](is_number_integer.md) - return whether the value is an integer or unsigned integer number
|
||||
- [`is_number_integer`](is_number_integer.md) - return whether the value is an integer or unsigned integer number
|
||||
- [`BasicJsonType::is_number_unsigned`](../basic_json/is_number_unsigned.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -37,9 +37,9 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_structured](is_structured.md) - return whether the type is structured
|
||||
- [size](size.md) - the number of elements
|
||||
- [empty](empty.md) - whether there are no elements
|
||||
- [`is_structured`](is_structured.md) - return whether the type is structured
|
||||
- [`size`](size.md) - the number of elements
|
||||
- [`empty`](empty.md) - whether there are no elements
|
||||
- [`BasicJsonType::is_object`](../basic_json/is_object.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -37,7 +37,7 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_structured](is_structured.md) - return whether the type is structured (the complement of this function, for a
|
||||
- [`is_structured`](is_structured.md) - return whether the type is structured (the complement of this function, for a
|
||||
non-discarded view)
|
||||
- [`BasicJsonType::is_primitive`](../basic_json/is_primitive.md) - the corresponding function of `basic_json`
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [source_offset](source_offset.md) - byte offset of this value in the source text, which differs for strings: an
|
||||
- [`source_offset`](source_offset.md) - byte offset of this value in the source text, which differs for strings: an
|
||||
escaped string has none
|
||||
- [`BasicJsonType::is_string`](../basic_json/is_string.md) - the corresponding function of `basic_json`
|
||||
|
||||
|
||||
@@ -37,8 +37,8 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [is_primitive](is_primitive.md) - return whether the type is primitive
|
||||
- [size](size.md), [empty](empty.md) - the number of elements, and whether there are none
|
||||
- [`is_primitive`](is_primitive.md) - return whether the type is primitive
|
||||
- [`size`](size.md), [`empty`](empty.md) - the number of elements, and whether there are none
|
||||
- [`BasicJsonType::is_structured`](../basic_json/is_structured.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
/* unspecified */ items() const noexcept;
|
||||
```
|
||||
|
||||
Returns a range of items -- (key, value) pairs -- for use in range-based for loops. An item's `#!cpp key()` is a
|
||||
Returns a range of items — (key, value) pairs — for use in range-based for loops. An item's `#!cpp key()` is a
|
||||
`#!cpp string_view_t` (for an array element, its index converted to a string, as for
|
||||
[`BasicJsonType::items()`](../basic_json/items.md)), and its `#!cpp value()` is a `basic_json_view` of the element.
|
||||
|
||||
@@ -47,7 +47,7 @@ Constant.
|
||||
## Notes
|
||||
|
||||
As for [`begin()`](begin.md)/[`end()`](end.md), `items()` visits **every** member of an object, including all
|
||||
occurrences of a duplicate key -- unlike [`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md),
|
||||
occurrences of a duplicate key — unlike [`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md),
|
||||
and [`contains`](contains.md), which resolve to the *first* member with a given key. See the
|
||||
[Notes on duplicate keys](operator[].md#notes) of `operator[]`.
|
||||
|
||||
@@ -63,8 +63,8 @@ and [`contains`](contains.md), which resolve to the *first* member with a given
|
||||
|
||||
The example below shows a settings object whose source text records every update to a key as a duplicate
|
||||
member, in the order they happened. `items()` walks all of them, so the update history is visible, while
|
||||
[`operator[]`](operator[].md) only ever sees the *first* one and [`materialize()`](materialize.md) -- like
|
||||
[`BasicJsonType::parse()`](../basic_json/parse.md) -- keeps only the *last*.
|
||||
[`operator[]`](operator[].md) only ever sees the *first* one and [`materialize()`](materialize.md) — like
|
||||
[`BasicJsonType::parse()`](../basic_json/parse.md) — keeps only the *last*.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__items.cpp"
|
||||
@@ -78,7 +78,7 @@ and [`contains`](contains.md), which resolve to the *first* member with a given
|
||||
|
||||
## See also
|
||||
|
||||
- [begin](begin.md), [end](end.md) - the iterators `items()` is built on
|
||||
- [`begin`](begin.md), [`end`](end.md) - the iterators `items()` is built on
|
||||
- [`BasicJsonType::items`](../basic_json/items.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -28,7 +28,7 @@ Linear in the size of the subtree.
|
||||
## Notes
|
||||
|
||||
`materialize()` replays the subtree through the same SAX builder [`BasicJsonType::parse()`](../basic_json/parse.md)
|
||||
uses, so the result matches it exactly -- including, for an object, that a repeated key keeps only its
|
||||
uses, so the result matches it exactly — including, for an object, that a repeated key keeps only its
|
||||
last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion
|
||||
would be; the JSON nesting depth is limited only by available memory, as for `BasicJsonType::parse()` itself.
|
||||
|
||||
@@ -43,7 +43,7 @@ never caches the result.
|
||||
|
||||
??? example
|
||||
|
||||
The example below skips messages that are not useful -- a discarded value, or an empty array -- using only
|
||||
The example below skips messages that are not useful — a discarded value, or an empty array — using only
|
||||
[`is_array()`](is_array.md) and [`empty()`](empty.md), and calls `materialize()` only for the messages that are
|
||||
actually used, so no `BasicJsonType` value (and none of its per-element allocations) is ever built for the
|
||||
skipped ones.
|
||||
@@ -60,10 +60,11 @@ never caches the result.
|
||||
|
||||
## See also
|
||||
|
||||
- [root](../basic_json_document/root.md) - the view of a document's root value
|
||||
- [`root`](../basic_json_document/root.md) - the view of a document's root value
|
||||
- [`BasicJsonType::parse`](../basic_json/parse.md) - build a `BasicJsonType` value directly from a JSON text
|
||||
- [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - source positions on parsed values (not
|
||||
produced by `materialize()`)
|
||||
- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - when to build a basic_json value from a view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -10,14 +10,14 @@ enum class number_format {
|
||||
This enumeration is used in [`dump`](dump.md) to choose how numbers are written. Two values are differentiated:
|
||||
|
||||
shortest
|
||||
: integers are copied from the source text -- already canonical in JSON -- except that `#!cpp -0` becomes
|
||||
: integers are copied from the source text — already canonical in JSON — except that `#!cpp -0` becomes
|
||||
`#!cpp 0`, the way [`BasicJsonType::parse()`](../basic_json/parse.md) reads it; floats are written with the
|
||||
library's shortest round-trip conversion, exactly as [`BasicJsonType::dump()`](../basic_json/dump.md) would (e.g.
|
||||
`#!cpp 1.5`, `#!cpp 100.0`, `#!cpp 1e+100`)
|
||||
|
||||
source
|
||||
: every number is copied exactly as it appears in the source text -- `#!cpp 1.50`, `#!cpp 1E2`, `#!cpp -0`, all
|
||||
digits of an integer literal with more digits than any number type holds -- something `BasicJsonType` cannot do,
|
||||
: every number is copied exactly as it appears in the source text — `#!cpp 1.50`, `#!cpp 1E2`, `#!cpp -0`, all
|
||||
digits of an integer literal with more digits than any number type holds — something `BasicJsonType` cannot do,
|
||||
since parsing already reduces every number to its parsed value
|
||||
|
||||
## Examples
|
||||
@@ -41,10 +41,11 @@ source
|
||||
|
||||
## See also
|
||||
|
||||
- [dump](dump.md) - serialize to a JSON-formatted string
|
||||
- [number_token](number_token.md) - get a single number's token text without dumping the whole value
|
||||
- [`dump`](dump.md) - serialize to a JSON-formatted string
|
||||
- [`number_token`](number_token.md) - get a single number's token text without dumping the whole value
|
||||
- [`BasicJsonType::error_handler_t`](../basic_json/error_handler_t.md) - the analogous enumeration for
|
||||
`BasicJsonType::dump`'s decoding-error behavior
|
||||
- [Zero-copy JSON views](../../features/json_view.md#writing-a-view-back) - writing numbers as they appeared in the source
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ Returns the number exactly as it appears in the source text, without parsing or
|
||||
## Return value
|
||||
|
||||
The number's token text, as a [`string_view_t`](index.md#member-types) into the document's
|
||||
[`source()`](../basic_json_document/source.md) text -- for example `#!cpp "1.50"`, `#!cpp "1E2"`, `#!cpp "-0"`, or an
|
||||
[`source()`](../basic_json_document/source.md) text — for example `#!cpp "1.50"`, `#!cpp "1E2"`, `#!cpp "-0"`, or an
|
||||
integer literal with more digits than any number type holds (such as a 30-digit integer, which [`get<T>()`](get.md)
|
||||
and [`materialize()`](materialize.md) can only represent approximately, as a `number_float_t`).
|
||||
|
||||
@@ -35,12 +35,12 @@ Constant.
|
||||
`BasicJsonType` has no counterpart to this function: once a number is parsed into `number_integer_t`,
|
||||
`number_unsigned_t`, or `number_float_t`, its original textual form (leading zeros aside, which are already rejected
|
||||
by the grammar; trailing zeros in the fraction; the case and sign of the exponent; ...) is gone. `number_token()` is
|
||||
useful precisely where that form must survive -- a price or an identifier that must be reproduced exactly, or a
|
||||
useful precisely where that form must survive — a price or an identifier that must be reproduced exactly, or a
|
||||
number too large for any of `BasicJsonType`'s number types to hold without loss.
|
||||
|
||||
The returned [`string_view_t`](index.md#member-types) always points into the document's
|
||||
[`source()`](../basic_json_document/source.md) text -- numbers are never decoded into the document's separate string
|
||||
buffer -- and is valid exactly as long as that text is, see the [validity rules](index.md) of `basic_json_view`.
|
||||
[`source()`](../basic_json_document/source.md) text — numbers are never decoded into the document's separate string
|
||||
buffer — and is valid exactly as long as that text is, see the [validity rules](index.md) of `basic_json_view`.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -48,7 +48,7 @@ buffer -- and is valid exactly as long as that text is, see the [validity rules]
|
||||
|
||||
The example below keeps a price and an order ID exactly as they were written in an incoming order, where
|
||||
converting them with [`get<T>()`](get.md) would lose information: the price picks up floating-point rounding, and
|
||||
the order ID -- more digits than a 64-bit integer holds -- can only be approximated as a `#!cpp double` once
|
||||
the order ID — more digits than a 64-bit integer holds — can only be approximated as a `#!cpp double` once
|
||||
`#!cpp materialize()`d.
|
||||
|
||||
```cpp
|
||||
@@ -63,11 +63,12 @@ buffer -- and is valid exactly as long as that text is, see the [validity rules]
|
||||
|
||||
## See also
|
||||
|
||||
- [get](get.md) - convert the value to a given type
|
||||
- [get_string](get_string.md) - the string, without a copy
|
||||
- [`get`](get.md) - convert the value to a given type
|
||||
- [`get_string`](get_string.md) - the string, without a copy
|
||||
- [`BasicJsonType::number_integer_t`](../basic_json/number_integer_t.md),
|
||||
[`number_unsigned_t`](../basic_json/number_unsigned_t.md), [`number_float_t`](../basic_json/number_float_t.md) - the
|
||||
number types `#!cpp get<T>()` and `materialize()` convert into
|
||||
- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - reading a number exactly as written
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -15,8 +15,8 @@ basic_json_view operator[](IntegerType idx) const;
|
||||
basic_json_view operator[](const json_pointer& ptr) const;
|
||||
```
|
||||
|
||||
1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see
|
||||
the [Notes](#notes) below) -- or a [discarded](is_discarded.md) view if there is no such member.
|
||||
1. Returns the value of the object member with key `key` — the first one, should the key occur more than once (see
|
||||
the [Notes](#notes) below) — or a [discarded](is_discarded.md) view if there is no such member.
|
||||
2. Returns the array element at index `idx`, or a [discarded](is_discarded.md) view if `idx` is out of range. The
|
||||
template accepts every integer type except `#!cpp bool` and `#!cpp std::size_t` (`#!cpp int`, `#!cpp unsigned`,
|
||||
`#!cpp long`, `#!cpp std::int64_t`, ...) and forwards to the `size_type` overload, so that an integer argument is
|
||||
@@ -55,11 +55,11 @@ Strong guarantee: there are no changes to the view or the document it refers to.
|
||||
## Exceptions
|
||||
|
||||
1. Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the value is not an object and
|
||||
not [discarded](is_discarded.md) --
|
||||
not [discarded](is_discarded.md) —
|
||||
the same exception, with the same message, that the **const** overload of
|
||||
[`BasicJsonType::operator[]`](../basic_json/operator%5B%5D.md) throws for a string argument on a non-object value.
|
||||
2. Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the value is not an array and
|
||||
not [discarded](is_discarded.md) --
|
||||
not [discarded](is_discarded.md) —
|
||||
the same exception, with the same message, that the **const** overload of
|
||||
[`BasicJsonType::operator[]`](../basic_json/operator%5B%5D.md) throws for a numeric argument on a non-array value.
|
||||
3. Throws the same exceptions, with the same messages, that the **const** overload of
|
||||
@@ -81,7 +81,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
|
||||
|
||||
1. Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after
|
||||
another, in document order, stopping at the first match. Each comparison first checks the
|
||||
key's length -- already known from the index, without reading the key bytes -- before comparing its content, so a
|
||||
key's length — already known from the index, without reading the key bytes — before comparing its content, so a
|
||||
key of a different length than `key` is rejected without touching the source text.
|
||||
Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
|
||||
constant time on average.
|
||||
@@ -97,7 +97,7 @@ Unlike `BasicJsonType::operator[]`, which is undefined behavior (guarded by a
|
||||
[runtime assertion](../../features/assertions.md)) for a missing key on a **const** value, this operator returns a
|
||||
safe, testable result for a missing key or an index out of range: a [discarded](is_discarded.md) view, which is
|
||||
tested with [`is_discarded`](is_discarded.md).
|
||||
There is also no non-const overload that inserts a missing key or extends an array -- a view never modifies the
|
||||
There is also no non-const overload that inserts a missing key or extends an array — a view never modifies the
|
||||
document.
|
||||
|
||||
!!! info "Chained access"
|
||||
@@ -126,8 +126,8 @@ document.
|
||||
|
||||
Overload 3 walks `ptr` one reference token at a time, starting at this value, the same way [`at`](at.md) and
|
||||
[`contains`](contains.md) do. It only ever returns a discarded view where the **const** overload of
|
||||
`BasicJsonType::operator[]` would be undefined behavior for the same pointer -- a missing object member or an
|
||||
out-of-range array index -- and still throws for every other way `ptr` can fail to resolve. See
|
||||
`BasicJsonType::operator[]` would be undefined behavior for the same pointer — a missing object member or an
|
||||
out-of-range array index — and still throws for every other way `ptr` can fail to resolve. See
|
||||
[`at`](at.md#exceptions) for the checked version, which throws in every case instead, and
|
||||
[`contains`](contains.md) for a version that never throws.
|
||||
|
||||
@@ -137,7 +137,7 @@ document.
|
||||
|
||||
The example below reads a couple of fields out of a batch of user records without ever materializing a full
|
||||
`BasicJsonType` value for the batch. `operator[]` is used both to look up an optional object member and to index
|
||||
into an array -- in both cases, a missing value comes back as a discarded view that can be tested with a plain
|
||||
into an array — in both cases, a missing value comes back as a discarded view that can be tested with a plain
|
||||
`#!cpp if`, instead of relying on undefined behavior.
|
||||
|
||||
```cpp
|
||||
@@ -168,9 +168,9 @@ document.
|
||||
|
||||
## See also
|
||||
|
||||
- [at](at.md) - access specified element with bounds checking (throws instead of returning a discarded view)
|
||||
- [front](front.md), [back](back.md) - access the first or last element
|
||||
- [find](find.md), [contains](contains.md) - look up a member without throwing
|
||||
- [`at`](at.md) - access specified element with bounds checking (throws instead of returning a discarded view)
|
||||
- [`front`](front.md), [`back`](back.md) - access the first or last element
|
||||
- [`find`](find.md), [`contains`](contains.md) - look up a member without throwing
|
||||
- [`BasicJsonType::operator[]`](../basic_json/operator%5B%5D.md) - the corresponding function of `basic_json`
|
||||
- [`json_pointer`](../json_pointer/index.md) - JSON pointer type used by overload 3
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ bool operator==(const BasicJsonType& lhs, const basic_json_view& rhs);
|
||||
|
||||
Neither overload builds a `BasicJsonType` value for a view to do the comparison (see [Notes](#notes) below). Numbers
|
||||
compare by value across their types (`#!cpp 1 == 1.0`), and an object compares by its members, with duplicate keys
|
||||
resolved exactly as `parse()` resolves them -- the last value, at the position of the first occurrence of the key.
|
||||
resolved exactly as `parse()` resolves them — the last value, at the position of the first occurrence of the key.
|
||||
This is not what [`operator[]`](operator[].md) and the other lookups return for a duplicate key: they find the *first*
|
||||
member (see [Duplicate keys](../../features/json_view.md#duplicate-keys)).
|
||||
|
||||
@@ -55,7 +55,7 @@ compared. Two arrays of different [`size()`](size.md) are rejected without visit
|
||||
## Notes
|
||||
|
||||
Only a single number, boolean, or `#!cpp null` value is ever materialized into a `BasicJsonType`, to reuse its
|
||||
`operator==` -- for numbers, so that values written differently in the source text but equal in value (e.g. an
|
||||
`operator==` — for numbers, so that values written differently in the source text but equal in value (e.g. an
|
||||
integer and a floating-point literal) still compare equal, following the same rules `BasicJsonType` does for special
|
||||
values such as `#!cpp NaN`. Constructing one of these scalars never allocates. Strings are compared directly, without
|
||||
allocating, either from the source text on both sides or, for overload 2, against `BasicJsonType`'s own string.
|
||||
@@ -85,7 +85,7 @@ the way to get a `BasicJsonType` value that supports it.
|
||||
??? example
|
||||
|
||||
The example below checks whether a newly received configuration differs from the previous one, and whether a
|
||||
received document matches what a test expects -- directly on views, without ever materializing a `BasicJsonType`
|
||||
received document matches what a test expects — directly on views, without ever materializing a `BasicJsonType`
|
||||
value for either side.
|
||||
|
||||
```cpp
|
||||
@@ -100,8 +100,8 @@ the way to get a `BasicJsonType` value that supports it.
|
||||
|
||||
## See also
|
||||
|
||||
- [operator!=](operator_ne.md) - compare for inequality
|
||||
- [materialize](materialize.md) - build a `BasicJsonType` value, e.g. to keep comparing after the document is gone
|
||||
- [`operator!=`](operator_ne.md) - compare for inequality
|
||||
- [`materialize`](materialize.md) - build a `BasicJsonType` value, e.g. to keep comparing after the document is gone
|
||||
- [`BasicJsonType::operator==`](../basic_json/operator_eq.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -6,7 +6,7 @@ std::ostream& operator<<(std::ostream& o, const basic_json_view& v);
|
||||
|
||||
Not available when [`JSON_NO_IO`](../macros/json_no_io.md) is defined.
|
||||
|
||||
Serializes the given view `v` to the output stream `o`, using [`dump`](dump.md) -- exactly as
|
||||
Serializes the given view `v` to the output stream `o`, using [`dump`](dump.md) — exactly as
|
||||
`#!cpp operator<<(std::ostream&, const basic_json&)` does for a `basic_json` value.
|
||||
|
||||
- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
|
||||
@@ -38,7 +38,7 @@ the stream `o`
|
||||
|
||||
May throw `#!cpp std::bad_alloc`, propagated from [`dump`](dump.md#exceptions). Unlike
|
||||
`#!cpp operator<<(std::ostream&, const basic_json&)`, there is no UTF-8 decoding step that could throw
|
||||
[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316), and no `error_handler` to choose between --
|
||||
[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316), and no `error_handler` to choose between —
|
||||
see the [Exceptions](dump.md#exceptions) of `dump`.
|
||||
|
||||
## Complexity
|
||||
@@ -49,8 +49,8 @@ Linear, as [`dump`](dump.md#complexity).
|
||||
|
||||
??? example
|
||||
|
||||
The example below writes one record out of a larger batch straight to a log stream -- compact for a one-line
|
||||
entry, and pretty-printed with `std::setw`/`std::setfill` for a readable dump -- without ever building a
|
||||
The example below writes one record out of a larger batch straight to a log stream — compact for a one-line
|
||||
entry, and pretty-printed with `std::setw`/`std::setfill` for a readable dump — without ever building a
|
||||
`BasicJsonType` value for the record, or for the rest of the batch.
|
||||
|
||||
```cpp
|
||||
@@ -65,9 +65,10 @@ Linear, as [`dump`](dump.md#complexity).
|
||||
|
||||
## See also
|
||||
|
||||
- [dump](dump.md) - serialize to a JSON-formatted string
|
||||
- [`dump`](dump.md) - serialize to a JSON-formatted string
|
||||
- [`operator<<(std::ostream&)`](../operator_ltlt.md) - the corresponding operator for `basic_json`
|
||||
- [`JSON_NO_IO`](../macros/json_no_io.md) - switch off functions relying on certain C++ I/O headers
|
||||
- [Zero-copy JSON views](../../features/json_view.md#writing-a-view-back) - writing a view back without building a tree
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ bool operator!=(const BasicJsonType& lhs, const basic_json_view& rhs);
|
||||
|
||||
Since `operator!=` is defined as the negation of [`operator==`](operator_eq.md), it follows the same rules for
|
||||
special cases: for instance, since a [discarded](is_discarded.md) view is never equal to anything by default (see
|
||||
[operator=='s Notes](operator_eq.md#notes)), it is never *unequal* to anything either -- `#!cpp discarded != discarded`
|
||||
[operator=='s Notes](operator_eq.md#notes)), it is never *unequal* to anything either — `#!cpp discarded != discarded`
|
||||
is also `#!cpp false`, exactly as for a discarded `BasicJsonType` value.
|
||||
|
||||
## Parameters
|
||||
@@ -46,7 +46,7 @@ Linear, as [`operator==`](operator_eq.md#complexity).
|
||||
|
||||
## Notes
|
||||
|
||||
See the [Notes](operator_eq.md#notes) of `operator==` -- in particular for how an object's members are compared
|
||||
See the [Notes](operator_eq.md#notes) of `operator==` — in particular for how an object's members are compared
|
||||
(order matters for [`ordered_json_view`](../ordered_json_view.md) but not for [`json_view`](../json_view.md)) and
|
||||
for how discarded views compare.
|
||||
|
||||
@@ -58,7 +58,7 @@ the way to get a `BasicJsonType` value that supports it.
|
||||
??? example
|
||||
|
||||
The example below asserts, as a test would, that a received document differs from an unwanted value, and shows
|
||||
that -- as for [`json`](../json.md)/[`ordered_json`](../ordered_json.md) -- reordering an object's members is
|
||||
that — as for [`json`](../json.md)/[`ordered_json`](../ordered_json.md) — reordering an object's members is
|
||||
detected as a difference for an `ordered_json_view` but not for a `json_view`.
|
||||
|
||||
```cpp
|
||||
@@ -73,8 +73,8 @@ the way to get a `BasicJsonType` value that supports it.
|
||||
|
||||
## See also
|
||||
|
||||
- [operator==](operator_eq.md) - compare for equality
|
||||
- [materialize](materialize.md) - build a `BasicJsonType` value, e.g. to keep comparing after the document is gone
|
||||
- [`operator==`](operator_eq.md) - compare for equality
|
||||
- [`materialize`](materialize.md) - build a `BasicJsonType` value, e.g. to keep comparing after the document is gone
|
||||
- [`BasicJsonType::operator!=`](../basic_json/operator_ne.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -30,10 +30,10 @@ Constant: for an object or array, the element count is stored in the index, not
|
||||
|
||||
## Notes
|
||||
|
||||
As for [`BasicJsonType::size()`](../basic_json/size.md), this does not return the length of a string value -- it is
|
||||
As for [`BasicJsonType::size()`](../basic_json/size.md), this does not return the length of a string value — it is
|
||||
`1` for a string, regardless of its length.
|
||||
|
||||
If the source text has an object with a duplicate key, every occurrence counts towards its `size()` -- unlike
|
||||
If the source text has an object with a duplicate key, every occurrence counts towards its `size()` — unlike
|
||||
[`materialize()`](materialize.md) (and [`BasicJsonType::parse()`](../basic_json/parse.md)), which keeps only the last
|
||||
value for a repeated key. This means `#!cpp v.size()` can be larger than `#!cpp v.materialize().size()`. See the
|
||||
[Notes on duplicate keys](operator[].md#notes) of `operator[]` for why lookups and iteration disagree on how many
|
||||
@@ -58,7 +58,7 @@ members there are.
|
||||
|
||||
## See also
|
||||
|
||||
- [empty](empty.md) - return whether the value has no elements
|
||||
- [`empty`](empty.md) - return whether the value has no elements
|
||||
- [`BasicJsonType::size`](../basic_json/size.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -13,7 +13,7 @@ materializing anything.
|
||||
byte offset of the first byte of the value's token (for a string: the first byte after the opening quote) in
|
||||
[`source()`](../basic_json_document/source.md).
|
||||
- `#!cpp static_cast<std::size_t>(-1)` for a [discarded](is_discarded.md) view, and for a string that contains
|
||||
escapes -- such a string was decoded once into the document's own buffer, so there is no single byte range in
|
||||
escapes — such a string was decoded once into the document's own buffer, so there is no single byte range in
|
||||
`source()` left to point at.
|
||||
|
||||
## Exception safety
|
||||
@@ -47,8 +47,9 @@ string, whose token length is not the same as its decoded [`size()`](size.md).
|
||||
|
||||
## See also
|
||||
|
||||
- [source](../basic_json_document/source.md) - the parsed text
|
||||
- [is_string](is_string.md) - return whether the value is a string
|
||||
- [`source`](../basic_json_document/source.md) - the parsed text
|
||||
- [`is_string`](is_string.md) - return whether the value is a string
|
||||
- [Zero-copy JSON views](../../features/json_view.md#images) - images and the source text
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ value_t type() const noexcept;
|
||||
```
|
||||
|
||||
Returns the type of the value this view refers to, as a value from the [`value_t`](../basic_json/value_t.md)
|
||||
enumeration -- the same enumeration [`BasicJsonType::type()`](../basic_json/type.md) uses.
|
||||
enumeration — the same enumeration [`BasicJsonType::type()`](../basic_json/type.md) uses.
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -44,8 +44,8 @@ JSON text has no binary values, so `type()` only distinguishes the eight ordinar
|
||||
|
||||
## See also
|
||||
|
||||
- [is_null](is_null.md), [is_boolean](is_boolean.md), [is_number](is_number.md), [is_string](is_string.md),
|
||||
[is_array](is_array.md), [is_object](is_object.md) - type-specific predicates built on `type()`
|
||||
- [`is_null`](is_null.md), [`is_boolean`](is_boolean.md), [`is_number`](is_number.md), [`is_string`](is_string.md),
|
||||
[`is_array`](is_array.md), [`is_object`](is_object.md) - type-specific predicates built on `type()`
|
||||
- [`BasicJsonType::type`](../basic_json/type.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
const char* type_name() const noexcept;
|
||||
```
|
||||
|
||||
Returns the type name as string to be used in error messages -- usually to indicate that a function was called on a
|
||||
Returns the type name as string to be used in error messages — usually to indicate that a function was called on a
|
||||
wrong JSON type. Identical to [`BasicJsonType::type_name()`](../basic_json/type_name.md), including the extra
|
||||
`#!cpp "discarded"` return value for a [discarded](is_discarded.md) view (`BasicJsonType::type_name()` produces the
|
||||
same string for a discarded `BasicJsonType` value).
|
||||
@@ -39,7 +39,7 @@ Constant.
|
||||
|
||||
??? example
|
||||
|
||||
The example below reports why some parsed messages were rejected, using only `type_name()` -- no
|
||||
The example below reports why some parsed messages were rejected, using only `type_name()` — no
|
||||
`BasicJsonType` value is ever built for the ones that are wrong, and the message text matches what
|
||||
[`BasicJsonType::type_name()`](../basic_json/type_name.md) would produce for the same value.
|
||||
|
||||
@@ -55,7 +55,7 @@ Constant.
|
||||
|
||||
## See also
|
||||
|
||||
- [type](type.md) - return the type of the value
|
||||
- [`type`](type.md) - return the type of the value
|
||||
- [`BasicJsonType::type_name`](../basic_json/type_name.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -12,8 +12,8 @@ T value(const json_pointer& ptr, const T& default_value) const;
|
||||
string_t value(const json_pointer& ptr, const char* default_value) const;
|
||||
```
|
||||
|
||||
1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see
|
||||
[Notes on duplicate keys](operator[].md#notes)) -- converted to `T`, or `default_value` if there is no such member.
|
||||
1. Returns the value of the object member with key `key` — the first one, should the key occur more than once (see
|
||||
[Notes on duplicate keys](operator[].md#notes)) — converted to `T`, or `default_value` if there is no such member.
|
||||
2. Returns the value a JSON pointer `ptr` refers to, starting at this value, converted to `T`, or `default_value` if
|
||||
`ptr` cannot be resolved.
|
||||
|
||||
@@ -48,16 +48,16 @@ Strong guarantee: there are no changes to the view or the document it refers to.
|
||||
|
||||
## Exceptions
|
||||
|
||||
1. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the value is not an object --
|
||||
1. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the value is not an object —
|
||||
the same exception, with the same message, that [`BasicJsonType::value`](../basic_json/value.md) throws for the
|
||||
same call. If a member with key `key` is found, throws whatever converting it to `T` throws (typically
|
||||
[`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302), with the same message
|
||||
[`BasicJsonType::value`](../basic_json/value.md) throws for the same mismatch); a missing member never throws.
|
||||
2. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if this value -- not the value `ptr`
|
||||
resolves to -- is neither an object nor an array. Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106)
|
||||
2. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if this value — not the value `ptr`
|
||||
resolves to — is neither an object nor an array. Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106)
|
||||
or [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if `ptr` contains a malformed array
|
||||
index. If `ptr` resolves to a value, throws whatever converting it to `T` throws. Every other way `ptr` can fail to
|
||||
resolve -- a missing key, an out-of-range or "`-`" array index, an unresolvable token on a primitive -- yields
|
||||
resolve — a missing key, an out-of-range or "`-`" array index, an unresolvable token on a primitive — yields
|
||||
`default_value` instead of throwing, exactly as [`BasicJsonType::value`](../basic_json/value.md) catches
|
||||
`out_of_range` and returns `default_value`.
|
||||
|
||||
@@ -73,7 +73,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
|
||||
Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
|
||||
constant time on average.
|
||||
2. 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 for the [`operator[]`](operator[].md#complexity) and
|
||||
that level or the index into the array — as for the [`operator[]`](operator[].md#complexity) and
|
||||
[`at`](at.md#complexity) overloads that take a JSON pointer. Plus the complexity of converting the resolved value
|
||||
to `T`.
|
||||
|
||||
@@ -89,7 +89,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
|
||||
!!! info "Differences to `at` and `operator[]`"
|
||||
|
||||
Unlike [`at`](at.md), this function does not throw if `key`/`ptr` resolves to no value. Unlike
|
||||
[`operator[]`](operator[].md), it never returns a [discarded](is_discarded.md) view -- it always returns a `T` --
|
||||
[`operator[]`](operator[].md), it never returns a [discarded](is_discarded.md) view — it always returns a `T` —
|
||||
and it is available on any view, since it never needs to insert a missing element the way the non-const
|
||||
`BasicJsonType::operator[]` would.
|
||||
|
||||
@@ -131,8 +131,8 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
|
||||
|
||||
## See also
|
||||
|
||||
- [at](at.md) - access specified element with bounds checking (throws instead of returning a default value)
|
||||
- [operator[]](operator[].md) - access specified element (returns a discarded view instead of a default value)
|
||||
- [`at`](at.md) - access specified element with bounds checking (throws instead of returning a default value)
|
||||
- [`operator[]`](operator[].md) - access specified element (returns a discarded view instead of a default value)
|
||||
- [`BasicJsonType::value`](../basic_json/value.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
Reference in new issue
Block a user