docs: name the documents the generic view function accepts

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

.github/external_ci/appveyor.yml

@@ -18,7 +18,8 @@ environment:
   matrix:
     # The Visual Studio 2017 jobs compile everything with /std:c++17, so they
     # only build the C++17 variant of each test, split into two jobs each to
-    # stay below AppVeyor's 60-minute limit per job.
+    # stay below AppVeyor's 60-minute limit per job. The Visual Studio 2019
+    # job builds the tests for all standards and is split for the same reason.
     - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015
       configuration: Debug
       platform: x86
@@ -50,7 +51,13 @@ environment:
       configuration: Release
       platform: x86
       CXX_FLAGS: "/W4 /WX"
-      CMAKE_OPTIONS: "-DJSON_ImplicitConversions=OFF"
+      CMAKE_OPTIONS: "-DJSON_ImplicitConversions=OFF -DJSON_TestShard=0/2"
+      GENERATOR: Visual Studio 16 2019
+    - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
+      configuration: Release
+      platform: x86
+      CXX_FLAGS: "/W4 /WX"
+      CMAKE_OPTIONS: "-DJSON_ImplicitConversions=OFF -DJSON_TestShard=1/2"
       GENERATOR: Visual Studio 16 2019
 
     - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015

.github/labeler.yml

@@ -64,6 +64,7 @@ labels:
     - "tests/src/unit-json_view.*"
     - "tests/src/json_view_test_helpers\\.hpp"
     - "tests/src/fuzzer-(parse_json_view|json_view_image)\\.cpp"
+    - "tests/benchmarks/json_view/.*"
     - "tools/amalgamate/config_json_view\\.json"
     - "docs/mkdocs/docs/features/json_view\\.md"
     - "docs/mkdocs/docs/api/basic_json_(document|view)/.*"

.github/workflows/check_amalgamation.yml

@@ -154,6 +154,28 @@ jobs:
           # PR content in a job without credentials.
           python3 tools/generate_natvis/generate_natvis.py $MAIN_DIR
 
+      - name: Check the nlohmann_json.natvis generator options
+        run: |
+          cd $MAIN_DIR
+          # The options for configurations outside the checked-in file write
+          # to a temporary file, so they do not affect the diff below.
+          GENERATOR=tools/generate_natvis/generate_natvis.py
+          python3 $GENERATOR --list-tags
+          TAG_COUNT=$(python3 $GENERATOR --list-tags | wc -l)
+
+          python3 $GENERATOR --abi-tags diag,_dp,_ns --abi-tags _diag --output $RUNNER_TEMP/abi_tags.natvis
+          grep -q '<!-- Namespace nlohmann::json_abi_diag_dp_ns -->' $RUNNER_TEMP/abi_tags.natvis
+          grep -q '<!-- Namespace nlohmann::json_abi_diag_dp_ns_v[0-9_]* -->' $RUNNER_TEMP/abi_tags.natvis
+          test $(grep -c '<!-- Namespace ' $RUNNER_TEMP/abi_tags.natvis) -eq $(( $(grep -c '<!-- Namespace ' nlohmann_json.natvis) + 2 ))
+
+          python3 $GENERATOR --all --output $RUNNER_TEMP/all.natvis
+          test $(grep -c '<!-- Namespace ' $RUNNER_TEMP/all.natvis) -eq $(( (1 << TAG_COUNT) * 2 + 1 ))
+
+          if python3 $GENERATOR --abi-tags _unknown --output $RUNNER_TEMP/unknown.natvis; then
+            echo "generate_natvis.py accepted an unknown ABI tag"
+            exit 1
+          fi
+
       - name: Build patch and check for differences
         id: diff
         run: |

.github/workflows/codeql-analysis.yml

@@ -38,14 +38,14 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+      uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
       with:
         languages: c-cpp
 
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+      uses: github/codeql-action/autobuild@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+      uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0

.github/workflows/comment_check_amalgamation.yml

@@ -37,6 +37,14 @@ jobs:
             var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
               return artifact.name == "pr"
             })[0];
+            // a run that failed before its jobs started (e.g. a stale queued
+            // run cancelled long after its push) has no artifact to report on
+            if (!matchArtifact) {
+              core.notice('Run ${{ github.event.workflow_run.id }} has no "pr" artifact; nothing to comment on.');
+              core.setOutput('found', 'false');
+              return;
+            }
+            core.setOutput('found', 'true');
             var download = await github.rest.actions.downloadArtifact({
                owner: context.repo.owner,
                repo: context.repo.repo,
@@ -51,9 +59,11 @@ jobs:
       # Extract the untrusted PR artifact into a dedicated empty directory and
       # read only the two expected files by fixed path afterwards. This avoids a
       # malicious archive overwriting workspace files or escaping via ../ paths.
-      - run: unzip -o pr.zip -d ./pr_artifact
+      - if: steps.download.outputs.found == 'true'
+        run: unzip -o pr.zip -d ./pr_artifact
 
       - name: 'Comment on PR'
+        if: steps.download.outputs.found == 'true'
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/flawfinder.yml

@@ -47,6 +47,6 @@ jobs:
           output: 'flawfinder_results.sarif'
 
       - name: Upload analysis results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           sarif_file: ${{github.workspace}}/flawfinder_results.sarif

.github/workflows/json_view_benchmarks.yml

@@ -0,0 +1,84 @@
+name: "json_view benchmarks"
+
+# On demand only: runs the comparison of json_view with yyjson, simdjson, and
+# Boost.JSON (tests/benchmarks/json_view/compare.py) on GitHub-hosted runners,
+# for numbers from x86-64 and AArch64 Linux. It runs when started by hand, or
+# when a pull request gets the label "benchmark" (on both architectures, with
+# GCC and the default settings). Shared runners are noisy: the results show
+# where json_view stands, but published numbers need a quiet machine (see
+# tests/benchmarks/json_view/README.md).
+
+on:
+  pull_request:
+    types: [labeled]
+  workflow_dispatch:
+    inputs:
+      runner:
+        description: "Runner image"
+        type: choice
+        options:
+          - ubuntu-24.04
+          - ubuntu-24.04-arm
+        default: ubuntu-24.04
+      compiler:
+        description: "Compiler"
+        type: choice
+        options:
+          - g++
+          - clang++
+        default: g++
+      native:
+        description: "Compile for the runner's CPU (-march=native)"
+        type: boolean
+        default: false
+      rounds:
+        description: "Rounds of bench_view"
+        type: number
+        default: 30
+
+permissions:
+  contents: read
+
+concurrency:
+  # (the label is part of the group: adding an unrelated label must not cancel a running benchmark)
+  group: json-view-benchmarks-${{ github.workflow }}-${{ github.ref }}-${{ github.event.label.name }}
+  cancel-in-progress: true
+
+jobs:
+  compare:
+    if: github.event_name == 'workflow_dispatch' || github.event.label.name == 'benchmark'
+    strategy:
+      matrix:
+        runner: ${{ fromJSON(github.event_name == 'workflow_dispatch' && format('["{0}"]', inputs.runner) || '["ubuntu-24.04", "ubuntu-24.04-arm"]') }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 60
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Download test data
+        run: |
+          cmake -S . -B build -DJSON_BuildTests=On
+          cmake --build build --target download_test_data
+
+      - name: Run the comparison
+        env:
+          CXX: ${{ inputs.compiler || 'g++' }}
+          CC: ${{ inputs.compiler == 'clang++' && 'clang' || 'gcc' }}
+          ROUNDS: ${{ inputs.rounds || 30 }}
+          NATIVE: ${{ inputs.native && '--native' || '' }}
+        run: python3 tests/benchmarks/json_view/compare.py --data build/test_files --download --rounds "$ROUNDS" $NATIVE
+
+      - name: Summary
+        run: cat tests/benchmarks/json_view/results/*.md >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: json_view-benchmarks-${{ matrix.runner }}-${{ inputs.compiler || 'g++' }}
+          path: tests/benchmarks/json_view/results/

.github/workflows/scorecards.yml

@@ -80,6 +80,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           sarif_file: results.sarif

.github/workflows/semgrep.yml

@@ -65,7 +65,7 @@ jobs:
 
       # Upload SARIF file generated in previous step
       - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           sarif_file: semgrep.sarif
         if: always()

BUILD.bazel

@@ -37,6 +37,7 @@ cc_library(
         "include/nlohmann/detail/input/parser.hpp",
         "include/nlohmann/detail/input/position_t.hpp",
         "include/nlohmann/detail/input/pow5_table.hpp",
+        "include/nlohmann/detail/input/simd_scan.hpp",
         "include/nlohmann/detail/input/string_scan.hpp",
         "include/nlohmann/detail/iterators/internal_iterator.hpp",
         "include/nlohmann/detail/iterators/iter_impl.hpp",
@@ -89,6 +90,7 @@ cc_library(
         "include/nlohmann/detail/view/simd.hpp",
         "include/nlohmann/detail/view/string_ref.hpp",
         "include/nlohmann/detail/view/value.hpp",
+        "include/nlohmann/detail/view/view_mode.hpp",
         "include/nlohmann/json.hpp",
         "include/nlohmann/json_fwd.hpp",
         "include/nlohmann/json_literals.hpp",

FILES.md

@@ -6,6 +6,7 @@ This file describes the source for supporting files; that is, files that are not
 - [GitHub](#github)
 - [REUSE](#reuse)
 - [Package Managers](#package-managers)
+- [Debugging](#debugging)
 
 ## Continuous Integration
 
@@ -289,3 +290,29 @@ The module definition for [Bazel](https://bazel.build)'s [Bzlmod](https://bazel.
 Further documentation:
 
 - [Bazel modules](https://bazel.build/external/module)
+
+## Debugging
+
+### `nlohmann_json.natvis`
+
+The [Natvis](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects) file that
+gives `json` values a friendly view in the Visual Studio debugger. The file is generated by
+`tools/generate_natvis/generate_natvis.py` from the template `tools/generate_natvis/nlohmann_json.natvis.j2` and the ABI
+tags and version in `include/nlohmann/detail/abi_macros.hpp`; change the script or the template rather than editing
+the file by hand. The file can be updated by calling
+
+```shell
+make natvis
+```
+
+The "Check amalgamation" workflow fails if the file is out of date.
+
+The file covers the namespace variants with up to two ABI tags. A Natvis file for other configurations can be
+generated with the `--abi-tags` or `--all` options, for example
+`make natvis NATVIS_ARGS="--abi-tags _diag,_dp,_ns --output my_nlohmann_json.natvis"`; see
+[`tools/generate_natvis`](tools/generate_natvis/README.md). With MSVC, CMake adds the file to the `nlohmann_json`
+target and installs it.
+
+Further documentation:
+
+- [Create custom views of C++ objects in the debugger using the Natvis framework](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects)

Makefile

@@ -46,7 +46,7 @@ all:
 	@echo "clean - remove built files"
 	@echo "(fuzzers) - see tests/fuzzing.md, or run 'make -C tests fuzzers' to build the AFL fuzzers"
 	@echo "macro_builder_check - check that macro_scope.hpp matches tools/macro_builder's output"
-	@echo "natvis - regenerate nlohmann_json.natvis from the current ABI tags and version"
+	@echo "natvis - regenerate nlohmann_json.natvis from the current ABI tags and version (pass generator options via NATVIS_ARGS, see tools/generate_natvis/README.md)"
 	@echo "pretty - beautify code with Artistic Style"
 	@echo "pvs_studio - run the PVS-Studio static analyzer and open the report"
 	@echo "release - create the release files (include.zip, json.tar.xz, single headers, signatures, hashes)"
@@ -120,13 +120,15 @@ $(AMALGAMATED_VIEW_FILE): $(SRCS)
 	tools/amalgamate/amalgamate.py -c tools/amalgamate/config_json_view.json -s . --verbose=yes
 
 NATVIS_VENV=tools/generate_natvis/venv
+# extra options for generate_natvis.py, e.g. NATVIS_ARGS="--abi-tags _diag,_dp,_ns --output my.natvis"
+NATVIS_ARGS=
 
 # regenerate nlohmann_json.natvis from the ABI tags and version in include/nlohmann/detail/abi_macros.hpp
 # (the dependencies are installed into a virtual environment first)
 natvis:
 	@test -d $(NATVIS_VENV) || python3 -mvenv $(NATVIS_VENV)
 	@$(NATVIS_VENV)/bin/python3 -c 'import jinja2' 2>/dev/null || $(NATVIS_VENV)/bin/pip3 install --quiet -r tools/generate_natvis/requirements.txt
-	$(NATVIS_VENV)/bin/python3 tools/generate_natvis/generate_natvis.py .
+	$(NATVIS_VENV)/bin/python3 tools/generate_natvis/generate_natvis.py $(NATVIS_ARGS) .
 
 # regenerate the two tools/macro_builder blocks of $(MACRO_SCOPE_HPP) (see its README.md) and diff against the
 # checked-in header; phony, because it never writes $(MACRO_SCOPE_HPP) itself

docs/docset/generate_docset.py

@@ -341,13 +341,14 @@ def download(url, docs) -> str:
         raise ValueError(f'not an http(s) URL: {url}')
     req = urllib.request.Request(u.geturl(), headers={'User-Agent': USER_AGENT})
     # (the scheme is checked above)
+    # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
     with urllib.request.urlopen(req, timeout=20) as r:  # nosec B310
         data = r.read()
         ctype = r.headers.get_content_type()
     path = urllib.parse.unquote(u.path).lstrip('/')
     ext = os.path.splitext(path)[1]
     if u.query or not ext or path.endswith('/'):
-        digest = hashlib.sha1(url.encode(), usedforsecurity=False).hexdigest()[:12]
+        digest = hashlib.sha256(url.encode()).hexdigest()[:12]
         path = os.path.join(os.path.dirname(path), digest + CONTENT_TYPE_EXT.get(ctype, ext or '.bin'))
     rel = os.path.normpath(os.path.join('assets', 'external', u.hostname, path))
     out = os.path.join(docs, rel)

docs/mkdocs/docs/api/adl_serializer/index.md

@@ -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.

docs/mkdocs/docs/api/basic_json/accept.md

@@ -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"
 

docs/mkdocs/docs/api/basic_json/at.md

@@ -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
+3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
-   already supported by [`operator[]`](operator[].md), [`value`](value.md), [`find`](find.md), and other lookup
+   across the lookup functions.
-   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.

docs/mkdocs/docs/api/basic_json/back.md

@@ -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.

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

@@ -482,15 +482,15 @@ basic_json(basic_json&& other) noexcept;
 
 ## Version history
 
-1. Since version 1.0.0.
+1. Added in version 1.0.0.
-2. Since version 1.0.0.
+2. Added in version 1.0.0.
-3. Since version 2.1.0.
+3. Added in version 2.1.0.
-4. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
+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.
+5. Added in version 1.0.0.
-6. Since version 1.0.0.
+6. Added in 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
+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.
+8. Added in version 1.0.0.
-9. Since version 1.0.0.
+9. Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/contains.md

@@ -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
+2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Support for keys
-   version 3.13.0 to consistently accept `std::string_view`-convertible keys, as already supported by
+   convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
-   [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other 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.

docs/mkdocs/docs/api/basic_json/count.md

@@ -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
+2. Added in version 1.0.0. Changed to support comparable key types in version 3.11.0. Support for keys convertible to
-   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
+   `std::string_view` added in version 3.13.0, consistently across the lookup functions.
-   [`at`](at.md), [`value`](value.md), and other 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.

docs/mkdocs/docs/api/basic_json/emplace.md

@@ -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`.

docs/mkdocs/docs/api/basic_json/emplace_back.md

@@ -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.

docs/mkdocs/docs/api/basic_json/erase.md

@@ -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
+4. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
-   already supported by [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup
+   across the lookup functions.
-   functions.
 5. Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/exception.md

@@ -84,4 +84,4 @@ constructor.
 
 ## Version history
 
-- Since version 3.0.0.
+- Added in version 3.0.0.

docs/mkdocs/docs/api/basic_json/find.md

@@ -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
+2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Support for keys convertible to
-   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
+   `std::string_view` added in version 3.13.0, consistently across the lookup functions.
-   [`at`](at.md), [`value`](value.md), and other 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.

docs/mkdocs/docs/api/basic_json/front.md

@@ -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.

docs/mkdocs/docs/api/basic_json/get.md

@@ -188,6 +188,6 @@ overload (3).
 
 ## Version history
 
-1. Since version 2.1.0.
+1. Added in version 2.1.0.
-2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0.
+2. Added in version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.1.2.
-3. Since version 1.0.0.
+3. Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/get_to.md

@@ -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.

docs/mkdocs/docs/api/basic_json/index.md

@@ -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
 

docs/mkdocs/docs/api/basic_json/invalid_iterator.md

@@ -75,4 +75,4 @@ classDiagram
 
 ## Version history
 
-- Since version 3.0.0.
+- Added in version 3.0.0.

docs/mkdocs/docs/api/basic_json/items.md

@@ -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 in version 3.1.0 as the replacement of the static function `iterator_wrapper`, which was available since
-- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
+  version 1.0.0 and is deprecated since version 3.1.0.
 - Added structured binding support in version 3.5.0.
 
 !!! warning "Deprecation"

docs/mkdocs/docs/api/basic_json/json_serializer.md

@@ -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.

docs/mkdocs/docs/api/basic_json/merge_patch.md

@@ -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.

docs/mkdocs/docs/api/basic_json/operator+=.md

@@ -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.
+1. Added in version 1.0.0.
-2. Since version 1.0.0.
+2. Added in version 1.0.0.
-3. Since version 2.0.0.
+3. Added in version 2.0.0.

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -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)
+2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. The `T* key` overloads forward to
-   in version 3.11.0.
+   overload 3 since 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
+3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
-   already supported by [`at`](at.md), [`value`](value.md), [`find`](find.md), and other lookup functions.
+   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

docs/mkdocs/docs/api/basic_json/operator_ValueType.md

@@ -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.

docs/mkdocs/docs/api/basic_json/other_error.md

@@ -75,4 +75,4 @@ classDiagram
 
 ## Version history
 
-- Since version 3.0.0.
+- Added in version 3.0.0.

docs/mkdocs/docs/api/basic_json/out_of_range.md

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

docs/mkdocs/docs/api/basic_json/parse.md

@@ -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"
 

docs/mkdocs/docs/api/basic_json/parse_error.md

@@ -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.

docs/mkdocs/docs/api/basic_json/push_back.md

@@ -125,6 +125,6 @@ throws.
 
 ## Version history
 
-1. Since version 1.0.0.
+1. Added in version 1.0.0.
-2. Since version 1.0.0.
+2. Added in version 1.0.0.
-3. Since version 2.0.0.
+3. Added in version 2.0.0.

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -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"
 

docs/mkdocs/docs/api/basic_json/swap.md

@@ -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.
+1. Added in 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.
+2. Added in 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.
+3. Added in version 1.0.0.
-4. Since version 1.0.0.
+4. Added in version 1.0.0.
-5. Since version 1.0.0.
+5. Added in version 1.0.0.
-6. Since version 3.8.0.
+6. Added in version 3.8.0.
-7. Since version 3.8.0.
+7. Added in version 3.8.0.

docs/mkdocs/docs/api/basic_json/to_bjdata.md

@@ -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.

docs/mkdocs/docs/api/basic_json/type_error.md

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

docs/mkdocs/docs/api/basic_json/value.md

@@ -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
+2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Support for keys
-   to consistently accept `std::string_view`-convertible keys, as already supported by
+   convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
-   [`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. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109)
-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)
    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.

docs/mkdocs/docs/api/basic_json_document/erase.md

@@ -12,7 +12,7 @@ void erase(view_type array, I idx);
 std::size_t erase(const json_pointer& ptr);
 ```
 
-Only an **editable** document (`#!cpp Editable == true`, e.g. [`json_editable_document`](../json_editable_document.md))
+Only an **editable** document (`#!cpp view_mode::editable`, e.g. [`json_editable_document`](../json_editable_document.md))
 has `erase`; calling it on a read-only `basic_json_document` fails to compile (`#!cpp static_assert`).
 
 1. Removes every member of `object` whose key is `key` (see [Notes](#notes) on duplicate keys) and returns how many

docs/mkdocs/docs/api/basic_json_document/index.md

@@ -3,14 +3,14 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-template<typename BasicJsonType, bool Editable = false>
+template<typename BasicJsonType, view_mode Mode = view_mode::read_only>
 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
+Strings and floating-point numbers stay in the source text; integers are converted while parsing, and strings that
-the document. [`basic_json_view`](../basic_json_view/index.md) is a read-only handle to one value of a
+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.
 
@@ -20,9 +20,9 @@ is move-only: a copy would duplicate the whole index, the decoded-string buffer,
 enough in every use we know of. The index, the decoded strings, and the owned text live in one heap block that the
 document holds through a `#!cpp std::unique_ptr`; this is also why views survive a move of the document.
 
-With `#!cpp Editable == true`, the document also offers [`set`](set.md), [`push_back`](push_back.md),
+With `#!cpp Mode == view_mode::editable`, the document also offers [`set`](set.md), [`push_back`](push_back.md),
 [`insert`](insert.md), and [`erase`](erase.md) to change values in place, see [Edits](#edits) below. The source text
-itself is never written; a read-only document (`#!cpp Editable == false`, the default) does not carry any of the
+itself is never written; a read-only document (`#!cpp view_mode::read_only`, the default) does not carry any of the
 bookkeeping edits need, and calling any of them on one fails to compile (`#!cpp static_assert`).
 
 ## Template parameters
@@ -32,9 +32,10 @@ bookkeeping edits need, and calling any of them on one fails to compile (`#!cpp
     [`ordered_json`](../ordered_json.md). Only 64-bit `number_integer_t`/`number_unsigned_t` types are supported; this
     is checked with a `static_assert`.
 
-`Editable`
+`Mode`
-:   whether the document supports [`set`](set.md), [`push_back`](push_back.md), [`insert`](insert.md), and
+:   a [`view_mode`](../view_mode.md): `#!cpp view_mode::editable` if the document supports [`set`](set.md),
-    [`erase`](erase.md) (optional, `#!cpp false` by default). See [Edits](#edits) below.
+    [`push_back`](push_back.md), [`insert`](insert.md), and [`erase`](erase.md) (optional, `#!cpp view_mode::read_only`
+    by default). See [Edits](#edits) below.
 
 ## Specializations
 
@@ -47,7 +48,7 @@ bookkeeping edits need, and calling any of them on one fails to compile (`#!cpp
 
 ## Member types
 
-- **view_type** - the type of view returned by [`root()`](root.md) (`#!cpp basic_json_view<BasicJsonType, Editable>`)
+- **view_type** - the type of view returned by [`root()`](root.md) (`#!cpp basic_json_view<BasicJsonType, Mode>`)
 - **value_t** - the JSON type enumeration, see [`basic_json::value_t`](../basic_json/value_t.md)
 - **image_check** - how [`load()`](load.md) validates an image (`full`, `bounds`, `none`), see [`image_check`](load.md#image_check)
 
@@ -80,15 +81,15 @@ bookkeeping edits need, and calling any of them on one fails to compile (`#!cpp
 ### Edits
 
 - [**set**](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers
-  to (`#!cpp Editable` documents only)
+  to (editable documents only)
-- [**push_back**](push_back.md) - append to an array (`#!cpp Editable` documents only)
+- [**push_back**](push_back.md) - append to an array (editable documents only)
-- [**insert**](insert.md) - insert an element into an array before a given position (`#!cpp Editable` documents only)
+- [**insert**](insert.md) - insert an element into an array before a given position (editable documents only)
 - [**erase**](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
-  (`#!cpp Editable` documents only)
+  (editable documents only)
 
 ## Edits
 
-An editable document (`#!cpp Editable == true`) can be changed after parsing, with [`set`](set.md),
+An editable document (`#!cpp view_mode::editable`) can be changed after parsing, with [`set`](set.md),
 [`push_back`](push_back.md), [`insert`](insert.md), and [`erase`](erase.md);
 [`json_editable_document`](../json_editable_document.md) and
 [`ordered_json_editable_document`](../ordered_json_editable_document.md) are the corresponding specializations. A few
@@ -115,6 +116,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.

docs/mkdocs/docs/api/basic_json_document/insert.md

@@ -5,7 +5,7 @@ template<typename I, typename V>
 view_type insert(view_type array, I idx, V&& value);
 ```
 
-Only an **editable** document (`#!cpp Editable == true`, e.g. [`json_editable_document`](../json_editable_document.md))
+Only an **editable** document (`#!cpp view_mode::editable`, e.g. [`json_editable_document`](../json_editable_document.md))
 has `insert`; calling it on a read-only `basic_json_document` fails to compile (`#!cpp static_assert`).
 
 Inserts `value` into `array` as a new element before position `idx`, which must not be past the end

docs/mkdocs/docs/api/basic_json_document/load.md

@@ -55,10 +55,7 @@ validate with overload 2 first, if the original vector must survive a failed loa
 
 ## Exceptions
 
-On a big-endian target, throws [`type_error.320`](../../home/exceptions.md#jsonexceptiontype_error320) -- the same
+Throws [`parse_error.116`](../../home/exceptions.md#jsonexceptionparse_error116) if `image` is not one
-exception [`save()`](save.md#exceptions) throws there, since the image format is little-endian only.
-
-Otherwise throws [`parse_error.116`](../../home/exceptions.md#jsonexceptionparse_error116) if `image` is not one
 `save()` could have written, or fails the requested `check`:
 
 | message               | when                                                                                                |
@@ -95,6 +92,9 @@ are checked once, however many nodes refer to it.
 
 ## Notes
 
+**Little-endian targets only.** On a big-endian target, `load()` does not exist, just like
+[`save()`](save.md#notes): the image format is little-endian, so a call fails to compile.
+
 ### `image_check` { #image_check }
 
 ```cpp

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

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

docs/mkdocs/docs/api/basic_json_document/push_back.md

@@ -13,7 +13,7 @@ editable, and it does not have to be `array`'s own document -- which is copied s
 source document afterward; a `BasicJsonType` value; or anything `BasicJsonType` can be constructed from (numbers,
 strings, `#!cpp bool`, `#!cpp nullptr`, containers, ...).
 
-Only an **editable** document (`#!cpp Editable == true`, e.g. [`json_editable_document`](../json_editable_document.md))
+Only an **editable** document (`#!cpp view_mode::editable`, e.g. [`json_editable_document`](../json_editable_document.md))
 has `push_back`; calling it on a read-only `basic_json_document` fails to compile (`#!cpp static_assert`).
 
 ## Template parameters

docs/mkdocs/docs/api/basic_json_document/save.md

@@ -12,7 +12,7 @@ An edited document is written in its *current* state, with its values in documen
 parser would have produced them for that JSON text: a member [`set`](set.md) added goes at the end, an
 [`erase`](erase.md)d member leaves no trace, and a float that is not finite (NaN or positive/negative infinity)
 becomes null, the same substitution [`dump()`](../basic_json_view/dump.md) makes. The same document always saves to
-the same bytes -- also across `BasicJsonType` and `#!cpp Editable`, since the image reflects document order and
+the same bytes -- also across `BasicJsonType` and the [`view_mode`](../view_mode.md), since the image reflects document order and
 values only, not which specialization produced them.
 
 ## Return value
@@ -31,9 +31,6 @@ Throws [`type_error.320`](../../home/exceptions.md#jsonexceptiontype_error320) i
 [discarded](is_discarded.md) -- a default-constructed document, or one a failed [`parse()`](parse.md)/
 [`read()`](read.md) with `allow_exceptions == false` left discarded.
 
-On a big-endian target, throws `type_error.320` with a different message instead: the image format is little-endian
-only (see [Notes](#notes)).
-
 Throws [`out_of_range.416`](../../home/exceptions.md#jsonexceptionout_of_range416) if the node count, the text, or
 the decoded strings of the image would individually reach 4 GiB -- the same 32-bit offsets
 [`parse()`](parse.md#exceptions) and, for edits, [`set`](set.md)/[`push_back`](push_back.md) are already limited to.
@@ -44,9 +41,6 @@ the decoded strings of the image would individually reach 4 GiB -- the same 32-b
     [json.exception.type_error.320] cannot save a discarded json_document
     ```
     ```
-    [json.exception.type_error.320] json_document images need a little-endian target
-    ```
-    ```
     [json.exception.out_of_range.416] images of 4 GiB or more are not supported by json_document
     ```
 
@@ -70,9 +64,9 @@ else -- see [`load`'s Exceptions](load.md#exceptions).
     the *same* build on the *same* (little-endian) machine -- not as a long-term storage format. Keep the original
     JSON text if you need to read a saved document back with a future library version.
 
-**Little-endian only.** The image is written as raw little-endian bytes, with no byte-swapping. `save()` (and
+**Little-endian targets only.** The image is written as raw little-endian bytes, with no byte-swapping. On a
-[`load`](load.md)) throw `type_error.320` on a big-endian target rather than silently produce bytes a big-endian
+big-endian target, `save()` and [`load`](load.md) do not exist: a call fails to compile rather than produce bytes a
-reader could not interpret correctly.
+big-endian reader could not interpret correctly.
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json_document/set.md

@@ -18,7 +18,7 @@ template<typename V>
 view_type set(const json_pointer& ptr, V&& value);
 ```
 
-Only an **editable** document (`#!cpp Editable == true`, e.g. [`json_editable_document`](../json_editable_document.md))
+Only an **editable** document (`#!cpp view_mode::editable`, e.g. [`json_editable_document`](../json_editable_document.md))
 has `set`; calling it on a read-only `basic_json_document` fails to compile (`#!cpp static_assert`).
 
 1. Replaces the value `target` refers to with `value`.

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

@@ -80,7 +80,8 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
    Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
    constant time on average.
 2. Linear in `idx`: elements are skipped one at a time from the first one, since they are not a fixed size in the
-   index (unlike `BasicJsonType`'s array, which is random-access).
+   index (unlike `BasicJsonType`'s array, which is random-access). Constant if no element of the array is an array
+   or object, since the elements are then adjacent in the index.
 3. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
    that level (as 1.) or the index into the array (as 2.).
 

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

@@ -28,7 +28,8 @@ This exception does not carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.
 
 Linear in the size of the array or object: unlike [`front()`](front.md), which only ever looks at the first
 element, `back()` has to walk every element to find where they end, since elements are not a fixed size in the
-index.
+index. Constant if no element of the array is an array or object, since the elements are then adjacent
+in the index.
 
 ## Notes
 

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

@@ -19,16 +19,36 @@ For the types below, the conversion works directly on the flat index -- no `Basi
   document's own buffer of decoded strings (see [`get_string()`](get_string.md))
 - `BasicJsonType` -- equivalent to [`materialize()`](materialize.md)
 - `basic_json_view` -- returns `#!cpp *this`
-- `#!cpp std::vector<U, A>` -- from an array, element by element, each converted with `#!cpp get<U>()`; `#!cpp
+- `#!cpp std::vector<U, A>` of the types above -- from an array, element by element, each converted with
-  std::vector<basic_json_view>` keeps a view of every element instead of a value
+  `#!cpp get<U>()`; `#!cpp std::vector<basic_json_view>` keeps a view of every element instead of a value
-- `#!cpp std::map<K, V, C, A>` and `#!cpp std::unordered_map<K, V, H, E, A>`, if `K` is constructible from a `#!cpp
+- `#!cpp std::map<K, basic_json_view, C, A>` and `#!cpp std::unordered_map<K, basic_json_view, H, E, A>`, if `K` is
-  (const char*, std::size_t)` pair -- from an object, member by member, each value converted with `#!cpp get<V>()`; with a repeated
+  constructible from a `#!cpp (const char*, std::size_t)` pair -- views of the members of an object; with a repeated
-  key, the *last* value is kept, as [`BasicJsonType::parse()`](../basic_json/parse.md) (and
+  key, the view of the *last* member is kept, as [`BasicJsonType::parse()`](../basic_json/parse.md) keeps its value
-  [`materialize()`](materialize.md)) does; `#!cpp std::map<std::string, basic_json_view>` keeps views of the members
-  instead of values
 
-Every other `T` -- `#!cpp std::list`, `#!cpp std::pair`, `#!cpp std::array`, enumerations, user types with a
+A default-constructible `T` whose `from_json()` accepts views reads the view directly as well, without building a
-`from_json()`, ... -- is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
+`BasicJsonType` value. This covers the library's own conversions of the standard library types -- all other
+`#!cpp std::vector`s, `#!cpp std::map`/`#!cpp std::unordered_map` (also with other key types), `#!cpp std::list`,
+`#!cpp std::deque`, `#!cpp std::set`, `#!cpp std::forward_list`, `#!cpp std::valarray`, `#!cpp std::array`, C arrays,
+`#!cpp std::pair`, `#!cpp std::tuple`, `#!cpp std::optional`, enumerations, `#!cpp std::filesystem::path`, ... --
+which give the same values as `#!cpp materialize().get<T>()` (from an object, a repeated key keeps the *last* value,
+as [`BasicJsonType::parse()`](../basic_json/parse.md) does), as well as the types of the
+[`NLOHMANN_DEFINE_TYPE_*`](../macros/nlohmann_define_type_intrusive.md) and
+[`NLOHMANN_DEFINE_DERIVED_TYPE_*`](../macros/nlohmann_define_derived_type.md) macros and the enumerations of
+[`NLOHMANN_JSON_SERIALIZE_ENUM`](../macros/nlohmann_json_serialize_enum.md), and any `from_json()` constrained to
+accept views, e.g. with [`is_json_view`](../is_json_view.md). A `from_json()` that also accepts types that are no JSON
+values at all, such as the unconstrained `#!cpp template<typename BasicJsonType> void from_json(const BasicJsonType&,
+T&)` of [arbitrary type conversions](../../features/arbitrary_types.md), is not called with a view: it may use
+`BasicJsonType` functions a view does not have. See [Writing generic code](../../features/json_view.md#writing-generic-code).
+
+!!! warning "Duplicate keys"
+
+    Such a `from_json()` looks members up in the view, where a repeated key finds the **first** member, while
+    `#!cpp materialize().get<T>()` sees the **last** one, as [`BasicJsonType::parse()`](../basic_json/parse.md)
+    keeps it: for `#!cpp {"x":1,"x":2}`, `#!cpp get<point>()` reads `#!cpp x == 1`. See
+    [Duplicate keys](../../features/json_view.md#duplicate-keys).
+
+Every other `T` -- user types whose `from_json()` is written for `BasicJsonType` only, types without a default
+constructor, `#!cpp std::tuple`s holding references, ... -- is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
 value first (as [`BasicJsonType::parse()`](../basic_json/parse.md) would), and converted from there exactly as
 [`BasicJsonType::get<T>()`](../basic_json/get.md) would convert it.
 
@@ -53,12 +73,15 @@ Strong guarantee: there are no changes to the view or the document it refers to.
   throws for the same JSON type and `T`.
 - For `#!cpp std::vector<U, A>`: throws `type_error.302` if the value is not an array; otherwise, whatever converting
   an element to `U` throws.
-- For `#!cpp std::map`/`#!cpp std::unordered_map`: throws `type_error.302` if the value is not an object; otherwise,
+- For `#!cpp std::map`/`#!cpp std::unordered_map` of views: throws `type_error.302` if the value is not an object.
-  whatever converting a member to the mapped type throws.
+- For a `T` whose `from_json()` reads the view: whatever that `from_json()` throws; for the library's conversions and
+  the macros, the same exceptions with the same messages as [`BasicJsonType::get<T>()`](../basic_json/get.md) of the
+  same value.
 - For every other `T`: whatever [`materialize().get<T>()`](../basic_json/get.md) throws -- typically `type_error.302`,
   or whatever a user-provided `from_json()` throws.
 
-None of the exceptions thrown directly by this function (the first three bullets above) carry a
+None of the exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four
+bullets above) carry a
 [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no `BasicJsonType` value to point at. An
 exception thrown while converting through `materialize()` (the last bullet) is different: it is thrown by a real
 `BasicJsonType` value, so it **does** carry a `JSON_DIAGNOSTICS` path if `BasicJsonType` was built with it enabled.
@@ -76,6 +99,8 @@ document.
 - `#!cpp std::map`/`#!cpp std::unordered_map`: linear in the number of members for walking them, plus the container's
   own insertion cost per member (logarithmic for `#!cpp std::map`, amortized constant for `#!cpp
   std::unordered_map`), times the complexity of converting one member to the mapped type.
+- a `T` whose `from_json()` reads the view: the cost of that `from_json()`; for the macros, linear in the number of
+  members times the cost of a lookup, plus the cost of converting the members.
 - every other `T`: the cost of [`materialize()`](materialize.md) and of destroying the `BasicJsonType` value
   afterwards, plus that of [`BasicJsonType::get<T>()`](../basic_json/get.md).
 

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

@@ -5,12 +5,13 @@ template<typename T>
 T& get_to(T& v) const;
 ```
 
-Converts the value to `T` and stores it in `v`, in one of two ways:
+Converts the value to `T` and stores it in `v`, in one of three ways:
 
 - For the types that [`get<T>()`](get.md) converts directly -- arithmetic types, `#!cpp bool`,
   `#!cpp std::nullptr_t`, [`string_view_t`](index.md#member-types), `#!cpp std::basic_string`, `BasicJsonType`,
-  `basic_json_view`, `#!cpp std::vector`, and `#!cpp std::map`/`#!cpp std::unordered_map` with string keys -- `v` is
+  `basic_json_view`, vectors of these, and maps of views -- `v` is assigned: `#!cpp v = get<T>()`.
-  assigned: `#!cpp v = get<T>()`.
+- For a type whose `from_json()` accepts views (see [`get<T>()`](get.md)), that `from_json()` is called with the
+  view and the existing `v`, without building a `BasicJsonType` value.
 - For every other type, the subtree is built into a `BasicJsonType` value and `#!cpp materialize().get_to(v)` is
   called, i.e. `from_json()` is invoked with the existing `v`, exactly as
   [`BasicJsonType::get_to()`](../basic_json/get_to.md) does.

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

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-template<typename BasicJsonType, bool Editable = false>
+template<typename BasicJsonType, view_mode Mode = view_mode::read_only>
 class basic_json_view;
 ```
 
@@ -37,7 +37,7 @@ Moving the document itself does not invalidate its views: the index is heap-allo
 `#!cpp operator ValueType()`), and no `#!cpp get_ptr()` or `#!cpp get_ref()`; see [`get`](get.md).
 
 `basic_json_view` itself is always read-only -- it never has a `set` or `push_back` of its own. A view of an
-**editable** document (`#!cpp Editable == true`) sees every edit made through
+**editable** document (`#!cpp view_mode::editable`) sees every edit made through
 [`basic_json_document::set`](../basic_json_document/set.md) and
 [`basic_json_document::push_back`](../basic_json_document/push_back.md): once a value is changed, every view that
 still refers to it -- including ones taken before the change -- reads the new value. See
@@ -49,9 +49,10 @@ still refers to it -- including ones taken before the change -- reads the new va
 :   a specialization of [`basic_json`](../basic_json/index.md), matching the
     [`basic_json_document`](../basic_json_document/index.md) the view was taken from.
 
-`Editable`
+`Mode`
-:   whether the view is of an editable document, matching the [`basic_json_document`](../basic_json_document/index.md)
+:   a [`view_mode`](../view_mode.md): whether the view is of an editable document, matching the
-    it was taken from (optional, `#!cpp false` by default). See [Edits](../basic_json_document/index.md#edits).
+    [`basic_json_document`](../basic_json_document/index.md) it was taken from (optional, `#!cpp view_mode::read_only` by
+    default). See [Edits](../basic_json_document/index.md#edits).
 
 ## Specializations
 
@@ -63,6 +64,7 @@ still refers to it -- including ones taken before the change -- reads the new va
 
 ## Member types
 
+- **basic_json_type** - `BasicJsonType` (it also marks the class for [`is_json_view`](../is_json_view.md))
 - **value_t** - the JSON type enumeration, see [`basic_json::value_t`](../basic_json/value_t.md)
 - **string_t**, **number_integer_t**, **number_unsigned_t**, **number_float_t**, **json_pointer** - the corresponding
   member types of `BasicJsonType`
@@ -143,6 +145,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.

docs/mkdocs/docs/api/basic_json_view/operator[].md

@@ -86,7 +86,8 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
    Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
    constant time on average.
 2. Linear in `idx`: elements are skipped one at a time from the first one, since they are not a fixed size in the
-   index (unlike `BasicJsonType`'s array, which is random-access).
+   index (unlike `BasicJsonType`'s array, which is random-access). Constant if no element of the array is an array
+   or object, since the elements are then adjacent in the index.
 3. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
    that level (as 1.) or the index into the array (as 2.).
 

docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md

@@ -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.

docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md

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

docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md

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

docs/mkdocs/docs/api/byte_container_with_subtype/index.md

@@ -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.

docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md

@@ -44,4 +44,4 @@ Constant.
 
 ## Version history
 
-Since version 3.8.0.
+Added in version 3.8.0.

docs/mkdocs/docs/api/is_json_view.md

@@ -0,0 +1,56 @@
+# <small>nlohmann::</small>is_json_view
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+template<typename T>
+struct is_json_view;
+```
+
+A type trait: `#!cpp is_json_view<T>::value` is `#!cpp true` if `T` is a [`basic_json_view`](basic_json_view/index.md)
+of any `BasicJsonType` and any [`view_mode`](view_mode.md) -- [`json_view`](json_view.md),
+[`json_editable_view`](json_editable_view.md), [`ordered_json_view`](ordered_json_view.md), ... -- and
+`#!cpp false` otherwise, for [`basic_json`](basic_json/index.md) as well.
+
+It is meant for constraining templates that accept views, in particular a `from_json()` that should read views
+directly: [`get<T>()`](basic_json_view/get.md) on a view calls a `from_json()` with the view only if that `from_json()`
+accepts views but not arbitrary types.
+
+## Template parameters
+
+`T`
+:   the type to check (without cv-qualifiers or references)
+
+## Notes
+
+A view is recognized by its member type `basic_json_type` (a [`basic_json`](basic_json/index.md) specialization) and
+its [`materialize()`](basic_json_view/materialize.md) returning that type, so the trait needs no declaration of the
+view class.
+
+## Examples
+
+??? example
+
+    The example below shows the trait, and a `from_json()` constrained to `json` values and views: `get<T>()` on a view
+    reads the view directly.
+
+    ```cpp
+    --8<-- "examples/is_json_view.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/is_json_view.output"
+    ```
+
+## See also
+
+- [basic_json_view](basic_json_view/index.md) - a handle to one value of a document
+- [get](basic_json_view/get.md) - which conversions read the view directly
+- [view_mode](view_mode.md) - read-only or editable
+- [Writing generic code](../features/json_view.md#writing-generic-code) - functions and `from_json()` for views
+
+## Version history
+
+Added in version 3.13.0.

docs/mkdocs/docs/api/json.md

@@ -30,4 +30,4 @@ types.
 
 ## Version history
 
-Since version 1.0.0.
+Added in version 1.0.0.

docs/mkdocs/docs/api/json_document.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using json_document = basic_json_document<json>;
+using json_document = basic_json_document<json, view_mode::read_only>;
 ```
 
 This type is a [`basic_json_document`](basic_json_document/index.md) of the default [`json`](json.md)
@@ -32,4 +32,4 @@ specialization.
 
 ## Version history
 
-Since version 3.13.0.
+Added in version 3.13.0.

docs/mkdocs/docs/api/json_editable_document.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using json_editable_document = basic_json_document<json, true>;
+using json_editable_document = basic_json_document<json, view_mode::editable>;
 ```
 
 This type is an **editable** [`basic_json_document`](basic_json_document/index.md) of the default
@@ -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.

docs/mkdocs/docs/api/json_editable_view.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using json_editable_view = basic_json_view<json, true>;
+using json_editable_view = basic_json_view<json, view_mode::editable>;
 ```
 
 This type is a [`basic_json_view`](basic_json_view/index.md) of a value of a
@@ -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.

docs/mkdocs/docs/api/json_pointer/operator_string_t.md

@@ -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.

docs/mkdocs/docs/api/json_pointer/to_string.md

@@ -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.

docs/mkdocs/docs/api/json_sax/index.md

@@ -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.

docs/mkdocs/docs/api/json_view.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using json_view = basic_json_view<json>;
+using json_view = basic_json_view<json, view_mode::read_only>;
 ```
 
 This type is a [`basic_json_view`](basic_json_view/index.md) of a value of a [`json_document`](json_document.md).
@@ -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.

docs/mkdocs/docs/api/macros/index.md

@@ -38,12 +38,11 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
 - [**JSON_NO_AUTOMATIC_UDLS**](json_no_automatic_udls.md) - do not include the user-defined string literals (UDLs) automatically
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
+- [**JSON_NO_SIMD**](json_no_simd.md) - use only portable code instead of vector instructions (SSE2, SSSE3, NEON)
 - [**JSON_NO_THREAD_LOCAL**](json_no_thread_local.md) - switch off the use of `thread_local` storage
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
 - [**JSON_USE_GLOBAL_UDLS**](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace
 - [**JSON_USE_SIMDUTF**](json_use_simdutf.md) - use the simdutf library to accelerate UTF-8 validation
-- [**JSON_VIEW_NO_SIMD**](json_view_no_simd.md) - use only portable code in the parser of `json_view.hpp`
-- [**JSON_VIEW_USE_SSSE3**](json_view_use_ssse3.md) - validate non-ASCII strings with SSSE3 in the parser of `json_view.hpp`
 
 ## Library version
 
@@ -136,4 +135,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

docs/mkdocs/docs/api/macros/json_no_simd.md

@@ -0,0 +1,85 @@
+# JSON_NO_SIMD
+
+```cpp
+#define JSON_NO_SIMD
+```
+
+When defined, the library uses only portable C++ code where it would otherwise use vector instructions: when scanning
+strings during parsing, and when writing floating-point numbers during serialization. This includes the parser of
+[`basic_json_document`](../basic_json_document/index.md) (`<nlohmann/json_view.hpp>`).
+
+The macro is an escape hatch, for example for toolchains that cannot compile the vector code, for sanitizers or
+analyzers that do not understand it, or to compare the speed of both variants. It does not change any result: values,
+exceptions, and error positions are the same either way. Only the speed differs.
+
+## Default definition
+
+By default, `#!cpp JSON_NO_SIMD` is not defined, and vector instructions are used where the target has them.
+
+```cpp
+#undef JSON_NO_SIMD
+```
+
+## Notes
+
+!!! note "Which instructions are used"
+
+    - **x86-64:** SSE2, which every x86-64 CPU has, finds the end of runs of plain string characters 16 bytes at a time
+      and writes the digits of floating-point numbers. The UTF-8 check of non-ASCII text needs SSSE3, which is not part
+      of x86-64: it is compiled for SSSE3 with a function attribute and used when the CPU has SSSE3 (every x86-64 CPU
+      since about 2011), else the portable check. Code compiled for SSSE3 anyway (e.g., with `-mssse3` or `-march=native`)
+      skips this check of the CPU. 32-bit x86 uses SSE2 for strings when the compiler targets it.
+    - **AArch64:** NEON, which every 64-bit Arm CPU has, checks UTF-8 text and long runs of plain string characters 16
+      bytes at a time, and writes the digits of floating-point numbers. With MSVC, only the floating-point digits use
+      NEON.
+    - **Other targets:** portable code only.
+
+    Strings are only scanned this way for contiguous input and for the characters a `#!cpp std::istream` holds in its
+    stream buffer (see [`JSON_DISABLE_STREAM_BULK_SCAN`](json_disable_stream_bulk_scan.md)); other inputs are read one
+    character at a time.
+
+!!! note "Interaction with `JSON_USE_SIMDUTF`"
+
+    With [`JSON_USE_SIMDUTF`](json_use_simdutf.md), runs of string characters are first validated by simdutf; the code
+    described here is used for what simdutf does not accept, so that errors are reported at the same position.
+    `JSON_NO_SIMD` does not affect simdutf.
+
+!!! note "ABI compatibility"
+
+    The macro selects between two definitions of the library's internal scanning and formatting functions. Whether it
+    is defined is encoded in the [namespace](../../features/namespace.md) (tag `_ns`), resulting in distinct symbol
+    names. Translation units compiled with and without it can therefore be linked into the same program without One
+    Definition Rule (ODR) violations, but they cannot exchange instances of library types.
+
+## Examples
+
+??? example "Example: switching off vector instructions"
+
+    The program parses and serializes the same values with and without the macro:
+
+    ```cpp
+    #define JSON_NO_SIMD
+    #include <iostream>
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        const json j = json::parse(R"({"name": "日本語 text", "pi": 3.141592653589793})");
+        std::cout << j.dump() << '\n';  // {"name":"日本語 text","pi":3.141592653589793}
+    }
+    ```
+
+## See also
+
+- [**parse**](../basic_json/parse.md) - deserialize from a compatible input
+- [**dump**](../basic_json/dump.md) - serialization
+- [**JSON_USE_SIMDUTF**](json_use_simdutf.md) - use the simdutf library to accelerate UTF-8 validation
+- [**JSON_DISABLE_STREAM_BULK_SCAN**](json_disable_stream_bulk_scan.md) - read a `std::istream` one character at a time
+- [Parsing: input sources and performance](../../features/parsing/index.md#input-sources-and-performance)
+- [json_view](../../features/json_view.md) - the zero-copy view, whose parser the macro also affects
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/macros/json_use_simdutf.md

@@ -6,8 +6,9 @@
 
 When defined, the parser validates the UTF-8 content of JSON strings that come from a **contiguous byte input**
 (`std::string`, `std::vector<char>`/`<std::uint8_t>`, string literals, `const char*` ranges, …) using the
-[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in scalar validator. On text with many
+[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in validator (which uses SSSE3 or NEON where
-non-ASCII characters (e.g. CJK or emoji) this can validate several times faster.
+available, see [`JSON_NO_SIMD`](json_no_simd.md)). On text with many non-ASCII characters (e.g. CJK or emoji) this can
+validate faster, depending on the CPU.
 
 This is an **opt-in external dependency**. The library itself remains header-only and its behavior is unchanged: the
 same input is accepted or rejected either way, and every parse error is reported at the same position with the same

docs/mkdocs/docs/api/macros/json_view_no_simd.md

@@ -1,52 +0,0 @@
-# JSON_VIEW_NO_SIMD
-
-```cpp
-#define JSON_VIEW_NO_SIMD
-```
-
-When defined, the parser of [`basic_json_document`](../basic_json_document/index.md) (`<nlohmann/json_view.hpp>`)
-uses only portable C++ to scan strings. By default, it scans long runs of string bytes 16 at a time with NEON on
-AArch64 (with GCC and Clang) and SSE2 on x86-64, which are part of the baseline instruction sets of these
-architectures, and validates non-ASCII text with NEON (or SSSE3, see
-[`JSON_VIEW_USE_SSSE3`](json_view_use_ssse3.md)).
-
-The same input is accepted or rejected either way, with the same values, and errors are reported the same way; only
-the speed differs. The macro exists for platforms whose compilers lack the intrinsics headers, and to test the portable
-code.
-
-!!! note "ABI compatibility"
-
-    The macro selects between two definitions of the same inline functions. Whether it is defined is encoded in the
-    [namespace](../../features/namespace.md) (tag `_vns`), resulting in distinct symbol names. Translation units
-    compiled with and without it can therefore be linked into the same program without One Definition Rule (ODR)
-    violations, but they cannot exchange instances of library types.
-
-## Default definition
-
-By default, `#!cpp JSON_VIEW_NO_SIMD` is not defined, and the vector code is used where available.
-
-```cpp
-#undef JSON_VIEW_NO_SIMD
-```
-
-## Examples
-
-??? example
-
-    The code below uses the portable string scanning of the view.
-
-    ```cpp
-    #define JSON_VIEW_NO_SIMD
-    #include <nlohmann/json_view.hpp>
-
-    ...
-    ```
-
-## See also
-
-- [JSON_VIEW_USE_SSSE3](json_view_use_ssse3.md) - validate non-ASCII strings with SSSE3 on x86-64
-- [json_view](../../features/json_view.md) - the zero-copy view
-
-## Version history
-
-- Added in version 3.13.0.

docs/mkdocs/docs/api/macros/json_view_use_ssse3.md

@@ -1,53 +0,0 @@
-# JSON_VIEW_USE_SSSE3
-
-```cpp
-#define JSON_VIEW_USE_SSSE3
-```
-
-When defined on x86-64, the parser of [`basic_json_document`](../basic_json_document/index.md)
-(`<nlohmann/json_view.hpp>`) validates non-ASCII text in strings with SSSE3 without asking the CPU first.
-
-By default, the parser checks once at run time whether the CPU has SSSE3 (all x86-64 CPUs since about 2011 have it)
-and then validates non-ASCII text 16 bytes at a time, using the "lookup4" algorithm of
-[simdjson](https://github.com/simdjson/simdjson); on CPUs without SSSE3, it validates one UTF-8 sequence at a time.
-The vector check is compiled for SSSE3 with a function attribute (GCC 4.9 and later, Clang), so this needs no compiler
-option. With MSVC, the check uses `__cpuid`. On AArch64, the vector check uses NEON and is always on.
-
-Define the macro only together with a compiler option that enables SSSE3 (e.g. `-mssse3`, or `-march=` with a CPU that
-has it), and only for programs that run on such CPUs. It saves the check of the CPU, which costs little. The same
-input is accepted or rejected either way; only the speed of non-ASCII text differs.
-
-!!! note "ABI compatibility"
-
-    The macro selects between two definitions of the same inline functions. Whether it is defined is encoded in the
-    [namespace](../../features/namespace.md) (tag `_vssse3`, on every architecture), resulting in distinct symbol
-    names. Translation units compiled with and without it can therefore be linked into the same program without One
-    Definition Rule (ODR) violations, but they cannot exchange instances of library types.
-
-## Default definition
-
-By default, `#!cpp JSON_VIEW_USE_SSSE3` is not defined.
-
-```cpp
-#undef JSON_VIEW_USE_SSSE3
-```
-
-## Examples
-
-??? example
-
-    With CMake, for a program that only runs on CPUs with SSSE3:
-
-    ```cmake
-    target_compile_definitions(your_target PRIVATE JSON_VIEW_USE_SSSE3)
-    target_compile_options(your_target PRIVATE -mssse3)
-    ```
-
-## See also
-
-- [JSON_VIEW_NO_SIMD](json_view_no_simd.md) - use only portable code in the view's parser
-- [JSON_USE_SIMDUTF](json_use_simdutf.md) - validate UTF-8 with simdutf in `basic_json`'s parser
-
-## Version history
-
-- Added in version 3.13.0.

docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md

@@ -147,6 +147,13 @@ void to_json(BasicJsonType& j, const B& b) {
     See Implementation limits for [NLOHMANN_DEFINE_TYPE_INTRUSIVE](nlohmann_define_type_intrusive.md) and
     [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE](nlohmann_define_type_non_intrusive.md), respectively.
 
+!!! info "Views"
+
+    The generated `from_json()` also reads the views of [`json_document`](../json_document.md)s
+    (`<nlohmann/json_view.hpp>`): [`get<T>()`](../basic_json_view/get.md) on a view looks the members up in the
+    view, without building a `json` value first. The base part is read from the view as well if the base's
+    `from_json()` accepts views, and from [`materialize()`](../basic_json_view/materialize.md) otherwise.
+
 ## Examples
 
 ??? example "Example: (1) NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE"
@@ -192,3 +199,5 @@ void to_json(BasicJsonType& j, const B& b) {
 6. Added in version 3.12.0.
 
 All six macros were changed to allow an empty member list in version 3.13.0.
+
+The generated `from_json()` reads the views of `json_document`s since version 3.13.0.

docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md

@@ -81,6 +81,12 @@ See the examples below for the concrete generated code.
       that serializes a struct's members positionally into a JSON array; for that, write `to_json`/`from_json` by
       hand, building/reading a `json::array()` of the members in order.
 
+!!! info "Views"
+
+    The generated `from_json()` also reads the views of [`json_document`](../json_document.md)s
+    (`<nlohmann/json_view.hpp>`): [`get<T>()`](../basic_json_view/get.md) on a view looks the members up in the
+    view, without building a `json` value first.
+
 ## Examples
 
 ??? example "Example: (1) NLOHMANN_DEFINE_TYPE_INTRUSIVE"
@@ -189,3 +195,5 @@ See the examples below for the concrete generated code.
 
 All three macros were changed to work with any `basic_json` specialization (not only `nlohmann::json`) in version 3.12.0,
 and to allow an empty member list in version 3.13.0.
+
+The generated `from_json()` reads the views of `json_document`s since version 3.13.0.

docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md

@@ -80,6 +80,12 @@ See the examples below for the concrete generated code.
       that serializes a struct's members positionally into a JSON array; for that, write `to_json`/`from_json` by
       hand, building/reading a `json::array()` of the members in order.
 
+!!! info "Views"
+
+    The generated `from_json()` also reads the views of [`json_document`](../json_document.md)s
+    (`<nlohmann/json_view.hpp>`): [`get<T>()`](../basic_json_view/get.md) on a view looks the members up in the
+    view, without building a `json` value first.
+
 ## Examples
 
 ??? example "Example: (1) NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE"
@@ -188,3 +194,5 @@ See the examples below for the concrete generated code.
 
 All three macros were changed to work with any `basic_json` specialization (not only `nlohmann::json`) in version 3.12.0,
 and to allow an empty member list in version 3.13.0.
+
+The generated `from_json()` reads the views of `json_document`s since version 3.13.0.

docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md

@@ -39,6 +39,6 @@ the library.
 ## Version history
 
 - Added in version 3.11.0. Changed inline namespace name in version 3.11.2. Added the ABI tag `_dp` in
-  version 3.12.0, and the ABI tags `_bics`, `_psp`, `_snul`, `_sbu8`, `_ekmo`, `_dsbs`, `_dufio`, `_vns`, and
+  version 3.12.0, and the ABI tags `_bics`, `_psp`, `_snul`, `_sbu8`, `_ekmo`, `_dsbs`, `_dufio`, and `_ns` in
-  `_vssse3` in version 3.13.0; see
+  version 3.13.0; see
   [`nlohmann` Namespace](../../features/namespace.md#structure).

docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum.md

@@ -45,6 +45,12 @@ inline void from_json(const BasicJsonType& j, type& e);
       Define [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](json_use_objects_for_enum_keyed_maps.md) to store them as objects
       with the converted keys. Such maps can be read from both forms.
 
+!!! info "Views"
+
+    The generated `from_json()` also reads the views of [`json_document`](../json_document.md)s
+    (`<nlohmann/json_view.hpp>`), comparing the view with the entries of the mapping, without building a `json` value
+    first.
+
 ## Examples
 
 ??? example "Example: Basic usage"
@@ -88,3 +94,5 @@ inline void from_json(const BasicJsonType& j, type& e);
 ## Version history
 
 Added in version 3.4.0.
+
+The generated `from_json()` reads the views of `json_document`s since version 3.13.0.

docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md

@@ -48,6 +48,12 @@ inline void from_json(const BasicJsonType& j, type& e);
       Define [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](json_use_objects_for_enum_keyed_maps.md) to store them as objects
       with the converted keys. Such maps can be read from both forms.
 
+!!! info "Views"
+
+    The generated `from_json()` also reads the views of [`json_document`](../json_document.md)s
+    (`<nlohmann/json_view.hpp>`), comparing the view with the entries of the mapping, without building a `json` value
+    first.
+
 ## Examples
 
 ??? example "Example: Basic usage"

docs/mkdocs/docs/api/ordered_json.md

@@ -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.

docs/mkdocs/docs/api/ordered_json_document.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using ordered_json_document = basic_json_document<ordered_json>;
+using ordered_json_document = basic_json_document<ordered_json, view_mode::read_only>;
 ```
 
 This type is a [`basic_json_document`](basic_json_document/index.md) of the [`ordered_json`](ordered_json.md)
@@ -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.

docs/mkdocs/docs/api/ordered_json_editable_document.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using ordered_json_editable_document = basic_json_document<ordered_json, true>;
+using ordered_json_editable_document = basic_json_document<ordered_json, view_mode::editable>;
 ```
 
 This type is an **editable** [`basic_json_document`](basic_json_document/index.md) of the
@@ -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.

docs/mkdocs/docs/api/ordered_json_editable_view.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using ordered_json_editable_view = basic_json_view<ordered_json, true>;
+using ordered_json_editable_view = basic_json_view<ordered_json, view_mode::editable>;
 ```
 
 This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an
@@ -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.

docs/mkdocs/docs/api/ordered_json_view.md

@@ -3,7 +3,7 @@
 <small>Defined in header `<nlohmann/json_view.hpp>`</small>
 
 ```cpp
-using ordered_json_view = basic_json_view<ordered_json>;
+using ordered_json_view = basic_json_view<ordered_json, view_mode::read_only>;
 ```
 
 This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an
@@ -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.

docs/mkdocs/docs/api/view_mode.md

@@ -0,0 +1,81 @@
+# <small>nlohmann::</small>view_mode
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+enum class view_mode : std::uint8_t
+{
+    read_only,
+    editable
+};
+```
+
+The second template parameter of [`basic_json_document`](basic_json_document/index.md) and
+[`basic_json_view`](basic_json_view/index.md): whether a document can be changed after parsing, and whether a view is
+of such a document.
+
+`read_only`
+:   the default: the document is parsed once and then only read. It carries none of the bookkeeping edits need, and
+    calling [`set`](basic_json_document/set.md), [`push_back`](basic_json_document/push_back.md),
+    [`insert`](basic_json_document/insert.md), or [`erase`](basic_json_document/erase.md) on it fails to compile.
+
+`editable`
+:   the document also offers [`set`](basic_json_document/set.md), [`push_back`](basic_json_document/push_back.md),
+    [`insert`](basic_json_document/insert.md), and [`erase`](basic_json_document/erase.md); its views see every edit,
+    see [Edits](basic_json_document/index.md#edits).
+
+The shortcuts name both modes: [`json_document`](json_document.md) and [`json_view`](json_view.md) are read-only,
+[`json_editable_document`](json_editable_document.md) and [`json_editable_view`](json_editable_view.md) are editable
+(and likewise for `ordered_json`).
+
+## Notes
+
+The mode is a compile-time property of the document's and the view's type, not a setting of a call, and there is no conversion between the two modes: a read-only view reads a
+container in place, while a view of an editable document follows the links that edits leave behind. A function that
+accepts views therefore names the modes it accepts in its signature:
+
+```cpp
+// views of editable documents only
+template<typename BasicJsonType>
+void f(basic_json_view<BasicJsonType, view_mode::editable> v);
+
+// views of read-only documents only
+template<typename BasicJsonType>
+void f(basic_json_view<BasicJsonType, view_mode::read_only> v);
+
+// views of either document type
+template<typename BasicJsonType, view_mode Mode>
+void f(basic_json_view<BasicJsonType, Mode> v);
+```
+
+A function that takes a [`json_view`](json_view.md) accepts neither an [`ordered_json_view`](ordered_json_view.md)
+nor a [`json_editable_view`](json_editable_view.md). Views of the two modes still compare with
+[`operator==`](basic_json_view/operator_eq.md).
+
+## Examples
+
+??? example
+
+    The example below shows a function template that accepts the views of both modes, and one that accepts only
+    views of editable documents.
+
+    ```cpp
+    --8<-- "examples/view_mode.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/view_mode.output"
+    ```
+
+## See also
+
+- [basic_json_document](basic_json_document/index.md) - a parsed JSON text
+- [basic_json_view](basic_json_view/index.md) - a handle to one value of a document
+- [json_editable_document](json_editable_document.md) - an editable document of `json`
+- [Writing generic code](../features/json_view.md#writing-generic-code) - functions that accept views
+
+## Version history
+
+Added in version 3.13.0.

docs/mkdocs/docs/community/roadmap.md

@@ -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:
 

docs/mkdocs/docs/css/custom.css

@@ -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);
+}

docs/mkdocs/docs/examples/accept__wide_string.cpp

@@ -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';
+}

docs/mkdocs/docs/examples/accept__wide_string.output

@@ -0,0 +1 @@
+true false

docs/mkdocs/docs/examples/is_json_view.cpp

@@ -0,0 +1,34 @@
+#include <iostream>
+#include <type_traits>
+#include <nlohmann/json_view.hpp>
+
+using nlohmann::json;
+
+namespace ns
+{
+struct person
+{
+    std::string name;
+    int age = 0;
+};
+
+// reads json values and views (of any document type), but nothing else
+template < typename J, typename std::enable_if < nlohmann::is_json_view<J>::value || std::is_same<J, json>::value, int >::type = 0 >
+void from_json(const J& j, person& p)
+{
+    p.name = j.at("name").template get<std::string>();
+    p.age = j.at("age").template get<int>();
+}
+} // namespace ns
+
+int main()
+{
+    std::cout << std::boolalpha
+              << nlohmann::is_json_view<nlohmann::json_view>::value << ' '
+              << nlohmann::is_json_view<nlohmann::ordered_json_editable_view>::value << ' '
+              << nlohmann::is_json_view<json>::value << '\n';
+
+    const nlohmann::json_document doc = nlohmann::json_document::parse(R"({"name": "Ada", "age": 36})");
+    const auto p = doc.root().get<ns::person>(); // reads the view, no json value is built
+    std::cout << p.name << ' ' << p.age << '\n';
+}

docs/mkdocs/docs/examples/is_json_view.output

@@ -0,0 +1,2 @@
+true true false
+Ada 36

docs/mkdocs/docs/examples/ordered_json_editable_document.cpp

@@ -5,7 +5,7 @@ using ordered_json_editable_document = nlohmann::ordered_json_editable_document;
 
 int main()
 {
-    // ordered_json_editable_document is basic_json_document<nlohmann::ordered_json, true>
+    // ordered_json_editable_document is basic_json_document<nlohmann::ordered_json, nlohmann::view_mode::editable>
     ordered_json_editable_document doc = ordered_json_editable_document::parse(R"({"z": 1, "a": 2, "m": 3})");
     doc.set(doc.root(), "b", 4); // set() always appends a new member at the end
 

docs/mkdocs/docs/examples/parse__wide_string.cpp

@@ -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';
+}

docs/mkdocs/docs/examples/parse__wide_string.output

@@ -0,0 +1,6 @@
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+[1,2,3]
+{"name":"é"}