Fix rollback of pointer operator[] for unusual object and string types

Follow-up to the strong exception guarantee of the non-const operator[](json_pointer): - get_unchecked_create assumed that emplace() always inserts the key that the walk did not find. For object types whose lookup and emplace() disagree (e.g. a copied fifo_map), nothing was inserted, the rollback erased the existing member, and the walk continued with a value of the wrong type (assertion, type_error.305, or a crash). It now checks the result of emplace(), arms the rollback only if a key was inserted, and otherwise continues the walk with the member found, as basic_json's operator[] does: such pointers throw out_of_range.404 and leave the value unchanged, as before the strong guarantee. - The rollback erased the inserted key by key, which converts string_t to object_t::key_type and may allocate inside a noexcept function (std::terminate on bad_alloc with custom key types). It now erases by the iterator emplace() returned, and shrinks a grown array with erase() at the end instead of resize(). The documentation states the remaining requirement for custom template parameters. - Creating values no longer calls string_t::begin(), so the non-const operator[](json_pointer) compiles with string types that lack it (as the alternative string type of the tests). - Correct the @throw lists of get_unchecked and get_unchecked_create. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Make the strongly exception-safe pointer operator[] faster than before
2026-10-27 00:08:55 +00:00 · 2026-10-26 17:13:52 +01:00 · 2026-10-26 17:13:52 +01:00 · 2026-10-26 17:13:52 +01:00 · 2026-10-26 17:13:48 +01:00 · 2026-10-26 17:12:05 +01:00
750 changed files with 29174 additions and 673536 deletions
@@ -1,3 +1,33 @@
 # Style or vendor rule sets that do not fit a header-only library:
 #   altera-*, fuchsia-*, llvmlibc-*, android-cloexec-fopen, boost-use-ranges, llvm-header-guard,
 #   llvm-include-order, llvm-prefer-static-over-anonymous-namespace, llvm-use-ranges,
 #   misc-use-anonymous-namespace, google-runtime-float, google-runtime-int, hicpp-signed-bitwise,
 #   bugprone-signed-bitwise, hicpp-explicit-conversions, google-explicit-constructor,
 #   cppcoreguidelines-explicit-constructor, misc-explicit-constructor (implicit conversions are the
 #   API), readability-trailing-comma,
 #   hicpp-avoid-goto / cppcoreguidelines-avoid-goto, hicpp-no-array-decay,
 #   hicpp-uppercase-literal-suffix, readability-uppercase-literal-suffix, modernize-use-trailing-return-type.
 # Constructs the library needs on purpose (the library supports C++11 and legacy compilers):
 #   cppcoreguidelines-macro-usage, cppcoreguidelines-avoid-do-while (macros),
 #   cppcoreguidelines-pro-bounds-*, cppcoreguidelines-pro-type-reinterpret-cast,
 #   cppcoreguidelines-pro-type-union-access (parsers, serializers, basic_json's value union),
 #   cppcoreguidelines-avoid-const-or-ref-data-members, cppcoreguidelines-rvalue-reference-param-not-moved,
 #   cppcoreguidelines-avoid-non-const-global-variables, misc-non-private-member-variables-in-classes,
 #   misc-no-recursion (value walks are recursive, bounded by detail::recursion_depth_limit()),
 #   modernize-type-traits, modernize-use-constraints, modernize-use-ranges, modernize-use-std-numbers,
 #   modernize-use-designated-initializers, modernize-use-nodiscard, modernize-concat-nested-namespaces,
 #   readability-redundant-typename, readability-redundant-parentheses,
 #   readability-redundant-access-specifiers, readability-simplify-boolean-expr,
 #   readability-use-concise-preprocessor-directives, modernize-use-string-view,
 #   modernize-use-integer-sign-comparison (needs std::cmp_less; the flagged
 #   static_cast<std::size_t>(end - pos) < n comparisons are deliberate)
 #   (all need a newer standard or compiler than C++11, or would change macro-generated or
 #   deliberately explicit code).
 # Too noisy to be useful (numeric parsing/formatting code, doctest, tests):
 #   bugprone-easily-swappable-parameters, cppcoreguidelines-avoid-magic-numbers, readability-magic-numbers,
 #   readability-identifier-length, readability-function-cognitive-complexity, performance-enum-size,
 #   concurrency-mt-unsafe, misc-confusable-identifiers, misc-include-cleaner (run on its own for
 #   the consumer headers in cmake/ci.cmake).
 # portability-avoid-pragma-once: kept disabled on purpose. #pragma once is accepted
 # by every supported compiler, and tools/amalgamate/amalgamate.py strips it from
 # single_include, so there is nothing left to fix here.
@@ -10,14 +40,14 @@ Checks: '*,
         -android-cloexec-fopen,
         -boost-use-ranges,
         -bugprone-easily-swappable-parameters,
-         -cert-err58-cpp,
+         -bugprone-signed-bitwise,
         -clang-analyzer-webkit.NoUncountedMemberChecker,
         -concurrency-mt-unsafe,
         -cppcoreguidelines-avoid-const-or-ref-data-members,
         -cppcoreguidelines-avoid-do-while,
         -cppcoreguidelines-avoid-goto,
         -cppcoreguidelines-avoid-magic-numbers,
         -cppcoreguidelines-avoid-non-const-global-variables,
         -cppcoreguidelines-explicit-constructor,
         -cppcoreguidelines-macro-usage,
         -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access,
         -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
@@ -26,19 +56,15 @@ Checks: '*,
         -cppcoreguidelines-pro-type-reinterpret-cast,
         -cppcoreguidelines-pro-type-union-access,
         -cppcoreguidelines-rvalue-reference-param-not-moved,
         -cppcoreguidelines-virtual-class-destructor,
         -fuchsia-default-arguments-calls,
         -fuchsia-default-arguments-declarations,
         -fuchsia-overloaded-operator,
         -google-explicit-constructor,
         -google-readability-function-size,
         -google-runtime-float,
         -google-runtime-int,
         -hicpp-avoid-goto,
         -hicpp-explicit-conversions,
         -hicpp-function-size,
         -hicpp-no-array-decay,
         -hicpp-no-assembler,
         -hicpp-signed-bitwise,
         -hicpp-uppercase-literal-suffix,
         -llvm-header-guard,
@@ -48,6 +74,7 @@ Checks: '*,
         -llvmlibc-*,
         -misc-use-anonymous-namespace,
         -misc-confusable-identifiers,
         -misc-explicit-constructor,
         -misc-include-cleaner,
         -misc-no-recursion,
         -misc-non-private-member-variables-in-classes,
@@ -55,20 +82,22 @@ Checks: '*,
         -modernize-type-traits,
         -modernize-use-constraints,
         -modernize-use-designated-initializers,
         -modernize-use-integer-sign-comparison,
         -modernize-use-nodiscard,
         -modernize-use-ranges,
         -modernize-use-string-view,
         -modernize-use-std-numbers,
         -modernize-use-trailing-return-type,
         -performance-enum-size,
         -portability-avoid-pragma-once,
         -readability-function-cognitive-complexity,
         -readability-function-size,
         -readability-identifier-length,
         -readability-magic-numbers,
         -readability-redundant-access-specifiers,
         -readability-redundant-parentheses,
         -readability-redundant-typename,
         -readability-simplify-boolean-expr,
         -readability-trailing-comma,
         -readability-uppercase-literal-suffix,
         -readability-use-concise-preprocessor-directives'
@@ -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
@@ -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)/.*"
@@ -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,_vns --abi-tags _diag --output $RUNNER_TEMP/abi_tags.natvis
          grep -q '<!-- Namespace nlohmann::json_abi_diag_dp_vns -->' $RUNNER_TEMP/abi_tags.natvis
          grep -q '<!-- Namespace nlohmann::json_abi_diag_dp_vns_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: |
@@ -1,81 +0,0 @@
 name: "Check API documentation"
 on:
  pull_request:
 permissions:
  contents: read
 jobs:
  check_api_docs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
        with:
          egress-policy: audit
      - name: Checkout pull request
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Install clang
        # Used only as a subprocess for `clang++ -E -v` system-include-path discovery in
        # extract_api.py; it does not need to version-match the pinned libclang pip wheel
        # below, which does the actual AST parsing. Do not "fix" this to be version-matched.
        run: sudo apt-get update && sudo apt-get install -y clang
      - name: Install Python dependencies
        run: pip install -r tools/api_checker/requirements.txt
      - name: Extract API and regenerate the committed surface file
        run: |
          python3 tools/api_checker/extract_api.py \
            --header include/nlohmann/json.hpp \
            --include include \
            --output /tmp/api_snapshot.json \
            --surface-output tools/api_checker/api_surface.json
      - name: "Check API documentation (Phase 1: advisory)"
        # Surfaces missing/broken @sa links without failing the job while the backlog from the
        # initial AST-based rollout is burned down. See tools/api_checker/POLICY.md and the PR
        # that introduced this workflow for the two-phase rollout plan.
        continue-on-error: true
        run: |
          python3 tools/api_checker/check_docs.py \
            --snapshot /tmp/api_snapshot.json
      - name: Check macro documentation (advisory only)
        # Cross-checks docs/mkdocs/docs/api/macros/ pages against #define sites. Only checks the
        # documented-macro-still-exists direction; never blocks CI. See POLICY.md.
        run: python3 tools/api_checker/check_macros.py
      - name: Check for uncommitted API surface changes
        id: diff
        run: |
          mkdir -p ${{ github.workspace }}/patch
          git diff --patch --no-color -- tools/api_checker/api_surface.json > ${{ github.workspace }}/patch/api_surface.patch
          if [ -s ${{ github.workspace }}/patch/api_surface.patch ]; then
            echo "tools/api_checker/api_surface.json is out of date. Diff:"
            cat ${{ github.workspace }}/patch/api_surface.patch
            echo "has_diff=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_diff=false" >> "$GITHUB_OUTPUT"
          fi
      # Uploaded so contributors can fix their PR with `git apply api_surface.patch`
      # instead of installing libclang locally.
      - name: Upload patch
        if: steps.diff.outputs.has_diff == 'true'
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: api-surface-patch
          path: patch/api_surface.patch
      - name: Fail if API surface file is not up to date
        # Unlike the doc-backlog check above, this is purely mechanical regeneration with no
        # backlog to phase in -- blocking from the start, matching check_amalgamation.yml's
        # precedent. Contributors who add/remove/rename public API must regenerate and commit
        # tools/api_checker/api_surface.json as part of their PR.
        if: steps.diff.outputs.has_diff == 'true'
        run: exit 1
@@ -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
@@ -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 }}
@@ -43,10 +43,11 @@ jobs:
      - name: flawfinder_scan
        uses: david-a-wheeler/flawfinder@c4216b74cf2639ffa98503768bd6e4299b5440c9 # v2.0.20
        with:
-          arguments: '--sarif ./'
+          # single_include/ is generated from include/ and would report every finding twice
          arguments: "--sarif --exclude '*/single_include/*' ./"
          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
@@ -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/
@@ -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
@@ -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()
@@ -3,7 +3,6 @@
 *.gcno
 *.gcda
 .DS_Store
 __pycache__/
 /.idea
 /cmake-build-*
@@ -45,10 +44,6 @@ venv
 nlohmann_json.spdx
 # api_checker: ephemeral, location/doc-status-sensitive working file (not the committed
 # release-tracking artifact -- see tools/api_checker/api_surface.json for that)
 /tools/api_checker/api_snapshot.json
 # Bazel-related
 MODULE.bazel.lock
@@ -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",
@@ -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,_vns --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)
@@ -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,_vns --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
@@ -105,7 +105,7 @@ Thanks everyone!
 :books: If you want to **learn more** about how to use the library, check out the rest of the [**README**](#examples), have a look at [**code examples**](https://github.com/nlohmann/json/tree/develop/docs/mkdocs/docs/examples), or browse through the [**help pages**](https://json.nlohmann.me).
-:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below. The public API surface is derived mechanically and checked for documentation coverage by the tooling in [`tools/api_checker/`](tools/api_checker/), whose [POLICY.md](tools/api_checker/POLICY.md) defines what counts as public API and what stability is guaranteed.
+:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below.
 :bug: If you found a **bug**, please check the [**FAQ**](https://json.nlohmann.me/home/faq/) if it is a known issue or the result of a design decision. Please also have a look at the [**issue list**](https://github.com/nlohmann/json/issues) before you [**create a new issue**](https://github.com/nlohmann/json/issues/new/choose). Please provide as much information as possible to help us understand and reproduce your issue.
@@ -151,7 +151,7 @@ The `json` class provides an API for manipulating a JSON value. To create a `jso
 ```cpp
 #include <fstream>
 #include <nlohmann/json.hpp>
-using json = nlohmann::json;
+using nlohmann::json;
 // ...
@@ -164,7 +164,7 @@ If using modules (enabled with `NLOHMANN_JSON_BUILD_MODULES`), this example beco
 import std;
 import nlohmann.json;
-using json = nlohmann::json;
+using nlohmann::json;
 // ...
@@ -842,7 +842,7 @@ assert(p == p2);
 To make this work with one of your types, you only need to provide two functions:
 ```cpp
-using json = nlohmann::json;
+using nlohmann::json;
 namespace ns {
    void to_json(json& j, const person& p) {
@@ -1257,7 +1257,7 @@ See the page [quality assurance](https://json.nlohmann.me/community/quality_assu
 #include <nlohmann/json.hpp>
 // for convenience
-using json = nlohmann::json;
+using nlohmann::json;
 ```
 to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and Clang).
@@ -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)
@@ -30,6 +30,14 @@ struct adl_serializer {
 - [**from_json**](from_json.md) - convert a JSON value to any value type
 - [**to_json**](to_json.md) - convert any value type to a JSON value
 ## See also
 - [Arbitrary type conversions](../../features/arbitrary_types.md) - how to make your types convertible
 - [**get**](../basic_json/get.md) / [**get_to**](../basic_json/get_to.md) - convert a JSON value to a C++ type
 - [**basic_json**](../basic_json/basic_json.md) - construct a JSON value from a C++ value
 - [**NLOHMANN_DEFINE_TYPE_INTRUSIVE**](../macros/nlohmann_define_type_intrusive.md) - generate the conversion functions for a type
 - [Specializing enum conversion](../../features/enum_conversion.md)
 ## Version history
 - Added in version 2.1.0.
@@ -23,6 +23,9 @@ Checks whether the input is valid JSON.
    respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
    the iterator type with `operator!=`.
    Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its
    low surrogate, and a code point above `U+10FFFF` all make this function return `false`.
 Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
 (i.e., a parse error) nor creates diagnostic information.
@@ -35,9 +38,12 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
    - a `#!c FILE` pointer (throws if null)
    - a C-style array of characters
    - a pointer to a null-terminated string of single byte characters (throws if null)
-    - a `std::string`
+    - a `std::string` or a `std::string_view` (C++17)
    - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
      (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
    - wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
      (`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
      null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported
 `IteratorType`
 :   a compatible iterator type, for instance.
@@ -125,6 +131,21 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
    --8<-- "examples/accept__iterator_pair.output"
    ```
 ??? example "Example: (3) reading from UTF-16 strings"
    The encoding is deduced from the character type of the input. String literals like `u"..."`, `U"..."`, and
    `L"..."` work as well.
    ```cpp
    --8<-- "examples/accept__wide_string.cpp"
    ```
    Output:
    ```json
    --8<-- "examples/accept__wide_string.output"
    ```
 ## See also
 - [parse](parse.md) - deserialize from a compatible input
@@ -151,6 +172,9 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
 - Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
  a code point above `U+10FFFF`) is rejected in version 3.13.0; before that, some such sequences were accepted or
  ended the input silently.
 !!! warning "Deprecation"
@@ -90,7 +90,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Constant.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
-4. Logarithmic in the size of the container.
+4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
   constant for an array.
 ## Notes
@@ -239,9 +240,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.
@@ -63,4 +63,4 @@ Constant.
 ## Version history
 - Added in version 1.0.0.
- Adjusted code to return reference to binary values in version 3.8.0.
+- Binary values are supported since version 3.8.0.
@@ -482,17 +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. Also initializes the position reported by
+4. Added in version 3.1.2. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
-   [`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) from `val` when
+   version 3.13.0.
-   [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is enabled, since version 3.12.0. Explicit
+5. Added in version 1.0.0.
-   for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.0.
+6. Added in version 1.0.0.
-5. Since version 1.0.0.
+7. Added in version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
 6. Since version 1.0.0.
 7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
   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.
@@ -1,38 +0,0 @@
 # <small>nlohmann::basic_json::</small>bjdata_version_t
 ```cpp
 enum class bjdata_version_t
 {
    draft2,
    draft3,
 };
 ```
 This enumeration is used in the [`to_bjdata`](to_bjdata.md) function to choose which draft version of
 the BJData specification to encode ND-array extensions for:
 draft2
 :   encode using the BJData Draft 2 ND-array format
 draft3
 :   encode using the BJData Draft 3 ND-array format
 ## Examples
 ??? example
    The example shows how `bjdata_version_t` selects the BJData draft used by `to_bjdata`.
    ```cpp
    --8<-- "examples/bjdata_version_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/bjdata_version_t.output"
    ```
 ## Version history
 - Added in version 3.12.0.
@@ -61,11 +61,18 @@ Strong exception safety: if an exception occurs, the original value stays intact
 ## Complexity
-Logarithmic in the size of the JSON object.
+1. Logarithmic in the size of the JSON object.
 2. Logarithmic in the size of the JSON object.
 3. At most one lookup per reference token of `ptr`, each logarithmic in the size of the container at that level:
   O(*n* log *m*) for *n* reference tokens and containers of size at most *m*.
 4. Deleted; a call with an integral argument does not compile.
 ## Notes
- This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+- Overloads (1) and (2) always return `#!cpp false` when executed on a JSON type that is not an object. Overload (3)
  also works on arrays and on primitive values: the empty JSON pointer resolves in every JSON value (so
  `#!cpp json(1).contains(""_json_pointer)` returns `#!cpp true`), and `#!cpp json({1, 2}).contains("/1"_json_pointer)`
  returns `#!cpp true`.
 - This method can be executed on any JSON value type.
 - Calling this function with an integer argument (for example, `#!cpp contains(0)`) does not compile: such an argument
  would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when
@@ -141,9 +148,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.
@@ -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.
@@ -2,17 +2,27 @@
 ```cpp
 static basic_json diff(const basic_json& source,
-                       const basic_json& target);
+                       const basic_json& target,
                       const string_t& path = "");
 ```
 Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling
 [`patch`](patch.md) function.
-For two JSON values `source` and `target`, the following code always yields `#!cpp true`:
+For two JSON values `source` and `target`, the following code yields `#!cpp true`:
 ```cpp
 source.patch(diff(source, target)) == target;
 ```
 The equality holds up to [`operator==`](operator_eq.md), so it has the following exceptions:
 - A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and
  to [discarded](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is
  serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`.
 - Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`,
  `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `#!json []`. The patched value is then
  the `source` and keeps its number type.
 ## Parameters
 `source` (in)
@@ -21,6 +31,12 @@ source.patch(diff(source, target)) == target;
 `target` (in)
 :   JSON value to compare against
 `path` (in)
 :   a prefix that is put verbatim in front of the `path` member of every operation (default: `""`, which addresses the
    root of the value). The prefix is neither escaped nor validated: `#!cpp diff(1, 2, "abc")` yields an operation with
    the `path` `abc`, which is not a valid JSON Pointer. Use it with a valid JSON Pointer such as `/root` and escape
    `~` and `/` in its reference tokens (see [JSON Pointer](../../features/json_pointer.md)).
 ## Return value
 a JSON patch to convert the `source` to `target`
@@ -31,11 +47,32 @@ Strong guarantee: `source` and `target` are never modified.
 ## Complexity
-Linear in the lengths of `source` and `target`.
+Linear in the total number of values (including nested ones) in `source` and `target`, times the cost of a key-based
 object operation (looking up a key in an object): logarithmic for [`json`](../json.md), and linear for
 [`ordered_json`](../ordered_json.md) (see [`ordered_map` complexity](../ordered_map.md#complexity)). For
 `ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²) when their keys do not line up
 (e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of
 operations times the length of their paths, so a small change deep inside a value yields a long `path`.
 ## Notes
-Currently, only `remove`, `add`, and `replace` operations are generated.
+- Currently, only `remove`, `add`, and `replace` operations are generated.
 - The patch is correct, but not guaranteed to be minimal. For instance, `diff([1,2,3], [0,1,2,3])` yields three
  `replace` operations and one `add` operation instead of a single insertion.
 - Differences between two arrays are reported index by index. Elements that were added at the end of the array are added
  with `add` operations on the path `/-` (appended in order), and elements that were removed are removed with `remove`
  operations from the highest index down to the lowest, so that the remaining indices stay valid.
 - For objects, the operations for the members of `source` come first (`replace`, `remove`, or the operations for nested
  values, in the iteration order of `source`), followed by `add` operations for the members that only `target` has.
 - For [`ordered_json`](../ordered_json.md), objects with the same keys in a different order are different. As a patch
  cannot reorder members, `diff` removes all keys of the `source` object and adds them again in the order of the
  `target`.
 - If `source` and `target` differ as a whole (e.g., different types), the patch consists of a single `replace`
  operation for the root of the value, i.e., with the `path` `""` (or the given `path` prefix).
 - The `value` members of the patch hold copies of values of `target`. A [binary](../../features/binary_values.md) value
  has no JSON representation: when a patch that contains one is serialized, it becomes an object such as
  `#!json {"bytes":[1,3],"subtype":null}`, so a parsed patch no longer holds a binary value (and would set that object
  instead).
 ## Examples
@@ -69,6 +69,6 @@ Logarithmic in the size of the container, O(log(`size()`)).
 ## Version history
- Since version 2.0.8.
+- Added in version 2.0.8.
 - Fixed in version 3.13.0: for [`ordered_json`](../ordered_json.md), the value could previously only be passed as an
  rvalue; it can now also be passed as an lvalue or a `#!cpp const` lvalue, matching the behavior of `json`.
@@ -67,5 +67,5 @@ Amortized constant.
 ## Version history
- Since version 2.0.8.
+- Added in version 2.0.8.
 - Returns reference since 3.7.0.
@@ -213,7 +213,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 3. Added in version 1.0.0.
-4. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
+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.
@@ -84,4 +84,4 @@ constructor.
 ## Version history
- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -99,8 +99,7 @@ Logarithmic in the size of the JSON object.
 ## Version history
 1. Added in version 3.11.0.
-2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Fixed in version 3.13.0 to
+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.
@@ -57,4 +57,4 @@ Constant.
 ## Version history
 - Added in version 1.0.0.
- Adjusted code to return reference to binary values in version 3.8.0.
+- Binary values are supported since version 3.8.0.
@@ -188,6 +188,6 @@ overload (3).
 ## Version history
-1. Since version 2.1.0.
+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.
@@ -45,7 +45,7 @@ Constant.
    #include <iostream>
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -76,5 +76,5 @@ Depends on the `json_serializer<ValueType>::from_json()` implementation.
 ## Version history
- Since version 3.3.0.
+- Added in version 3.3.0.
 - Added a `static_assert` with a clear message for `const` arguments in version 3.13.0.
@@ -44,6 +44,22 @@ are collected in [Template Parameter Requirements](../../features/types/template
 - [**json**](../json.md) - default specialization
 - [**ordered_json**](../ordered_json.md) - a specialization that maintains the insertion order of object keys
 ## Documents and views
 Besides `basic_json`, the library offers a second way to hold a parsed JSON text: a
 [`basic_json_document`](../basic_json_document/index.md), which owns or borrows the text and holds a flat index of the
 values in it, and a [`basic_json_view`](../basic_json_view/index.md), a read-only handle to one value of such a document.
 Both are defined in the header `<nlohmann/json_view.hpp>`; see
 [Zero-copy JSON views](../../features/json_view.md) for the concept and the trade-offs.
 - [**json_document**](../json_document.md) / [**ordered_json_document**](../ordered_json_document.md) - read-only
  documents of the `basic_json` specialization they belong to
 - [**json_editable_document**](../json_editable_document.md) /
  [**ordered_json_editable_document**](../ordered_json_editable_document.md) - documents that can be modified in place
 - [**json_view**](../json_view.md) / [**ordered_json_view**](../ordered_json_view.md) - views of a document
 - [**json_editable_view**](../json_editable_view.md) /
  [**ordered_json_editable_view**](../ordered_json_editable_view.md) - views of an editable document
 ## Iterator invalidation
 All operations that add values to an **array** ([`push_back`](push_back.md) , [`operator+=`](operator+=.md),
@@ -343,6 +359,9 @@ Access to the JSON value
 ## See also
 - [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
 - [basic_json_document](../basic_json_document/index.md) / [basic_json_view](../basic_json_view/index.md) - parse a JSON
  text into a flat index and read it through a view
 - [Zero-copy JSON views](../../features/json_view.md) - when to use a document and a view instead of a `basic_json`
 ## Version history
@@ -1,32 +0,0 @@
 # <small>nlohmann::basic_json::</small>initializer_list_t
 ```cpp
 using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
 ```
 The type used for the initializer-list [constructor](basic_json.md) (overload 5) and for functions
 such as [`operator=`](operator=.md) that accept a braced-init-list of JSON values. Each element wraps a
 `basic_json` value or something convertible to one, deferring the decision of whether the list should be
 parsed as a JSON array or a JSON object to the constructor itself.
 See the [constructor](basic_json.md) documentation for how `initializer_list_t` values are interpreted.
 ## Examples
 ??? example
    The example shows how an `initializer_list_t` is used to construct a JSON value.
    ```cpp
    --8<-- "examples/initializer_list_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/initializer_list_t.output"
    ```
 ## Version history
 - Since version 1.0.0.
@@ -75,4 +75,4 @@ classDiagram
 ## Version history
- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -104,8 +104,8 @@ When iterating over an array, `key()` will return the index of the element as st
 ## Version history
- Added `iterator_wrapper` in version 3.0.0.
+- Added 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"
@@ -1,31 +0,0 @@
 # <small>nlohmann::basic_json::</small>json_sax_t
 ```cpp
 using json_sax_t = json_sax<basic_json>;
 ```
 The [`json_sax`](../json_sax/index.md) interface bound to this `basic_json` specialization, i.e. with
 `BasicJsonType` fixed to `basic_json`. Used as the SAX interface type by [`sax_parse`](sax_parse.md) and
 other SAX-based parsing functions.
 See [`nlohmann::json_sax`](../json_sax/index.md) for more information.
 ## Examples
 ??? example
    The example shows the type `json_sax_t`.
    ```cpp
    --8<-- "examples/json_sax_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/json_sax_t.output"
    ```
 ## Version history
 - Added in version 3.2.0.
@@ -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.
@@ -38,7 +38,7 @@ Strong guarantee: `source` and `target` are never modified.
 Linear in the total number of values (including nested ones) in `source` and `target`, times the cost of a key-based
 object operation (looking up a key, or adding one to the patch): logarithmic for [`json`](../json.md), and linear for
-[`ordered_json`](../ordered_json.md) (see [`ordered_map` complexity](../ordered_map/index.md#complexity)). For
+[`ordered_json`](../ordered_json.md) (see [`ordered_map` complexity](../ordered_map.md#complexity)). For
 `ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²).
 ## Notes
@@ -39,13 +39,33 @@ Basic guarantee: if an exception is thrown during the operation, the JSON value
 ## Complexity
-Linear in the lengths of `apply_patch`.
+Linear in the total number of values (including nested ones) in `apply_patch`, times the cost of a key-based object
 operation (looking up, adding, or erasing a member): logarithmic for [`json`](../json.md), and linear for
 [`ordered_json`](../ordered_json.md) (see [`ordered_map` complexity](../ordered_map.md#complexity)). For
 `ordered_json`, patching an object that has `n` members with a patch that has `m` members therefore takes O(n·m). The
 cost also includes one copy of `apply_patch` (see the notes below).
 ## Notes
-`apply_patch` may be `#!cpp *this` itself or refer to a value contained in `#!cpp *this` (for example, a subobject
+- `apply_patch` may be `#!cpp *this` itself or refer to a value contained in `#!cpp *this` (for example, a subobject
-returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was called, before any modification of
+  returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was called, before any modification of
-`#!cpp *this`.
+  `#!cpp *this`. To make this possible, the function copies `apply_patch` before it modifies `#!cpp *this`, so the cost
  includes one copy of the patch.
 - A merge patch uses `#!json null` to remove a member, so it cannot set a member to `#!json null`: applying
  `#!json {"a":null}` to `#!json {"a":1}` gives `#!json {}`.
 - Arrays are not merged: an array in the patch replaces the target value as a whole, and a `#!json null` inside an
  array is kept as an element. `#!json null` members of the target that the patch does not mention are preserved.
 - A `#!json null` in the patch only removes a member; it does not prevent the creation of the enclosing objects.
  Applying `#!json {"a":{"b":null}}` to `#!json {}` gives `#!json {"a":{}}` (see example 15 in Appendix A of the RFC).
 - If `apply_patch` is not an object, it replaces the target as a whole. In particular, a `#!json null` patch turns the
  target into `#!json null`. If `apply_patch` is an object and the target is not, the target is first replaced by an
  empty object, so applying `#!json {}` to `#!json 1` gives `#!json {}`.
 - A merge patch cannot express every change; for example, it cannot reorder array elements or remove a specific array
  element. Use [JSON Patch](../../features/json_patch.md) ([RFC 6902](https://tools.ietf.org/html/rfc6902)) for that.
  [`merge_diff`](merge_diff.md) has a matching limitation, see its notes.
 - A [discarded](is_discarded.md) value is treated like any other non-object value: a discarded
  `apply_patch` turns the target into a discarded value, and an object patch replaces a discarded target by an object
  as described above.
 ## Examples
@@ -71,6 +91,6 @@ returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was
 ## Version history
- Added in version 3.0.0.
+- Added in version 3.1.0.
 - Fixed use of freed or relocated memory when `apply_patch` is `#!cpp *this` or refers to a value contained in
  `#!cpp *this`, in version 3.13.0.
@@ -128,6 +128,6 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
 ## Version history
-1. Since version 1.0.0.
+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.
@@ -51,5 +51,3 @@ Linear.
 ## Version history
 - Added in version 1.0.0.
 - The `noexcept` specification was extended to also depend on
  [`json_base_class_t`](json_base_class_t.md)'s move-assignment in version 3.11.3.
@@ -92,12 +92,20 @@ Strong exception safety: if an exception occurs, the original value stays intact
    For the **const** version, an object key or array index in `ptr` that does not exist is not reported by an
    exception, but is undefined behavior (see the notes below). Use [`at`](at.md) for checked access.
    If the **non-const** version throws, the value is left unchanged: values it created for earlier reference tokens
    of `ptr` are removed again. This also holds for exceptions such as `#!cpp std::bad_alloc` or
    `#!cpp std::length_error` thrown while padding an array up to a very large index. With custom
    [template parameters](../../features/types/template_parameters.md), this requires that `erase()` of the object and
    array types and the move operations of the custom base class do not throw.
 ## Complexity
 1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
-4. Logarithmic in the size of the container.
+4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
   constant for an array. When the non-const version pads an array with `#!json null` values, it is additionally
   linear in `idx - size()` for that array.
 ## Notes
@@ -137,10 +145,21 @@ Strong exception safety: if an exception occurs, the original value stays intact
        When the JSON pointer traverses intermediate levels that don't exist at all yet (not just a missing
        leaf), each missing level is created as an array or an object depending on whether the corresponding
-        pointer token parses as a non-negative integer: a numeric token creates an array, a non-numeric token
+        pointer token is a valid array index: the token `0`, a sequence of digits that does not begin with `0`,
-        creates an object. For example, on an initially `#!json null` value, `/foo/0/0/0` creates nested arrays,
+        or the token `-` creates an array, and every other token creates an object. For example, on an
-        while `/foo/one/one/one` creates nested objects. This is not specified by the JSON Pointer RFC; it is
+        initially `#!json null` value, `/foo/0/0/0` creates nested arrays, while `/foo/one/one/one` creates
-        this library's own, intentional disambiguation rule. See also [JSON Pointer](../../features/json_pointer.md).
+        nested objects. Tokens such as `01` or the empty token cannot be array indices (cf. RFC 6901, Sect. 4)
        and therefore create objects, just as they would if the level already existed as an object. This is not
        specified by the JSON Pointer RFC; it is this library's own, intentional disambiguation rule. See also
        [JSON Pointer](../../features/json_pointer.md).
    !!! warning "Large array indices"
        As the array is filled up with `#!json null` values to the given index, the memory used grows with the index
        and not with the size of the pointer: on a 64-bit platform, the index `10000000` allocates about 160 MB.
        The library does not limit the index, so check the array indices of a JSON pointer from untrusted input
        before using it with the non-const version. See
        [Parsing untrusted input](../../features/parsing/untrusted_input.md#json-pointers-and-flattened-keys).
 !!! warning "Deprecation"
@@ -284,11 +303,13 @@ 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
-a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
+a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones. Fixed in version 3.13.0 to leave the value
 unchanged if the non-const version throws (strong exception safety, as documented); before, values created for earlier
 reference tokens of `ptr` were kept.
@@ -89,11 +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.
 - The exclusion of `std::any` from this conversion became conditional on
  [`JSON_HAS_STATIC_RTTI`](../macros/json_has_static_rtti.md) in version 3.11.3.
 - `std::optional<T>` excluded from this conversion in version 3.13.0; use
  [`get<std::optional<T>>()`](get.md)/[`get_to()`](get_to.md) instead (see
  [Converting values](../../features/conversions.md)).
@@ -75,4 +75,4 @@ classDiagram
 ## Version history
- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -76,4 +76,4 @@ classDiagram
 ## Version history
- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -25,6 +25,10 @@ static basic_json parse(IteratorType first, SentinelType last,
    respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
    the iterator type with `operator!=`.
    Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its
    low surrogate, and a code point above `U+10FFFF` all yield a
    [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101).
 ## Template parameters
 `InputType`
@@ -34,9 +38,12 @@ static basic_json parse(IteratorType first, SentinelType last,
    - a `FILE` pointer (throws if null)
    - a C-style array of characters
    - a pointer to a null-terminated string of single byte characters (throws if null)
-    - a `std::string`
+    - a `std::string` or a `std::string_view` (C++17)
    - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
      (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
    - wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
      (`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
      null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported
 `IteratorType`
 :   a compatible iterator type, for instance.
@@ -112,6 +119,13 @@ By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input
 outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-bytes-in-the-input) for details and the
 [`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) macro to opt into rejecting it instead.
 !!! tip "Parsing into a document instead of a value"
    [`basic_json_document::parse`](../basic_json_document/parse.md) accepts the same inputs and the same options, but
    keeps the result as a flat index of the parsed values instead of a tree of `basic_json` values. It is faster and uses
    less memory when only parts of the document are read, and it also accepts a pointer to a null-terminated wide string,
    which `parse()` does not. See [Zero-copy JSON views](../../features/json_view.md).
 !!! tip "Performance"
    Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A
@@ -250,6 +264,22 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
    --8<-- "examples/trailing_commas.output"
    ```
 ??? example "Example: parse from UTF-16, UTF-32, and wide strings"
    The encoding is deduced from the character type of the input; `std::u16string` and `std::u32string` are interpreted
    as UTF-16 and UTF-32, and `std::wstring` uses the platform's `wchar_t` width. String literals like `u"..."`,
    `U"..."`, and `L"..."` work as well, as do iterators over wide characters.
    ```cpp
    --8<-- "examples/parse__wide_string.cpp"
    ```
    Output:
    ```json
    --8<-- "examples/parse__wide_string.output"
    ```
 ## See also
 - [accept](accept.md) - check if the input is valid JSON
@@ -280,6 +310,9 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
  time).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) restores `std::fgetc`).
 - Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
  a code point above `U+10FFFF`) is rejected with `parse_error.101` in version 3.13.0; before that, some such
  sequences were accepted or ended the input silently.
 !!! warning "Deprecation"
@@ -84,4 +84,4 @@ or the end of file. This also holds true when reading a byte vector for binary f
 ## Version history
- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -40,7 +40,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
  where an existing element is required (the "path" of "replace", the "from" of "move" and "copy"); example:
  `"array index '-' (3) is out of range"`.
 - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch
-  could not be resolved successfully in the current JSON value; example: `"key baz not found"`.
+  could not be resolved successfully in the current JSON value; example: `"key 'baz' not found"`.
 - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if a reference token of a JSON
  pointer inside the patch cannot be resolved, e.g., `-` in a "remove" operation or `1a` for an array; example:
  `"unresolved reference token '-'"`.
@@ -53,7 +53,10 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [`out_of_range.414`](../../home/exceptions.md#jsonexceptionout_of_range414) if a "move" operation's "from"
  location is a proper prefix of its "path" location.
 - Throws [`other_error.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
-  unsuccessful.
+  unsuccessful. A "test" operation whose "path" does not exist is unsuccessful, too: the failed lookup is reported as a
  failed test, even if the operation has no "value" member (which would otherwise be
  [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105)). Which of the two errors is reported for
  this combination depends on the order in which the operands of a comparison are evaluated, so do not rely on it.
 ## Complexity
@@ -65,6 +68,10 @@ the JSON value, the complexity can usually be neglected.
 The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception
 is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.
 Duplicate member names inside an operation object are resolved by the parser before the patch is applied (the last one
 is kept, see [`object_t`](object_t.md#behavior)), so `#!json {"op": "add", "op": "remove", "path": "/a"}` is a
 `remove` operation.
 ## Examples
 ??? example "Example: apply a JSON patch"
@@ -108,6 +115,7 @@ is thrown. In any case, the original value is not changed: the patch is applied
 - Added in version 2.0.0.
 - Added [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) and stopped relying on an internal assertion when an "add" operation's
  target location has a non-object/non-array parent in version 3.13.0.
  This includes a `null` parent, which was previously silently converted to an object, in version 3.13.0.
 - Added [`out_of_range.413`](../../home/exceptions.md#jsonexceptionout_of_range413) and stopped silently ignoring a "remove" operation whose target
  location has a non-object/non-array parent in version 3.13.0.
 - Added [`out_of_range.414`](../../home/exceptions.md#jsonexceptionout_of_range414) and rejected a "move" operation whose "from" location is a proper
@@ -36,7 +36,7 @@ No guarantees, value may be corrupted by an unsuccessful patch operation.
  where an existing element is required (the "path" of "replace", the "from" of "move" and "copy"); example:
  `"array index '-' (3) is out of range"`.
 - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch
-  could not be resolved successfully in the current JSON value; example: `"key baz not found"`.
+  could not be resolved successfully in the current JSON value; example: `"key 'baz' not found"`.
 - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if a reference token of a JSON
  pointer inside the patch cannot be resolved, e.g., `-` in a "remove" operation or `1a` for an array; example:
  `"unresolved reference token '-'"`.
@@ -49,7 +49,10 @@ No guarantees, value may be corrupted by an unsuccessful patch operation.
 - Throws [`out_of_range.414`](../../home/exceptions.md#jsonexceptionout_of_range414) if a "move" operation's "from"
  location is a proper prefix of its "path" location.
 - Throws [`other_error.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
-  unsuccessful.
+  unsuccessful. A "test" operation whose "path" does not exist is unsuccessful, too: the failed lookup is reported as a
  failed test, even if the operation has no "value" member (which would otherwise be
  [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105)). Which of the two errors is reported for
  this combination depends on the order in which the operands of a comparison are evaluated, so do not rely on it.
 ## Complexity
@@ -62,6 +65,10 @@ Unlike [`patch`](patch.md), `patch_inplace` applies the operation "in place" and
 That makes it faster for large documents by avoiding the copy. However, the JSON value might be corrupted if the
 function throws an exception.
 Duplicate member names inside an operation object are resolved by the parser before the patch is applied (the last one
 is kept, see [`object_t`](object_t.md#behavior)), so `#!json {"op": "add", "op": "remove", "path": "/a"}` is a
 `remove` operation.
 ## Examples
 ??? example "Example: apply a JSON patch in place"
@@ -106,6 +113,7 @@ function throws an exception.
 - Added in version 3.11.0.
 - Added [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) and stopped relying on an internal assertion when an "add" operation's
  target location has a non-object/non-array parent in version 3.13.0.
  This includes a `null` parent, which was previously silently converted to an object, in version 3.13.0.
 - Added [`out_of_range.413`](../../home/exceptions.md#jsonexceptionout_of_range413) and stopped silently ignoring a "remove" operation whose target
  location has a non-object/non-array parent in version 3.13.0.
 - Added [`out_of_range.414`](../../home/exceptions.md#jsonexceptionout_of_range414) and rejected a "move" operation whose "from" location is a proper
@@ -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.
@@ -31,6 +31,10 @@ Read from input and generate SAX events
    respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
    the iterator type with `operator!=`.
    Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its
    low surrogate, and a code point above `U+10FFFF` all yield a
    [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101).
 The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).
 ## Template parameters
@@ -42,8 +46,12 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
    - a `FILE` pointer
    - a C-style array of characters
    - a pointer to a null-terminated string of single byte characters
    - a `std::string` or a `std::string_view` (C++17)
    - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
      (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
    - wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
      (`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
      null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported
 `IteratorType`
 :   a compatible iterator type for overload (2); a pair of character iterators whose `value_type` is an integral type
@@ -160,6 +168,9 @@ use the same file with stdio functions, but it must not wait for another thread
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
 - Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
  a code point above `U+10FFFF`) is rejected with `parse_error.101` in version 3.13.0; before that, some such
  sequences were accepted or ended the input silently.
 !!! warning "Deprecation"
@@ -182,10 +182,10 @@ Constant.
 ## Version history
-1. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
+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.
@@ -124,5 +124,3 @@ Linear in the size of the JSON value `j`.
  [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
  array or object was silently skipped, producing invalid BJData.
 - Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0; previously, they were
  silently truncated to 64 bits.
@@ -76,4 +76,4 @@ classDiagram
 ## Version history
- Since version 3.0.0.
+- Added in version 3.0.0.
@@ -36,9 +36,9 @@ The function can throw the following exceptions:
 - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in a key is not a
  number; example: `"array index 'one' is not a number"`
 - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if a level becomes an array
-  (because one of its keys is `0`) and another key at that level begins with a digit but is not a valid array index
+  (because one of its keys is `0`) and another key at that level is empty (as in `/a/`), is `-`, or begins with a digit
-  (such as `1a`), or is `-`; example:
+  but is not a valid array index (such as `1a`); examples: `"unresolved reference token '-'"`,
-  `"unresolved reference token '-'"`
+  `"unresolved reference token ''"`
 ## Complexity
@@ -46,7 +46,7 @@ Linear in the size of the JSON value.
 ## Notes
-Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and cannot unflattened to
+Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and cannot be unflattened to
 their original type.
 A flattened array and a flattened object whose keys are array indices are indistinguishable, because both are
@@ -54,7 +54,12 @@ described by the same JSON pointers. A value is therefore restored as an array i
 reference token `0`, and as an object otherwise: `#!json {"2": 1}` is restored unchanged, whereas `#!json {"0": 1}` is
 restored as `#!json [1]`. This decision does not depend on the order in which the flattened object is iterated.
-Apart from these two cases, for a JSON value `j`, the following is always true:
+A third case is an object that has the key `0` next to a key that is not a valid array index: `#!json {"0": 1, "b": 2}`
 is flattened to `#!json {"/0": 1, "/b": 2}`, and unflatten treats the level as an array and throws
 [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) because `b` is not a number. (For the keys
 `-`, `1a`, or the empty key instead of `b`, it throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404).)
 Apart from these three cases, for a JSON value `j`, the following is always true:
 `#!cpp j == j.flatten().unflatten()`.
 ## Examples
@@ -45,6 +45,9 @@ This is equivalent to Python's `dict.get(key, default)`.
       return default_value;
    }
    ```
    with one exception: if the JSON value is neither an array nor an object, the function throws
    [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) before looking at `ptr`, even for the empty
    pointer, whereas `at` returns the value itself for the empty pointer.
 !!! note "Differences to `at` and `operator[]`"
@@ -231,11 +234,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.
@@ -9,8 +9,8 @@ class basic_json_document;
 A parsed JSON text, held as a flat index of its values
 ([16 bytes per value](../../home/architecture.md#node-index-of-json-views)) instead of a tree of `BasicJsonType` values.
-Strings and numbers stay in the source text; only strings that contain escapes are decoded, into one buffer owned by
+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.
@@ -115,6 +115,13 @@ points apply to every edit:
  [`source_offset()`](../basic_json_view/source_offset.md) of a value introduced by an edit is
  `#!cpp static_cast<std::size_t>(-1)`, the same value it reports for a decoded string.
 ## See also
 - [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
 - [**basic_json_view**](../basic_json_view/index.md) - the non-owning handle to a value in a document
 - [**json_document**](../json_document.md) and [**json_editable_document**](../json_editable_document.md) - the default specializations
 - [**materialize**](../basic_json_view/materialize.md) - build a `basic_json` value from a view
 ## Version history
 - Added in version 3.13.0.
@@ -21,17 +21,19 @@ static basic_json_document parse(IteratorType first, IteratorType last,
 Both overloads accept the same JSON text as [`BasicJsonType::parse()`](../basic_json/parse.md), with the same
 `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](index.md) (a flat index into
-the input) instead of a tree of `BasicJsonType` values. They take the same inputs as `BasicJsonType::parse()`. Byte
+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`.
@@ -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.).
@@ -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
@@ -143,6 +143,13 @@ still refers to it -- including ones taken before the change -- reads the new va
 - [**source_offset**](source_offset.md) - byte offset of this value in the document's source text
 ## See also
 - [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
 - [**basic_json_document**](../basic_json_document/index.md) - the document that owns the parsed data
 - [**json_view**](../json_view.md) and [**json_editable_view**](../json_editable_view.md) - the default specializations
 - [**materialize**](materialize.md) - build a `basic_json` value from a view
 ## Version history
 - Added in version 3.13.0.
@@ -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.).
@@ -51,4 +51,4 @@ byte_container_with_subtype(container_type&& container, subtype_type subtype);
 ## Version history
-Since version 3.8.0.
+Added in version 3.8.0.
@@ -39,4 +39,4 @@ Constant.
 ## Version history
-Since version 3.8.0.
+Added in version 3.8.0.
@@ -1,32 +0,0 @@
 # <small>nlohmann::byte_container_with_subtype::</small>container_type
 ```cpp
 using container_type = BinaryType;
 ```
 The type of the underlying binary container, forwarded from the `BinaryType` template parameter that
 `byte_container_with_subtype` is instantiated with. `byte_container_with_subtype` publicly inherits from
 `container_type`.
 See [`basic_json::binary_t`](../basic_json/binary_t.md) for the type typically used to instantiate
 `BinaryType`.
 ## Examples
 ??? example
    The example shows the type `container_type`.
    ```cpp
    --8<-- "examples/byte_container_with_subtype__container_type.cpp"
    ```
    Output:
    ```
    --8<-- "examples/byte_container_with_subtype__container_type.output"
    ```
 ## Version history
 - Since version 3.8.0.
@@ -42,4 +42,4 @@ Constant.
 ## Version history
-Since version 3.8.0.
+Added in version 3.8.0.
@@ -29,6 +29,14 @@ specific naming scheme in order to override the binary type.
 - [**has_subtype**](has_subtype.md) - return whether the value has a subtype
 - [**clear_subtype**](clear_subtype.md) - clears the binary subtype
 ## See also
 - [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
 - [**binary**](../basic_json/binary.md) - create a binary array value
 - [**get_binary**](../basic_json/get_binary.md) - get a reference to the stored binary value
 - [**binary_t**](../basic_json/binary_t.md) - type for binary arrays
 - [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values
 ## Version history
 - Added in version 3.8.0.
@@ -44,4 +44,4 @@ Constant.
 ## Version history
-Since version 3.8.0.
+Added in version 3.8.0.
@@ -1,28 +0,0 @@
 # <small>nlohmann::byte_container_with_subtype::</small>subtype_type
 ```cpp
 using subtype_type = std::uint64_t;
 ```
 The type used to store the optional binary subtype tag. See [`subtype`](subtype.md) and
 [`set_subtype`](set_subtype.md).
 ## Examples
 ??? example
    The example shows the type `subtype_type`.
    ```cpp
    --8<-- "examples/byte_container_with_subtype__subtype_type.cpp"
    ```
    Output:
    ```
    --8<-- "examples/byte_container_with_subtype__subtype_type.output"
    ```
 ## Version history
 - Since version 3.8.0.
@@ -30,4 +30,4 @@ types.
 ## Version history
-Since version 1.0.0.
+Added in version 1.0.0.
@@ -32,4 +32,4 @@ specialization.
 ## Version history
-Since version 3.13.0.
+Added in version 3.13.0.
@@ -40,4 +40,4 @@ parsing, without ever rewriting the source text -- see [Edits](basic_json_docume
 ## Version history
-Since version 3.13.0.
+Added in version 3.13.0.
@@ -38,4 +38,4 @@ still referring to it seeing the change, see [Edits](basic_json_document/index.m
 ## Version history
-Since version 3.13.0.
+Added in version 3.13.0.
@@ -51,5 +51,5 @@ operator string_t() const
 ## Version history
- Since version 2.0.0.
+- Added in version 2.0.0.
 - Changed type to `string_t` and deprecated in version 3.11.0.
@@ -12,7 +12,8 @@ Parent of this JSON pointer; in case this JSON pointer is the root, the root its
 ## Exception safety
-No-throw guarantee: this function never throws exceptions.
+Strong exception safety: if an exception occurs, the original value stays intact. The function is not `#!cpp noexcept`
 and allocates a new JSON pointer, so it can throw `#!cpp std::bad_alloc`; it throws no library exceptions.
 ## Complexity
@@ -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.
@@ -1,30 +0,0 @@
 # <small>nlohmann::json_sax::</small>binary_t
 ```cpp
 using binary_t = typename BasicJsonType::binary_t;
 ```
 The type used by the [`binary`](binary.md) callback for JSON binary values, forwarded from the
 `BasicJsonType` template parameter.
 See [`basic_json::binary_t`](../basic_json/binary_t.md) for more information.
 ## Examples
 ??? example
    The example shows the type `binary_t` and its relation to `basic_json::binary_t`.
    ```cpp
    --8<-- "examples/json_sax__binary_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/json_sax__binary_t.output"
    ```
 ## Version history
 - Added in version 3.8.0.
@@ -59,6 +59,13 @@ leading `-` sign.
 - [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read
 - [**string**](string.md) (_virtual_) - a string value was read
 ## See also
 - [SAX interface](../../features/parsing/sax_interface.md) - guide to event-based parsing
 - [**sax_parse**](../basic_json/sax_parse.md) - generate SAX events from an input
 - [**parse**](../basic_json/parse.md) - DOM parsing, with optional [parser callbacks](../../features/parsing/parser_callbacks.md)
 - [Parse exceptions](../../features/parsing/parse_exceptions.md)
 ## Version history
 - Added in version 3.2.0.
@@ -1,33 +0,0 @@
 # <small>nlohmann::json_sax::</small>json_sax
 ```cpp
 // (1)
 json_sax() = default;
 // (2)
 json_sax(const json_sax&) = default;
 // (3)
 json_sax(json_sax&&) noexcept = default;
 ```
 1. Default constructor.
 2. Copy constructor.
 3. Move constructor.
 `json_sax` is a pure abstract base class with no data members of its own, so all three constructors are
 defaulted and only exist to make derived SAX consumers explicitly copyable/movable.
 ## Exception safety
 No-throw guarantee: none of these constructors throw exceptions.
 ## Complexity
 Constant.
 <!-- NOLINT Examples -->
 ## Version history
 - Added in version 3.2.0.
@@ -1,30 +0,0 @@
 # <small>nlohmann::json_sax::</small>number_float_t
 ```cpp
 using number_float_t = typename BasicJsonType::number_float_t;
 ```
 The type used by the [`number_float`](number_float.md) callback for JSON floating-point numbers,
 forwarded from the `BasicJsonType` template parameter.
 See [`basic_json::number_float_t`](../basic_json/number_float_t.md) for more information.
 ## Examples
 ??? example
    The example shows the type `number_float_t` and its relation to `basic_json::number_float_t`.
    ```cpp
    --8<-- "examples/json_sax__number_float_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/json_sax__number_float_t.output"
    ```
 ## Version history
 - Added in version 3.2.0.
@@ -1,30 +0,0 @@
 # <small>nlohmann::json_sax::</small>number_integer_t
 ```cpp
 using number_integer_t = typename BasicJsonType::number_integer_t;
 ```
 The type used by the [`number_integer`](number_integer.md) callback for JSON integer numbers, forwarded
 from the `BasicJsonType` template parameter.
 See [`basic_json::number_integer_t`](../basic_json/number_integer_t.md) for more information.
 ## Examples
 ??? example
    The example shows the type `number_integer_t` and its relation to `basic_json::number_integer_t`.
    ```cpp
    --8<-- "examples/json_sax__number_integer_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/json_sax__number_integer_t.output"
    ```
 ## Version history
 - Added in version 3.2.0.
@@ -1,30 +0,0 @@
 # <small>nlohmann::json_sax::</small>number_unsigned_t
 ```cpp
 using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
 ```
 The type used by the [`number_unsigned`](number_unsigned.md) callback for JSON unsigned integer numbers,
 forwarded from the `BasicJsonType` template parameter.
 See [`basic_json::number_unsigned_t`](../basic_json/number_unsigned_t.md) for more information.
 ## Examples
 ??? example
    The example shows the type `number_unsigned_t` and its relation to `basic_json::number_unsigned_t`.
    ```cpp
    --8<-- "examples/json_sax__number_unsigned_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/json_sax__number_unsigned_t.output"
    ```
 ## Version history
 - Added in version 3.2.0.
@@ -1,29 +0,0 @@
 # <small>nlohmann::json_sax::</small>operator=
 ```cpp
 // (1)
 json_sax& operator=(const json_sax&) = default;
 // (2)
 json_sax& operator=(json_sax&&) noexcept = default;
 ```
 1. Copy assignment operator.
 2. Move assignment operator.
 `json_sax` is a pure abstract base class with no data members of its own, so both assignment operators
 are defaulted and only exist to make derived SAX consumers explicitly copy-/move-assignable.
 ## Exception safety
 No-throw guarantee: neither operator throws exceptions.
 ## Complexity
 Constant.
 <!-- NOLINT Examples -->
 ## Version history
 - Added in version 3.2.0.
@@ -1,30 +0,0 @@
 # <small>nlohmann::json_sax::</small>string_t
 ```cpp
 using string_t = typename BasicJsonType::string_t;
 ```
 The type used by the [`string`](string.md) and [`key`](key.md) callbacks for JSON strings and object
 keys, forwarded from the `BasicJsonType` template parameter.
 See [`basic_json::string_t`](../basic_json/string_t.md) for more information.
 ## Examples
 ??? example
    The example shows the type `string_t` and its relation to `basic_json::string_t`.
    ```cpp
    --8<-- "examples/json_sax__string_t.cpp"
    ```
    Output:
    ```
    --8<-- "examples/json_sax__string_t.output"
    ```
 ## Version history
 - Added in version 3.2.0.
@@ -1,22 +0,0 @@
 # <small>nlohmann::json_sax::</small>~json_sax
 ```cpp
 virtual ~json_sax() = default;
 ```
 Destructor. Virtual to allow proper destruction of derived SAX consumer classes through a
 pointer/reference to `json_sax`.
 ## Exception safety
 No-throw guarantee: this destructor never throws exceptions.
 ## Complexity
 Constant.
 <!-- NOLINT Examples -->
 ## Version history
 - Added in version 3.2.0.
@@ -31,4 +31,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of a [`j
 ## Version history
-Since version 3.13.0.
+Added in version 3.13.0.
@@ -38,6 +38,7 @@ 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
@@ -137,3 +138,12 @@ header. See also the [macro overview page](../../features/macros.md).
  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
 ## 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
@@ -38,7 +38,7 @@ Therefore, assertions can be switched off by defining `NDEBUG`.
    ```cpp
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -64,7 +64,7 @@ Therefore, assertions can be switched off by defining `NDEBUG`.
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -79,7 +79,7 @@ The default value is `0` (disabled — existing behavior is preserved).
    ```cpp
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -98,7 +98,7 @@ The default value is `0` (disabled — existing behavior is preserved).
    #define JSON_BRACE_INIT_COPY_SEMANTICS 1
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -54,7 +54,7 @@ The default value is `0` (disabled, the deprecated functions can still be called
    ```cpp
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -72,7 +72,7 @@ The default value is `0` (disabled, the deprecated functions can still be called
    #define JSON_DELETE_DEPRECATED_FUNCTIONS 1
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -39,7 +39,7 @@ The default value is `0`.
    #define JSON_DISABLE_ENUM_SERIALIZATION 1
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    enum class Choice
    {
@@ -66,7 +66,7 @@ The default value is `0`.
    #define JSON_DISABLE_ENUM_SERIALIZATION 1
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    enum class Choice
    {
@@ -99,7 +99,7 @@ The default value is `0`.
    #define JSON_DISABLE_ENUM_SERIALIZATION 1
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    enum class Choice
    {
@@ -92,7 +92,7 @@ The default value is `0`: streams are scanned in bulk.
    #include <sstream>
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -115,7 +115,7 @@ The default value is `0`: streams are scanned in bulk.
    #include <sstream>
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -72,7 +72,7 @@ The default value is `0` (disabled — existing behavior is preserved).
    ```cpp
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -89,7 +89,7 @@ The default value is `0` (disabled — existing behavior is preserved).
    #define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -73,7 +73,7 @@ The default value is `0`: the file is locked once and read with the unlocked std
    #include <cstdio>
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -92,7 +92,7 @@ The default value is `0`: the file is locked once and read with the unlocked std
    #include <cstdio>
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -0,0 +1,83 @@
 # 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.
 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 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)
 ## Version history
 - Added in version 3.13.0.
@@ -94,7 +94,7 @@ The default value is `0` (disabled — existing behavior is preserved).
    #include <sstream>
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
@@ -115,7 +115,7 @@ The default value is `0` (disabled — existing behavior is preserved).
    #include <sstream>
    #include <nlohmann/json.hpp>
-    using json = nlohmann::json;
+    using nlohmann::json;
    int main()
    {
`@@ -84,4 +84,4 @@ constructor.`

	`## Version history`	`## Version history`

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

	`## Version history`	`## Version history`

	`- Since version 3.0.0.`	`- Added in version 3.0.0.`
`@@ -51,4 +51,4 @@ deserializes. See [Template Parameter Requirements](../../features/types/templat`

	`## Version history`	`## Version history`

	`- Since version 2.0.0.`	`- Added in version 2.1.0.`
`@@ -76,4 +76,4 @@ classDiagram`

	`## Version history`	`## Version history`

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

	`## Version history`	`## Version history`

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

	`## Version history`	`## Version history`

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

	`## Version history`	`## Version history`

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

	`## Version history`	`## Version history`

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

	`## Version history`	`## Version history`

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

	`## Version history`	`## Version history`

	`Since version 1.0.0.`	`Added in version 1.0.0.`