Merge branch 'develop' into claude/todo-191-plan-508110

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Fix links to moved API pages in the API changes page
2026-10-24 23:08:56 +00:00 · 2026-10-21 10:51:41 +02:00 · 2026-10-10 07:42:37 +02:00 · 2026-10-10 04:01:42 +02:00 · 2026-10-04 17:35:55 +02:00 · 2026-09-30 20:36:12 +02:00
330 changed files with 670129 additions and 22638 deletions
@@ -18,8 +18,7 @@ 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. The Visual Studio 2019
+    # stay below AppVeyor's 60-minute limit per job.
    # 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
@@ -51,13 +50,7 @@ environment:
      configuration: Release
      platform: x86
      CXX_FLAGS: "/W4 /WX"
-      CMAKE_OPTIONS: "-DJSON_ImplicitConversions=OFF -DJSON_TestShard=0/2"
+      CMAKE_OPTIONS: "-DJSON_ImplicitConversions=OFF"
      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,7 +64,6 @@ 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,28 +154,6 @@ 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: |
@@ -0,0 +1,81 @@
 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@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+      uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
      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@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+      uses: github/codeql-action/autobuild@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+      uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
@@ -37,14 +37,6 @@ 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,
@@ -59,11 +51,9 @@ 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.
-      - if: steps.download.outputs.found == 'true'
+      - run: unzip -o pr.zip -d ./pr_artifact
        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 }}
@@ -47,6 +47,6 @@ jobs:
          output: 'flawfinder_results.sarif'
      - name: Upload analysis results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
        with:
          sarif_file: ${{github.workspace}}/flawfinder_results.sarif
@@ -1,84 +0,0 @@
 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@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
        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@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
        with:
          sarif_file: semgrep.sarif
        if: always()
@@ -3,6 +3,7 @@
 *.gcno
 *.gcda
 .DS_Store
 __pycache__/
 /.idea
 /cmake-build-*
@@ -44,6 +45,10 @@ 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,7 +37,6 @@ 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,7 +6,6 @@ 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
@@ -290,29 +289,3 @@ 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 (pass generator options via NATVIS_ARGS, see tools/generate_natvis/README.md)"
+	@echo "natvis - regenerate nlohmann_json.natvis from the current ABI tags and version"
 	@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,15 +120,13 @@ $(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_ARGS) .
+	$(NATVIS_VENV)/bin/python3 tools/generate_natvis/generate_natvis.py .
 # 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.
+: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.
 :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.
@@ -341,14 +341,13 @@ 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.sha256(url.encode()).hexdigest()[:12]
+        digest = hashlib.sha1(url.encode(), usedforsecurity=False).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,14 +30,6 @@ 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,9 +23,6 @@ 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.
@@ -38,12 +35,9 @@ 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` or a `std::string_view` (C++17)
+    - a `std::string`
    - 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.
@@ -131,21 +125,6 @@ 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
@@ -172,9 +151,6 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
 - Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
  a code point above `U+10FFFF`) is rejected in version 3.13.0; before that, some such sequences were accepted or
  ended the input silently.
 !!! warning "Deprecation"
@@ -239,8 +239,9 @@ 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. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
+3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
-   across the lookup functions.
+   already supported by [`operator[]`](operator[].md), [`value`](value.md), [`find`](find.md), and other lookup
   functions.
 4. Added in version 2.0.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
 [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
 a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
@@ -63,4 +63,4 @@ Constant.
 ## Version history
 - Added in version 1.0.0.
- Binary values are supported since version 3.8.0.
+- Adjusted code to return reference to binary values in version 3.8.0.
@@ -482,15 +482,17 @@ basic_json(basic_json&& other) noexcept;
 ## Version history
-1. Added in version 1.0.0.
+1. Since version 1.0.0.
-2. Added in version 1.0.0.
+2. Since version 1.0.0.
-3. Added in version 2.1.0.
+3. Since version 2.1.0.
-4. Added in version 3.1.2. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
+4. Since version 3.2.0. Also initializes the position reported by
-   version 3.13.0.
+   [`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) from `val` when
-5. Added in version 1.0.0.
+   [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is enabled, since version 3.12.0. Explicit
-6. Added in version 1.0.0.
+   for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.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
+5. Since version 1.0.0.
 6. Since version 1.0.0.
 7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
   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. Added in version 1.0.0.
+8. Since version 1.0.0.
-9. Added in version 1.0.0.
+9. Since version 1.0.0.
@@ -0,0 +1,38 @@
 # <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.
@@ -141,8 +141,9 @@ 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. Support for keys
+2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Fixed in
-   convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
+   version 3.13.0 to consistently accept `std::string_view`-convertible keys, as already supported by
   [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup functions.
 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,7 +92,8 @@ 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 key types in version 3.11.0. Support for keys convertible to
+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
-   `std::string_view` added in version 3.13.0, consistently across the lookup functions.
+   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
   [`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.
@@ -69,6 +69,6 @@ Logarithmic in the size of the container, O(log(`size()`)).
 ## Version history
- Added in version 2.0.8.
+- Since 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
- Added in version 2.0.8.
+- Since version 2.0.8.
 - Returns reference since 3.7.0.
@@ -213,6 +213,7 @@ 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. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
+4. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
-   across the lookup functions.
+   already supported by [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup
   functions.
 5. Added in version 1.0.0.
@@ -84,4 +84,4 @@ constructor.
 ## Version history
- Added in version 3.0.0.
+- Since version 3.0.0.
@@ -99,7 +99,8 @@ 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. Support for keys convertible to
+2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Fixed in version 3.13.0 to
-   `std::string_view` added in version 3.13.0, consistently across the lookup functions.
+   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
   [`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.
- Binary values are supported since version 3.8.0.
+- Adjusted code to return reference to binary values in version 3.8.0.
@@ -188,6 +188,6 @@ overload (3).
 ## Version history
-1. Added in version 2.1.0.
+1. Since version 2.1.0.
-2. Added in version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.1.2.
+2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0.
-3. Added in version 1.0.0.
+3. Since version 1.0.0.
@@ -76,5 +76,5 @@ Depends on the `json_serializer<ValueType>::from_json()` implementation.
 ## Version history
- Added in version 3.3.0.
+- Since version 3.3.0.
 - Added a `static_assert` with a clear message for `const` arguments in version 3.13.0.
@@ -44,22 +44,6 @@ 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),
@@ -359,9 +343,6 @@ 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
@@ -0,0 +1,32 @@
 # <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
- Added in version 3.0.0.
+- Since 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 in version 3.1.0 as the replacement of the static function `iterator_wrapper`, which was available since
+- Added `iterator_wrapper` in version 3.0.0.
-  version 1.0.0 and is deprecated since version 3.1.0.
+- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
 - Added structured binding support in version 3.5.0.
 !!! warning "Deprecation"
@@ -0,0 +1,31 @@
 # <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
- Added in version 2.1.0.
+- Since version 2.0.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.md#complexity)). For
+[`ordered_json`](../ordered_json.md) (see [`ordered_map` complexity](../ordered_map/index.md#complexity)). For
 `ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²).
 ## Notes
@@ -71,6 +71,6 @@ returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was
 ## Version history
- Added in version 3.1.0.
+- Added in version 3.0.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. Added in version 1.0.0.
+1. Since version 1.0.0.
-2. Added in version 1.0.0.
+2. Since version 1.0.0.
-3. Added in version 2.0.0.
+3. Since version 2.0.0.
@@ -51,3 +51,5 @@ 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.
@@ -284,10 +284,10 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Added in version 1.0.0. Fixed in version 3.13.0 to throw `#!cpp std::length_error` instead of emptying the array and
   accessing it out of bounds when `idx` equals the maximum value of `size_type`. A missing index in the const version
   is guarded by a runtime assertion since version 3.13.0.
-2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. The `T* key` overloads forward to
+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)
-   overload 3 since version 3.11.0.
+   in version 3.11.0.
-3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
+3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
-   across the lookup functions.
+   already supported by [`at`](at.md), [`value`](value.md), [`find`](find.md), and other lookup functions.
 4. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since
   version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
 [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
@@ -89,6 +89,11 @@ Linear in the size of the JSON value.
 ## Version history
- Added in version 1.0.0.
+- Since 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
- Added in version 3.0.0.
+- Since version 3.0.0.
@@ -76,4 +76,4 @@ classDiagram
 ## Version history
- Added in version 3.0.0.
+- Since version 3.0.0.
@@ -25,10 +25,6 @@ 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`
@@ -38,12 +34,9 @@ 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` or a `std::string_view` (C++17)
+    - a `std::string`
    - 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.
@@ -119,13 +112,6 @@ 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
@@ -264,22 +250,6 @@ 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
@@ -310,9 +280,6 @@ 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
- Added in version 3.0.0.
+- Since version 3.0.0.
@@ -125,6 +125,6 @@ throws.
 ## Version history
-1. Added in version 1.0.0.
+1. Since version 1.0.0.
-2. Added in version 1.0.0.
+2. Since version 1.0.0.
-3. Added in version 2.0.0.
+3. Since version 2.0.0.
@@ -31,10 +31,6 @@ 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
@@ -46,12 +42,8 @@ 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
@@ -168,9 +160,6 @@ 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. Added in version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
+1. 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.
+2. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
-3. Added in version 1.0.0.
+3. Since version 1.0.0.
-4. Added in version 1.0.0.
+4. Since version 1.0.0.
-5. Added in version 1.0.0.
+5. Since version 1.0.0.
-6. Added in version 3.8.0.
+6. Since version 3.8.0.
-7. Added in version 3.8.0.
+7. Since version 3.8.0.
@@ -124,3 +124,5 @@ 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
- Added in version 3.0.0.
+- Since version 3.0.0.
@@ -231,8 +231,11 @@ 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. Support for keys
+2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Fixed in version 3.13.0
-   convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
+   to consistently accept `std::string_view`-convertible keys, as already supported by
-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)
+   [`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md), and other lookup functions.
 3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving
   `ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or
   `default_value`, as documented). Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109)
   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 floating-point numbers stay in the source text; integers are converted while parsing, and strings that
+Strings and numbers stay in the source text; only strings that contain escapes are decoded, into one buffer owned by
-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
+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,13 +115,6 @@ 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,19 +21,17 @@ 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 accept every input `BasicJsonType::parse()` takes, and in
+the input) instead of a tree of `BasicJsonType` values. They take the same inputs as `BasicJsonType::parse()`. Byte
-addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of
+inputs that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, non-contiguous
-single-byte characters that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, which
+iterators) are read into a copy that the document owns -- see the Notes. Use [`parse_copy()`](parse_copy.md) to get an
-must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns -- see the
+owned copy of a borrowable input as well.
 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`, a `#!cpp std::string_view` (C++17), or a C-style array of single-byte characters
+    - a `#!cpp std::string`, `#!cpp std::string_view`, or a C-style array of single-byte characters
    - a pointer to a null-terminated string of single-byte characters (`#!cpp char`, `#!cpp signed char`,
      `#!cpp unsigned char`, `#!cpp std::uint8_t`)
    - a container for which `#!cpp obj.data()` and `#!cpp obj.size()` give contiguous single-byte access, e.g.
@@ -49,10 +47,6 @@ 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)
@@ -161,5 +155,3 @@ 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,8 +80,7 @@ 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). Constant if no element of the array is an array
+   index (unlike `BasicJsonType`'s array, which is random-access).
   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,8 +28,7 @@ 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. Constant if no element of the array is an array or object, since the elements are then adjacent
+index.
 in the index.
 ## Notes
@@ -143,13 +143,6 @@ 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,8 +86,7 @@ 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). Constant if no element of the array is an array
+   index (unlike `BasicJsonType`'s array, which is random-access).
   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
-Added in version 3.8.0.
+Since version 3.8.0.
@@ -39,4 +39,4 @@ Constant.
 ## Version history
-Added in version 3.8.0.
+Since version 3.8.0.
@@ -0,0 +1,32 @@
 # <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
-Added in version 3.8.0.
+Since version 3.8.0.
@@ -29,14 +29,6 @@ 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
-Added in version 3.8.0.
+Since version 3.8.0.
@@ -0,0 +1,28 @@
 # <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
-Added in version 1.0.0.
+Since version 1.0.0.
@@ -32,4 +32,4 @@ specialization.
 ## Version history
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -40,4 +40,4 @@ parsing, without ever rewriting the source text -- see [Edits](basic_json_docume
 ## Version history
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -38,4 +38,4 @@ still referring to it seeing the change, see [Edits](basic_json_document/index.m
 ## Version history
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -51,5 +51,5 @@ operator string_t() const
 ## Version history
- Added in version 2.0.0.
+- Since version 2.0.0.
 - Changed type to `string_t` and deprecated in version 3.11.0.
@@ -49,5 +49,5 @@ ptr == json_pointer(ptr.to_string());
 ## Version history
- Added in version 2.0.0.
+- Since version 2.0.0.
 - Changed return type to `string_t` in version 3.11.0.
@@ -0,0 +1,30 @@
 # <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,13 +59,6 @@ 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.
@@ -0,0 +1,33 @@
 # <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.
@@ -0,0 +1,30 @@
 # <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.
@@ -0,0 +1,30 @@
 # <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.
@@ -0,0 +1,30 @@
 # <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.
@@ -0,0 +1,29 @@
 # <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.
@@ -0,0 +1,30 @@
 # <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.
@@ -0,0 +1,22 @@
 # <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
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -38,7 +38,6 @@ 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
@@ -138,12 +137,3 @@ 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
@@ -1,83 +0,0 @@
 # 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 json = nlohmann::json;
    int main()
    {
        const json j = json::parse(R"({"name": "日本語 text", "pi": 3.141592653589793})");
        std::cout << j.dump() << '\n';  // {"name":"日本語 text","pi":3.141592653589793}
    }
    ```
 ## See also
 - [**parse**](../basic_json/parse.md) - deserialize from a compatible input
 - [**dump**](../basic_json/dump.md) - serialization
 - [**JSON_USE_SIMDUTF**](json_use_simdutf.md) - use the simdutf library to accelerate UTF-8 validation
 - [**JSON_DISABLE_STREAM_BULK_SCAN**](json_disable_stream_bulk_scan.md) - read a `std::istream` one character at a time
 - [Parsing: input sources and performance](../../features/parsing/index.md#input-sources-and-performance)
 ## Version history
 - Added in version 3.13.0.
@@ -6,9 +6,8 @@
 When defined, the parser validates the UTF-8 content of JSON strings that come from a **contiguous byte input**
 (`std::string`, `std::vector<char>`/`<std::uint8_t>`, string literals, `const char*` ranges, …) using the
-[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in validator (which uses SSSE3 or NEON where
+[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in scalar validator. On text with many
-available, see [`JSON_NO_SIMD`](json_no_simd.md)). On text with many non-ASCII characters (e.g. CJK or emoji) this can
+non-ASCII characters (e.g. CJK or emoji) this can validate several times faster.
 validate faster, depending on the CPU.
 This is an **opt-in external dependency**. The library itself remains header-only and its behavior is unchanged: the
 same input is accepted or rejected either way, and every parse error is reported at the same position with the same
@@ -39,6 +39,6 @@ the library.
 ## Version history
 - Added in version 3.11.0. Changed inline namespace name in version 3.11.2. Added the ABI tag `_dp` in
-  version 3.12.0, and the ABI tags `_bics`, `_psp`, `_snul`, `_sbu8`, `_ekmo`, `_dsbs`, `_dufio`, `_ns`, `_vns`,
+  version 3.12.0, and the ABI tags `_bics`, `_psp`, `_snul`, `_sbu8`, `_ekmo`, `_dsbs`, `_dufio`, `_vns`, and
-  and `_vssse3` in version 3.13.0; see
+  `_vssse3` in version 3.13.0; see
  [`nlohmann` Namespace](../../features/namespace.md#structure).
@@ -8,16 +8,16 @@ This type preserves the insertion order of object keys.
 ## Iterator invalidation
-The type is based on [`ordered_map`](ordered_map.md) which in turn uses a `std::vector` to store object elements.
+The type is based on [`ordered_map`](ordered_map/index.md) which in turn uses a `std::vector` to store object elements.
 Therefore, adding object elements can yield a reallocation in which case all iterators (including the
 [`end()`](basic_json/end.md) iterator) and all references to the elements are invalidated. Also, any iterator or
 reference after the insertion point will point to the same index, which is now a different value.
 ## Complexity
-[`ordered_map`](ordered_map.md) has no lookup index: every key-based object operation is a linear scan, so building or
+[`ordered_map`](ordered_map/index.md) has no lookup index: every key-based object operation is a linear scan, so building or
 parsing an object of `n` keys costs O(n²) rather than O(n log n). See
-[`ordered_map` complexity](ordered_map.md#complexity) for the per-operation table and for measured numbers.
+[`ordered_map` complexity](ordered_map/index.md#complexity) for the per-operation table and for measured numbers.
 ## Examples
@@ -37,9 +37,9 @@ parsing an object of `n` keys costs O(n²) rather than O(n log n). See
 ## See also
- [ordered_map](ordered_map.md)
+- [ordered_map](ordered_map/index.md)
 - [Object Order](../features/object_order.md)
 ## Version history
-Added in version 3.9.0.
+Since version 3.9.0.
@@ -35,4 +35,4 @@ of object keys, instead of sorting them like [`json_document`](json_document.md)
 ## Version history
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -44,4 +44,4 @@ members [`set`](basic_json_document/set.md) added -- instead of sorting them lik
 ## Version history
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -37,4 +37,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an
 ## Version history
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -32,4 +32,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an
 ## Version history
-Added in version 3.13.0.
+Since version 3.13.0.
@@ -0,0 +1,28 @@
 # <small>nlohmann::ordered_map::</small>Container
 ```cpp
 using Container = std::vector<std::pair<const Key, T>, Allocator>;
 ```
 The base container type that `ordered_map` publicly inherits from. Elements are stored in insertion
 order as `#!cpp std::pair<const Key, T>` entries in a `std::vector`.
 ## Examples
 ??? example
    The example shows the type `Container`.
    ```cpp
    --8<-- "examples/ordered_map__Container.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__Container.output"
    ```
 ## Version history
 - Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -0,0 +1,61 @@
 # <small>nlohmann::ordered_map::</small>at
 ```cpp
 // (1)
 T& at(const key_type& key);
 const T& at(const key_type& key) const;
 // (2)
 template<class KeyType>
 T& at(KeyType&& key);
 template<class KeyType>
 const T& at(KeyType&& key) const;
 ```
 1. Returns a reference to the value mapped to `key`.
 2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
   (heterogeneous lookup, e.g. looking up by a `#!cpp const char*` without constructing a temporary
   `key_type`). Only participates in overload resolution if `KeyType` is usable as a key type.
 ## Template parameters
 `KeyType`
 :   a type comparable to `key_type` via [`key_compare`](key_compare.md)
 ## Parameters
 `key` (in)
 :   key of the element to find
 ## Return value
 reference to the mapped value of the element with key equal to `key`
 ## Exceptions
 Throws `std::out_of_range` if no element with key `key` exists.
 ## Complexity
 Linear in the number of elements.
 ## Examples
 ??? example
    The example shows how `at` is used.
    ```cpp
    --8<-- "examples/ordered_map__at.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__at.output"
    ```
 ## Version history
 - Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
 - Overload (2) added in version 3.11.0.
@@ -0,0 +1,53 @@
 # <small>nlohmann::ordered_map::</small>count
 ```cpp
 // (1)
 size_type count(const key_type& key) const;
 // (2)
 template<class KeyType>
 size_type count(KeyType&& key) const;
 ```
 1. Returns the number of elements with key equal to `key` (0 or 1, since keys are unique).
 2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
 ## Template parameters
 `KeyType`
 :   a type comparable to `key_type` via [`key_compare`](key_compare.md)
 ## Parameters
 `key` (in)
 :   key of the elements to count
 ## Return value
 number of elements with key equal to `key` (0 or 1)
 ## Complexity
 Linear in the number of elements.
 ## Examples
 ??? example
    The example shows how `count` is used.
    ```cpp
    --8<-- "examples/ordered_map__count.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__count.output"
    ```
 ## Version history
 - Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
 - Overload (2) added in version 3.11.0.
@@ -0,0 +1,58 @@
 # <small>nlohmann::ordered_map::</small>emplace
 ```cpp
 // (1)
 std::pair<iterator, bool> emplace(const key_type& key, T&& t);
 // (2)
 template<class KeyType>
 std::pair<iterator, bool> emplace(KeyType&& key, T&& t);
 ```
 1. Inserts `#!cpp {key, t}` if no element with an equal key already exists (per [`key_compare`](key_compare.md)),
   appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
 2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
 ## Template parameters
 `KeyType`
 :   a type comparable to `key_type` via [`key_compare`](key_compare.md)
 ## Parameters
 `key` (in)
 :   key of the element to insert
 `t` (in)
 :   value of the element to insert
 ## Return value
 pair of an iterator to the (possibly newly inserted) element, and a `bool` that is `true` if insertion
 took place and `false` if an element with an equal key already existed
 ## Complexity
 Linear in the number of elements.
 ## Examples
 ??? example
    The example shows how `emplace` is used.
    ```cpp
    --8<-- "examples/ordered_map__emplace.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__emplace.output"
    ```
 ## Version history
 - Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
 - Overload (2) added in version 3.11.0.
@@ -0,0 +1,75 @@
 # <small>nlohmann::ordered_map::</small>erase
 ```cpp
 // (1)
 size_type erase(const key_type& key);
 // (2)
 template<class KeyType>
 size_type erase(KeyType&& key);
 // (3)
 iterator erase(iterator pos);
 // (4)
 iterator erase(iterator first, iterator last);
 ```
 1. Removes the element with key equal to `key`, if any, preserving the relative order of the remaining
   elements.
 2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
 3. Removes the element at `pos`.
 4. Removes the elements in range `[first, last)`.
 ## Template parameters
 `KeyType`
 :   a type comparable to `key_type` via [`key_compare`](key_compare.md)
 ## Parameters
 `key` (in)
 :   key of the element to remove
 `pos` (in)
 :   iterator to the element to remove
 `first` (in)
 :   iterator to the first element to remove
 `last` (in)
 :   iterator one past the last element to remove
 ## Return value
 1. number of elements removed (0 or 1)
 2. number of elements removed (0 or 1)
 3. iterator following the removed element
 4. iterator following the last removed element
 ## Complexity
 Linear in the number of elements (elements after the removed one(s) are shifted to keep storage
 contiguous).
 ## Examples
 ??? example
    The example shows how `erase` is used.
    ```cpp
    --8<-- "examples/ordered_map__erase.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__erase.output"
    ```
 ## Version history
 - Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
 - Overload (2) added in version 3.11.0.
@@ -0,0 +1,56 @@
 # <small>nlohmann::ordered_map::</small>find
 ```cpp
 // (1)
 iterator find(const key_type& key);
 const_iterator find(const key_type& key) const;
 // (2)
 template<class KeyType>
 iterator find(KeyType&& key);
 template<class KeyType>
 const_iterator find(KeyType&& key) const;
 ```
 1. Returns an iterator to the element with key equal to `key`, or `end()` if no such element exists.
 2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
 ## Template parameters
 `KeyType`
 :   a type comparable to `key_type` via [`key_compare`](key_compare.md)
 ## Parameters
 `key` (in)
 :   key of the element to find
 ## Return value
 iterator to the element with key equal to `key`, or `end()` if not found
 ## Complexity
 Linear in the number of elements.
 ## Examples
 ??? example
    The example shows how `find` is used.
    ```cpp
    --8<-- "examples/ordered_map__find.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__find.output"
    ```
 ## Version history
 - Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
 - Overload (2) added in version 3.11.0.
@@ -6,7 +6,7 @@ template<class Key, class T, class IgnoredLess = std::less<Key>,
 struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
 ```
-A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](ordered_json.md)
+A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](../ordered_json.md)
 (`nlohmann::basic_json<ordered_map>`).
 ## Template parameters
@@ -30,19 +30,19 @@ case all iterators (including the `end()` iterator) and all references to the el
 When the storage grows, the keys are copied and the mapped values are moved to the new storage. A plain `std::vector`
 would copy the whole elements instead, because their `#!cpp const` keys make them not nothrow move constructible; for
-[`ordered_json`](ordered_json.md), this would be a deep copy of every nested value. The values are only copied if
+[`ordered_json`](../ordered_json.md), this would be a deep copy of every nested value. The values are only copied if
 `T` is not default constructible or not nothrow move assignable.
 ## Member types
 - **key_type** - key type (`Key`)
 - **mapped_type** - mapped type (`T`)
- **Container** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
+- [**Container**](Container.md) - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
 - **iterator**
 - **const_iterator**
 - **size_type**
 - **value_type**
- **key_compare** - key comparison function
+- [**key_compare**](key_compare.md) - key comparison function
 ```cpp
 std::equal_to<Key>  // until C++14
@@ -51,15 +51,16 @@ std::equal_to<>     // since C++14
 ## Member functions
- (constructor)
+- [(constructor)](ordered_map.md)
- (destructor)
+- [(destructor)](~ordered_map.md)
- **emplace**
+- [**operator=**](operator=.md)
- **operator\[\]**
+- [**emplace**](emplace.md)
- **at**
+- [**operator\[\]**](operator[].md)
- **erase**
+- [**at**](at.md)
- **count**
+- [**erase**](erase.md)
- **find**
+- [**count**](count.md)
- **insert**
+- [**find**](find.md)
 - [**insert**](insert.md)
 ## Exception safety
@@ -89,7 +90,7 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
 !!! warning "Quadratic cost of building large objects"
    Because every insertion scans all elements inserted so far, building an object of `n` distinct keys costs
-    **O(n²)** in total. This applies to filling an [`ordered_json`](ordered_json.md) object key by key as well as to
+    **O(n²)** in total. This applies to filling an [`ordered_json`](../ordered_json.md) object key by key as well as to
    parsing one, since the parser inserts each key as it is read.
    The cost is negligible for the object sizes typically found in configuration files or API payloads, but it grows
@@ -106,7 +107,7 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
    If key order matters for objects of that size, consider a container with a lookup index, such as
    [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map)
    ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)), as the object type -- see
-    [object order](../features/object_order.md).
+    [object order](../../features/object_order.md).
 ## Examples
@@ -126,10 +127,10 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
 ## See also
- [ordered_json](ordered_json.md)
+- [ordered_json](../ordered_json.md)
 ## Version history
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
 - Added **key_compare** member in version 3.11.0.
 - Changed in version 3.13.0: growing the storage moves the mapped values instead of copying them.
@@ -0,0 +1,63 @@
 # <small>nlohmann::ordered_map::</small>insert
 ```cpp
 // (1)
 std::pair<iterator, bool> insert(value_type&& value);
 std::pair<iterator, bool> insert(const value_type& value);
 // (2)
 template<typename InputIt>
 void insert(InputIt first, InputIt last);
 ```
 1. Inserts `value` if no element with an equal key already exists (per [`key_compare`](key_compare.md)),
   appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
 2. Inserts the elements from range `[first, last)`, in iteration order, applying the same equal-key rule
   as (1) to each element.
 ## Template parameters
 `InputIt`
 :   an input iterator type
 ## Parameters
 `value` (in)
 :   value to insert
 `first` (in)
 :   iterator to the first element to insert
 `last` (in)
 :   iterator one past the last element to insert
 ## Return value
 1. pair of an iterator to the (possibly newly inserted) element, and a `bool` that is `true` if insertion
   took place and `false` if an element with an equal key already existed
 2. (none)
 ## Complexity
 1. Linear in the number of elements.
 2. Linear in the distance between `first` and `last`, times linear in the number of elements.
 ## Examples
 ??? example
    The example shows how `insert` is used.
    ```cpp
    --8<-- "examples/ordered_map__insert.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__insert.output"
    ```
 ## Version history
 - Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
Author	SHA1	Message	Date
Niels Lohmann	9222763ab9	Merge branch 'develop' into claude/todo-191-plan-508110 Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-10-21 10:51:41 +02:00
Niels Lohmann	d13c9e7212	Fix links to moved API pages in the API changes page mkdocs --strict rejects links to pages that only exist as redirects. Also link operator<< to operator_ltlt.md and operator>> to operator_gtgt.md instead of the other way round. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-10-10 07:42:37 +02:00
Niels Lohmann	522e7465b0	Merge branch 'develop' into claude/todo-191-plan-508110 Regenerate tools/api_checker/api_surface.json with the CI libclang (18.1.1 on Linux) and point the new ordered_map links in features/performance.md to api/ordered_map/index.md. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-10-10 04:01:42 +02:00
Niels Lohmann	fe4e78e867	Merge branch 'develop' into claude/todo-191-plan-508110 - ordered_map.hpp: develop's refactored members, with this branch's @sa links on every public member - byte_container_with_subtype operator==/!= and ordered_map docs: develop's reviewed text (#5638); drop the now unreferenced examples - basic_json.md: keep both version-history additions - add the docset entries that develop's style check now requires for the 25 API pages this branch adds - regenerate tools/api_checker/api_surface.json for develop's API Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-10-04 17:35:55 +02:00
Niels Lohmann	9196e92520	Merge branch 'develop' into claude/todo-191-plan-508110 Conflicts: none textual. Follow-up fixes for develop's changes: - docs/mkdocs/docs/api/ordered_map/index.md: develop's new paragraph (#5609) was written for api/ordered_map.md; fixed its relative ordered_json.md link for the page's new location, plus two pre-existing links from an earlier merge (ordered_json.md, features/object_order.md) - tools/api_checker/api_surface.json: regenerated with libclang 18.1.1 on Linux (swap() noexcept now includes json_base_class_t; new integral-key contains/count/find/value overloads) Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-30 20:36:12 +02:00
Niels Lohmann	7d22d865dd	Merge branch 'develop' into claude/todo-191-plan-508110 Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-28 22:22:46 +02:00
Niels Lohmann	4c73319d3b	Use one-line module docstrings in the API checker scripts Codacy runs two docstring checkers with opposite rules for module docstrings: with the summary on the first line it reported D213, with the summary on the second line it reports D212. A one-line docstring satisfies both. Keep the summary as the docstring and move the details into a comment below it; nothing reads the module docstrings. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-28 18:42:34 +02:00
Niels Lohmann	da5097abcd	Restore the CI spelling of json_pointer's operator string_t in the API surface The develop merge regenerated api_surface.json on macOS, whose libclang spells the name of the deprecated conversion operator as "operator nlohmann::json_pointer::string_t_helper<...>::type". CI's pinned libclang 18.1.1 on Linux spells it "operator typename string_t_helper<...>::type", so check_api_docs reported the file as out of date. This restores CI's spelling, which is byte-identical to the file CI regenerated. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 21:37:14 +02:00
Niels Lohmann	2319f6e6f9	Address Codacy findings in the API checker scripts Put multi-line docstring summaries on their own line, as a single sentence followed by a blank line (pydocstyle D205, D209, D213, D415). Annotate the subprocess import and calls with nosec: they only run fixed argument lists, never through a shell (Bandit B404, B603, B607). Do the same for the three broad except clauses in extract_api.py, which deliberately fall through to the next libclang candidate or skip an unresolvable alias (Bandit B110, B112). Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 18:09:03 +02:00
Niels Lohmann	9a0d1c0c47	Merge branch 'develop' into claude/todo-191-plan-508110 Resolve the conflict in docs/mkdocs/docs/home/architecture.md by taking develop's rewritten page and pointing its ordered_map links at the moved api/ordered_map/index.md. Also update the ordered_map.md links develop added in ordered_json.md, object_order.md, and template_parameters.md. Regenerate api_surface.json for the new BON8 functions and the changed comparison operator. Restrict the documented_non_public leak check to @sa URLs into json.nlohmann.me: develop now uses @sa to link GitHub issues from private members such as copy_structured, which is not a documentation leak. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 18:07:00 +02:00
Niels Lohmann	1bbb5d400a	Regenerate api_surface.json after merging develop develop added JSON_HEDLEY_WARN_UNUSED_RESULT to a number of basic_json members (#5520) and reworked operator<<'s output adapter, so the committed API surface no longer matched what extract_api.py produces and the "Check for uncommitted API surface changes" step failed. This is the patch the workflow itself uploads for that purpose; the changes are limited to recorded signatures plus the way libclang spells json_pointer's conversion operator. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-15 10:06:55 +02:00
Niels Lohmann	08d18d5a82	Merge remote-tracking branch 'origin/develop' into HEAD	2026-09-14 21:26:29 +02:00
Niels LohmannandClaude Sonnet 5	a27065bd12	Regenerate api_surface.json after merging develop develop gained iterator+sentinel support for accept()/parse()/sax_parse()/ from_cbor()/from_msgpack()/from_ubjson()/from_bjdata()/from_bson() (#5205) since this branch was created, which check_api_docs.yml's drift check caught immediately: GitHub's pull_request trigger checks out the PR-vs-base merge commit, not the PR branch in isolation, so CI was comparing the committed api_surface.json (generated before that upstream change existed) against a fresh extraction of a json.hpp that already had it. This superseded an earlier, incorrect diagnosis of the same symptom (a JSON_HAS_RANGES cross-environment pin) -- that fix remains in place since it's still a real, independent determinism improvement for three other JSON_HAS_RANGES-gated locations in type_traits.hpp, but it wasn't the actual cause of this particular mismatch: these new overloads turned out to be unconditional (SFINAE-gated via can_compare_ne, not preprocessor-gated), so no environment-detection difference was involved here at all. Signed-off-by: Niels Lohmann <mail@nlohmann.me> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-07-11 23:45:46 +02:00
Niels Lohmann	3940f4b730	Merge remote-tracking branch 'origin/develop' into claude/todo-191-plan-508110	2026-07-11 23:43:30 +02:00
Niels LohmannandClaude Sonnet 5	0663907b68	Fix cross-environment API-surface drift and lint findings from CI extract_api.py's own extraction wasn't deterministic across machines, which CI's drift check caught immediately: JSON_HAS_RANGES auto-detects via the standard library's __cpp_lib_ranges feature-test macro, which isn't reliably gated to C++20 mode by every stdlib -- undefined under -std=c++17 with macOS's libc++, but defined under the identical flag with the Ubuntu stdlib CI uses, so parse()/accept()/from_*() extracted different signatures purely depending on which machine ran the extraction. Pinned to -DJSON_HAS_RANGES=0: the deterministic and safe choice, since pinning to 1 was tried first and found to fail to parse on a stdlib without full <ranges> support even when the macro claims otherwise. Also found and fixed a second, independent source of the same class of drift: get_identity_name() used cursor.spelling verbatim for CONVERSION_FUNCTION cursors, which libclang renders as its own internally-canonicalized form of the return type rather than what's literally written. Confirmed for json_pointer::operator string_t() spelling differently on two machines pinned to the identical libclang==18.1.1 wheel, with the JSON_HAS_RANGES fix above ruled out as the cause. Now derived from the cursor's own raw source text instead, immune to libclang's dependent-type resolution differences and incidentally more readable than the libclang-internal forms it replaces. Bumped SURFACE_FORMAT_VERSION to 3 and regenerated all 27 history snapshots and the committed api_surface.json; both fixes are documented in tools/api_checker/history/README.md's format-history log. Also fixes diff_api.py's format_version guard, which only compared the two loaded surfaces against each other and never against SURFACE_FORMAT_VERSION (what this build actually understands) -- two surfaces on the same, newer-than-expected format_version would have silently passed the guard. Remaining fixes are the concretely actionable findings from Codacy's review of the new tools/api_checker/ files: unused imports/variables, a stray f-string with no placeholders. Left the docstring-formatting nitpicks (pydocstyle D2xx/D4xx) and generic subprocess-usage notices alone -- the former has no established convention elsewhere in this codebase's Python tooling to conform to, and the latter are inherent to a dev tool that shells out to git/clang with developer-controlled arguments, not user input. Signed-off-by: Niels Lohmann <mail@nlohmann.me> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-07-11 18:59:19 +02:00
Niels LohmannandClaude Sonnet 5	f23b3c63a2	Add AST-based public API checker and fix documentation gaps it found (#3691 ) Adds tools/api_checker/: extract_api.py derives the public API surface directly from the libclang AST (independent of documentation status), check_docs.py flags public entries missing @sa links (and @sa on non-public ones), diff_api.py does an overload-aware breaking/feature diff between two refs, check_macros.py cross- checks documented macros against #define sites, and snapshot_release.py backfills immutable per-release surface snapshots into tools/api_checker/history/ (v3.1.0 through v3.12.0) so diff_api.py can compare releases without live extraction. POLICY.md documents what counts as public API and what stability is guaranteed. Running this tooling against the current tree found and fixed a real documentation backlog: ~25 new API doc pages (ordered_map's methods, json_sax's ctor/dtor/ operator=, byte_container_with_subtype's comparison operators, several orphaned type aliases), each with a compiled and output-verified example, plus missing @sa comments and stale/incorrect Version History entries on several existing pages (found by diffing consecutive release pairs and checking whether the resulting change was actually reflected in the target page's history section). Also adds docs/home/api_changes.md, a per-release, per-function reference of public API changes (v3.1.0 through v3.12.0) generated from the history/ snapshots, complementing (not replacing) the existing release notes. Along the way, found and fixed several extractor bugs by testing against real release tags rather than trusting the algorithm in isolation -- most notably an identity-key scheme based on libclang's USR that encoded the enclosing class template's own arity, and a since-renamed ABI inline-namespace pattern (json_v3_11_0 vs. today's json_abi_v3_11_2) that neither of two earlier regex attempts stripped correctly. Both are documented in extract_api.py's docstrings and tools/api_checker/history/README.md so the failure mode doesn't recur silently. .github/workflows/check_api_docs.yml runs extract_api.py + check_docs.py in CI, advisory-only for now (documented backlog may not be at zero for entities this PR didn't touch), plus a blocking drift check on the committed tools/api_checker/api_surface.json. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-07-11 18:59:00 +02:00
`@@ -84,4 +84,4 @@ constructor.`

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

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

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

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

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

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

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

	`- Added in version 3.0.0.`	`- Since 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`

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

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

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

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

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

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

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

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

	`Added in version 3.8.0.`	`Since version 3.8.0.`