json_view: dump canada.json faster than yyjson (batched float decisions)

Dump of float tokens of 16 or 17 digits without an exponent (SIMD targets, little-endian), in batches of up to 256 floats ahead of the walk, one loop per step: - the digits (16 bytes at a time) and the token's last four digits; - locate_token(): Eisel-Lemire's product gives the double x, and x's position relative to the token is exact in a 64-bit fixed-point number (56 bits after the point of the token's last digit), with the radius of its interval; - token_digits_1/2(), one loop per kind (g): the multiple of 10^g nearest to x if it is in the interval, else the multiple of 10^(g - 1) nearest to x, the digits that dump() (Zmij) writes. Exact ties between two candidates (like 754570942.33984373, whose double is ...33984375) are left to the full conversion; - the output is the token with its last four digits replaced; a rounding that carries further goes to the writer of Zmij's results. The batch storage is on the heap (allocated by the first conversion), and a pair of floats like [x, y] in a read-only document is written without a frame. Reading: get<double>() converts such tokens with a lean Eisel-Lemire (coordinate_float()). Output is byte-identical to the previous writer: 10^9 generated tokens in one array and 3 * 10^8 in arrays of 1 to 9 elements on Apple M1, 2.5 * 10^8 and 10^8 on x86-64 (all exponents, subnormals, 15-18 digits, exact binary fractions and ties, near-short decimals); get<double>() equals json::parse on 5 * 10^7 values. compare.py --download, Apple M1 Max, clang 21, 30 rounds, two runs (and two with aligned code: -falign-loops=64 -mllvm -align-all-functions=6); json_view, and the factor of yyjson 0.13.0 over it: - canada dump 3636 -> 1623 us (0.47x -> 1.06x; aligned 1.05x) - canada traverse 2287 -> 1817 us (0.85x -> 1.07x; aligned 0.99x) - canada patch 4628 -> 2735 us (0.80x -> 1.36x) - canada update 4763 -> 2911 us (0.78x -> 1.28x) Linux x86-64 (Haswell VPS, GCC 13, one run): canada dump 0.53x -> 0.72x, traverse 0.89x -> 0.95x, patch 1.01x -> 1.17x, update 0.96x -> 1.13x. Open: canada traverse in the aligned build (0.99x) and canada dump on x86-64 (0.72x) are still behind yyjson. Canada parse and select are about 2 % slower in bench_view in both builds, with identical parser code (likely layout; the corpus parse row is not slower). In the plain build only, rpc, status, and twitter dump are 2-4 % slower (0-6 % faster in the aligned build). Signed-off-by: Niels Lohmann <mail@nlohmann.me>
json_view: faster float tokens of 16 to 19 digits (canada dump, traverse)
2026-10-25 07:18:55 +00:00 · 2026-10-25 07:23:43 +01:00 · 2026-10-25 07:23:42 +01:00 · 2026-10-25 06:18:07 +01:00 · 2026-10-25 06:17:51 +01:00 · 2026-10-25 06:17:50 +01:00
168 changed files with 6898 additions and 7018 deletions
@@ -30,6 +30,14 @@ struct adl_serializer {
 - [**from_json**](from_json.md) - convert a JSON value to any value type
 - [**to_json**](to_json.md) - convert any value type to a JSON value

+## See also
+
+- [Arbitrary type conversions](../../features/arbitrary_types.md) - how to make your types convertible
+- [**get**](../basic_json/get.md) / [**get_to**](../basic_json/get_to.md) - convert a JSON value to a C++ type
+- [**basic_json**](../basic_json/basic_json.md) - construct a JSON value from a C++ value
+- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE**](../macros/nlohmann_define_type_intrusive.md) - generate the conversion functions for a type
+- [Specializing enum conversion](../../features/enum_conversion.md)
+
 ## Version history

 - Added in version 2.1.0.
@@ -23,6 +23,9 @@ Checks whether the input is valid JSON.
    respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
    the iterator type with `operator!=`.
    
+    Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its
+    low surrogate, and a code point above `U+10FFFF` all make this function return `false`.
+
 Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
 (i.e., a parse error) nor creates diagnostic information.

@@ -35,9 +38,12 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
    - a `#!c FILE` pointer (throws if null)
    - a C-style array of characters
    - a pointer to a null-terminated string of single byte characters (throws if null)
-    - a `std::string`
+    - a `std::string` or a `std::string_view` (C++17)
    - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
      (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
+    - wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
+      (`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
+      null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported

 `IteratorType`
 :   a compatible iterator type, for instance.
@@ -125,6 +131,21 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
    --8<-- "examples/accept__iterator_pair.output"
    ```

+??? example "Example: (3) reading from UTF-16 strings"
+
+    The encoding is deduced from the character type of the input. String literals like `u"..."`, `U"..."`, and
+    `L"..."` work as well.
+
+    ```cpp
+    --8<-- "examples/accept__wide_string.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/accept__wide_string.output"
+    ```
+
 ## See also

 - [parse](parse.md) - deserialize from a compatible input
@@ -151,6 +172,9 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
+- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
+  a code point above `U+10FFFF`) is rejected in version 3.13.0; before that, some such sequences were accepted or
+  ended the input silently.

 !!! warning "Deprecation"

@@ -239,9 +239,8 @@ Strong exception safety: if an exception occurs, the original value stays intact

 1. Added in version 1.0.0.
 2. Added in version 1.0.0.
-3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
-   already supported by [`operator[]`](operator[].md), [`value`](value.md), [`find`](find.md), and other lookup
-   functions.
+3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
+   across the lookup functions.
 4. Added in version 2.0.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
 [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
 a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
@@ -63,4 +63,4 @@ Constant.
 ## Version history

 - Added in version 1.0.0.
- Adjusted code to return reference to binary values in version 3.8.0.
+- Binary values are supported since version 3.8.0.
@@ -482,15 +482,15 @@ basic_json(basic_json&& other) noexcept;

 ## Version history

-1. Since version 1.0.0.
-2. Since version 1.0.0.
-3. Since version 2.1.0.
-4. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
+1. Added in version 1.0.0.
+2. Added in version 1.0.0.
+3. Added in version 2.1.0.
+4. Added in version 3.1.2. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
   version 3.13.0.
-5. Since version 1.0.0.
-6. Since version 1.0.0.
-7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
+5. Added in version 1.0.0.
+6. Added in version 1.0.0.
+7. Added in version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
   that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied,
   unlike the other primitive types.
-8. Since version 1.0.0.
-9. Since version 1.0.0.
+8. Added in version 1.0.0.
+9. Added in version 1.0.0.
@@ -141,9 +141,8 @@ Logarithmic in the size of the JSON object.
 ## Version history

 1. Added in version 3.11.0.
-2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Fixed in
-   version 3.13.0 to consistently accept `std::string_view`-convertible keys, as already supported by
-   [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup functions.
+2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Support for keys
+   convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
 3. Added in version 3.7.0.
 4. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of
   causing undefined behavior at runtime.
@@ -92,8 +92,7 @@ Logarithmic in the size of the JSON object.
 ## Version history

 1. Added in version 3.11.0.
-2. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0. Fixed in version 3.13.0 to
-   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
-   [`at`](at.md), [`value`](value.md), and other lookup functions.
+2. Added in version 1.0.0. Changed to support comparable key types in version 3.11.0. Support for keys convertible to
+   `std::string_view` added in version 3.13.0, consistently across the lookup functions.
 3. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of
   causing undefined behavior at runtime.
@@ -69,6 +69,6 @@ Logarithmic in the size of the container, O(log(`size()`)).

 ## Version history

- Since version 2.0.8.
+- Added in version 2.0.8.
 - Fixed in version 3.13.0: for [`ordered_json`](../ordered_json.md), the value could previously only be passed as an
  rvalue; it can now also be passed as an lvalue or a `#!cpp const` lvalue, matching the behavior of `json`.
@@ -67,5 +67,5 @@ Amortized constant.

 ## Version history

- Since version 2.0.8.
+- Added in version 2.0.8.
 - Returns reference since 3.7.0.
@@ -213,7 +213,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 3. Added in version 1.0.0.
-4. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
-   already supported by [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup
-   functions.
+4. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
+   across the lookup functions.
 5. Added in version 1.0.0.
@@ -84,4 +84,4 @@ constructor.

 ## Version history

- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -99,8 +99,7 @@ Logarithmic in the size of the JSON object.
 ## Version history

 1. Added in version 3.11.0.
-2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Fixed in version 3.13.0 to
-   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
-   [`at`](at.md), [`value`](value.md), and other lookup functions.
+2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Support for keys convertible to
+   `std::string_view` added in version 3.13.0, consistently across the lookup functions.
 3. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of
   causing undefined behavior at runtime.
@@ -57,4 +57,4 @@ Constant.
 ## Version history

 - Added in version 1.0.0.
- Adjusted code to return reference to binary values in version 3.8.0.
+- Binary values are supported since version 3.8.0.
@@ -188,6 +188,6 @@ overload (3).

 ## Version history

-1. Since version 2.1.0.
-2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0.
-3. Since version 1.0.0.
+1. Added in version 2.1.0.
+2. Added in version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.1.2.
+3. Added in version 1.0.0.
@@ -76,5 +76,5 @@ Depends on the `json_serializer<ValueType>::from_json()` implementation.

 ## Version history

- Since version 3.3.0.
+- Added in version 3.3.0.
 - Added a `static_assert` with a clear message for `const` arguments in version 3.13.0.
@@ -44,6 +44,22 @@ are collected in [Template Parameter Requirements](../../features/types/template
 - [**json**](../json.md) - default specialization
 - [**ordered_json**](../ordered_json.md) - a specialization that maintains the insertion order of object keys

+## Documents and views
+
+Besides `basic_json`, the library offers a second way to hold a parsed JSON text: a
+[`basic_json_document`](../basic_json_document/index.md), which owns or borrows the text and holds a flat index of the
+values in it, and a [`basic_json_view`](../basic_json_view/index.md), a read-only handle to one value of such a document.
+Both are defined in the header `<nlohmann/json_view.hpp>`; see
+[Zero-copy JSON views](../../features/json_view.md) for the concept and the trade-offs.
+
+- [**json_document**](../json_document.md) / [**ordered_json_document**](../ordered_json_document.md) - read-only
+  documents of the `basic_json` specialization they belong to
+- [**json_editable_document**](../json_editable_document.md) /
+  [**ordered_json_editable_document**](../ordered_json_editable_document.md) - documents that can be modified in place
+- [**json_view**](../json_view.md) / [**ordered_json_view**](../ordered_json_view.md) - views of a document
+- [**json_editable_view**](../json_editable_view.md) /
+  [**ordered_json_editable_view**](../ordered_json_editable_view.md) - views of an editable document
+
 ## Iterator invalidation

 All operations that add values to an **array** ([`push_back`](push_back.md) , [`operator+=`](operator+=.md),
@@ -343,6 +359,9 @@ Access to the JSON value
 ## See also

 - [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
+- [basic_json_document](../basic_json_document/index.md) / [basic_json_view](../basic_json_view/index.md) - parse a JSON
+  text into a flat index and read it through a view
+- [Zero-copy JSON views](../../features/json_view.md) - when to use a document and a view instead of a `basic_json`

 ## Version history

@@ -75,4 +75,4 @@ classDiagram

 ## Version history

- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -104,8 +104,8 @@ When iterating over an array, `key()` will return the index of the element as st

 ## Version history

- Added `iterator_wrapper` in version 3.0.0.
- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
+- Added in version 3.1.0 as the replacement of the static function `iterator_wrapper`, which was available since
+  version 1.0.0 and is deprecated since version 3.1.0.
 - Added structured binding support in version 3.5.0.

 !!! warning "Deprecation"
@@ -51,4 +51,4 @@ deserializes. See [Template Parameter Requirements](../../features/types/templat

 ## Version history

- Since version 2.0.0.
+- Added in version 2.1.0.
@@ -71,6 +71,6 @@ returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was

 ## Version history

- Added in version 3.0.0.
+- Added in version 3.1.0.
 - Fixed use of freed or relocated memory when `apply_patch` is `#!cpp *this` or refers to a value contained in
  `#!cpp *this`, in version 3.13.0.
@@ -128,6 +128,6 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se

 ## Version history

-1. Since version 1.0.0.
-2. Since version 1.0.0.
-3. Since version 2.0.0.
+1. Added in version 1.0.0.
+2. Added in version 1.0.0.
+3. Added in version 2.0.0.
@@ -284,10 +284,10 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Added in version 1.0.0. Fixed in version 3.13.0 to throw `#!cpp std::length_error` instead of emptying the array and
   accessing it out of bounds when `idx` equals the maximum value of `size_type`. A missing index in the const version
   is guarded by a runtime assertion since version 3.13.0.
-2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3)
-   in version 3.11.0.
-3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
-   already supported by [`at`](at.md), [`value`](value.md), [`find`](find.md), and other lookup functions.
+2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. The `T* key` overloads forward to
+   overload 3 since version 3.11.0.
+3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
+   across the lookup functions.
 4. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since
   version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
 [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
@@ -89,6 +89,6 @@ Linear in the size of the JSON value.

 ## Version history

- Since version 1.0.0.
+- Added in version 1.0.0.
 - Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added
  in version 3.9.0.
@@ -75,4 +75,4 @@ classDiagram

 ## Version history

- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -76,4 +76,4 @@ classDiagram

 ## Version history

- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -25,6 +25,10 @@ static basic_json parse(IteratorType first, SentinelType last,
    respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
    the iterator type with `operator!=`.

+    Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its
+    low surrogate, and a code point above `U+10FFFF` all yield a
+    [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101).
+
 ## Template parameters

 `InputType`
@@ -34,9 +38,12 @@ static basic_json parse(IteratorType first, SentinelType last,
    - a `FILE` pointer (throws if null)
    - a C-style array of characters
    - a pointer to a null-terminated string of single byte characters (throws if null)
-    - a `std::string`
+    - a `std::string` or a `std::string_view` (C++17)
    - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
      (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
+    - wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
+      (`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
+      null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported

 `IteratorType`
 :   a compatible iterator type, for instance.
@@ -112,6 +119,13 @@ By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input
 outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-bytes-in-the-input) for details and the
 [`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) macro to opt into rejecting it instead.

+!!! tip "Parsing into a document instead of a value"
+
+    [`basic_json_document::parse`](../basic_json_document/parse.md) accepts the same inputs and the same options, but
+    keeps the result as a flat index of the parsed values instead of a tree of `basic_json` values. It is faster and uses
+    less memory when only parts of the document are read, and it also accepts a pointer to a null-terminated wide string,
+    which `parse()` does not. See [Zero-copy JSON views](../../features/json_view.md).
+
 !!! tip "Performance"

    Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A
@@ -250,6 +264,22 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
    --8<-- "examples/trailing_commas.output"
    ```

+??? example "Example: parse from UTF-16, UTF-32, and wide strings"
+
+    The encoding is deduced from the character type of the input; `std::u16string` and `std::u32string` are interpreted
+    as UTF-16 and UTF-32, and `std::wstring` uses the platform's `wchar_t` width. String literals like `u"..."`,
+    `U"..."`, and `L"..."` work as well, as do iterators over wide characters.
+
+    ```cpp
+    --8<-- "examples/parse__wide_string.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/parse__wide_string.output"
+    ```
+
 ## See also

 - [accept](accept.md) - check if the input is valid JSON
@@ -280,6 +310,9 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
  time).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) restores `std::fgetc`).
+- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
+  a code point above `U+10FFFF`) is rejected with `parse_error.101` in version 3.13.0; before that, some such
+  sequences were accepted or ended the input silently.

 !!! warning "Deprecation"

@@ -84,4 +84,4 @@ or the end of file. This also holds true when reading a byte vector for binary f

 ## Version history

- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -125,6 +125,6 @@ throws.

 ## Version history

-1. Since version 1.0.0.
-2. Since version 1.0.0.
-3. Since version 2.0.0.
+1. Added in version 1.0.0.
+2. Added in version 1.0.0.
+3. Added in version 2.0.0.
@@ -31,6 +31,10 @@ Read from input and generate SAX events
    respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
    the iterator type with `operator!=`.

+    Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its
+    low surrogate, and a code point above `U+10FFFF` all yield a
+    [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101).
+
 The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).

 ## Template parameters
@@ -42,8 +46,12 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
    - a `FILE` pointer
    - a C-style array of characters
    - a pointer to a null-terminated string of single byte characters
+    - a `std::string` or a `std::string_view` (C++17)
    - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
      (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
+    - wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
+      (`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
+      null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported

 `IteratorType`
 :   a compatible iterator type for overload (2); a pair of character iterators whose `value_type` is an integral type
@@ -160,6 +168,9 @@ use the same file with stdio functions, but it must not wait for another thread
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
+- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
+  a code point above `U+10FFFF`) is rejected with `parse_error.101` in version 3.13.0; before that, some such
+  sequences were accepted or ended the input silently.

 !!! warning "Deprecation"

@@ -182,10 +182,10 @@ Constant.

 ## Version history

-1. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
-2. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
-3. Since version 1.0.0.
-4. Since version 1.0.0.
-5. Since version 1.0.0.
-6. Since version 3.8.0.
-7. Since version 3.8.0.
+1. Added in version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
+2. Added in version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
+3. Added in version 1.0.0.
+4. Added in version 1.0.0.
+5. Added in version 1.0.0.
+6. Added in version 3.8.0.
+7. Added in version 3.8.0.
@@ -124,5 +124,3 @@ Linear in the size of the JSON value `j`.
  [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
  array or object was silently skipped, producing invalid BJData.
- Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0; previously, they were
-  silently truncated to 64 bits.
@@ -76,4 +76,4 @@ classDiagram

 ## Version history

- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -231,11 +231,8 @@ changes to any JSON value.
 1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version
   3.11.0. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time
   instead of causing undefined behavior at runtime.
-2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Fixed in version 3.13.0
-   to consistently accept `std::string_view`-convertible keys, as already supported by
-   [`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md), and other lookup functions.
-3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving
-   `ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or
-   `default_value`, as documented). Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109)
+2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Support for keys
+   convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
+3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109)
   instead of returning `default_value` for a one-character array index that is not a digit (e.g., `/x`) in version
   3.13.0, as it already did for longer ones.
@@ -9,8 +9,8 @@ class basic_json_document;

 A parsed JSON text, held as a flat index of its values
 ([16 bytes per value](../../home/architecture.md#node-index-of-json-views)) instead of a tree of `BasicJsonType` values.
-Strings and numbers stay in the source text; only strings that contain escapes are decoded, into one buffer owned by
-the document. [`basic_json_view`](../basic_json_view/index.md) is a read-only handle to one value of a
+Strings and floating-point numbers stay in the source text; integers are converted while parsing, and strings that
+contain escapes are decoded into one buffer owned by the document. [`basic_json_view`](../basic_json_view/index.md) is a read-only handle to one value of a
 `basic_json_document`; [`materialize()`](../basic_json_view/materialize.md) turns a subtree into the
 `BasicJsonType` value that [`BasicJsonType::parse()`](../basic_json/parse.md) would have produced for it.

@@ -115,6 +115,13 @@ points apply to every edit:
  [`source_offset()`](../basic_json_view/source_offset.md) of a value introduced by an edit is
  `#!cpp static_cast<std::size_t>(-1)`, the same value it reports for a decoded string.

+## See also
+
+- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
+- [**basic_json_view**](../basic_json_view/index.md) - the non-owning handle to a value in a document
+- [**json_document**](../json_document.md) and [**json_editable_document**](../json_editable_document.md) - the default specializations
+- [**materialize**](../basic_json_view/materialize.md) - build a `basic_json` value from a view
+
 ## Version history

 - Added in version 3.13.0.
@@ -21,17 +21,19 @@ static basic_json_document parse(IteratorType first, IteratorType last,

 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. They take the same inputs as `BasicJsonType::parse()`. Byte
-inputs that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, non-contiguous
-iterators) are read into a copy that the document owns -- see the Notes. Use [`parse_copy()`](parse_copy.md) to get an
-owned copy of a borrowable input as well.
+the input) instead of a tree of `BasicJsonType` values. They accept every input `BasicJsonType::parse()` takes, and in
+addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of
+single-byte characters that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, which
+must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns -- see the
+Notes. Use [`parse_copy()`](parse_copy.md) to get an owned copy of a borrowable input
+as well.

 ## Template parameters

 `InputType`
 :   A compatible input, for instance:

-    - a `#!cpp std::string`, `#!cpp std::string_view`, or a C-style array of single-byte characters
+    - a `#!cpp std::string`, a `#!cpp std::string_view` (C++17), 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.
@@ -47,6 +49,10 @@ owned copy of a borrowable input as well.
    `#!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

+Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low
+surrogate, and a code point above `U+10FFFF` all yield a
+[`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101).
+
 ## Parameters

 `input` (in)
@@ -155,3 +161,5 @@ buffer of a given length, pass a pair of pointers: `#!cpp parse(ptr, ptr + len)`
 ## Version history

 - Added in version 3.13.0.
+- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
+  a code point above `U+10FFFF`) is rejected with `parse_error.101`.
@@ -143,6 +143,13 @@ still refers to it -- including ones taken before the change -- reads the new va

 - [**source_offset**](source_offset.md) - byte offset of this value in the document's source text

+## 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
+
 ## Version history

 - Added in version 3.13.0.
@@ -51,4 +51,4 @@ byte_container_with_subtype(container_type&& container, subtype_type subtype);

 ## Version history

-Since version 3.8.0.
+Added in version 3.8.0.
@@ -39,4 +39,4 @@ Constant.

 ## Version history

-Since version 3.8.0.
+Added in version 3.8.0.
@@ -42,4 +42,4 @@ Constant.

 ## Version history

-Since version 3.8.0.
+Added in version 3.8.0.
@@ -29,6 +29,14 @@ specific naming scheme in order to override the binary type.
 - [**has_subtype**](has_subtype.md) - return whether the value has a subtype
 - [**clear_subtype**](clear_subtype.md) - clears the binary subtype

+## See also
+
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [**binary**](../basic_json/binary.md) - create a binary array value
+- [**get_binary**](../basic_json/get_binary.md) - get a reference to the stored binary value
+- [**binary_t**](../basic_json/binary_t.md) - type for binary arrays
+- [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values
+
 ## Version history

 - Added in version 3.8.0.
@@ -44,4 +44,4 @@ Constant.

 ## Version history

-Since version 3.8.0.
+Added in version 3.8.0.
@@ -30,4 +30,4 @@ types.

 ## Version history

-Since version 1.0.0.
+Added in version 1.0.0.
@@ -32,4 +32,4 @@ specialization.

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -40,4 +40,4 @@ parsing, without ever rewriting the source text -- see [Edits](basic_json_docume

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -38,4 +38,4 @@ still referring to it seeing the change, see [Edits](basic_json_document/index.m

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -51,5 +51,5 @@ operator string_t() const

 ## Version history

- Since version 2.0.0.
+- Added in version 2.0.0.
 - Changed type to `string_t` and deprecated in version 3.11.0.
@@ -49,5 +49,5 @@ ptr == json_pointer(ptr.to_string());

 ## Version history

- Since version 2.0.0.
+- Added in version 2.0.0.
 - Changed return type to `string_t` in version 3.11.0.
@@ -59,6 +59,13 @@ leading `-` sign.
 - [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read
 - [**string**](string.md) (_virtual_) - a string value was read

+## See also
+
+- [SAX interface](../../features/parsing/sax_interface.md) - guide to event-based parsing
+- [**sax_parse**](../basic_json/sax_parse.md) - generate SAX events from an input
+- [**parse**](../basic_json/parse.md) - DOM parsing, with optional [parser callbacks](../../features/parsing/parser_callbacks.md)
+- [Parse exceptions](../../features/parsing/parse_exceptions.md)
+
 ## Version history

 - Added in version 3.2.0.
@@ -31,4 +31,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of a [`j

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -137,4 +137,13 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES**](nlohmann_define_type_with_names.md) - serialize/deserialize
  a derived class; uses default values; uses custom names
 - [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES**](nlohmann_define_type_with_names.md) - serialize a derived
-  class; uses custom names
+  class; uses custom names
+
+## See also
+
+- [Macros](../../features/macros.md) - guide to the supported macros
+- [Runtime assertions](../../features/assertions.md)
+- [Arbitrary type conversions](../../features/arbitrary_types.md) - using the `NLOHMANN_DEFINE_TYPE_*` macros
+- [Enum conversion](../../features/enum_conversion.md) - using `NLOHMANN_JSON_SERIALIZE_ENUM`
+- [The `nlohmann` namespace](../../features/namespace.md)
+- [CMake integration](../../integration/cmake.md) - setting macros from the build system
@@ -42,4 +42,4 @@ parsing an object of `n` keys costs O(n²) rather than O(n log n). See

 ## Version history

-Since version 3.9.0.
+Added in version 3.9.0.
@@ -35,4 +35,4 @@ of object keys, instead of sorting them like [`json_document`](json_document.md)

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -44,4 +44,4 @@ members [`set`](basic_json_document/set.md) added -- instead of sorting them lik

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -37,4 +37,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -32,4 +32,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an

 ## Version history

-Since version 3.13.0.
+Added in version 3.13.0.
@@ -58,7 +58,7 @@ particular, a 3.x release does not:
 - remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does.

 Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are
-documented in the [release notes](../home/releases.md).
+documented in the [release notes](../home/releases/index.md).

 The following are **not** part of the public API and may change in any release, including patch releases:

@@ -18,3 +18,32 @@
    white-space: nowrap;
    cursor: help;
 }
+
+/* byte layout tables of the binary formats */
+.md-typeset .byte-layout td code {
+    white-space: pre-wrap;
+}
+
+.md-typeset .bl {
+    display: inline-block;
+    padding: 0 .25em;
+    border-radius: .2em;
+    font-family: var(--md-code-font-family);
+    font-size: .85em;
+    white-space: nowrap;
+}
+
+.md-typeset .bl-t {
+    background-color: rgba(66, 133, 244, .25);
+    box-shadow: inset 0 -.12em 0 rgba(66, 133, 244, .8);
+}
+
+.md-typeset .bl-l {
+    background-color: rgba(251, 140, 0, .25);
+    box-shadow: inset 0 -.12em 0 rgba(251, 140, 0, .8);
+}
+
+.md-typeset .bl-d {
+    background-color: rgba(67, 160, 71, .25);
+    box-shadow: inset 0 -.12em 0 rgba(67, 160, 71, .8);
+}
@@ -0,0 +1,18 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // a valid JSON text, given as UTF-16
+    const std::u16string valid_text = u"{\"name\":\"\u00e9\"}";
+
+    // an invalid JSON text, given as UTF-16
+    const std::u16string invalid_text = u"{\"name\":\"\u00e9\",}";
+
+    std::cout << std::boolalpha
+              << json::accept(valid_text) << ' '
+              << json::accept(invalid_text) << '\n';
+}
@@ -0,0 +1 @@
+true false
@@ -0,0 +1,27 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // the same JSON text, given in different encodings
+    const std::string utf8 = "{\"name\":\"\u00e9\"}";
+    const std::u16string utf16 = u"{\"name\":\"\u00e9\"}";
+    const std::u32string utf32 = U"{\"name\":\"\u00e9\"}";
+    const std::wstring wide = L"{\"name\":\"\u00e9\"}";
+
+    // the encoding is deduced from the character type of the input, and all
+    // of them yield the same value
+    std::cout << json::parse(utf8) << '\n'
+              << json::parse(utf16) << '\n'
+              << json::parse(utf32) << '\n'
+              << json::parse(wide) << '\n';
+
+    // a wide string literal works as well: u"..." is UTF-16, U"..." is UTF-32
+    std::cout << json::parse(u"[1, 2, 3]") << '\n';
+
+    // iterators over wide characters work as well
+    std::cout << json::parse(utf16.begin(), utf16.end()) << '\n';
+}
@@ -0,0 +1,6 @@
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+[1,2,3]
+{"name":"é"}
@@ -190,6 +190,41 @@ The library uses the following mapping from JSON values types to BJData types ac
    --8<-- "examples/to_bjdata.output"
    ```

+
+
+
+
+### Byte layout
+
+Consider the following JSON value (shown formatted for readability):
+
+```json
+{
+  "id": 300,
+  "name": "json",
+  "pi": 3.14,
+  "tags": [
+    "a",
+    "b"
+  ]
+}
+```
+
+`to_bjdata` encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
+
+<div class="byte-layout" markdown="0"><table>
+<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
+<tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr>
+<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">2C 01</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), little-endian</td></tr>
+<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr>
+<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>key: length 2; value: float64 (<code>D</code>), little-endian</td></tr>
+<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr>
+<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr>
+<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr>
+<tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr>
+<tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr>
+</tbody></table></div>
+
 ## Deserialization

 The library maps BJData types to JSON value types as follows:
@@ -105,6 +105,41 @@ serialized as 0x81 0x65 0xFF, but `[1,2,3,4,"e"]` as 0x85 0x91 0x92 0x93 0x94 0x
    --8<-- "examples/to_bon8.output"
    ```

+
+
+
+
+### Byte layout
+
+Consider the following JSON value (shown formatted for readability):
+
+```json
+{
+  "id": 300,
+  "name": "json",
+  "pi": 3.14,
+  "tags": [
+    "a",
+    "b"
+  ]
+}
+```
+
+`to_bon8` encodes it to 35 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
+
+<div class="byte-layout" markdown="0"><table>
+<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
+<tr><td><code>{</code></td><td><span class="bl bl-t">8A</span></td><td>object with 4 members</td></tr>
+<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-d">69 64</span> <span class="bl bl-t">C4</span> <span class="bl bl-d">04</span></td><td>key: UTF-8 bytes; the string ends at the next byte, which cannot continue a UTF-8 character; value: 2-byte positive integer (lead byte, then a byte below 0x80)</td></tr>
+<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-l">FF</span> <span class="bl bl-d">6A 73 6F 6E</span> <span class="bl bl-l">FF</span></td><td>key: UTF-8 bytes; 0xFF terminates the string as another string follows; value: UTF-8 bytes; terminated as a string key follows</td></tr>
+<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-d">70 69</span> <span class="bl bl-t">8F</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: UTF-8 bytes; value: binary64 (IEEE 754, big-endian); its marker also ends <code>&quot;pi&quot;</code></td></tr>
+<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">82</span></td><td>key: UTF-8 bytes; value: array with 2 elements; its marker also ends <code>&quot;tags&quot;</code></td></tr>
+<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-d">61</span> <span class="bl bl-l">FF</span></td><td>UTF-8 bytes; terminated as a string follows</td></tr>
+<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-d">62</span> <span class="bl bl-l">FF</span></td><td>UTF-8 bytes; terminated as nothing follows</td></tr>
+<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr>
+<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr>
+</tbody></table></div>
+
 ## Deserialization

 The library maps BON8 types to JSON value types as follows:
@@ -61,6 +61,41 @@ The library uses the following mapping from JSON values types to BSON types:
    ```


+
+
+
+
+### Byte layout
+
+Consider the following JSON value (shown formatted for readability):
+
+```json
+{
+  "id": 300,
+  "name": "json",
+  "pi": 3.14,
+  "tags": [
+    "a",
+    "b"
+  ]
+}
+```
+
+`to_bson` encodes it to 69 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
+
+<div class="byte-layout" markdown="0"><table>
+<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
+<tr><td><code>{</code></td><td><span class="bl bl-l">45 00 00 00</span></td><td>document size: 69 bytes (int32, little-endian)</td></tr>
+<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-t">10</span> <span class="bl bl-d">69 64 00</span> <span class="bl bl-d">2C 01 00 00</span></td><td>int32 element; key as NUL-terminated string; value (little-endian)</td></tr>
+<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">6E 61 6D 65 00</span> <span class="bl bl-l">05 00 00 00</span> <span class="bl bl-d">6A 73 6F 6E 00</span></td><td>string element; key; length incl. NUL (int32); NUL-terminated UTF-8 bytes</td></tr>
+<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-t">01</span> <span class="bl bl-d">70 69 00</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>double element; key; value (little-endian)</td></tr>
+<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-t">04</span> <span class="bl bl-d">74 61 67 73 00</span> <span class="bl bl-l">17 00 00 00</span></td><td>array element; key; embedded document of 23 bytes (keys are the indices)</td></tr>
+<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">30 00</span> <span class="bl bl-l">02 00 00 00</span> <span class="bl bl-d">61 00</span></td><td>string element; key <code>&quot;0&quot;</code>; length 2; <code>a</code> + NUL</td></tr>
+<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">31 00</span> <span class="bl bl-l">02 00 00 00</span> <span class="bl bl-d">62 00</span></td><td>string element; key <code>&quot;1&quot;</code>; length 2; <code>b</code> + NUL</td></tr>
+<tr><td><code>]</code></td><td><span class="bl bl-t">00</span></td><td>end of the array document</td></tr>
+<tr><td><code>}</code></td><td><span class="bl bl-t">00</span></td><td>end of the document</td></tr>
+</tbody></table></div>
+
 ## Deserialization

 The library maps BSON record types to JSON value types as follows:
@@ -110,6 +110,41 @@ see "binary" cells in the table above.
    --8<-- "examples/to_cbor.output"
    ```

+
+
+
+
+### Byte layout
+
+Consider the following JSON value (shown formatted for readability):
+
+```json
+{
+  "id": 300,
+  "name": "json",
+  "pi": 3.14,
+  "tags": [
+    "a",
+    "b"
+  ]
+}
+```
+
+`to_cbor` encodes it to 39 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
+
+<div class="byte-layout" markdown="0"><table>
+<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
+<tr><td><code>{</code></td><td><span class="bl bl-t">A4</span></td><td>map with 4 key/value pairs</td></tr>
+<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-t">62</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">19</span> <span class="bl bl-d">01 2C</span></td><td>key: text string of length 2, then its UTF-8 bytes; value: unsigned integer, 2 bytes follow (big-endian)</td></tr>
+<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-t">64</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">64</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: text string of length 4; value: text string of length 4</td></tr>
+<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-t">62</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">FB</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: text string of length 2; value: double-precision float (IEEE 754, big-endian)</td></tr>
+<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-t">64</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">82</span></td><td>key: text string of length 4; value: array with 2 elements</td></tr>
+<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">61</span> <span class="bl bl-d">61</span></td><td>text string of length 1</td></tr>
+<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">61</span> <span class="bl bl-d">62</span></td><td>text string of length 1</td></tr>
+<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr>
+<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr>
+</tbody></table></div>
+
 ## Deserialization

 The library maps CBOR types to JSON value types as follows:
@@ -45,12 +45,19 @@ See [binary values](../binary_values.md) for more information.
 | BJData             | 53.2 %      | 91.1 %       | 78.1 %            | 96.6 %        |
 | BJData (size)      | 58.6 %      | 92.1 %       | 86.7 %            | 97.4 %        |
 | BJData (size+type) | 58.6 %      | 92.1 %       | 86.5 %            | 97.4 %        |
-| BON8               | 50.5 %      | 83.8 %       | 63.5 %            | 87.5 %        |
+| BON8               | **50.5 %**  | **83.8 %**   | **63.5 %**        | **87.5 %**    |
 | BSON               | 85.8 %      | 95.2 %       | 95.8 %            | 106.7 %       |
-| CBOR               | 50.5 %      | 86.3 %       | 68.4 %            | 88.0 %        |
-| MessagePack        | 50.5 %      | 86.0 %       | 68.5 %            | 87.9 %        |
+| CBOR               | **50.5 %**  | 86.3 %       | 68.4 %            | 88.0 %        |
+| MessagePack        | **50.5 %**  | 86.0 %       | 68.5 %            | 87.9 %        |
 | UBJSON             | 53.2 %      | 91.3 %       | 78.2 %            | 96.6 %        |
 | UBJSON (size)      | 58.6 %      | 92.3 %       | 86.8 %            | 97.4 %        |
 | UBJSON (size+type) | 55.9 %      | 92.3 %       | 85.0 %            | 95.0 %        |

-Sizes compared to minified JSON value.
+Sizes compared to minified JSON value; the smallest size per file is printed in bold.
+
+## See also
+
+- [Binary values](../binary_values.md) - binary values and subtypes
+- [**to_cbor**](../../api/basic_json/to_cbor.md) / [**from_cbor**](../../api/basic_json/from_cbor.md), [**to_msgpack**](../../api/basic_json/to_msgpack.md) / [**from_msgpack**](../../api/basic_json/from_msgpack.md), [**to_bson**](../../api/basic_json/to_bson.md) / [**from_bson**](../../api/basic_json/from_bson.md), [**to_ubjson**](../../api/basic_json/to_ubjson.md) / [**from_ubjson**](../../api/basic_json/from_ubjson.md), [**to_bjdata**](../../api/basic_json/to_bjdata.md) / [**from_bjdata**](../../api/basic_json/from_bjdata.md), [**to_bon8**](../../api/basic_json/to_bon8.md) / [**from_bon8**](../../api/basic_json/from_bon8.md) - the conversion functions
+- [Parsing untrusted input](../parsing/untrusted_input.md)
+- [SAX interface](../parsing/sax_interface.md) - decode binary formats without building a value
@@ -91,6 +91,41 @@ specification:
    --8<-- "examples/to_msgpack.output"
    ```

+
+
+
+
+### Byte layout
+
+Consider the following JSON value (shown formatted for readability):
+
+```json
+{
+  "id": 300,
+  "name": "json",
+  "pi": 3.14,
+  "tags": [
+    "a",
+    "b"
+  ]
+}
+```
+
+`to_msgpack` encodes it to 39 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
+
+<div class="byte-layout" markdown="0"><table>
+<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
+<tr><td><code>{</code></td><td><span class="bl bl-t">84</span></td><td>map with 4 key/value pairs</td></tr>
+<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-t">A2</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">CD</span> <span class="bl bl-d">01 2C</span></td><td>key: fixstr of length 2, then its UTF-8 bytes; value: uint 16 (big-endian)</td></tr>
+<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-t">A4</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">A4</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: fixstr of length 4; value: fixstr of length 4</td></tr>
+<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-t">A2</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">CB</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: fixstr of length 2; value: float 64 (IEEE 754, big-endian)</td></tr>
+<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-t">A4</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">92</span></td><td>key: fixstr of length 4; value: fixarray with 2 elements</td></tr>
+<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">A1</span> <span class="bl bl-d">61</span></td><td>fixstr of length 1</td></tr>
+<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">A1</span> <span class="bl bl-d">62</span></td><td>fixstr of length 1</td></tr>
+<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr>
+<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr>
+</tbody></table></div>
+
 ## Deserialization

 The library maps MessagePack types to JSON value types as follows:
@@ -103,6 +103,41 @@ The library uses the following mapping from JSON values types to UBJSON types ac
    --8<-- "examples/to_ubjson.output"
    ```

+
+
+
+
+### Byte layout
+
+Consider the following JSON value (shown formatted for readability):
+
+```json
+{
+  "id": 300,
+  "name": "json",
+  "pi": 3.14,
+  "tags": [
+    "a",
+    "b"
+  ]
+}
+```
+
+`to_ubjson` encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
+
+<div class="byte-layout" markdown="0"><table>
+<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
+<tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr>
+<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">01 2C</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), big-endian</td></tr>
+<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr>
+<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: length 2; value: float64 (<code>D</code>), big-endian</td></tr>
+<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr>
+<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr>
+<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr>
+<tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr>
+<tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr>
+</tbody></table></div>
+
 ## Deserialization

 The library maps UBJSON types to JSON value types as follows:
@@ -38,6 +38,18 @@ which avoids repeating it:
    --8<-- "examples/get_to.output"
    ```

+!!! info "Getting values out of a document or a view"
+
+    A [view](../api/basic_json_view/index.md) offers the same `get<T>()` conversion. For the built-in types (booleans,
+    numbers, strings, `#!cpp std::vector`, `#!cpp std::map`, ...) it reads the value straight from the document's
+    index, without building a `basic_json` value first; user-defined types with a `from_json()` are converted from a
+    `basic_json` value, see the [list](../api/basic_json_view/get.md). Two conversions never copy at all:
+    [`get_string()`](../api/basic_json_view/get_string.md) returns a string as a view into the source text, and
+    [`number_token()`](../api/basic_json_view/number_token.md) returns a number exactly as it was written. Every other
+    type is obtained from a subtree that is built on demand with
+    [`materialize()`](../api/basic_json_view/materialize.md). See
+    [Zero-copy JSON views](json_view.md#getting-values-out-without-copying).
+
 The library already knows how to convert to and from the scalar types and the STL containers (such as
 `#!cpp std::vector`, `#!cpp std::map`, `#!cpp std::array`, `#!cpp std::optional`, and many more). Converting a JSON
 object back to a `#!cpp std::map` or a JSON array back to a `#!cpp std::vector` therefore works without any extra code:
@@ -234,3 +246,4 @@ The conversions above are built in for standard types. To make the same syntax w
 - [`get_ref`](../api/basic_json/get_ref.md) / [`get_ptr`](../api/basic_json/get_ptr.md) - access the stored value without copying
 - [Arbitrary types conversions](arbitrary_types.md) - support your own types
 - [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) - toggle implicit conversions
+- [Zero-copy JSON views](json_view.md) - get values out of a document or a view
@@ -1,7 +1,9 @@
 # Creating JSON values

 There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text
-instead, see [parsing](parsing/index.md).
+instead, see [parsing](parsing/index.md). A JSON text can also be parsed into a
+[document](../api/basic_json_document/index.md) and read through a [view](../api/basic_json_view/index.md) instead of
+into a value; see [Zero-copy JSON views](json_view.md).

 ## From C++ values

@@ -101,3 +103,4 @@ string `#!json "42"`.
 - [`operator""_json`](../api/operator_literal_json.md) - the `_json` literal
 - [Converting values](conversions.md) - which C++ types can be used
 - [Parsing](parsing/index.md) - create a value from JSON text
+- [Zero-copy JSON views](json_view.md) - create a document and a view from JSON text instead of a value
@@ -21,3 +21,12 @@ flowchart TD
    A --> F{"just testing first?"}
    F -->|"yes"| G["contains() / find()"]
 ```
+
+## See also
+
+- [**operator[]**](../../api/basic_json/operator%5B%5D.md) - unchecked access
+- [**at**](../../api/basic_json/at.md) - checked access
+- [**value**](../../api/basic_json/value.md) - access with default value
+- [**contains**](../../api/basic_json/contains.md) and [**find**](../../api/basic_json/find.md) - test for existence
+- [**front**](../../api/basic_json/front.md) and [**back**](../../api/basic_json/back.md) - first and last element
+- [**items**](../../api/basic_json/items.md) - iterate over keys and values
@@ -59,3 +59,11 @@ C++ types, and finally serialize it again.

    This section gives conceptual overviews. For the precise signature, parameters, and return value of a function, see
    the [API Documentation](../api/basic_json/index.md).
+
+## See also
+
+- [API documentation](../api/basic_json/index.md) - reference of all classes and functions
+- [FAQ](../home/faq.md) - answers to common questions
+- [Exceptions](../home/exceptions.md) - all exceptions and their error codes
+- [Design goals](../home/design_goals.md)
+- [Integration](../integration/index.md) - how to add the library to a project
@@ -287,6 +287,23 @@ external dependency and is not defined by default.

 See [full documentation of `JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md).

+## `JSON_VIEW_NO_SIMD`
+
+When defined, the parser of [`basic_json_document`](../api/basic_json_document/index.md)
+(`<nlohmann/json_view.hpp>`) uses only portable C++ to scan strings, instead of vector instructions (SSE2 on x86-64,
+NEON on AArch64). The same input is accepted or rejected either way; only the speed differs. It is not defined by
+default.
+
+See [full documentation of `JSON_VIEW_NO_SIMD`](../api/macros/json_view_no_simd.md).
+
+## `JSON_VIEW_USE_SSSE3`
+
+When defined on x86-64, the parser of [`basic_json_document`](../api/basic_json_document/index.md)
+(`<nlohmann/json_view.hpp>`) validates non-ASCII text in strings with SSSE3 without asking the CPU first. It is not
+defined by default.
+
+See [full documentation of `JSON_VIEW_USE_SSSE3`](../api/macros/json_view_use_ssse3.md).
+
 ## `NLOHMANN_DEFINE_TYPE_*(...)`, `NLOHMANN_DEFINE_DERIVED_TYPE_*(...)`

 The library defines 12 macros to simplify the serialization/deserialization of types. See the page on
@@ -85,6 +85,18 @@ json a = {1, 2, 3, 4};
 a.erase(1);             // [1,3,4]  (erase by index)
 ```

+## Editing a document
+
+The operations above work on a `basic_json` value. A JSON text that was parsed into a
+[document](json_view.md#editing-a-document) can also be changed in place, without building a `basic_json` tree for the
+parts that are not touched: [`set`](../api/basic_json_document/set.md) replaces a value, adds or replaces an object
+member, or replaces an array element (also through a JSON pointer),
+[`push_back`](../api/basic_json_document/push_back.md) appends to an array,
+[`insert`](../api/basic_json_document/insert.md) inserts into an array (unlike `basic_json::insert`, it has no object
+overload; members are added with `set`), and [`erase`](../api/basic_json_document/erase.md) removes a member or an
+element. These functions are available on the
+editable document types, such as [`json_editable_document`](../api/json_editable_document.md).
+
 ## See also

 - [`push_back`](../api/basic_json/push_back.md) / [`emplace_back`](../api/basic_json/emplace_back.md) - append to an array
@@ -93,3 +105,4 @@ a.erase(1);             // [1,3,4]  (erase by index)
 - [`merge_patch`](../api/basic_json/merge_patch.md) - apply an RFC 7396 merge patch
 - [`erase`](../api/basic_json/erase.md) / [`clear`](../api/basic_json/clear.md) - remove elements
 - [JSON Patch and Diff](json_patch.md) and [JSON Merge Patch](merge_patch.md) - structured modifications
+- [Editing a document](json_view.md#editing-a-document) - change a parsed document in place
@@ -18,6 +18,7 @@ flowchart LR
 The [`parse`](../../api/basic_json/parse.md) function reads a JSON value from an input. The input can be

 - a string (`#!cpp std::string`, C string, or string literal),
+- a wide string (`#!cpp std::u16string`, `#!cpp std::u32string`, or `#!cpp std::wstring`, or a wide string literal),
 - a `#!cpp std::istream` (e.g., an `#!cpp std::ifstream` reading from a file),
 - a `#!cpp FILE*` pointer,
 - a pair of iterators over a contiguous range (e.g., a `#!cpp std::vector<std::uint8_t>`), or
@@ -32,12 +33,18 @@ std::ifstream f("example.json");
 json data = json::parse(f);
 ```

-The input must be encoded in UTF-8; other encodings are not supported. A single input may contain only one JSON value.
+The input must be encoded in UTF-8; other encodings are not supported. The exception is wide-character input, which
+is read as UTF-16 or UTF-32 -- depending on the character type -- and converted to UTF-8; see the
+[`parse`](../../api/basic_json/parse.md) page for an example. A single input may contain only one JSON value.
 Inputs consisting of multiple values separated by newlines are handled by the [JSON Lines](json_lines.md) format.

 By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the `parse`
 function — see [comments](../comments.md) and [trailing commas](../trailing_commas.md).

+[`basic_json_document::parse`](../../api/basic_json_document/parse.md) accepts the same inputs with the same options,
+but keeps the result in a document rather than in a `basic_json` value; see
+[Documents and views](#documents-and-views) below.
+
 ## Strictness and trailing data

 [`parse`](../../api/basic_json/parse.md) reads a single JSON value and requires the whole input to be consumed: any
@@ -98,6 +105,26 @@ The library offers two parsing models:
 You can influence a DOM parse without switching to the SAX interface by passing a
 [parser callback](parser_callbacks.md), which is called during parsing and can, for example, discard parts of the input.

+## Documents and views
+
+A third model sits between DOM and SAX: [`basic_json_document::parse`](../../api/basic_json_document/parse.md) parses
+the input into a document that keeps the text and a flat index of the values in it, and
+[`basic_json_view`](../../api/basic_json_view/index.md) gives read-only access to the values through that index.
+The whole input is validated during parsing, but only integers and strings that contain escape sequences are converted
+right away (the strings into a buffer owned by the document). Floating-point numbers and all other strings stay in the
+source text and are only converted when they are read, which is faster and uses less memory than building a tree of `basic_json` values when only parts
+of the document are needed. A document can also be
+modified in place, and it can be saved and loaded again without parsing it.
+
+```cpp
+#include <nlohmann/json_view.hpp>
+
+json_document doc = json_document::parse(R"({"happy": true, "pi": 3.141})");
+std::cout << doc.root()["happy"].get<bool>() << '\n';
+```
+
+See [Zero-copy JSON views](../json_view.md) for the concept and the trade-offs.
+
 ## Exceptions

 When the input is not valid JSON, the `parse` function throws an exception by default. If exceptions are undesired or
@@ -108,6 +135,7 @@ options.
 ## See also

 - [`parse`](../../api/basic_json/parse.md) - deserialize from a compatible input
+- [`basic_json_document::parse`](../../api/basic_json_document/parse.md) - deserialize into a document instead of a value
 - [`accept`](../../api/basic_json/accept.md) - check if the input is valid JSON
 - [`sax_parse`](../../api/basic_json/sax_parse.md) - generate SAX events
 - [JSON Lines](json_lines.md) - parse newline-delimited JSON
@@ -115,3 +143,4 @@ options.
 - [SAX interface](sax_interface.md) - implement a custom SAX handler
 - [parsing and exceptions](parse_exceptions.md) - control error handling
 - [parsing untrusted input](untrusted_input.md) - what to consider when parsing input from untrusted sources
+- [Zero-copy JSON views](../json_view.md) - parse into a document and read it through a view
@@ -81,6 +81,9 @@ Invalid UTF-8 is rejected while parsing, not just while serializing:

 - In JSON text, an ill-formed UTF-8 byte in a string is a
  [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) ("invalid string: ill-formed UTF-8 byte").
+- In UTF-16 or UTF-32 input, an ill-formed sequence is a
+  [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) as well: a lone surrogate, a high surrogate
+  that is not followed by its low surrogate, and a code point above `U+10FFFF` are all rejected.
 - In a binary format, a string that is not valid UTF-8 is a
  [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113).

@@ -286,3 +286,12 @@ This implementation does exactly follow this approach, as it uses double precisi
 ### Storage

 Integer number values, unsigned integer number values, and floating-point number values are stored directly inside a `basic_json` type.
+
+## See also
+
+- [Number handling](number_handling.md) - how numbers are stored and converted
+- [Template parameter requirements](template_parameters.md)
+- [**basic_json**](../../api/basic_json/index.md) - the class template and its member types
+- [**type**](../../api/basic_json/type.md) and [**value_t**](../../api/basic_json/value_t.md) - query the type of a value
+- [**object_t**](../../api/basic_json/object_t.md), [**array_t**](../../api/basic_json/array_t.md), [**string_t**](../../api/basic_json/string_t.md), [**number_integer_t**](../../api/basic_json/number_integer_t.md), [**number_float_t**](../../api/basic_json/number_float_t.md) - the underlying types
+- [Object order](../object_order.md)
@@ -1,7 +1,7 @@
 # Debugging

-This page collects the library's built-in debugger integrations and other debugging-related features. They are
-not linked from a single place elsewhere in the docs, so are collected here.
+This page collects the library's built-in debugger integrations and other debugging-related features. They are not
+covered by any single page elsewhere in the docs, so they are collected here.

 ## Visual Studio (natvis)

@@ -99,7 +99,8 @@ As this global context comes at the price of storing one additional pointer per

    Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.

-See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for more information.
+See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for more information, and
+[Debugging](debugging.md) for the debugger integrations of the library.

 ## Parse errors

@@ -81,8 +81,9 @@ rejected by default, and the library never adds them when serializing.

 The library supports **Unicode input** as follows:

- Only **UTF-8** encoded input is supported, which is the default encoding for JSON, according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
- `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.
+- **UTF-8** encoded input is supported, which is the default encoding for JSON, according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
+- `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively; `std::wstring` works as well and is interpreted as UTF-16 or UTF-32, depending on the width of the platform's `wchar_t`. These encodings cannot be read from a `FILE*` or a `std::istream`, which carry bytes only.
+- Ill-formed UTF-16 or UTF-32 input is rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above `U+10FFFF` all yield a parse error. The same holds for iterators over 2- or 4-byte characters.
 - Other encodings such as Latin-1 or ISO 8859-1 are **not** supported and will yield parse or serialization errors.
 - The library will not replace [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1).
 - Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
@@ -146,7 +147,7 @@ json::parse(std::string("\"") + '\0' + "\""); // throws parse_error.101: control

    Why are wide strings (e.g., `std::wstring`) dumped as arrays of numbers?

-As described [above](#parse-errors-reading-non-ascii-characters), the library assumes UTF-8 as encoding.  To store a wide string, you need to change the encoding.
+As described [above](#parse-errors-reading-non-ascii-characters), the library stores its strings as UTF-8. To store a wide string as a string, convert it to a UTF-8 encoded `std::string` first, as in the example below.

 !!! example

@@ -1,453 +0,0 @@
-# Releases
-
-This page summarizes the notable changes of every release and links to the relevant documentation.
-The **complete release notes** — including all changes, the download files, and their checksums — are
-published on the [GitHub releases page](https://github.com/nlohmann/json/releases).
-
-!!! info "Unreleased changes"
-
-    This documentation is built from the `develop` branch and may describe changes that are not part of a release
-    yet. Their version numbers are followed by an <span class="unreleased-version">unreleased</span> badge.
-
-## Unreleased
-
- Converting an rvalue container to JSON (`json j = std::move(vec);`, `json j = std::map<std::string, std::string>{...};`)
-  now **moves** the elements instead of copying them (e.g., `std::vector<std::string>` with 100,000 strings: 4.7 ms to
-  2.3 ms). Two consequences: the source container is left in a valid but unspecified (moved-from) state, and if an
-  exception is thrown during the conversion, the source may be partially moved-from, so the strong exception guarantee
-  no longer holds for the source of an rvalue conversion (the JSON value itself is unaffected). Lvalues and `const`
-  objects are still copied. See [`basic_json`](../api/basic_json/basic_json.md).
-
-## v3.12.0 (2025-04-11)
-
-Fixes bugs found in 3.11.3 and adds several features. All changes are backward-compatible.
-
- Adds diagnostic byte positions via [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md),
-  exposed through the new [`start_pos`](../api/basic_json/start_pos.md) and
-  [`end_pos`](../api/basic_json/end_pos.md) member functions.
- Makes the [conversion macros](../features/arbitrary_types.md#simplify-your-life-with-macros)
-  templated (so they also work with [`ordered_json`](../api/ordered_json.md)) and adds
-  [`NLOHMANN_DEFINE_DERIVED_TYPE`](../api/macros/nlohmann_define_derived_type.md) for derived classes.
- Adds `std::optional` support (C++17) and lets [`patch`](../api/basic_json/patch.md),
-  [`diff`](../api/basic_json/diff.md), and [`flatten`](../api/basic_json/flatten.md) work with
-  arbitrary string types.
- Extends the [binary formats](../features/binary_formats/index.md):
-  [BJData](../features/binary_formats/bjdata.md) draft 3 and unsigned 64-bit integers for
-  [BSON](../features/binary_formats/bson.md).
- Adds multidimensional C-array conversion and UTF-8 encoded `std::filesystem::path` conversions, and
-  raises the minimum [CMake](../integration/cmake.md) version to 3.5 and supports CMake 4.0.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.12.0).
-
-## v3.11.3 (2023-11-28)
-
-Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible.
-
- Adds a [custom base class](../api/basic_json/json_base_class_t.md) as a node customization point.
- Adds serialization-only [conversion macros](../features/macros.md)
-  (`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE` and `NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE`)
-  and a clearer parse error for empty input.
- Adds [Bazel](../integration/package_managers.md#bazel) and
-  [Swift Package Manager](../integration/package_managers.md#swift-package-manager) build support.
- Fixes custom allocators, a memory leak in [`adl_serializer`](../api/adl_serializer/to_json.md)'s
-  `to_json`, initializer-list construction when `size_type` is not `int`, and many compiler warnings.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.3).
-
-## v3.11.2 (2022-08-12)
-
-Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible.
-
- Fixes the [`value`](../api/basic_json/value.md) function (broken for strings, size types, and
-  `nullptr` in 3.11.0) and makes `json_fwd.hpp` self-contained.
- Restores using [`json_pointer`](../api/json_pointer/index.md) as a key in associative containers and
-  comparing it with strings.
- Restructures the inline [namespace](../features/namespace.md) and allows disabling the version
-  component, and avoids heap allocations in the [BJData](../features/binary_formats/bjdata.md) parser.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.2).
-
-## v3.11.1 (2022-08-01)
-
-Fixes a regression from 3.11.0. All changes are backward-compatible.
-
- Restores the global [user-defined string literals](../api/macros/json_use_global_udls.md)
-  [`operator""_json`](../api/operator_literal_json.md) and
-  [`operator""_json_pointer`](../api/operator_literal_json_pointer.md), which 3.11.0 had moved into a
-  namespace by default.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.1).
-
-## v3.11.0 (2022-08-01)
-
-One of the largest releases ever. All changes are backward-compatible.
-
- Allows `std::string_view` as object keys in [`at`](../api/basic_json/at.md),
-  [`operator[]`](../api/basic_json/operator%5B%5D.md), [`value`](../api/basic_json/value.md),
-  [`erase`](../api/basic_json/erase.md), [`find`](../api/basic_json/find.md),
-  [`contains`](../api/basic_json/contains.md), and [`count`](../api/basic_json/count.md).
- Adds the [BJData](../features/binary_formats/bjdata.md) binary format (the fifth supported format).
- Improves C++20 support, including [`operator<=>`](../api/basic_json/operator_spaceship.md) and
-  `<ranges>`-compatible iterators.
- Adds a versioned, ABI-tagged inline [namespace](../features/namespace.md)
-  ([`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md)) and the option to move the
-  UDLs out of the global namespace ([`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md)).
- Adds [`patch_inplace`](../api/basic_json/patch_inplace.md), default values for the
-  [conversion macros](../features/arbitrary_types.md#simplify-your-life-with-macros), and an option to
-  disable enum serialization ([`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md)).
-
-This release introduced a UDL regression that was fixed in
-[3.11.1](https://github.com/nlohmann/json/releases/tag/v3.11.1).
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.0).
-
-## v3.10.5 (2022-01-03)
-
-Bug-fix release. All changes are backward-compatible.
-
- Guards the `std::filesystem` conversions behind compiler-support checks
-  ([`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md)), which can be set to `0` to disable
-  them altogether.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.5).
-
-## v3.10.4 (2021-10-16)
-
-Fixes regressions introduced in 3.10.0. All changes are backward-compatible.
-
- Fixes the `std::filesystem::path` conversion (which could trigger a stack overflow and broke
-  compilation on Windows).
- Fixes compilation for types with an explicit defaulted constructor and for code relying on the
-  return values of `std::find` and `std::remove`.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.4).
-
-## v3.10.3 (2021-10-08)
-
-Fixes more regressions from 3.10.0. All changes are backward-compatible.
-
- Fixes [extended-diagnostics](../api/macros/json_diagnostics.md) assertions triggered by
-  [`update`](../api/basic_json/update.md) and by inserting into arrays.
- Supports custom allocators when writing binary formats into a `std::vector`, and allows conversion
-  from types that only provide `begin()`/`end()`.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.3).
-
-## v3.10.2 (2021-08-26)
-
-Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script.
-All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.2).
-
-## v3.10.1 (2021-08-24)
-
-Fixes a regression from 3.10.0. All changes are backward-compatible.
-
- Fixes an [extended-diagnostics](../api/macros/json_diagnostics.md) assertion triggered when used
-  with [`ordered_json`](../api/ordered_json.md), and hardens the GDB pretty-printer.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.1).
-
-## v3.10.0 (2021-08-17)
-
-Feature release. All changes are backward-compatible.
-
- Adds [extended diagnostic messages](../api/macros/json_diagnostics.md)
-  ([`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md)) that prepend a JSON pointer to exception
-  messages to pinpoint the offending value.
- Adds a GDB pretty-printer and a [`cbor_tag_handler_t`](../api/basic_json/cbor_tag_handler_t.md)
-  `store` option to keep CBOR tags as binary subtypes.
- Supports containers with non-default-constructible types and parsing from `std::byte`.
- Adds [`JSON_NO_IO`](../api/macros/json_no_io.md) to exclude the I/O headers and the
-  [`JSON_HAS_CPP_*`](../api/macros/json_has_cpp_11.md) macros to override the detected C++ standard.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.0).
-
-## v3.9.1 (2020-08-06)
-
-Fixes two regressions from 3.9.0. All changes are backward-compatible.
-
- Accepts consecutive [comments](../features/comments.md) and completes the
-  [`ordered_json`](../api/ordered_json.md) interface (e.g. `ordered_json::parse`).
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.1).
-
-## v3.9.0 (2020-07-27)
-
-Feature release adding four long-requested features. All changes are backward-compatible.
-
- Optional [comment](../features/comments.md) parsing in [`parse`](../api/basic_json/parse.md) via the
-  `ignore_comments` parameter.
- [`ordered_json`](../api/ordered_json.md) to preserve the [insertion order](../features/object_order.md)
-  of object keys.
- An option to switch off [implicit conversions](../api/macros/json_use_implicit_conversions.md).
- The [`NLOHMANN_DEFINE_TYPE_*`](../features/arbitrary_types.md#simplify-your-life-with-macros)
-  convenience macros, plus high-precision-number support for
-  [UBJSON](../features/binary_formats/ubjson.md) and CBOR tag handling.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.0).
-
-## v3.8.0 (2020-06-14)
-
-Feature release. All changes are backward-compatible.
-
- Introduces a [binary value](../features/binary_values.md) type that is read from and written to
-  [CBOR](../features/binary_formats/cbor.md), [BSON](../features/binary_formats/bson.md), and
-  [MessagePack](../features/binary_formats/messagepack.md), and can be shared between formats.
- Generalizes the input adapters to read from any `LegacyInputIterator` container (3–10 % faster
-  parsing).
- Fixes [`contains`](../api/basic_json/contains.md) for JSON pointers and makes the binary
-  [`from_cbor`](../api/basic_json/from_cbor.md)/[`from_msgpack`](../api/basic_json/from_msgpack.md)/etc.
-  functions respect `allow_exceptions`.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.8.0).
-
-## v3.7.3 (2019-11-17)
-
-Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes
-are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.3).
-
-## v3.7.2 (2019-11-10)
-
-Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing is now
-bounded only by available memory. All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.2).
-
-## v3.7.1 (2019-11-06)
-
-Bug-fix release. All changes are backward-compatible.
-
- Fixes a segmentation fault when serializing the `std::int64_t` minimum value and fixes
-  [`contains`](../api/basic_json/contains.md) for JSON pointers.
- Allows [`items`](../api/basic_json/items.md) with a custom string type and makes `json_pointer::back`
-  `const`.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.1).
-
-## v3.7.0 (2019-07-28)
-
-Convenience features and house-keeping. All changes are backward-compatible.
-
- Adds a [`contains`](../api/basic_json/contains.md) overload that checks a JSON pointer without
-  throwing, a generic `to_string`, and a return value for
-  [`emplace_back`](../api/basic_json/emplace_back.md).
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.0).
-
-## v3.6.1 (2019-03-20)
-
-Fixes a regression (GCC 7/8 compilation) and a `<Windows.h>` build error introduced in 3.6.0. All
-changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.1).
-
-## v3.6.0 (2019-03-20)
-
-Feature release. All changes are backward-compatible.
-
- Reworks the [JSON pointer](../features/json_pointer.md) interface (`operator/`, `push_back`,
-  `parent_pointer`, …).
- Adds a [`contains`](../api/basic_json/contains.md) function to test for an object key and greatly
-  improves the performance of integer serialization.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.0).
-
-## v3.5.0 (2018-12-22)
-
-Feature release. All changes are backward-compatible.
-
- Adds structured-binding support via the [`items`](../api/basic_json/items.md) function and reading
-  from `FILE*` in the [`parse`](../api/basic_json/parse.md) function.
- Fixes the `eofbit` handling on input streams and a bug in the BSON SAX parser.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.5.0).
-
-## v3.4.0 (2018-10-30)
-
-Feature release. All changes are backward-compatible.
-
- Adds [BSON](../features/binary_formats/bson.md) read/write support.
- Adds configurable Unicode error handlers to [`dump`](../api/basic_json/dump.md) (throw, replace with
-  U+FFFD, or ignore) and the
-  [`NLOHMANN_JSON_SERIALIZE_ENUM`](../api/macros/nlohmann_json_serialize_enum.md) macro for
-  [enum conversion](../features/enum_conversion.md).
- Improves parse-error messages with line/column positions and context.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.4.0).
-
-## v3.3.0 (2018-10-05)
-
-Feature release. All changes are backward-compatible.
-
- Adds GCC 4.8 support, the [`get_to`](../api/basic_json/get_to.md) function, and an overhauled and
-  documented [CMake](../integration/cmake.md) integration.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.3.0).
-
-## v3.2.0 (2018-08-20)
-
-Feature release. All changes are backward-compatible.
-
- Adds a [SAX interface](../features/parsing/sax_interface.md) and a non-recursive parser.
- Adds parsing from wide-string types (`std::wstring`, `std::u16string`, `std::u32string`) and
-  `std::string_view` (C++17), and round-tripping of `std::map`/`std::unordered_map` with non-string
-  keys.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.2.0).
-
-## v3.1.2 (2018-03-14)
-
-Bug-fix release. All changes are backward-compatible.
-
- Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser
-  and serializer.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.2).
-
-## v3.1.1 (2018-02-13)
-
-Bug-fix release. All changes are backward-compatible.
-
- Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and
-  overflow detection for UBJSON containers.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.1).
-
-## v3.1.0 (2018-02-01)
-
-Feature release. All changes are backward-compatible.
-
- Adds [UBJSON](../features/binary_formats/ubjson.md) read/write support and
-  [JSON Merge Patch](../features/merge_patch.md) via [`merge_patch`](../api/basic_json/merge_patch.md).
- Switches to the Grisu2 algorithm for short, round-trippable floating-point output, and splits the
-  header into [multiple files](../integration/index.md) with a forward-declaration header.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.0).
-
-## v3.0.1 (2017-12-29)
-
-Fixes small issues in the [JSON Pointer](../features/json_pointer.md) and
-[JSON Patch](../features/json_patch.md) implementations (invalid "copy" targets and non-integer array
-indices). All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.1).
-
-## v3.0.0 (2017-12-17)
-
-First 3.x release — a major release with breaking changes (see the
-[migration guide](../integration/migration_guide.md)).
-
- Introduces user-defined [exceptions](exceptions.md) (`json::exception` and subtypes, each with an
-  identifier).
- Adds a non-throwing [`accept`](../api/basic_json/accept.md) function and an `allow_exceptions` flag
-  for [`parse`](../api/basic_json/parse.md), and an [`update`](../api/basic_json/update.md) function to
-  merge objects.
- Adds streaming for CBOR and MessagePack and allows storing NaN/infinity.
- Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.0).
-
-## v2.1.1 (2017-02-25)
-
-Bug-fix release. All changes are backward-compatible.
-
- Makes number parsing and serialization locale-independent with correct floating-point
-  round-tripping; released files are now GPG-signed.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.1).
-
-## v2.1.0 (2017-01-28)
-
-Feature release. All changes are backward-compatible.
-
- Adds conversions from and to [arbitrary user-defined types](../features/arbitrary_types.md) via
-  `to_json`/`from_json`, the [`meta`](../api/basic_json/meta.md) function, and the option to switch off
-  exceptions ([`JSON_NOEXCEPTION`](../api/macros/json_noexception.md)).
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.0).
-
-## v2.0.10 (2017-01-02)
-
-Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All
-changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.10).
-
-## v2.0.9 (2016-12-16)
-
-Adds the [CBOR](../features/binary_formats/cbor.md) and
-[MessagePack](../features/binary_formats/messagepack.md) binary formats. All changes are
-backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.9).
-
-## v2.0.8 (2016-12-02)
-
-Adds the [`emplace`](../api/basic_json/emplace.md) and
-[`emplace_back`](../api/basic_json/emplace_back.md) functions and improves parsing and serialization
-performance. All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.8).
-
-## v2.0.7 (2016-11-02)
-
-Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding
-detection, surrogate pairs). All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.7).
-
-## v2.0.6 (2016-10-15)
-
-Fixes [`operator[]`](../api/basic_json/operator%5B%5D.md) for [JSON pointers](../features/json_pointer.md)
-so that it creates missing values like the other overloads. All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.6).
-
-## v2.0.5 (2016-09-14)
-
-Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.5).
-
-## v2.0.4 (2016-09-11)
-
-Fixes stream end-of-file detection in the parser. All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.4).
-
-## v2.0.3 (2016-08-31)
-
-Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the
-input-stream constructor in favor of the [`parse`](../api/basic_json/parse.md) function. All changes
-are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.3).
-
-## v2.0.2 (2016-07-31)
-
-Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and
-cleans up the code. All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.2).
-
-## v2.0.1 (2016-06-28)
-
-Fixes a performance regression in the [`dump`](../api/basic_json/dump.md) function by adjusting the
-stream locale once per serialization. All changes are backward-compatible.
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.1).
-
-## v2.0.0 (2016-06-24)
-
-Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept`
-and `constexpr` specifiers.
-
- Adds [JSON Pointer](../features/json_pointer.md) support in [`at`](../api/basic_json/at.md) and
-  [`operator[]`](../api/basic_json/operator%5B%5D.md), plus [`flatten`](../api/basic_json/flatten.md)
-  and [`unflatten`](../api/basic_json/unflatten.md).
- Adds [JSON Patch](../features/json_patch.md) via [`diff`](../api/basic_json/diff.md) and
-  [`patch`](../api/basic_json/patch.md), unsigned 64-bit integer support, and locale-independent
-  serialization.
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.0).
-
-## v1.1.0 (2016-01-24)
-
-Bug-fix and feature release. All changes are backward-compatible.
-
- Improves floating-point round-tripping, adds a `get_ref` accessor for stored values, and introduces
-  runtime [assertions](../features/assertions.md).
-
-[Full release notes](https://github.com/nlohmann/json/releases/tag/v1.1.0).
-
-## v1.0.0 (2015-12-28)
-
-First official release. [Full release notes](https://github.com/nlohmann/json/releases/tag/v1.0.0).
-
-## See also
-
- [Migration Guide](../integration/migration_guide.md) — how to future-proof your code for the next
-  major version and replace deprecated functions.
@@ -0,0 +1,155 @@
+# Releases
+
+This section summarizes the notable changes of every release and links to the relevant documentation.
+The **complete release notes** — including all changes, the download files, and their checksums — are
+published on the [GitHub releases page](https://github.com/nlohmann/json/releases).
+
+!!! info "Unreleased changes"
+
+    This documentation is built from the `develop` branch and may describe changes that are not part of a release
+    yet. Their version numbers are followed by an <span class="unreleased-version">unreleased</span> badge.
+
+Every release has its own page with a summary of its notable changes and an overview of the API that was added or
+changed in it. The API overview is generated from the "Version history" section of the
+[API pages](../../api/basic_json/index.md); it is not a change log, but helps to see whether a feature is available in
+the version you use.
+
+## Unreleased
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [Unreleased](unreleased.md) |  | Changes on the `develop` branch that are not part of a release yet. |
+
+## Version 3.12.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.12.0](v3.12.0.md) | 2025-04-11 | Fixes bugs found in 3.11.3 and adds several features. No public API was removed or renamed. |
+
+## Version 3.11.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.11.3](v3.11.3.md) | 2023-11-28 | Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible. |
+| [v3.11.2](v3.11.2.md) | 2022-08-12 | Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible. |
+| [v3.11.1](v3.11.1.md) | 2022-08-01 | Fixes a regression from 3.11.0. All changes are backward-compatible. |
+| [v3.11.0](v3.11.0.md) | 2022-08-01 | One of the largest releases ever. All changes are backward-compatible. |
+
+## Version 3.10.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.10.5](v3.10.5.md) | 2022-01-03 | Bug-fix release. All changes are backward-compatible. |
+| [v3.10.4](v3.10.4.md) | 2021-10-16 | Fixes regressions introduced in 3.10.0. All changes are backward-compatible. |
+| [v3.10.3](v3.10.3.md) | 2021-10-08 | Fixes more regressions from 3.10.0. All changes are backward-compatible. |
+| [v3.10.2](v3.10.2.md) | 2021-08-26 | Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. All changes are backward-compatible. |
+| [v3.10.1](v3.10.1.md) | 2021-08-24 | Fixes a regression from 3.10.0. All changes are backward-compatible. |
+| [v3.10.0](v3.10.0.md) | 2021-08-17 | Feature release. All changes are backward-compatible. |
+
+## Version 3.9.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.9.1](v3.9.1.md) | 2020-08-06 | Fixes two regressions from 3.9.0. All changes are backward-compatible. |
+| [v3.9.0](v3.9.0.md) | 2020-07-27 | Feature release adding four long-requested features. All changes are backward-compatible. |
+
+## Version 3.8.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.8.0](v3.8.0.md) | 2020-06-14 | Feature release. All changes are backward-compatible. |
+
+## Version 3.7.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.7.3](v3.7.3.md) | 2019-11-17 | Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes are backward-compatible. |
+| [v3.7.2](v3.7.2.md) | 2019-11-10 | Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing of JSON text is now bounded only by available memory (the binary-format parsers still recurse). All changes are backward-compatible. |
+| [v3.7.1](v3.7.1.md) | 2019-11-06 | Bug-fix release. All changes are backward-compatible. |
+| [v3.7.0](v3.7.0.md) | 2019-07-28 | Convenience features and house-keeping. All changes are backward-compatible. |
+
+## Version 3.6.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.6.1](v3.6.1.md) | 2019-03-20 | Fixes a regression (GCC 7/8 compilation) and a `<Windows.h>` build error introduced in 3.6.0. All changes are backward-compatible. |
+| [v3.6.0](v3.6.0.md) | 2019-03-20 | Feature release. All changes are backward-compatible. |
+
+## Version 3.5.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.5.0](v3.5.0.md) | 2018-12-22 | Feature release. All changes are backward-compatible. |
+
+## Version 3.4.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.4.0](v3.4.0.md) | 2018-10-30 | Feature release. All changes are backward-compatible. |
+
+## Version 3.3.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.3.0](v3.3.0.md) | 2018-10-05 | Feature release. All changes are backward-compatible. |
+
+## Version 3.2.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.2.0](v3.2.0.md) | 2018-08-20 | Feature release. All changes are backward-compatible. |
+
+## Version 3.1.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.1.2](v3.1.2.md) | 2018-03-14 | Bug-fix release. All changes are backward-compatible. |
+| [v3.1.1](v3.1.1.md) | 2018-02-13 | Bug-fix release. All changes are backward-compatible. |
+| [v3.1.0](v3.1.0.md) | 2018-02-01 | Feature release. All changes are backward-compatible. |
+
+## Version 3.0.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v3.0.1](v3.0.1.md) | 2017-12-29 | Fixes small issues in the [JSON Pointer](../../features/json_pointer.md) and [JSON Patch](../../features/json_patch.md) implementations (invalid "copy" targets and non-integer array indices). All changes are backward-compatible. |
+| [v3.0.0](v3.0.0.md) | 2017-12-17 | First 3.x release — a major release with breaking changes (see the [migration guide](../../integration/migration_guide.md)). |
+
+## Version 2.1.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v2.1.1](v2.1.1.md) | 2017-02-25 | Bug-fix release. All changes are backward-compatible. |
+| [v2.1.0](v2.1.0.md) | 2017-01-28 | Feature release. All changes are backward-compatible. |
+
+## Version 2.0.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v2.0.10](v2.0.10.md) | 2017-01-02 | Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All changes are backward-compatible. |
+| [v2.0.9](v2.0.9.md) | 2016-12-16 | Adds the [CBOR](../../features/binary_formats/cbor.md) and [MessagePack](../../features/binary_formats/messagepack.md) binary formats. All changes are backward-compatible. |
+| [v2.0.8](v2.0.8.md) | 2016-12-02 | Adds the [`emplace`](../../api/basic_json/emplace.md) and [`emplace_back`](../../api/basic_json/emplace_back.md) functions and improves parsing and serialization performance. All changes are backward-compatible. |
+| [v2.0.7](v2.0.7.md) | 2016-11-02 | Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding detection, surrogate pairs). All changes are backward-compatible. |
+| [v2.0.6](v2.0.6.md) | 2016-10-15 | Fixes [`operator[]`](../../api/basic_json/operator%5B%5D.md) for [JSON pointers](../../features/json_pointer.md) so that it creates missing values like the other overloads. All changes are backward-compatible. |
+| [v2.0.5](v2.0.5.md) | 2016-09-14 | Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. |
+| [v2.0.4](v2.0.4.md) | 2016-09-11 | Fixes stream end-of-file detection in the parser. All changes are backward-compatible. |
+| [v2.0.3](v2.0.3.md) | 2016-08-31 | Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the input-stream constructor in favor of the [`parse`](../../api/basic_json/parse.md) function. All changes are backward-compatible. |
+| [v2.0.2](v2.0.2.md) | 2016-07-31 | Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and cleans up the code. All changes are backward-compatible. |
+| [v2.0.1](v2.0.1.md) | 2016-06-28 | Fixes a performance regression in the [`dump`](../../api/basic_json/dump.md) function by adjusting the stream locale once per serialization. All changes are backward-compatible. |
+| [v2.0.0](v2.0.0.md) | 2016-06-24 | Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept` and `constexpr` specifiers. |
+
+## Version 1.1.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v1.1.0](v1.1.0.md) | 2016-01-24 | Bug-fix and feature release. All changes are backward-compatible. |
+
+## Version 1.0.x
+
+| Release | Date | Summary |
+|---------|------|---------|
+| [v1.0.0](v1.0.0.md) | 2015-12-28 | First official release. |
+
+## See also
+
+- [Migration Guide](../../integration/migration_guide.md) — how to future-proof your code for the next
+  major version and replace deprecated functions.
@@ -0,0 +1,14 @@
+# Unreleased
+
+These changes are part of the `develop` branch, but not of a release yet.
+
+- Converting an rvalue container to JSON (`json j = std::move(vec);`, `json j = std::map<std::string, std::string>{...};`)
+  now **moves** the elements instead of copying them (e.g., `std::vector<std::string>` with 100,000 strings: 4.7 ms to
+  2.3 ms). Two consequences: the source container is left in a valid but unspecified (moved-from) state, and if an
+  exception is thrown during the conversion, the source may be partially moved-from, so the strong exception guarantee
+  no longer holds for the source of an rvalue conversion (the JSON value itself is unaffected). Lvalues and `const`
+  objects are still copied. See [`basic_json`](../../api/basic_json/basic_json.md).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,9 @@
+# v1.0.0
+
+Released on 2015-12-28.
+
+First official release. [Full release notes](https://github.com/nlohmann/json/releases/tag/v1.0.0).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,14 @@
+# v1.1.0
+
+Released on 2016-01-24.
+
+Bug-fix and feature release. All changes are backward-compatible.
+
+- Improves floating-point round-tripping, adds a `get_ref` accessor for stored values, and introduces
+  runtime [assertions](../../features/assertions.md).
+
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v1.1.0).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,19 @@
+# v2.0.0
+
+Released on 2016-06-24.
+
+Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept`
+and `constexpr` specifiers.
+
+- Adds [JSON Pointer](../../features/json_pointer.md) support in [`at`](../../api/basic_json/at.md) and
+  [`operator[]`](../../api/basic_json/operator%5B%5D.md), plus [`flatten`](../../api/basic_json/flatten.md)
+  and [`unflatten`](../../api/basic_json/unflatten.md).
+- Adds [JSON Patch](../../features/json_patch.md) via [`diff`](../../api/basic_json/diff.md) and
+  [`patch`](../../api/basic_json/patch.md), unsigned 64-bit integer support, and locale-independent
+  serialization.
+
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.0).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,11 @@
+# v2.0.1
+
+Released on 2016-06-28.
+
+Fixes a performance regression in the [`dump`](../../api/basic_json/dump.md) function by adjusting the
+stream locale once per serialization. All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.1).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,10 @@
+# v2.0.10
+
+Released on 2017-01-02.
+
+Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All
+changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.10).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,11 @@
+# v2.0.2
+
+Released on 2016-07-31.
+
+Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and
+cleans up the code. All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.2).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,11 @@
+# v2.0.3
+
+Released on 2016-08-31.
+
+Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the
+input-stream constructor in favor of the [`parse`](../../api/basic_json/parse.md) function. All changes
+are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.3).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,10 @@
+# v2.0.4
+
+Released on 2016-09-11.
+
+Fixes stream end-of-file detection in the parser. All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.4).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,10 @@
+# v2.0.5
+
+Released on 2016-09-14.
+
+Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.5).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,11 @@
+# v2.0.6
+
+Released on 2016-10-15.
+
+Fixes [`operator[]`](../../api/basic_json/operator%5B%5D.md) for [JSON pointers](../../features/json_pointer.md)
+so that it creates missing values like the other overloads. All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.6).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,11 @@
+# v2.0.7
+
+Released on 2016-11-02.
+
+Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding
+detection, surrogate pairs). All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.7).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,12 @@
+# v2.0.8
+
+Released on 2016-12-02.
+
+Adds the [`emplace`](../../api/basic_json/emplace.md) and
+[`emplace_back`](../../api/basic_json/emplace_back.md) functions and improves parsing and serialization
+performance. All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.8).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,11 @@
+# v2.0.9
+
+Released on 2016-12-16.
+
+Adds the [CBOR](../../features/binary_formats/cbor.md) and
+[MessagePack](../../features/binary_formats/messagepack.md) binary formats. All changes are
+backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.9).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,15 @@
+# v2.1.0
+
+Released on 2017-01-28.
+
+Feature release. All changes are backward-compatible.
+
+- Adds conversions from and to [arbitrary user-defined types](../../features/arbitrary_types.md) via
+  `to_json`/`from_json`, the [`meta`](../../api/basic_json/meta.md) function, and the option to switch off
+  exceptions ([`JSON_NOEXCEPTION`](../../api/macros/json_noexception.md)).
+
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.0).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,14 @@
+# v2.1.1
+
+Released on 2017-02-25.
+
+Bug-fix release. All changes are backward-compatible.
+
+- Makes number parsing and serialization locale-independent with correct floating-point
+  round-tripping; commits and released files are GPG-signed.
+
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.1).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,20 @@
+# v3.0.0
+
+Released on 2017-12-17.
+
+First 3.x release — a major release with breaking changes (see the
+[migration guide](../../integration/migration_guide.md)).
+
+- Introduces user-defined [exceptions](../exceptions.md) (`json::exception` and subtypes, each with an
+  identifier).
+- Adds a non-throwing [`accept`](../../api/basic_json/accept.md) function and an `allow_exceptions` flag
+  for [`parse`](../../api/basic_json/parse.md), and an [`update`](../../api/basic_json/update.md) function to
+  merge objects.
+- Adds streaming for CBOR and MessagePack and allows storing NaN/infinity.
+- Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional.
+
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.0).
+
+## API changes
+
+<!-- api-changes -->
@@ -0,0 +1,12 @@
+# v3.0.1
+
+Released on 2017-12-29.
+
+Fixes small issues in the [JSON Pointer](../../features/json_pointer.md) and
+[JSON Patch](../../features/json_patch.md) implementations (invalid "copy" targets and non-integer array
+indices). All changes are backward-compatible.
+[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.1).
+
+## API changes
+
+<!-- api-changes -->