Add element access, iteration, values, and JSON pointers to json_view

Give basic_json_view the read-only access functions of basic_json:
operator[] and at() with keys and indices, front()/back(), find(),
contains(), count(), begin()/end() and cbegin()/cend(), items()
with structured bindings from C++17 on, and type_name().

Exceptions have the ids and messages of the const functions of
basic_json. Where basic_json has undefined behavior the view
answers safely: operator[] with a missing key or an out-of-range
index returns a discarded view, and front()/back() of an empty
container throw invalid_iterator.214. Objects are iterated in
document order, and all members are visited; duplicate-key lookups
find the first member (as yyjson and simdjson do), while parse(),
materialize(), and the map conversions keep the last value, as
parse() does. Keys of up to 16 bytes are compared with two
overlapping loads.

Add value conversions: get<T>()/get_to() for arithmetic types,
bool, nullptr_t, strings (std::basic_string copied,
string_view_t without a copy), BasicJsonType, views, std::vector,
and maps with string keys; get_string() for the string without a
copy; number_token() for the number exactly as written in the
source; value() with keys and JSON pointers; and operator[]/at()/
contains() with JSON pointers. Everything else, including types
with from_json(), goes through materialize() of that subtree.
get<T>() of arithmetic types is inlined down to the conversion, so
reading an integer needs no call.

detail::json_pointer_access exposes a pointer's reference tokens
to code outside basic_json.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/features/json_view.md

@@ -22,10 +22,15 @@ actually needed (for a string, only if it contains escape sequences, into one sh
 [`basic_json_view`](../api/basic_json_view/index.md) is a small, trivially copyable handle (two pointers) into that
 index. It gives you the read-only, type-inspection part of the `basic_json` interface --
 [`type()`](../api/basic_json_view/type.md) and the `is_*()` predicates,
-[`size()`](../api/basic_json_view/size.md)/[`empty()`](../api/basic_json_view/empty.md) -- without ever allocating a
-`basic_json` value. When you do need an actual `basic_json` value for a subtree,
-[`materialize()`](../api/basic_json_view/materialize.md) builds exactly the one
-[`parse()`](../api/basic_json/parse.md) would have produced for it.
+[`size()`](../api/basic_json_view/size.md)/[`empty()`](../api/basic_json_view/empty.md) -- as well as element access
+([`operator[]`](../api/basic_json_view/operator%5B%5D.md), [`at`](../api/basic_json_view/at.md),
+[`front`](../api/basic_json_view/front.md)/[`back`](../api/basic_json_view/back.md)), lookup
+([`find`](../api/basic_json_view/find.md), [`contains`](../api/basic_json_view/contains.md),
+[`count`](../api/basic_json_view/count.md)), and iteration
+([`begin`](../api/basic_json_view/begin.md)/[`end`](../api/basic_json_view/end.md),
+[`items`](../api/basic_json_view/items.md)) -- without ever allocating a `basic_json` value. When you do need an
+actual `basic_json` value for a subtree, [`materialize()`](../api/basic_json_view/materialize.md) builds exactly the
+one [`parse()`](../api/basic_json/parse.md) would have produced for it.
 
 ## How to use it
 
@@ -116,9 +121,50 @@ whenever any of the other conditions above was not met.
   [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md) enabled,
   [`materialize()`](../api/basic_json_view/materialize.md) does not set them: there is no lexer run during the
   replay to record them.
-- **Element access, iteration, `get<T>()`, JSON Pointer, `dump()`, and comparison are not (yet) provided** by
-  `basic_json_view`. For now, [`materialize()`](../api/basic_json_view/materialize.md) is the way to get a value you
-  can do those things with.
+- **Objects iterate in document order.** [`begin()`](../api/basic_json_view/begin.md)/
+  [`end()`](../api/basic_json_view/end.md) and [`items()`](../api/basic_json_view/items.md) visit an object's
+  members in the order they appear in the source text. `basic_json`'s default `object_t` is a `std::map`, which
+  sorts by key, so iterating a [`materialize()`](../api/basic_json_view/materialize.md)d value can print members in
+  a different order than iterating the view they came from.
+- **Duplicate keys are visible.** If an object in the source text repeats a key,
+  [`begin()`](../api/basic_json_view/begin.md)/[`end()`](../api/basic_json_view/end.md) and
+  [`items()`](../api/basic_json_view/items.md) visit *every* occurrence (and [`size()`](../api/basic_json_view/size.md)
+  counts all of them), while [`operator[]`](../api/basic_json_view/operator%5B%5D.md),
+  [`at`](../api/basic_json_view/at.md), [`find`](../api/basic_json_view/find.md),
+  [`contains`](../api/basic_json_view/contains.md), and [`count`](../api/basic_json_view/count.md) resolve to the
+  *first* occurrence, since a lookup can stop as soon as it finds a match. `basic_json::parse()` (and so
+  [`materialize()`](../api/basic_json_view/materialize.md)) instead keeps only the *last* value for a repeated key.
+  See the [Notes on duplicate keys](../api/basic_json_view/operator%5B%5D.md#notes) of `operator[]`.
+- **No [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) path.** Exceptions thrown by `basic_json_view`'s own
+  element access and lookup functions never carry the JSON Pointer path `JSON_DIAGNOSTICS` would otherwise add: the
+  view has no `basic_json` value to point at, so the exception is created without one, regardless of how
+  `BasicJsonType` was built.
+- **`dump()` and comparison are not (yet) provided** by `basic_json_view`. For now,
+  [`materialize()`](../api/basic_json_view/materialize.md) is the way to get a value you can do those things with.
+
+## Getting values out without copying
+
+[`get<T>()`](../api/basic_json_view/get.md) converts many `T` directly from the flat index, without ever building a
+`basic_json` value for the conversion: `#!cpp bool`, arithmetic types, `#!cpp std::nullptr_t`,
+`#!cpp std::string`/other `#!cpp std::basic_string`s (copied once), `basic_json`/`ordered_json` (via
+[`materialize()`](../api/basic_json_view/materialize.md)), `basic_json_view` itself, `#!cpp std::vector<U>`, and
+`#!cpp std::map`/`#!cpp std::unordered_map` with string-like keys. Every other type -- `#!cpp std::list`,
+`#!cpp std::pair`, `#!cpp std::array`, enumerations, user types with a `from_json()` -- goes through
+[`materialize()`](../api/basic_json_view/materialize.md)`.get<T>()` instead: the subtree is built into a real
+`basic_json` value first, exactly as [`parse()`](../api/basic_json/parse.md) would, and converted from there.
+
+Two conversions never copy at all:
+
+- [`get_string()`](../api/basic_json_view/get_string.md) (equivalently, `#!cpp get<string_view_t>()`) returns a
+  string as a `string_view_t` pointing into the document's [`source()`](../api/basic_json_document/source.md) text --
+  or, for a string that contains escape sequences, into the document's own buffer of decoded strings -- instead of
+  allocating a new `#!cpp std::string`.
+- [`number_token()`](../api/basic_json_view/number_token.md) returns a number exactly as it was written in the
+  source, e.g. `#!cpp "1.50"`, `#!cpp "1E2"`, or an integer with more digits than any number type holds, instead of
+  rounding it into a `#!cpp double`/`#!cpp int64_t` the way `#!cpp get<T>()` (and
+  [`basic_json::parse()`](../api/basic_json/parse.md)) would.
+
+Both results are only valid as long as the view -- and, for a string with no escapes, the borrowed source text -- is.
 
 ## Choosing between `json`, `ordered_json`, the SAX interface, and `json_view`