Merge branch 'json-view/08-view-builder' into json-view/11-view-access

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

docs/mkdocs/docs/api/basic_json/number_float_t.md

@@ -23,10 +23,10 @@ type to use.
 ## Template parameters
 
 `NumberFloatType`
-:   the type to store floating-point numbers. The parser converts `#!cpp float`, `#!cpp double`, and a
-    `#!cpp long double` that is IEEE 754 binary64 itself and other `#!cpp long double` formats with
-    `#!cpp std::from_chars` or `#!cpp std::strtold`, and serialization falls back to `#!cpp std::snprintf`, so the
-    type must be `#!cpp float`, `#!cpp double`, or `#!cpp long double`. The
+:   the type to store floating-point numbers. The type must be `#!cpp float`, `#!cpp double`, or
+    `#!cpp long double`. The parser converts `#!cpp float`, `#!cpp double`, and a `#!cpp long double` that is IEEE 754
+    binary64 itself. It converts other `#!cpp long double` formats with `#!cpp std::from_chars` where available, or
+    with `#!cpp std::strtold` otherwise. Serialization falls back to `#!cpp std::snprintf`. The
     [binary formats](../../features/binary_formats/index.md) additionally require `#!cpp float` or `#!cpp double`,
     because they have no encoding for `#!cpp long double`. See
     [Template Parameter Requirements](../../features/types/template_parameters.md#numberfloattype).

docs/mkdocs/docs/api/basic_json_document/accept.md

@@ -43,6 +43,11 @@ input's own copy (for inputs that are always read into a buffer) throws.
 
 Linear in the length of the input.
 
+## Notes
+
+An integer argument that is not a `#!cpp bool` where the flags are expected, such as `#!cpp accept(ptr, len)`, does not
+compile; see [`parse`](parse.md#notes).
+
 ## Examples
 
 ??? example

docs/mkdocs/docs/api/basic_json_document/parse.md

@@ -19,24 +19,33 @@ static basic_json_document parse(IteratorType first, IteratorType last,
 1. Deserialize from a compatible input, borrowing or owning it depending on its value category and type (see Notes).
 2. Deserialize from a pair of input iterators.
 
-Both overloads accept exactly what [`BasicJsonType::parse()`](../basic_json/parse.md) accepts, with the same
+Both overloads accept the same JSON text as [`BasicJsonType::parse()`](../basic_json/parse.md), with the same
 `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](index.md) (a flat index into
-the input) instead of a tree of `BasicJsonType` values.
+the input) instead of a tree of `BasicJsonType` values. The input must be byte-oriented (see the template parameters
+below): not every input type of `BasicJsonType::parse()` is supported.
 
 ## Template parameters
 
 `InputType`
-:   A compatible input, for instance:
+:   A byte-oriented input, one of:
 
-    - a `#!cpp std::string`, `#!cpp std::string_view`, or a C-style array of characters
-    - a pointer to a null-terminated string of single byte characters
+    - a `#!cpp std::string`, `#!cpp std::string_view`, or a C-style array of single-byte characters
+    - a pointer to a null-terminated string of single-byte characters (`#!cpp char`, `#!cpp signed char`,
+      `#!cpp unsigned char`, `#!cpp std::uint8_t`)
     - a container for which `#!cpp obj.data()` and `#!cpp obj.size()` give contiguous single-byte access, e.g.
       `#!cpp std::vector<char>` or `#!cpp std::vector<std::uint8_t>`
-    - an `#!cpp std::istream` object, or anything else [`BasicJsonType::parse()`](../basic_json/parse.md) accepts
+    - an `#!cpp std::istream` object
+    - a wide string object (`#!cpp std::wstring`, `#!cpp std::u16string`, `#!cpp std::u32string`), which is converted
+      to UTF-8
+
+    Other inputs are not supported: a `#!cpp FILE*`, and pointers to or arrays of wide characters (`#!cpp wchar_t`,
+    `#!cpp char16_t`, `#!cpp char32_t`) are rejected at compile time by a `#!cpp static_assert`. (Use
+    [`BasicJsonType::parse()`](../basic_json/parse.md) for these.)
 
 `IteratorType`
-:   a compatible iterator type, for instance a pair of pointers such as `ptr` and `ptr + len`, or a pair of
-    `#!cpp std::string::iterator`
+:   an input iterator type, for instance a pair of pointers such as `ptr` and `ptr + len`, or a pair of
+    `#!cpp std::string::iterator`; the iterators of single-byte characters are borrowed or read like the byte inputs
+    above, those of wide characters are converted to UTF-8
 
 ## Parameters
 
@@ -70,8 +79,8 @@ discarded; see [`is_discarded`](is_discarded.md).
 Throws the same exception [`BasicJsonType::parse()`](../basic_json/parse.md) throws for the same input and options --
 the same exception id, message, and position -- because on a failing input the library's own parser is run on the
 same bytes to produce the diagnostic. Additionally throws
-[`out_of_range.416`](../../home/exceptions.md#jsonexceptionout_of_range416) if the input is 4 GiB or larger, a size
-[`BasicJsonType::parse()`](../basic_json/parse.md) does not reject.
+[`out_of_range.416`](../../home/exceptions.md#jsonexceptionout_of_range416) if the input is 4294967280 bytes (4 GiB
+minus 16 bytes) or larger, a size [`BasicJsonType::parse()`](../basic_json/parse.md) does not reject.
 
 ## Complexity
 
@@ -84,8 +93,8 @@ Linear in the length of the input.
 | `input`                                                                             | ownership                                                    |
 |--------------------------------------------------------------------------------------|--------------------------------------------------------------|
 | lvalue byte container (`std::string`, `std::vector<char>`, ...), `std::string_view`, C string, character array | **borrowed** -- `input` must outlive the document |
-| rvalue `#!cpp std::string`                                                            | **owned**, moved in without a copy                            |
-| rvalue byte container other than `#!cpp std::string`                                  | **owned**, copied                                             |
+| non-const rvalue `#!cpp std::string`                                                  | **owned**, moved in without a copy                            |
+| other rvalue byte container (including a `#!cpp const` rvalue `#!cpp std::string`)  | **owned**, copied                                             |
 | stream, wide string, or anything else read through the general input adapter          | **owned**, read into a buffer (a stream is read to its end)   |
 
 For overload (2), a pair of pointers to single-byte integers (e.g. `#!cpp const char*`, `#!cpp std::uint8_t*`) is
@@ -100,6 +109,12 @@ See [`owns_source`](owns_source.md) to check which happened after a call, and th
 **Numbers.** As for [`BasicJsonType::parse()`](../basic_json/parse.md), an integer literal too large for the 64-bit
 integer type becomes a floating-point value.
 
+**No lengths.** An integer argument that is not a `#!cpp bool` where the flags are expected -- for example
+`#!cpp parse(ptr, len)` -- does not compile (the overload is deleted). Such a call would convert `len` to
+`allow_exceptions` and read `ptr` as a null-terminated string, past the end of a buffer that has none. To parse a
+buffer of a given length, pass a pair of pointers: `#!cpp parse(ptr, ptr + len)`. The same holds for
+[`parse_copy`](parse_copy.md), [`accept`](accept.md), and [`read`](read.md).
+
 ## Examples
 
 ??? example "Example: (1) borrowed vs. owned input, and errors identical to `BasicJsonType::parse()`"

docs/mkdocs/docs/api/basic_json_document/parse_copy.md

@@ -51,6 +51,9 @@ Linear in the length of the input.
 only differs in that the input is always copied rather than sometimes borrowed. Prefer [`parse()`](parse.md) when the
 input's lifetime already covers the document's, since it avoids the copy for borrowed inputs.
 
+An integer argument that is not a `#!cpp bool` where the flags are expected, such as `#!cpp parse_copy(ptr, len)`, does not
+compile; see [`parse`](parse.md#notes).
+
 ## Examples
 
 ??? example

docs/mkdocs/docs/api/basic_json_document/read.md

@@ -49,6 +49,9 @@ whether or not the new parse succeeds; take fresh views from [`root()`](root.md)
 `input` is borrowed or owned by the same rules as [`parse()`](parse.md#notes); a document can borrow on one call and
 own on the next, since ownership is decided freshly each time.
 
+An integer argument that is not a `#!cpp bool` where the flags are expected, such as `#!cpp read(ptr, len)`, does not
+compile; see [`parse`](parse.md#notes).
+
 ## Examples
 
 ??? example

docs/mkdocs/docs/api/basic_json_document/root.md

@@ -1,10 +1,15 @@
 # <small>nlohmann::basic_json_document::</small>root
 
 ```cpp
-view_type root() const noexcept;
+// (1)
+view_type root() const& noexcept;
+
+// (2)
+view_type root() const&& = delete;
 ```
 
-Returns a view of the root value of the document.
+1. Returns a view of the root value of the document.
+2. Deleted: the view of a temporary document would dangle.
 
 ## Return value
 
@@ -21,6 +26,16 @@ Constant.
 
 ## Notes
 
+**Lifetime.** A view refers into the document, so the document must outlive it. `root()` can therefore only be called
+on a document that has a name (an lvalue); calling it on a temporary does not compile:
+
+```cpp
+auto v = json_document::parse(text).root();  // error: the document is destroyed at the end of the statement
+
+auto doc = json_document::parse(text);       // OK: keep the document alive
+auto v = doc.root();
+```
+
 `root()` is a cheap handle into the document's index, not a copy of anything; call it as often as needed. The
 returned view is valid under the same conditions as any other view of the document -- see
 [Object inspection](../basic_json_view/index.md) -- in particular, it is invalidated by the next

docs/mkdocs/docs/api/basic_json_view/basic_json_view.md

@@ -4,8 +4,8 @@
 basic_json_view() noexcept = default;
 ```
 
-Creates an invalid (discarded) view: [`type()`](type.md) is `#!cpp value_t::discarded`,
-[`is_discarded()`](is_discarded.md) is `#!cpp true`, and `#!cpp explicit operator bool()` is `#!cpp false`.
+Creates an invalid (discarded) view: [`type()`](type.md) is `#!cpp value_t::discarded` and
+[`is_discarded()`](is_discarded.md) is `#!cpp true`.
 
 This is the only constructor a caller can use directly. Every other view is obtained from a
 [`basic_json_document`](../basic_json_document/index.md), via [`root()`](../basic_json_document/root.md) or by
@@ -44,7 +44,6 @@ 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
-- [operator bool](operator_bool.md) - return whether the view refers to a value
 - [root](../basic_json_document/root.md) - the view of a document's root value
 
 ## Version history

docs/mkdocs/docs/api/basic_json_view/index.md

@@ -69,7 +69,6 @@ comparison.
 - [**is_primitive**](is_primitive.md) - return whether the type is primitive
 - [**is_structured**](is_structured.md) - return whether the type is structured
 - [**is_discarded**](is_discarded.md) - return whether the view is invalid
-- [**operator bool**](operator_bool.md) - return whether the view refers to a value
 
 ### Element access
 

docs/mkdocs/docs/api/basic_json_view/is_discarded.md

@@ -27,8 +27,9 @@ Constant.
 
 ## Notes
 
-`#!cpp v.is_discarded()` and `#!cpp !static_cast<bool>(v)` are equivalent; use whichever reads better at the call
-site.
+A `basic_json_view` is not convertible to `#!cpp bool`: such a conversion would mean "refers to a value", whereas
+`basic_json` converts to the `#!cpp bool` it holds, so the same code would silently behave differently. Test
+`#!cpp !v.is_discarded()` explicitly.
 
 ## Examples
 
@@ -50,7 +51,6 @@ site.
 ## See also
 
 - [operator[]](operator[].md) - access specified element; yields a discarded view where an element is missing
-- [operator bool](operator_bool.md) - return whether the view refers to a value
 - [(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
 - [`BasicJsonType::is_discarded`](../basic_json/is_discarded.md) - the corresponding function of `basic_json`

docs/mkdocs/docs/api/basic_json_view/operator_bool.md

@@ -1,46 +0,0 @@
-# <small>nlohmann::basic_json_view::</small>operator bool
-
-```cpp
-explicit operator bool() const noexcept;
-```
-
-Returns whether this view refers to a value, i.e. the negation of [`is_discarded()`](is_discarded.md). Being
-`#!cpp explicit`, this conversion is only considered in a boolean context (`#!cpp if (v)`, `#!cpp !v`, `#!cpp v &&
-...`), not for implicit conversions to other types.
-
-## Return value
-
-`#!cpp true` if the view refers to a value, `#!cpp false` if it is [discarded](is_discarded.md).
-
-## Exception safety
-
-No-throw guarantee: this function never throws exceptions.
-
-## Complexity
-
-Constant.
-
-## Examples
-
-??? example
-
-    The example below classifies several parsed documents by the type of their root value, without materializing any
-    of them into a `BasicJsonType` value.
-
-    ```cpp
-    --8<-- "examples/basic_json_view__type_predicates.cpp"
-    ```
-
-    Output:
-
-    ```json
-    --8<-- "examples/basic_json_view__type_predicates.output"
-    ```
-
-## See also
-
-- [is_discarded](is_discarded.md) - return whether the view is invalid
-
-## Version history
-
-- Added in version 3.13.0.

docs/mkdocs/docs/examples/basic_json_view__basic_json_view.cpp

@@ -8,10 +8,10 @@ int main()
     // the default constructor is the only public one: it creates an invalid
     // (discarded) view, useful as a "no value yet" placeholder
     nlohmann::json_view v;
-    std::cout << static_cast<bool>(v) << ' ' << v.is_discarded() << '\n';
+    std::cout << v.is_discarded() << '\n';
 
     // views are trivially copyable handles (two pointers); the document owns
     // the actual data
     nlohmann::json_view copy = v;
-    std::cout << static_cast<bool>(copy) << '\n';
+    std::cout << copy.is_discarded() << '\n';
 }

docs/mkdocs/docs/examples/basic_json_view__basic_json_view.output

@@ -1,2 +1,2 @@
-false true
-false
+true
+true

docs/mkdocs/docs/examples/basic_json_view__type_predicates.cpp

@@ -35,8 +35,8 @@ int main()
     // parse without exceptions, are both discarded
     nlohmann::json_view invalid;
     json_document failed = json_document::parse("not json", /* allow_exceptions */ false);
-    std::cout << static_cast<bool>(invalid) << ' ' << invalid.is_discarded() << '\n';
-    std::cout << static_cast<bool>(failed.root()) << ' ' << failed.root().is_discarded() << '\n';
+    std::cout << invalid.is_discarded() << '\n';
+    std::cout << failed.root().is_discarded() << '\n';
 
     // type() returns the same value_t enumeration as basic_json::type()
     std::cout << (d_object.root().type() == nlohmann::json::value_t::object) << '\n';

docs/mkdocs/docs/examples/basic_json_view__type_predicates.output

@@ -7,6 +7,6 @@ true
 true true
 true false
 false
-false true
-false true
+true
+true
 true

docs/mkdocs/docs/features/json_view.md

@@ -81,6 +81,9 @@ Moving the document itself is fine and does **not** invalidate its views: the in
 that keeps its address across the move. Take a fresh view from [`root()`](../api/basic_json_document/root.md)
 whenever any of the other conditions above was not met.
 
+Because a view dies with its document, [`root()`](../api/basic_json_document/root.md) is not callable on a temporary
+document: `#!cpp auto v = json_document::parse(text).root();` does not compile. Give the document a name first.
+
 ??? example "Example: borrowed and owned documents, and when views become invalid"
 
     ```cpp
@@ -113,7 +116,7 @@ whenever any of the other conditions above was not met.
 
 - **Only 64-bit integers.** `basic_json_document<BasicJsonType>` requires `BasicJsonType::number_integer_t` and
   `number_unsigned_t` to both be 64 bits wide; this is a compile-time `#!cpp static_assert`.
-- **A 4 GiB input limit.** An input of 4 GiB or more throws
+- **A 4 GiB input limit.** An input of 4294967280 bytes (4 GiB minus 16 bytes) or more throws
   [`out_of_range.416`](../home/exceptions.md#jsonexceptionout_of_range416), a limit
   `#!cpp basic_json::parse()` does not have.
 - **A stream is always read to its end.** There is no partial/streaming read of an `#!cpp std::istream`.

docs/mkdocs/docs/features/types/template_parameters.md

@@ -353,16 +353,21 @@ using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
 ### Always required
 
 - A member type `value_type` that is one byte wide and `char`-compatible. The library stores and processes UTF-8
-  encoded `char` data and passes `data()` to functions that take a `#!cpp const char*`, such as `#!cpp std::strtod`.
+  encoded `char` data and passes `data()` to functions that take a `#!cpp const char*`, such as `#!cpp std::strtold`
+  (only used to parse a `#!cpp long double` that is not IEEE 754 binary64, see
+  [`NumberFloatType`](#numberfloattype)).
   `#!cpp std::wstring`, `#!cpp std::u16string`, and `#!cpp std::u32string` are **not** valid choices; see the FAQ on
   [wide string handling](../../home/faq.md#wide-string-handling).
 - Constructors: default, copy, move, from `#!cpp const char*` (which must not be `#!cpp explicit`), from
   `#!cpp (const char*, size_type)`, and from `#!cpp (size_type, char)`; and copy or move assignment.
 - Member functions `size()`, `clear()`, `resize(n, c)`, `data()`, `push_back(char)`, and `operator[]`
   (const and non-const, returning references). `c_str()` and `back()` are **not** required.
-- `data()` must return a pointer to a contiguous, **null-terminated** buffer -- the parser may hand it to
-  `#!cpp std::strtod`, which reads up to the null character. A type whose `data()` is not null-terminated does not
-  fail to compile; it can silently misparse floating-point numbers.
+- `data()` must return a pointer to a contiguous, **null-terminated** buffer. `#!cpp float`, `#!cpp double`, and a
+  `#!cpp long double` that is IEEE 754 binary64 are converted by the library itself and do not depend on this. For any
+  other `NumberFloatType` (a `#!cpp long double` of another format), the parser falls back to `#!cpp std::strtold` when
+  `#!cpp std::from_chars` is not available or declines the token, and `std::strtold` reads up to the null character. A type whose `data()`
+  is not null-terminated does not fail to compile; with such a `NumberFloatType` it can silently misparse
+  floating-point numbers.
 - `append(const char*, size_type)`, used by [`dump`](../../api/basic_json/dump.md), and `append(const StringType&)`,
   used by the CBOR reader for indefinite-length strings. The library's internal string concatenation additionally has
   to append a `#!cpp char` and a `#!cpp const char*`; for each it selects between `append(arg)`, `#!cpp operator+=`,

docs/mkdocs/docs/home/architecture.md

@@ -210,7 +210,8 @@ packet-beta
 - **Navigation** needs no pointers: the elements of an array or object follow its node, and the node after a value's
   subtree is `next` nodes further for an array or object, and the next node otherwise (`document_data::after`). Views
   step from element to element this way and skip whole subtrees in constant time.
-- **Offsets** are 32 bits wide, so a document is limited to 4 GiB (`out_of_range.416`).
+- **Offsets** are 32 bits wide, so a document is limited to 4294967279 bytes, 4 GiB minus 16 bytes (a margin below
+  2^32 for positions one scanner step past the end of the text; `out_of_range.416`).
 
 For example, `#!json {"a": [1, 2.5]}` becomes five nodes. Each node's elements follow it, and `next` leads from an
 array or object past its subtree:

docs/mkdocs/docs/home/exceptions.md

@@ -1048,12 +1048,12 @@ MessagePack's ext type and BSON's binary subtype are each stored in a single byt
 
 [`basic_json_document::parse()`](../api/basic_json_document/parse.md) and the other parsing functions of
 [`basic_json_document`](../api/basic_json_document/index.md) index a value's position in the source text in 32 bits,
-so they do not support an input of 4 GiB or more.
+so they do not support an input of 4294967280 bytes (4 GiB minus 16 bytes) or more.
 
 !!! failure "Example message"
 
     ```
-    [json.exception.out_of_range.416] input of 4 GiB or more is not supported by json_document
+    [json.exception.out_of_range.416] input of 4294967280 bytes or more is not supported by json_document
     ```
 
 !!! note

docs/mkdocs/docs/home/license.md

@@ -18,7 +18,7 @@ The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed und
 
 The class contains a slightly modified version of the Grisu2 algorithm from Florian Loitsch which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above). Copyright © 2009 [Florian Loitsch](https://florian.loitsch.com/)
 
-The class contains a port of the shortest double-to-decimal conversion of [Żmij](https://github.com/vitaut/zmij) by Victor Zverovich, which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above). Copyright © 2025 [Victor Zverovich](https://github.com/vitaut)
+The class contains a port of the shortest double-to-decimal conversion of [Żmij](https://github.com/vitaut/zmij) by Victor Zverovich, including the conversion of the digits to text by Xiang JunBo and the SIMD instruction sequence of Dougall Johnson, which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above). Copyright © 2025 [Victor Zverovich](https://github.com/vitaut)
 
 The class contains a copy of [Hedley](https://nemequ.github.io/hedley/) from Evan Nemerson which is licensed as [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/).
 

docs/mkdocs/mkdocs.yml

@@ -281,7 +281,6 @@ nav:
           - 'items': api/basic_json_view/items.md
           - 'materialize': api/basic_json_view/materialize.md
           - 'number_token': api/basic_json_view/number_token.md
-          - 'operator bool': api/basic_json_view/operator_bool.md
           - 'operator[]': api/basic_json_view/operator[].md
           - 'size': api/basic_json_view/size.md
           - 'source_offset': api/basic_json_view/source_offset.md