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-10-01 12:10:32 +00:00 · 2026-09-30 20:36:12 +02:00 · 2026-09-28 22:22:46 +02:00 · 2026-09-28 18:42:34 +02:00 · 2026-09-27 21:37:14 +02:00 · 2026-09-27 18:09:03 +02:00
191 changed files with 74739 additions and 3708 deletions
@@ -0,0 +1,17 @@
+arm_container:
+  image: gcc:latest
+
+check_task:
+  check_script:
+  # the gcc image ships an outdated CMake, so fetch a recent prebuilt binary
+  # instead of compiling CMake from source
+  - wget -q https://github.com/Kitware/CMake/releases/download/v4.3.4/cmake-4.3.4-linux-aarch64.tar.gz
+  - tar xfz cmake-4.3.4-linux-aarch64.tar.gz
+  - export PATH="$(pwd)/cmake-4.3.4-linux-aarch64/bin:$PATH"
+  - cmake --version
+  - mkdir build
+  - cd build
+  - cmake .. -DJSON_FastTests=ON
+  - make -j4
+  - cd tests
+  - ctest -j4
@@ -24,10 +24,6 @@ updates:
      interval: daily
    cooldown:
      default-days: 7
-    ignore:
-      # astyle is deliberately pinned (see tools/astyle/requirements.txt): newer versions
-      # reformat the code, and the pinned version defines the formatting CI enforces
-      - dependency-name: astyle

  - package-ecosystem: pip
    directory: /tools/generate_natvis
@@ -30,6 +30,14 @@ environment:
      CMAKE_OPTIONS: ""
      GENERATOR: Visual Studio 14 2015

+    - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015
+      configuration: Release
+      platform: x86
+      name: with_win_header
+      CXX_FLAGS: "/W4 /WX"
+      CMAKE_OPTIONS: ""
+      GENERATOR: Visual Studio 14 2015
+
    - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
      configuration: Release
      platform: x86
@@ -66,6 +74,9 @@ install:
  - if "%platform%"=="x86"    set GENERATOR_PLATFORM=Win32

 before_build:
+  # for with_win_header build, inject the inclusion of Windows.h to the single-header library
+  - ps: if ($env:name -Eq "with_win_header") { $header_path = "single_include\nlohmann\json.hpp" }
+  - ps: if ($env:name -Eq "with_win_header") { "#include <Windows.h>`n" + (Get-Content $header_path | Out-String) | Set-Content $header_path }
  - cmake . -G "%GENERATOR%" -A "%GENERATOR_PLATFORM%" -DCMAKE_CXX_FLAGS="%CXX_FLAGS%" -DCMAKE_IGNORE_PATH="C:/Program Files/Git/usr/bin" -DJSON_BuildTests=On "%CMAKE_OPTIONS%"

 build_script:
@@ -35,7 +35,6 @@ jobs:
      MAIN_DIR: ${{ github.workspace }}/main
      INCLUDE_DIR: ${{ github.workspace }}/main/single_include/nlohmann
      TOOL_DIR: ${{ github.workspace }}/tools/tools/amalgamate
-      NATVIS_TOOL_DIR: ${{ github.workspace }}/tools/tools/generate_natvis

    steps:
      - name: Harden Runner
@@ -62,48 +61,6 @@ jobs:
          python3 -mvenv venv
          venv/bin/pip3 install -r $MAIN_DIR/tools/astyle/requirements.txt

-      - name: Install generate_natvis dependencies
-        run: pip3 install -r $NATVIS_TOOL_DIR/requirements.txt
-
-      - name: Regenerate the tools/macro_builder tables in macro_scope.hpp
-        run: |
-          cd $MAIN_DIR
-
-          # Built from this PR's own tools/macro_builder/main.cpp, not a
-          # develop checkout: unlike amalgamate.py and generate_natvis.py,
-          # this tool has no other source of truth to check against (its
-          # own README documents that it must reproduce macro_scope.hpp
-          # byte for byte), so there is nothing to gain from checking out a
-          # separate copy, and doing so would make this step fail on a PR
-          # that adds support for a new dispatch table until that PR itself
-          # merges to develop, the same way generate_natvis.py's --version
-          # requirement briefly did.
-          TMPDIR=$(mktemp -d ./macro_builder_check.XXXXXX)
-          c++ -std=c++11 tools/macro_builder/main.cpp -o "$TMPDIR/macro_builder"
-          "$TMPDIR/macro_builder" > "$TMPDIR/paste.hpp"
-          "$TMPDIR/macro_builder" type_body > "$TMPDIR/type_body.hpp"
-
-          # Splice the (still unindented) generated blocks back into
-          # macro_scope.hpp; the astyle pass below indents their
-          # continuation lines the same way it does for the rest of
-          # include/, so a correctly regenerated file comes out unchanged.
-          awk -v newfile="$TMPDIR/paste.hpp" '
-            BEGIN { while ((getline line < newfile) > 0) { new = new line "\n" } }
-            /^#define NLOHMANN_JSON_EXPAND\( x \) x$/ { printf "%s", new; skip=1 }
-            skip && /^#define NLOHMANN_JSON_DOUBLE_PASTE63\(/ { skip=0; next }
-            skip { next }
-            { print }
-          ' include/nlohmann/detail/macro_scope.hpp > "$TMPDIR/macro_scope_1.hpp"
-          awk -v newfile="$TMPDIR/type_body.hpp" '
-            BEGIN { while ((getline line < newfile) > 0) { new = new line "\n" } }
-            /^#define NLOHMANN_JSON_TYPE_BODY\(Prefix, \.\.\.\)/ { printf "%s", new; skip=1 }
-            skip && /^[[:space:]]*NLOHMANN_JSON_TYPE_BODY_SENTINEL\)\)$/ { skip=0; next }
-            skip { next }
-            { print }
-          ' "$TMPDIR/macro_scope_1.hpp" > "$TMPDIR/macro_scope_2.hpp"
-          mv "$TMPDIR/macro_scope_2.hpp" include/nlohmann/detail/macro_scope.hpp
-          rm -rf "$TMPDIR"
-
      - name: Regenerate amalgamation, formatting, and BUILD.bazel
        run: |
          cd $MAIN_DIR
@@ -131,19 +88,6 @@ jobs:
          ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=none --quiet \
            $(find $SOURCE_DIRS -type f \( -name '*.hpp' -o -name '*.cpp' -o -name '*.cu' \) -not -path 'tests/thirdparty/*' -not -path 'tests/abi/include/nlohmann/*' | sort)

-      - name: Regenerate nlohmann_json.natvis
-        run: |
-          cd $MAIN_DIR
-          # Pass --version explicitly so this step also works with the tool
-          # copy from develop before this repository's own generate_natvis.py
-          # learns to derive the version itself: the older script requires
-          # --version, and the newer one accepts it as an explicit override.
-          ABI_MACROS=include/nlohmann/detail/abi_macros.hpp
-          VERSION_MAJOR=$(grep -m1 'define NLOHMANN_JSON_VERSION_MAJOR' $ABI_MACROS | grep -o '[0-9]\+')
-          VERSION_MINOR=$(grep -m1 'define NLOHMANN_JSON_VERSION_MINOR' $ABI_MACROS | grep -o '[0-9]\+')
-          VERSION_PATCH=$(grep -m1 'define NLOHMANN_JSON_VERSION_PATCH' $ABI_MACROS | grep -o '[0-9]\+')
-          python3 $NATVIS_TOOL_DIR/generate_natvis.py --version "$VERSION_MAJOR.$VERSION_MINOR.$VERSION_PATCH" $MAIN_DIR
-
      - 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@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+      uses: github/codeql-action/init@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
      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@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+      uses: github/codeql-action/autobuild@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1

    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+      uses: github/codeql-action/analyze@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
@@ -47,6 +47,6 @@ jobs:
          output: 'flawfinder_results.sarif'

      - name: Upload analysis results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
        with:
          sarif_file: ${{github.workspace}}/flawfinder_results.sarif
@@ -7,16 +7,6 @@ on:
      - develop
    paths:
      - docs/mkdocs/**
-      # the site also embeds these files via pymdownx.snippets
-      # (mkdocs.yml sets restrict_base_path: false for this)
-      - .clang-tidy
-      - .github/CODE_OF_CONDUCT.md
-      - .github/CONTRIBUTING.md
-      - .github/SECURITY.md
-      - cmake/clang_flags.cmake
-      - cmake/gcc_flags.cmake
-      - tests/fmt_formatter/project/main.cpp
-      - tools/astyle/.astylerc
  workflow_dispatch:

 # we don't want to have concurrent jobs, and we don't want to cancel running jobs to avoid broken publications
@@ -33,7 +23,7 @@ jobs:
      contents: write

    if: github.repository == 'nlohmann/json'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
@@ -41,8 +31,6 @@ jobs:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false

      - name: Install virtual environment
        run: make install_venv -C docs/mkdocs
@@ -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@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
        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@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
        with:
          sarif_file: semgrep.sarif
        if: always()
@@ -52,13 +52,6 @@ jobs:
        run: cmake -S . -B build -DJSON_CI=On
      - name: Build
        run: cmake --build build --target ci_infer
-      - name: Archive Infer report
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: infer-report
-          path: ${{ github.workspace }}/build/build_infer/infer-out/report.txt
-          if-no-files-found: ignore

  ci_static_analysis_ubuntu:
    runs-on: ubuntu-latest
@@ -104,13 +97,13 @@ jobs:

  ci_cmake_options:
    runs-on: ubuntu-latest
-    container: ubuntu:24.04
+    container: ubuntu:focal
    strategy:
      matrix:
-        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls, ci_test_disableenumserialization, ci_test_disabletuplereferenceconversion, ci_test_skiplibraryversioncheck, ci_test_simdutf, ci_test_strict_nul_handling, ci_test_no_thread_local]
+        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls, ci_test_disableenumserialization, ci_test_skiplibraryversioncheck, ci_test_simdutf, ci_test_strict_nul_handling, ci_test_no_thread_local]
    steps:
      - name: Install build-essential
-        run: apt-get update ; apt-get install -y build-essential unzip wget git
+        run: apt-get update ; apt-get install -y build-essential unzip wget git libssl-dev
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
@@ -353,8 +346,6 @@ jobs:
    container: intel/oneapi-hpckit:latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
      - name: Get latest CMake and ninja
        uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
      - name: Run CMake
@@ -367,8 +358,6 @@ jobs:
    container: nvcr.io/nvidia/nvhpc:25.5-devel-cuda12.9-ubuntu22.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
      - name: Get latest CMake and ninja
        uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
      - name: Run CMake
@@ -414,21 +403,3 @@ jobs:
        run: cmake -S . -B build -DJSON_CI=On
      - name: Build
        run: cmake --build build --target ${{ matrix.target }}
-
-  # Native Linux ARM64 runner with the latest GCC. The ubuntu-24.04-arm label is
-  # only available for public repositories.
-  ci_test_arm64:
-    runs-on: ubuntu-24.04-arm
-    container: gcc:latest
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
-      - name: Check that the job runs natively on arm64
-        run: uname -m && test "$(uname -m)" = aarch64
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ci_test_compiler_default
@@ -87,8 +87,6 @@ jobs:

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
      - name: Get latest CMake and ninja
        uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
      - name: Set extra CXX_FLAGS for latest std_version
@@ -125,8 +123,6 @@ jobs:

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
      - name: Run CMake (Release)
        run: cmake -S . -B build -G "Visual Studio 18 2026" -A ARM64 -DJSON_BuildTests=On -DCMAKE_CXX_FLAGS="/W4 /WX"
        if: matrix.build_type == 'Release'
@@ -3,6 +3,7 @@
 *.gcno
 *.gcda
 .DS_Store
+__pycache__/

 /.idea
 /cmake-build-*
@@ -43,5 +44,9 @@ 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
@@ -1,12 +0,0 @@
-{
-  "_comment": "Used by the ci_infer CMake target (#5715 item 4b). fail-on-issue makes CI fail on Infer findings; disable-issue-type is a type-level baseline for the ~174 pre-existing findings (all PULSE_UNNECESSARY_COPY*/PULSE_RESOURCE_LEAK/PULSE_CONST_REFABLE, mostly in test code) triaged in run https://github.com/nlohmann/json/actions/runs/35829411620 on commit 1054b2097, so CI fails only on a NEW issue type. Remove an entry here once its findings have been fixed or explicitly accepted.",
-  "fail-on-issue": true,
-  "disable-issue-type": [
-    "PULSE_UNNECESSARY_COPY_ASSIGNMENT",
-    "PULSE_UNNECESSARY_COPY",
-    "PULSE_UNNECESSARY_COPY_INTERMEDIATE",
-    "PULSE_UNNECESSARY_COPY_OPTIONAL",
-    "PULSE_RESOURCE_LEAK",
-    "PULSE_CONST_REFABLE"
-  ]
-}
@@ -55,7 +55,6 @@ option(JSON_Diagnostic_Positions           "Enable diagnostic positions." OFF)
 option(JSON_GlobalUDLs                     "Place user-defined string literals in the global namespace." ON)
 option(JSON_ImplicitConversions            "Enable implicit conversions." ON)
 option(JSON_DisableEnumSerialization       "Disable default integer enum serialization." OFF)
-option(JSON_DisableTupleReferenceConversion "Disable conversion from a one-element tuple of a JSON reference." OFF)
 option(JSON_LegacyDiscardedValueComparison "Enable legacy discarded value comparison." OFF)
 option(JSON_Install                        "Install CMake targets during install step." ${MAIN_PROJECT})
 option(JSON_MultipleHeaders                "Use non-amalgamated version of the library." ON)
@@ -102,10 +101,6 @@ if (JSON_DisableEnumSerialization)
    message(STATUS "Enum integer serialization is disabled (JSON_DISABLE_ENUM_SERIALIZATION=1)")
 endif()

-if (JSON_DisableTupleReferenceConversion)
-    message(STATUS "Tuple reference conversion is disabled (JSON_DISABLE_TUPLE_REFERENCE_CONVERSION=1)")
-endif()
-
 if (JSON_LegacyDiscardedValueComparison)
    message(STATUS "Legacy discarded value comparison enabled (JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1)")
 endif()
@@ -148,7 +143,6 @@ target_compile_definitions(
    $<$<NOT:$<BOOL:${JSON_GlobalUDLs}>>:JSON_USE_GLOBAL_UDLS=0>
    $<$<NOT:$<BOOL:${JSON_ImplicitConversions}>>:JSON_USE_IMPLICIT_CONVERSIONS=0>
    $<$<BOOL:${JSON_DisableEnumSerialization}>:JSON_DISABLE_ENUM_SERIALIZATION=1>
-    $<$<BOOL:${JSON_DisableTupleReferenceConversion}>:JSON_DISABLE_TUPLE_REFERENCE_CONVERSION=1>
    $<$<BOOL:${JSON_Diagnostics}>:JSON_DIAGNOSTICS=1>
    $<$<BOOL:${JSON_Diagnostic_Positions}>:JSON_DIAGNOSTIC_POSITIONS=1>
    $<$<BOOL:${JSON_LegacyDiscardedValueComparison}>:JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1>
@@ -33,6 +33,17 @@ Further documentation:
 > [!IMPORTANT]
 > The folder `.github/workflows` is predetermined by GitHub.

+### `.cirrus.yml`
+
+Configuration file for the pipeline at [Cirrus CI](https://cirrus-ci.com/github/nlohmann/json).
+
+Further documentation:
+
+- [Writing tasks](https://cirrus-ci.org/guide/writing-tasks/)
+
+> [!IMPORTANT]
+> The filename `.cirrus.yml` and position (root of the repository) are predetermined by Cirrus CI.
+
 ### `.github/external_ci/appveyor.yml`

 Configuration for the pipelines at [AppVeyor](https://ci.appveyor.com/project/nlohmann/json).
@@ -1,4 +1,4 @@
-.PHONY: pretty clean ChangeLog.md release update_hedley update_hedley_undef BUILD.bazel natvis macro_builder_check
+.PHONY: pretty clean ChangeLog.md release update_hedley update_hedley_undef BUILD.bazel

 ##########################################################################
 # configuration
@@ -24,9 +24,6 @@ AMALGAMATED_FWD_FILE=single_include/nlohmann/json_fwd.hpp
 # json_literals.hpp only includes <nlohmann/json.hpp>, so it is copied verbatim
 AMALGAMATED_LITERALS_FILE=single_include/nlohmann/json_literals.hpp

-# the header with the argument-counting macros generated by tools/macro_builder
-MACRO_SCOPE_HPP=include/nlohmann/detail/macro_scope.hpp
-

 ##########################################################################
 # documentation of the Makefile's targets
@@ -39,9 +36,13 @@ all:
 	@echo "ChangeLog.md - generate ChangeLog file"
 	@echo "check-amalgamation - check whether sources have been amalgamated and BUILD.bazel is up to date"
 	@echo "clean - remove built files"
-	@echo "fuzzing - see tests/fuzzing.md for how to build and run the fuzzers"
-	@echo "macro_builder_check - check that macro_scope.hpp matches tools/macro_builder's output"
-	@echo "natvis - regenerate nlohmann_json.natvis from the current ABI tags and version"
+	@echo "doctest - compile example files and check their output"
+	@echo "fuzz_testing - prepare fuzz testing of the JSON parser"
+	@echo "fuzz_testing_bon8 - prepare fuzz testing of the BON8 parser"
+	@echo "fuzz_testing_bson - prepare fuzz testing of the BSON parser"
+	@echo "fuzz_testing_cbor - prepare fuzz testing of the CBOR parser"
+	@echo "fuzz_testing_msgpack - prepare fuzz testing of the MessagePack parser"
+	@echo "fuzz_testing_ubjson - prepare fuzz testing of the UBJSON parser"
 	@echo "pretty - beautify code with Artistic Style"
 	@echo "run_benchmarks - build and run benchmarks"
 	@echo "update_hedley - download Hedley and regenerate hedley.hpp / hedley_undef.hpp"
@@ -60,6 +61,74 @@ run_benchmarks:
 	cd cmake-build-benchmarks ; ./json_benchmarks


+##########################################################################
+# fuzzing
+##########################################################################
+
+# the overall fuzz testing target
+fuzz_testing:
+	rm -fr fuzz-testing
+	mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
+	$(MAKE) parse_afl_fuzzer -C tests CXX=afl-clang++
+	mv tests/parse_afl_fuzzer fuzz-testing/fuzzer
+	find tests/data/json_tests -size -5k -name *json | xargs -I{} cp "{}" fuzz-testing/testcases
+	@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
+
+fuzz_testing_bon8:
+	rm -fr fuzz-testing
+	mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
+	$(MAKE) parse_bon8_fuzzer -C tests CXX=afl-clang++
+	mv tests/parse_bon8_fuzzer fuzz-testing/fuzzer
+	find tests/data -size -5k -name *.bon8 | xargs -I{} cp "{}" fuzz-testing/testcases
+	@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
+
+fuzz_testing_bson:
+	rm -fr fuzz-testing
+	mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
+	$(MAKE) parse_bson_fuzzer -C tests CXX=afl-clang++
+	mv tests/parse_bson_fuzzer fuzz-testing/fuzzer
+	find tests/data -size -5k -name *.bson | xargs -I{} cp "{}" fuzz-testing/testcases
+	@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
+
+fuzz_testing_cbor:
+	rm -fr fuzz-testing
+	mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
+	$(MAKE) parse_cbor_fuzzer -C tests CXX=afl-clang++
+	mv tests/parse_cbor_fuzzer fuzz-testing/fuzzer
+	find tests/data -size -5k -name *.cbor | xargs -I{} cp "{}" fuzz-testing/testcases
+	@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
+
+fuzz_testing_msgpack:
+	rm -fr fuzz-testing
+	mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
+	$(MAKE) parse_msgpack_fuzzer -C tests CXX=afl-clang++
+	mv tests/parse_msgpack_fuzzer fuzz-testing/fuzzer
+	find tests/data -size -5k -name *.msgpack | xargs -I{} cp "{}" fuzz-testing/testcases
+	@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
+
+fuzz_testing_ubjson:
+	rm -fr fuzz-testing
+	mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
+	$(MAKE) parse_ubjson_fuzzer -C tests CXX=afl-clang++
+	mv tests/parse_ubjson_fuzzer fuzz-testing/fuzzer
+	find tests/data -size -5k -name *.ubjson | xargs -I{} cp "{}" fuzz-testing/testcases
+	@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
+
+fuzzing-start:
+	afl-fuzz -S fuzzer1 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer > /dev/null &
+	afl-fuzz -S fuzzer2 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer > /dev/null &
+	afl-fuzz -S fuzzer3 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer > /dev/null &
+	afl-fuzz -S fuzzer4 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer > /dev/null &
+	afl-fuzz -S fuzzer5 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer > /dev/null &
+	afl-fuzz -S fuzzer6 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer > /dev/null &
+	afl-fuzz -S fuzzer7 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer > /dev/null &
+	afl-fuzz -M fuzzer0 -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer
+
+fuzzing-stop:
+	-killall fuzzer
+	-killall afl-fuzz
+
+
 ##########################################################################
 # Static analysis
 ##########################################################################
@@ -87,7 +156,11 @@ install_astyle:

 # call the Artistic Style pretty printer on all source files
 pretty: install_astyle
-	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) docs/mkdocs/docs/examples/*.cpp docs/mkdocs/docs/examples/*.hpp
+	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) docs/mkdocs/docs/examples/*.cpp
+
+# call the Clang-Format on all source files
+pretty_format:
+	for FILE in $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) docs/mkdocs/docs/examples/*.cpp; do echo $$FILE; clang-format -i $$FILE; done

 # create single header files and pretty print
 amalgamate: $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE)
@@ -105,26 +178,8 @@ $(AMALGAMATED_FWD_FILE): $(SRCS)
 $(AMALGAMATED_LITERALS_FILE): include/nlohmann/json_literals.hpp
 	cp include/nlohmann/json_literals.hpp $(AMALGAMATED_LITERALS_FILE)

-# regenerate nlohmann_json.natvis from the ABI tags and version in include/nlohmann/detail/abi_macros.hpp
-natvis:
-	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
-macro_builder_check:
-	@set -e; \
-	TMPDIR=$$(mktemp -d ./macro_builder_check.XXXXXX); \
-	trap 'rm -rf "$$TMPDIR"' EXIT; \
-	$(CXX) -std=c++11 tools/macro_builder/main.cpp -o "$$TMPDIR/macro_builder"; \
-	"$$TMPDIR/macro_builder" > "$$TMPDIR/paste.hpp"; \
-	"$$TMPDIR/macro_builder" type_body > "$$TMPDIR/type_body.hpp"; \
-	$(ASTYLE) --project=tools/astyle/.astylerc --suffix=none --quiet "$$TMPDIR/paste.hpp" "$$TMPDIR/type_body.hpp"; \
-	sed -n '/^#define NLOHMANN_JSON_EXPAND( x ) x$$/,/^#define NLOHMANN_JSON_DOUBLE_PASTE63(/p' $(MACRO_SCOPE_HPP) > "$$TMPDIR/paste_actual.hpp"; \
-	sed -n '/^#define NLOHMANN_JSON_TYPE_BODY(Prefix, \.\.\.)/,/^        NLOHMANN_JSON_TYPE_BODY_SENTINEL))$$/p' $(MACRO_SCOPE_HPP) > "$$TMPDIR/type_body_actual.hpp"; \
-	diff "$$TMPDIR/paste.hpp" "$$TMPDIR/paste_actual.hpp" || (echo "===================================================================\n  $(MACRO_SCOPE_HPP) (NLOHMANN_JSON_EXPAND..NLOHMANN_JSON_DOUBLE_PASTE63) is out of date!\n  Regenerate it, see tools/macro_builder/README.md.\n===================================================================" ; exit 1); \
-	diff "$$TMPDIR/type_body.hpp" "$$TMPDIR/type_body_actual.hpp" || (echo "===================================================================\n  $(MACRO_SCOPE_HPP) (NLOHMANN_JSON_TYPE_BODY) is out of date!\n  Regenerate it, see tools/macro_builder/README.md.\n===================================================================" ; exit 1)
-
 # check if file single_include/nlohmann/json.hpp has been amalgamated from the nlohmann sources
+# Note: this target is called by Travis
 check-amalgamation:
 	@mv $(AMALGAMATED_FILE) $(AMALGAMATED_FILE)~
 	@mv $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_FWD_FILE)~
@@ -140,11 +195,6 @@ check-amalgamation:
 	@$(MAKE) BUILD.bazel
 	@diff BUILD.bazel BUILD.bazel~ || (echo "===================================================================\n  BUILD.bazel is out of date! Please run 'make BUILD.bazel'.\n===================================================================" ; mv BUILD.bazel~ BUILD.bazel ; false)
 	@mv BUILD.bazel~ BUILD.bazel
-	@mv nlohmann_json.natvis nlohmann_json.natvis~
-	@$(MAKE) natvis
-	@diff nlohmann_json.natvis nlohmann_json.natvis~ || (echo "===================================================================\n  nlohmann_json.natvis is out of date! Please run 'make natvis'.\n===================================================================" ; mv nlohmann_json.natvis~ nlohmann_json.natvis ; false)
-	@mv nlohmann_json.natvis~ nlohmann_json.natvis
-	@$(MAKE) macro_builder_check

 # generate the Bazel BUILD file; phony, because a removed header would not trigger a rebuild
 BUILD.bazel:
@@ -196,7 +246,7 @@ release: include.zip json.tar.xz
 	cp $(AMALGAMATED_FWD_FILE) release_files
 	cp $(AMALGAMATED_LITERALS_FILE) release_files
 	mv $(AMALGAMATED_FILE).asc $(AMALGAMATED_FWD_FILE).asc $(AMALGAMATED_LITERALS_FILE).asc json.tar.xz json.tar.xz.asc include.zip include.zip.asc release_files
-	cd release_files ; shasum -a 256 $$(find . -type f -not -name '*.asc' | sed 's|^\./||' | sort) > hashes.txt
+	cd release_files ; shasum -a 256 json.hpp include.zip json.tar.xz > hashes.txt


 ##########################################################################
@@ -206,6 +256,7 @@ release: include.zip json.tar.xz
 # clean up
 clean:
 	rm -fr fuzz fuzz-testing *.dSYM tests/*.dSYM
+	rm -fr benchmarks/files/numbers/*.json
 	rm -fr cmake-build-benchmarks fuzz-testing cmake-build-pvs-studio release_files
 	$(MAKE) clean -Cdocs

@@ -7,6 +7,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/nlohmann/json/badge.svg?branch=develop)](https://coveralls.io/github/nlohmann/json?branch=develop)
 [![Coverity Scan Build Status](https://scan.coverity.com/projects/5550/badge.svg)](https://scan.coverity.com/projects/nlohmann-json)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e0d1a9d5d6fd46fcb655c4cb930bb3e8)](https://app.codacy.com/gh/nlohmann/json/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Cirrus CI](https://api.cirrus-ci.com/github/nlohmann/json.svg)](https://cirrus-ci.com/github/nlohmann/json)
 [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/json.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:json)
 [![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://wandbox.org/permlink/1mp10JbaANo6FUc7)
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://json.nlohmann.me)
@@ -105,7 +106,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.

@@ -40,14 +40,6 @@ execute_process(COMMAND ${IWYU_TOOL} --version OUTPUT_VARIABLE IWYU_TOOL_VERSION
 string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" IWYU_TOOL_VERSION "${IWYU_TOOL_VERSION}")
 message(STATUS "🔖 include-what-you-use ${IWYU_TOOL_VERSION} (${IWYU_TOOL})")

-# CMake's CXX_INCLUDE_WHAT_YOU_USE launcher runs IWYU during the normal compile step (useful to see
-# diagnostics inline), but CMake's own __run_co_compile wrapper does not propagate the launched
-# tool's exit code to the build, so IWYU's own "-Xiwyu --error" cannot fail that step (verified: a
-# deliberately-unused #include in a header still lets `cmake --build` finish with exit code 0).
-# iwyu_tool.py, which ships with IWYU, reads compile_commands.json and does return a non-zero exit
-# code for any analyzed file with findings; ci_single_binaries uses it to actually fail on findings.
-find_program(IWYU_TOOL_PY NAMES iwyu_tool iwyu_tool.py iwyu-tool)
-
 find_program(INFER_TOOL NAMES infer)
 execute_process(COMMAND ${INFER_TOOL} --version OUTPUT_VARIABLE INFER_TOOL_VERSION ERROR_VARIABLE INFER_TOOL_VERSION)
 string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" INFER_TOOL_VERSION "${INFER_TOOL_VERSION}")
@@ -63,6 +55,12 @@ execute_process(COMMAND ${NINJA_TOOL} --version OUTPUT_VARIABLE NINJA_TOOL_VERSI
 string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" NINJA_TOOL_VERSION "${NINJA_TOOL_VERSION}")
 message(STATUS "🔖 Ninja ${NINJA_TOOL_VERSION} (${NINJA_TOOL})")

+find_program(OCLINT_TOOL NAMES oclint-json-compilation-database)
+find_program(OCLINT_VERSION_TOOL NAMES oclint)
+execute_process(COMMAND ${OCLINT_VERSION_TOOL} --version OUTPUT_VARIABLE OCLINT_TOOL_VERSION ERROR_VARIABLE OCLINT_TOOL_VERSION)
+string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" OCLINT_TOOL_VERSION "${OCLINT_TOOL_VERSION}")
+message(STATUS "🔖 OCLint ${OCLINT_TOOL_VERSION} (${OCLINT_TOOL})")
+
 find_program(VALGRIND_TOOL NAMES valgrind)
 execute_process(COMMAND ${VALGRIND_TOOL} --version OUTPUT_VARIABLE VALGRIND_TOOL_VERSION ERROR_VARIABLE VALGRIND_TOOL_VERSION)
 string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" VALGRIND_TOOL_VERSION "${VALGRIND_TOOL_VERSION}")
@@ -130,16 +128,16 @@ foreach(CXX_STANDARD 11 14 17 20 23 26)
        COMMENT "Compile and test with Clang for C++${CXX_STANDARD}"
    )

-    # pass -stdlib=libc++ through CXXFLAGS: an explicit -DCMAKE_CXX_FLAGS would make CMake ignore CXXFLAGS
    add_custom_target(ci_test_clang_libcxx_cxx${CXX_STANDARD}
-        COMMAND CXX=${CLANG_TOOL} CXXFLAGS="${CLANG_CXXFLAGS};-stdlib=libc++" ${CMAKE_COMMAND}
+        COMMAND CXX=${CLANG_TOOL} CXXFLAGS="${CLANG_CXXFLAGS}" ${CMAKE_COMMAND}
            -DCMAKE_BUILD_TYPE=Debug -GNinja
            -DJSON_BuildTests=ON -DJSON_FastTests=ON
            -DJSON_TestStandards=${CXX_STANDARD}
+            -DCMAKE_CXX_FLAGS="-stdlib=libc++"
            -DCMAKE_EXE_LINKER_FLAGS="-lc++abi"
-            -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_clang_libcxx_cxx${CXX_STANDARD}
-        COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_clang_libcxx_cxx${CXX_STANDARD}
-        COMMAND cd ${PROJECT_BINARY_DIR}/build_clang_libcxx_cxx${CXX_STANDARD} && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+            -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_clang_cxx${CXX_STANDARD}
+        COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_clang_cxx${CXX_STANDARD}
+        COMMAND cd ${PROJECT_BINARY_DIR}/build_clang_cxx${CXX_STANDARD} && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
        COMMENT "Compile and test with Clang for C++${CXX_STANDARD} (libc++)"
    )
 endforeach()
@@ -278,20 +276,6 @@ add_custom_target(ci_test_disableenumserialization
    COMMENT "Compile and test with enum serialization disabled"
 )

-###############################################################################
-# Disable conversion from a one-element tuple of a JSON reference.
-###############################################################################
-
-add_custom_target(ci_test_disabletuplereferenceconversion
-    COMMAND ${CMAKE_COMMAND}
-    -DCMAKE_BUILD_TYPE=Debug -GNinja
-    -DJSON_BuildTests=ON -DJSON_FastTests=ON -DJSON_DisableTupleReferenceConversion=ON
-    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_disabletuplereferenceconversion
-    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_disabletuplereferenceconversion
-    COMMAND cd ${PROJECT_BINARY_DIR}/build_disabletuplereferenceconversion && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
-    COMMENT "Compile and test with tuple reference conversion disabled"
-)
-
 ###############################################################################
 # Skip the multiple-inclusion library version check.
 ###############################################################################
@@ -378,20 +362,13 @@ add_custom_target(ci_test_clang_sanitizer
 # Check if header is amalgamated and sources are properly indented.
 ###############################################################################

-# Same file set as .github/workflows/check_amalgamation.yml, so a direct push to develop/master/release/*
-# (which only this CMake target checks, not the pull_request-only workflow) is held to the same standard.
 file(GLOB_RECURSE INDENT_FILES
-    ${PROJECT_SOURCE_DIR}/docs/mkdocs/docs/examples/*.hpp
+    ${PROJECT_SOURCE_DIR}/include/nlohmann/*.hpp
+        ${PROJECT_SOURCE_DIR}/tests/src/*.cpp
+        ${PROJECT_SOURCE_DIR}/tests/src/*.hpp
+        ${PROJECT_SOURCE_DIR}/tests/benchmarks/src/benchmarks.cpp
    ${PROJECT_SOURCE_DIR}/docs/mkdocs/docs/examples/*.cpp
-    ${PROJECT_SOURCE_DIR}/docs/mkdocs/docs/examples/*.cu
-    ${PROJECT_SOURCE_DIR}/include/*.hpp
-    ${PROJECT_SOURCE_DIR}/include/*.cpp
-    ${PROJECT_SOURCE_DIR}/include/*.cu
-    ${PROJECT_SOURCE_DIR}/tests/*.hpp
-    ${PROJECT_SOURCE_DIR}/tests/*.cpp
-    ${PROJECT_SOURCE_DIR}/tests/*.cu
 )
-list(FILTER INDENT_FILES EXCLUDE REGEX "/tests/thirdparty/|/tests/abi/include/nlohmann/")

 set(include_dir ${PROJECT_SOURCE_DIR}/single_include/nlohmann)
 set(tool_dir ${PROJECT_SOURCE_DIR}/tools/amalgamate)
@@ -400,7 +377,6 @@ add_custom_target(ci_test_amalgamation
    COMMAND cp ${include_dir}/json.hpp ${include_dir}/json.hpp~
    COMMAND cp ${include_dir}/json_fwd.hpp ${include_dir}/json_fwd.hpp~
    COMMAND cp ${include_dir}/json_literals.hpp ${include_dir}/json_literals.hpp~
-    COMMAND cp ${PROJECT_SOURCE_DIR}/BUILD.bazel ${PROJECT_SOURCE_DIR}/BUILD.bazel~

    COMMAND ${Python3_EXECUTABLE} -mvenv venv_astyle
    COMMAND venv_astyle/bin/pip3 --quiet install -r ${CMAKE_SOURCE_DIR}/tools/astyle/requirements.txt
@@ -410,18 +386,16 @@ add_custom_target(ci_test_amalgamation
    COMMAND ${Python3_EXECUTABLE} ${tool_dir}/amalgamate.py -c ${tool_dir}/config_json_fwd.json -s .
    COMMAND cp ${PROJECT_SOURCE_DIR}/include/nlohmann/json_literals.hpp ${include_dir}/json_literals.hpp
    COMMAND venv_astyle/bin/astyle --project=tools/astyle/.astylerc --suffix=none ${include_dir}/json.hpp ${include_dir}/json_fwd.hpp
-    COMMAND ${CMAKE_COMMAND} -P ${PROJECT_SOURCE_DIR}/cmake/scripts/gen_bazel_build_file.cmake

    COMMAND diff ${include_dir}/json.hpp~ ${include_dir}/json.hpp
    COMMAND diff ${include_dir}/json_fwd.hpp~ ${include_dir}/json_fwd.hpp
    COMMAND diff ${include_dir}/json_literals.hpp~ ${include_dir}/json_literals.hpp
-    COMMAND diff ${PROJECT_SOURCE_DIR}/BUILD.bazel~ ${PROJECT_SOURCE_DIR}/BUILD.bazel

    COMMAND venv_astyle/bin/astyle --project=tools/astyle/.astylerc --suffix=orig ${INDENT_FILES}
    COMMAND for FILE in `find . -name '*.orig'`\; do false \; done

    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
-    COMMENT "Check amalgamation, formatting, and BUILD.bazel"
+    COMMENT "Check amalgamation and indentation"
 )

 ###############################################################################
@@ -456,14 +430,14 @@ add_custom_target(ci_test_valgrind
 # Check code with Clang Static Analyzer.
 ###############################################################################

-set(CLANG_ANALYZER_CHECKS "nullability.NullableDereferenced,nullability.NullablePassedToNonnull,nullability.NullableReturnedFromNonnull,optin.cplusplus.UninitializedObject,optin.cplusplus.VirtualCall,optin.performance.Padding,optin.portability.UnixAPI,security.FloatLoopCounter,security.insecureAPI.DeprecatedOrUnsafeBufferHandling,security.insecureAPI.bcmp,security.insecureAPI.bcopy,security.insecureAPI.bzero,security.insecureAPI.rand,security.insecureAPI.strcpy,valist.CopyToSelf,valist.Uninitialized,valist.Unterminated,core.CallAndMessage,core.DivideZero,core.NonNullParamChecker,core.NullDereference,core.StackAddressEscape,core.UndefinedBinaryOperatorResult,core.VLASize,core.uninitialized.ArraySubscript,core.uninitialized.Assign,core.uninitialized.Branch,core.uninitialized.CapturedBlockVariable,core.uninitialized.UndefReturn,cplusplus.InnerPointer,cplusplus.Move,cplusplus.NewDelete,cplusplus.NewDeleteLeaks,cplusplus.PlacementNew,cplusplus.PureVirtualCall,deadcode.DeadStores,nullability.NullPassedToNonnull,nullability.NullReturnedFromNonnull,security.insecureAPI.UncheckedReturn,security.insecureAPI.decodeValueOfObjCType,security.insecureAPI.getpw,security.insecureAPI.gets,security.insecureAPI.mkstemp,security.insecureAPI.mktemp,security.insecureAPI.vfork,unix.API,unix.Malloc,unix.MallocSizeof,unix.MismatchedDeallocator,unix.Vfork,unix.cstring.BadSizeArg,unix.cstring.NullArg")
+set(CLANG_ANALYZER_CHECKS "fuchsia.HandleChecker,nullability.NullableDereferenced,nullability.NullablePassedToNonnull,nullability.NullableReturnedFromNonnull,optin.cplusplus.UninitializedObject,optin.cplusplus.VirtualCall,optin.mpi.MPI-Checker,optin.osx.OSObjectCStyleCast,optin.osx.cocoa.localizability.EmptyLocalizationContextChecker,optin.osx.cocoa.localizability.NonLocalizedStringChecker,optin.performance.GCDAntipattern,optin.performance.Padding,optin.portability.UnixAPI,security.FloatLoopCounter,security.insecureAPI.DeprecatedOrUnsafeBufferHandling,security.insecureAPI.bcmp,security.insecureAPI.bcopy,security.insecureAPI.bzero,security.insecureAPI.rand,security.insecureAPI.strcpy,valist.CopyToSelf,valist.Uninitialized,valist.Unterminated,webkit.NoUncountedMemberChecker,webkit.RefCntblBaseVirtualDtor,core.CallAndMessage,core.DivideZero,core.NonNullParamChecker,core.NullDereference,core.StackAddressEscape,core.UndefinedBinaryOperatorResult,core.VLASize,core.uninitialized.ArraySubscript,core.uninitialized.Assign,core.uninitialized.Branch,core.uninitialized.CapturedBlockVariable,core.uninitialized.UndefReturn,cplusplus.InnerPointer,cplusplus.Move,cplusplus.NewDelete,cplusplus.NewDeleteLeaks,cplusplus.PlacementNew,cplusplus.PureVirtualCall,deadcode.DeadStores,nullability.NullPassedToNonnull,nullability.NullReturnedFromNonnull,osx.API,osx.MIG,osx.NumberObjectConversion,osx.OSObjectRetainCount,osx.ObjCProperty,osx.SecKeychainAPI,osx.cocoa.AtSync,osx.cocoa.AutoreleaseWrite,osx.cocoa.ClassRelease,osx.cocoa.Dealloc,osx.cocoa.IncompatibleMethodTypes,osx.cocoa.Loops,osx.cocoa.MissingSuperCall,osx.cocoa.NSAutoreleasePool,osx.cocoa.NSError,osx.cocoa.NilArg,osx.cocoa.NonNilReturnValue,osx.cocoa.ObjCGenerics,osx.cocoa.RetainCount,osx.cocoa.RunLoopAutoreleaseLeak,osx.cocoa.SelfInit,osx.cocoa.SuperDealloc,osx.cocoa.UnusedIvars,osx.cocoa.VariadicMethodTypes,osx.coreFoundation.CFError,osx.coreFoundation.CFNumber,osx.coreFoundation.CFRetainRelease,osx.coreFoundation.containers.OutOfBounds,osx.coreFoundation.containers.PointerSizedValues,security.insecureAPI.UncheckedReturn,security.insecureAPI.decodeValueOfObjCType,security.insecureAPI.getpw,security.insecureAPI.gets,security.insecureAPI.mkstemp,security.insecureAPI.mktemp,security.insecureAPI.vfork,unix.API,unix.Malloc,unix.MallocSizeof,unix.MismatchedDeallocator,unix.Vfork,unix.cstring.BadSizeArg,unix.cstring.NullArg")

 add_custom_target(ci_clang_analyze
    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
        -DCMAKE_BUILD_TYPE=Debug -GNinja
        -DJSON_BuildTests=ON
        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_clang_analyze
-    COMMAND cd ${PROJECT_BINARY_DIR}/build_clang_analyze && ${SCAN_BUILD_TOOL} -enable-checker ${CLANG_ANALYZER_CHECKS} --use-c++=${CLANG_TOOL} --use-analyzer=${CLANG_TOOL} -analyze-headers --status-bugs -o ${PROJECT_BINARY_DIR}/report ninja
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_clang_analyze && ${SCAN_BUILD_TOOL} -enable-checker ${CLANG_ANALYZER_CHECKS} --use-c++=${CLANG_TOOL} -analyze-headers -o ${PROJECT_BINARY_DIR}/report ninja
    COMMENT "Check code with Clang Analyzer"
 )

@@ -479,7 +453,7 @@ add_custom_target(ci_cppcheck
    COMMAND venv_cppcheck/bin/cppcheck --enable=warning --check-level=exhaustive --inline-suppr --inconclusive --force
            --std=c++11 ${PROJECT_SOURCE_DIR}/include/nlohmann/json.hpp -I ${CMAKE_SOURCE_DIR}/include
            --error-exitcode=1 --relative-paths=${PROJECT_SOURCE_DIR} -j ${N} --include=default_defines.hpp
-            --cppcheck-build-dir=cppcheck
+            --cppcheck-build-dir=cppcheck --check-level=exhaustive
            -UJSON_CATCH_USER -UJSON_TRY_USER -UJSON_ASSERT -UJSON_INTERNAL_CATCH -UJSON_THROW
            -DJSON_HAS_CPP_11 -UJSON_HAS_CPP_14 -UJSON_HAS_CPP_17 -UJSON_HAS_CPP_20 -UJSON_HAS_THREE_WAY_COMPARISON
    COMMENT "Check code with Cppcheck"
@@ -497,6 +471,34 @@ add_custom_target(ci_cpplint
    WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
 )

+###############################################################################
+# Check code with OCLint.
+###############################################################################
+
+file(COPY ${PROJECT_SOURCE_DIR}/single_include/nlohmann/json.hpp DESTINATION ${PROJECT_BINARY_DIR}/src_single)
+file(RENAME ${PROJECT_BINARY_DIR}/src_single/json.hpp ${PROJECT_BINARY_DIR}/src_single/all.cpp)
+file(APPEND "${PROJECT_BINARY_DIR}/src_single/all.cpp" "\n\nint main()\n{}\n")
+
+add_executable(single_all ${PROJECT_BINARY_DIR}/src_single/all.cpp)
+target_compile_features(single_all PRIVATE cxx_std_11)
+
+add_custom_target(ci_oclint
+    COMMAND ${CMAKE_COMMAND}
+        -DCMAKE_BUILD_TYPE=Debug
+        -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+        -DJSON_BuildTests=OFF -DJSON_CI=ON
+        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_oclint
+    COMMAND ${OCLINT_TOOL} -i ${PROJECT_BINARY_DIR}/build_oclint/src_single/all.cpp -p ${PROJECT_BINARY_DIR}/build_oclint --
+        -report-type html -enable-global-analysis --max-priority-1=0 --max-priority-2=1000 --max-priority-3=2000
+        --disable-rule=MultipleUnaryOperator
+        --disable-rule=DoubleNegative
+        --disable-rule=ShortVariableName
+        --disable-rule=GotoStatement
+        --disable-rule=LongLine
+        -o ${PROJECT_BINARY_DIR}/build_oclint/oclint_report.html
+    COMMENT "Check code with OCLint"
+)
+
 ###############################################################################
 # Check code with Clang-Tidy.
 ###############################################################################
@@ -511,16 +513,29 @@ add_custom_target(ci_clang_tidy
    COMMENT "Check code with Clang-Tidy"
 )

+###############################################################################
+# Check code with PVS-Studio Analyzer <https://www.viva64.com/en/pvs-studio/>.
+###############################################################################
+
+add_custom_target(ci_pvs_studio
+    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
+        -DCMAKE_BUILD_TYPE=Debug
+        -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+        -DJSON_BuildTests=ON
+        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_pvs_studio
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_pvs_studio && ${PVS_STUDIO_ANALYZER_TOOL} analyze -j 10
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_pvs_studio && ${PLOG_CONVERTER_TOOL} -a'GA:1,2;64:1;CS' -t fullhtml PVS-Studio.log -o pvs
+    COMMENT "Check code with PVS Studio"
+)
+
 ###############################################################################
 # Check code with Infer <https://fbinfer.com> static analyzer.
 ###############################################################################

-# .inferconfig (repository root) pins --fail-on-issue and the currently-triaged issue types that
-# are disabled until they are addressed separately; see #5715 item 4b.
 add_custom_target(ci_infer
    COMMAND mkdir -p ${PROJECT_BINARY_DIR}/build_infer
    COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} compile -- ${CMAKE_COMMAND} -DCMAKE_BUILD_TYPE=Debug ${PROJECT_SOURCE_DIR} -DJSON_BuildTests=ON
-    COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} run --project-root ${PROJECT_SOURCE_DIR} -- make
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} run -- make
    COMMENT "Check code with Infer"
 )

@@ -576,13 +591,7 @@ add_custom_target(ci_reproducible_tests
 # be compiled individually.
 ###############################################################################

-set(iwyu_options -Xiwyu --error -Xiwyu --max_line_length=300)
-set(iwyu_path_and_options ${IWYU_TOOL} ${iwyu_options})
-
-# CMake needs to know the exact flags used to compile each src_single/*.cpp below to hand them to
-# iwyu_tool.py; JSON_CI already implies a from-scratch configure, so enabling this project-wide has
-# no downside here.
-set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(iwyu_path_and_options ${IWYU_TOOL} -Xiwyu --max_line_length=300)

 foreach(SRC_FILE ${SRC_FILES})
    # get relative path of the header file
@@ -597,34 +606,14 @@ foreach(SRC_FILE ${SRC_FILES})
    target_include_directories(single_${RELATIVE_SRC_FILE} PRIVATE ${PROJECT_SOURCE_DIR}/include)
    target_compile_features(single_${RELATIVE_SRC_FILE} PRIVATE cxx_std_11)
    set_property(TARGET single_${RELATIVE_SRC_FILE} PROPERTY CXX_INCLUDE_WHAT_YOU_USE "${iwyu_path_and_options}")
-    # remember binary for ci_single_binaries
+    # remember binary for ci_single_binaries target
    list(APPEND single_binaries single_${RELATIVE_SRC_FILE})
-    # json.hpp pulls together the whole library behind heavily templated, SFINAE-based code, and
-    # IWYU's suggestion for its one truly ambiguous symbol (a container-comparison "swap,
-    # operator!=") is not deterministic between runs (observed <set>, <unordered_map>, and <map>
-    # for the exact same source across otherwise-identical local and containerized builds). Keep
-    # reporting its diagnostics (informational, via CXX_INCLUDE_WHAT_YOU_USE above) but exclude it
-    # from the hard gate below so a fresh IWYU/compiler combination does not fail this target on a
-    # nondeterministic suggestion for a header that already re-exports everything on purpose.
-    if(NOT RELATIVE_SRC_FILE STREQUAL "json")
-        list(APPEND single_binaries_tus src_single/${RELATIVE_SRC_FILE}.cpp)
-    endif()
 endforeach()

-if(IWYU_TOOL_PY)
-    add_custom_target(ci_single_binaries
-        DEPENDS ${single_binaries}
-        COMMAND ${IWYU_TOOL_PY} -p ${PROJECT_BINARY_DIR} ${single_binaries_tus} -- ${iwyu_options}
-        COMMENT "Check if headers are self-contained"
-    )
-else()
-    # iwyu_tool.py (ships with IWYU, e.g. as /usr/bin/iwyu_tool on Debian/Ubuntu) was not found;
-    # fall back to building the self-containment check without enforcing the IWYU findings.
-    add_custom_target(ci_single_binaries
-        DEPENDS ${single_binaries}
-        COMMENT "Check if headers are self-contained"
-    )
-endif()
+add_custom_target(ci_single_binaries
+    DEPENDS ${single_binaries}
+    COMMENT "Check if headers are self-contained"
+)

 ###############################################################################
 # Benchmarks
@@ -646,41 +635,21 @@ add_custom_target(ci_benchmarks
 # we test the project with different CMake versions:
 # - CMake 3.5 (the earliest supported)
 # - CMake 3.31.6 (the latest 3.x release)
-# - CMake 4.0.0 (the first 4.x release)
-# - the CMake version running this build (usually the latest release)
+# - CMake 4.0.0 (the latest release)

 function(ci_get_cmake version var)
    set(${var} ${PROJECT_BINARY_DIR}/cmake-${version}/bin/cmake)
-    if(CMAKE_HOST_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_HOST_SYSTEM_PROCESSOR MATCHES "^(x86_64|amd64)$")
-        # Kitware publishes a prebuilt Linux x86_64 archive for every release; unpacking it is far
-        # cheaper than compiling all of CMake (including its own test helpers) from source.
-        add_custom_command(
-            OUTPUT ${${var}}
-            COMMAND wget -nc https://github.com/Kitware/CMake/releases/download/v${version}/cmake-${version}-linux-x86_64.tar.gz
-            COMMAND wget -nc https://github.com/Kitware/CMake/releases/download/v${version}/cmake-${version}-SHA-256.txt
-            # verify the archive against Kitware's published SHA-256 sums before unpacking it
-            COMMAND sh -c "grep ' cmake-${version}-linux-x86_64[.]tar[.]gz$' cmake-${version}-SHA-256.txt | sha256sum -c -"
-            COMMAND tar xfz cmake-${version}-linux-x86_64.tar.gz
-            COMMAND rm cmake-${version}-linux-x86_64.tar.gz cmake-${version}-SHA-256.txt
-            COMMAND ${CMAKE_COMMAND} -E rm -rf cmake-${version}
-            COMMAND ${CMAKE_COMMAND} -E rename cmake-${version}-linux-x86_64 cmake-${version}
-            WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
-            COMMENT "Download prebuilt CMake ${version}"
-        )
-    else()
-        # no prebuilt archive for this platform (e.g. macOS or Linux aarch64): build from source
-        add_custom_command(
-            OUTPUT ${${var}}
-            COMMAND wget -nc https://github.com/Kitware/CMake/releases/download/v${version}/cmake-${version}.tar.gz
-            COMMAND tar xfz cmake-${version}.tar.gz
-            COMMAND rm cmake-${version}.tar.gz
-            # -DCMAKE_POLICY_VERSION_MINIMUM=3.5 required to compile older CMake versions with CMake 4.0.0
-            COMMAND cmake -S cmake-${version} -B cmake-${version} -DCMAKE_POLICY_VERSION_MINIMUM=3.5
-            COMMAND cmake --build cmake-${version} --parallel 10
-            WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
-            COMMENT "Download and build CMake ${version} from source"
-        )
-    endif()
+    add_custom_command(
+        OUTPUT ${${var}}
+        COMMAND wget -nc https://github.com/Kitware/CMake/releases/download/v${version}/cmake-${version}.tar.gz
+        COMMAND tar xfz cmake-${version}.tar.gz
+        COMMAND rm cmake-${version}.tar.gz
+        # -DCMAKE_POLICY_VERSION_MINIMUM=3.5 required to compile older CMake versions with CMake 4.0.0
+        COMMAND cmake -S cmake-${version} -B cmake-${version} -DCMAKE_POLICY_VERSION_MINIMUM=3.5
+        COMMAND cmake --build cmake-${version} --parallel 10
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+        COMMENT "Download CMake ${version}"
+    )
    set(${var} ${${var}} PARENT_SCOPE)
 endfunction()

@@ -690,24 +659,30 @@ ci_get_cmake(4.0.0  CMAKE_4_0_0_BINARY)

 # the tests require CMake 3.13 or later, so they are excluded for CMake 3.5.0
 set(JSON_CMAKE_FLAGS_3_5_0 JSON_Diagnostics JSON_Diagnostic_Positions JSON_GlobalUDLs JSON_ImplicitConversions JSON_DisableEnumSerialization
-    JSON_LegacyDiscardedValueComparison JSON_Install JSON_MultipleHeaders JSON_SystemInclude JSON_Valgrind
-    JSON_StrictNulHandling)
-set(JSON_CMAKE_FLAGS_3_31_6 JSON_BuildTests ${JSON_CMAKE_FLAGS_3_5_0})
+    JSON_LegacyDiscardedValueComparison JSON_Install JSON_MultipleHeaders JSON_SystemInclude JSON_Valgrind)
+set(JSON_CMAKE_FLAGS_3_31_6 JSON_BuildTests ${JSON_CMAKE_FLAGS_3_31_6})
 set(JSON_CMAKE_FLAGS_4_0_0 JSON_BuildTests ${JSON_CMAKE_FLAGS_3_5_0})

 function(ci_add_cmake_flags_targets flag min_version)
    string(TOLOWER "ci_cmake_flag_${flag}" flag_target)
    string(REPLACE . _ min_version_var ${min_version})
    set(cmake_binary ${CMAKE_${min_version_var}_BINARY})
+    add_custom_target(${flag_target}_${min_version}_2
+        COMMENT "Check CMake flag ${flag} (CMake ${CMAKE_VERSION})"
+        COMMAND ${CMAKE_COMMAND}
+            -Werror=dev
+            -D${flag}=ON
+            -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_${flag_target}
+    )
    add_custom_target(${flag_target}_${min_version_var}
-        COMMENT "Check CMake flag ${flag} (CMake ${min_version})"
+        COMMENT "Check CMake flag ${JSON_CMAKE_FLAG} (CMake ${min_version})"
        COMMAND mkdir -pv ${PROJECT_BINARY_DIR}/build_${flag_target}_${min_version_var}
        COMMAND cd ${PROJECT_BINARY_DIR}/build_${flag_target}_${min_version_var}
            && ${cmake_binary} -Werror=dev ${PROJECT_SOURCE_DIR} -D${flag}=ON
        DEPENDS ${cmake_binary}
    )
-    list(APPEND JSON_CMAKE_FLAG_TARGETS ${flag_target}_${min_version_var})
-    list(APPEND JSON_CMAKE_FLAG_BUILD_DIRS ${PROJECT_BINARY_DIR}/build_${flag_target}_${min_version_var})
+    list(APPEND JSON_CMAKE_FLAG_TARGETS ${JSON_CMAKE_FLAG_TARGET} ${flag_target}_${min_version_var})
+    list(APPEND JSON_CMAKE_FLAG_BUILD_DIRS ${PROJECT_BINARY_DIR}/build_${flag_target} ${PROJECT_BINARY_DIR}/build_${flag_target}_${min_version_var})
    set(JSON_CMAKE_FLAG_TARGETS ${JSON_CMAKE_FLAG_TARGETS} PARENT_SCOPE)
    set(JSON_CMAKE_FLAG_BUILD_DIRS ${JSON_CMAKE_FLAG_BUILD_DIRS} PARENT_SCOPE)
 endfunction()
@@ -724,20 +699,6 @@ foreach(JSON_CMAKE_FLAG ${JSON_CMAKE_FLAGS_4_0_0})
    ci_add_cmake_flags_targets(${JSON_CMAKE_FLAG} 4.0.0)
 endforeach()

-# check the same flags with the CMake version running this build
-foreach(JSON_CMAKE_FLAG ${JSON_CMAKE_FLAGS_4_0_0})
-    string(TOLOWER "ci_cmake_flag_${JSON_CMAKE_FLAG}" flag_target)
-    add_custom_target(${flag_target}
-        COMMENT "Check CMake flag ${JSON_CMAKE_FLAG} (CMake ${CMAKE_VERSION})"
-        COMMAND ${CMAKE_COMMAND}
-            -Werror=dev
-            -D${JSON_CMAKE_FLAG}=ON
-            -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_${flag_target}
-    )
-    list(APPEND JSON_CMAKE_FLAG_TARGETS ${flag_target})
-    list(APPEND JSON_CMAKE_FLAG_BUILD_DIRS ${PROJECT_BINARY_DIR}/build_${flag_target})
-endforeach()
-
 add_custom_target(ci_cmake_flags
    DEPENDS ${JSON_CMAKE_FLAG_TARGETS}
    COMMENT "Check CMake flags"
@@ -896,6 +857,6 @@ add_custom_target(ci_test_build_documentation
 ###############################################################################

 add_custom_target(ci_clean
-    COMMAND rm -fr ${PROJECT_BINARY_DIR}/build_* ${PROJECT_BINARY_DIR}/cmake-3.5.0 ${PROJECT_BINARY_DIR}/cmake-3.31.6 ${PROJECT_BINARY_DIR}/cmake-4.0.0 ${JSON_CMAKE_FLAG_BUILD_DIRS} ${single_binaries}
+    COMMAND rm -fr ${PROJECT_BINARY_DIR}/build_* cmake-3.5.0-Darwin64 ${JSON_CMAKE_FLAG_BUILD_DIRS} ${single_binaries}
    COMMENT "Clean generated directories"
 )
@@ -11,31 +11,20 @@ EXAMPLES = $(wildcard mkdocs/docs/examples/*.cpp)

 cxx_standard = $(lastword c++11 $(filter c++%, $(subst ., ,$1)))

-# common compile flags for the stand-alone example files
-EXAMPLE_CPPFLAGS = -I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0
-EXAMPLE_WARNFLAGS = -Werror=deprecated-declarations
-
-# examples that document deprecated API and are allowed to use it
-DEPRECATED_EXAMPLES = $(addprefix mkdocs/docs/examples/, \
-	json_pointer__operator__equal_stringtype \
-	json_pointer__operator__notequal_stringtype \
-	json_pointer__operator_string_t)
-$(DEPRECATED_EXAMPLES:=.output) $(DEPRECATED_EXAMPLES:=.test): EXAMPLE_WARNFLAGS = -Wno-deprecated-declarations
-
 # create output from a stand-alone example file
 %.output: %.cpp
-	@echo "standard $(call cxx_standard,$(<:.cpp=))"
+	@echo "standard $(call cxx_standard $(<:.cpp=))"
 	$(MAKE) $(<:.cpp=) \
-		CPPFLAGS="$(EXAMPLE_CPPFLAGS)" \
-		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) $(EXAMPLE_WARNFLAGS)"
+		CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \
+		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	rm $(<:.cpp=)

 # compare created output with current output of the example files
 %.test: %.cpp
 	$(MAKE) $(<:.cpp=) \
-		CPPFLAGS="$(EXAMPLE_CPPFLAGS)" \
-		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) $(EXAMPLE_WARNFLAGS)"
+		CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \
+		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	diff $@ $(<:.cpp=.output)
 	rm $(<:.cpp=) $@
@@ -13,7 +13,7 @@
    <key>dashIndexFilePath</key>
    <string>index.html</string>
    <key>DashDocSetFallbackURL</key>
-    <string>https://json.nlohmann.me/</string>
+    <string>https://nlohmann.github.io/json/</string>
    <key>isJavaScriptEnabled</key>
    <true/>
 </dict>
@@ -52,25 +52,35 @@ install_docset_zeal: JSON_for_Modern_C++.docset
 	mkdir -p $$docset_root; \
 	cp -r JSON_for_Modern_C++.docset $$docset_root/

-# both targets below compare the docset search index with the mkdocs page
-# set. They share the same normalization (docs/foo/index.md and
-# docs/foo.md both become foo/index.html, the URL mkdocs itself would
-# give the page; the top-level index.md is excluded, as it is not part
-# of the hand-curated docSet.sql) and use comm(1) on two sorted lists
-# instead of running a sqlite3 query, or an O(n*m) nested shell loop,
-# once per page.
-DOCSET_INDEX_PATHS=$(shell sqlite3 docSet.dsidx "SELECT DISTINCT path FROM searchIndex" | sort)
-DOCSET_PAGE_PATHS=$(shell echo '$(MKDOCS_PAGES)' | tr ' ' '\n' | grep -v '^index\.md$$' | $(SED) -E 's@/index\.md$$@/index.html@; s@\.md$$@/index.html@' | sort)
-
 # list mkdocs pages missing from the docset index
 .PHONY: list_missing_pages
 list_missing_pages: docSet.dsidx
-	@comm -23 <(echo '$(DOCSET_PAGE_PATHS)' | tr ' ' '\n') <(echo '$(DOCSET_INDEX_PATHS)' | tr ' ' '\n')
+	@for page in $(MKDOCS_PAGES); do \
+		case "$$page" in \
+			*/index.md) path=$${page/\/index.md/} ;; \
+			*)          path=$${page/.md/}        ;; \
+		esac; \
+		if [ "x$$page" != "xindex.md" -a "x$$(sqlite3 docSet.dsidx "SELECT COUNT(*) FROM searchIndex WHERE path='$$path/index.html'")" = "x0" ]; then \
+			echo $$page; \
+		fi \
+	done

 # list paths in the docset index without a corresponding mkdocs page
 .PHONY: list_removed_paths
 list_removed_paths: docSet.dsidx
-	@comm -13 <(echo '$(DOCSET_PAGE_PATHS)' | tr ' ' '\n') <(echo '$(DOCSET_INDEX_PATHS)' | tr ' ' '\n')
+	@for path in $$(sqlite3 docSet.dsidx "SELECT path FROM searchIndex"); do \
+		page=$${path/\/index.html/.md}; \
+		page_index=$${path/index.html/index.md}; \
+		page_found=0; \
+		for p in $(MKDOCS_PAGES); do \
+			if [ "x$$p" = "x$$page" -o "x$$p" = "x$$page_index" ]; then \
+				page_found=1; \
+			fi \
+		done; \
+		if [ "x$$page_found" = "x0" ]; then \
+			echo $$path; \
+		fi \
+	done

 .PHONY: clean
 clean:
@@ -7,11 +7,10 @@ documentation browsers like [Dash](https://kapeli.com/dash), [Velocity](https://
 The docset can be created with

 ```sh
-make JSON_for_Modern_C++.docset
+make nlohmann_json.docset
 ```

-The generated folder `JSON_for_Modern_C++.docset` can then be opened in the documentation browser. `make all` builds a
-`JSON_for_Modern_C++.tgz` archive instead, and `make install_docset_zeal` installs the docset for Zeal directly.
+The generated folder `nlohmann_json.docset` can then be opened in the documentation browser.

 A recent version is also part of the [Dash user contributions](https://github.com/Kapeli/Dash-User-Contributions/tree/master/docsets/JSON_for_Modern_C%2B%2B).

@@ -210,7 +210,6 @@ INSERT INTO searchIndex(name, type, path) VALUES ('JSON_CATCH_USER', 'Macro', 'a
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTICS', 'Macro', 'api/macros/json_diagnostics/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTIC_POSITIONS', 'Macro', 'api/macros/json_diagnostic_positions/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_ENUM_SERIALIZATION', 'Macro', 'api/macros/json_disable_enum_serialization/index.html');
-INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_TUPLE_REFERENCE_CONVERSION', 'Macro', 'api/macros/json_disable_tuple_reference_conversion/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_11', 'Macro', 'api/macros/json_has_cpp_11/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_14', 'Macro', 'api/macros/json_has_cpp_11/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_17', 'Macro', 'api/macros/json_has_cpp_11/index.html');
@@ -159,8 +159,6 @@ basic_json(basic_json&& other) noexcept;
    - `CompatibleType` is not `basic_json` (to avoid hijacking copy/move constructors),
    - `CompatibleType` is not a different `basic_json` type (i.e. with different template arguments)
    - `CompatibleType` is not a `basic_json` nested type (e.g., `json_pointer`, `iterator`, etc.)
-    - if [`JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](../macros/json_disable_tuple_reference_conversion.md) is defined
-      to `1`: `CompatibleType` is not a one-element `std::tuple` holding a reference to `basic_json`
    - `json_serializer<U>` (with `U = uncvref_t<CompatibleType>`) has a `to_json(basic_json_t&, CompatibleType&&)`
       method

@@ -422,7 +420,9 @@ basic_json(basic_json&& other) noexcept;
 1. Since version 1.0.0.
 2. Since version 1.0.0.
 3. Since version 2.1.0.
-4. Since version 3.2.0.
+4. Since version 3.2.0. Also initializes the position reported by
+   [`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) from `val` when
+   [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is enabled, since version 3.12.0.
 5. Since version 1.0.0.
 6. Since version 1.0.0.
 7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
@@ -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.
@@ -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.
@@ -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.
@@ -37,12 +37,6 @@ Thereby, `Target` is the current object; that is, the patch is applied to the cu

 Linear in the lengths of `apply_patch`.

-## Notes
-
-`apply_patch` may be `#!cpp *this` itself or refer to a value contained in `#!cpp *this` (for example, a subobject
-returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was called, before any modification of
-`#!cpp *this`.
-
 ## Examples

 ??? example
@@ -67,5 +61,3 @@ returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was
 ## Version history

 - 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.
@@ -51,7 +51,7 @@ range will yield over/underflow when used in a constructor. During deserializati
 will automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).

 [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
-> Note that when such software is used, numbers that are integers and are in the range [-2<sup>53</sup>+1, 2<sup>53</sup>-1] are
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
 > interoperable in the sense that implementations will agree exactly on their numeric values.

 As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is
@@ -52,7 +52,7 @@ when used in a constructor. During deserialization, too large or small integer n
 as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).

 [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
-> Note that when such software is used, numbers that are integers and are in the range [-2<sup>53</sup>+1, 2<sup>53</sup>-1] are
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
 > interoperable in the sense that implementations will agree exactly on their numeric values.

 As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported
@@ -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.
@@ -85,3 +85,8 @@ Linear in the size of the JSON value.
 - 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)).
@@ -54,7 +54,7 @@ classDiagram

 ## Notes

-For an input with <i>n</i> bytes, 1 is the index of the first character and <i>n</i>+1 is the index of the terminating null byte
+For an input with $n$ bytes, 1 is the index of the first character and $n+1$ is the index of the terminating null byte
 or the end of file. This also holds true when reading a byte vector for binary formats.

 ## Examples
@@ -59,12 +59,6 @@ Basic guarantee: if an exception is thrown during the operation, the JSON value
 1. O(N*log(size() + N)), where N is the number of elements to insert.
 2. O(N*log(size() + N)), where N is the number of elements to insert.

-## Notes
-
-The argument `j` (or, for overload (2), the range `[first, last)`) may be `#!cpp *this` itself or refer to a value
-contained in `#!cpp *this` (for example, a subobject returned by `#!cpp (*this)[key]`); it is read as it was when
-`update()` was called, before any modification of `#!cpp *this`.
-
 ## Examples

 ??? example
@@ -161,5 +155,3 @@ contained in `#!cpp *this` (for example, a subobject returned by `#!cpp (*this)[

 - Added in version 3.0.0.
 - Added `merge_objects` parameter in 3.10.5.
- Fixed use of freed or relocated memory when the argument is `#!cpp *this` or refers to a value contained in
-  `#!cpp *this`, in version 3.13.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.
@@ -0,0 +1,45 @@
+# <small>nlohmann::byte_container_with_subtype::</small>operator==
+
+```cpp
+bool operator==(const byte_container_with_subtype& rhs) const;
+```
+
+Compares two `byte_container_with_subtype` values for equality by comparing the underlying binary
+container, the subtype, and whether a subtype is set.
+
+## Parameters
+
+`rhs` (in)
+:   value to compare `*this` against
+
+## Return value
+
+whether `*this` and `rhs` are equal
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Linear in the size of the underlying binary container.
+
+## Examples
+
+??? example
+
+    The example demonstrates comparing `byte_container_with_subtype` values.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__operator_eq.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/byte_container_with_subtype__operator_eq.output"
+    ```
+
+## Version history
+
+- Since version 3.8.0.
@@ -0,0 +1,45 @@
+# <small>nlohmann::byte_container_with_subtype::</small>operator!=
+
+```cpp
+bool operator!=(const byte_container_with_subtype& rhs) const;
+```
+
+Compares two `byte_container_with_subtype` values for inequality. Implemented as the negation of
+[`operator==`](operator_eq.md).
+
+## Parameters
+
+`rhs` (in)
+:   value to compare `*this` against
+
+## Return value
+
+whether `*this` and `rhs` are not equal
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Linear in the size of the underlying binary container.
+
+## Examples
+
+??? example
+
+    The example demonstrates comparing `byte_container_with_subtype` values.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__operator_ne.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/byte_container_with_subtype__operator_ne.output"
+    ```
+
+## Version history
+
+- 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.
@@ -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.
@@ -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.
@@ -53,7 +53,6 @@ header. See also the [macro overview page](../../features/macros.md).

 - [**JSON_BRACE_INIT_COPY_SEMANTICS**](json_brace_init_copy_semantics.md) - opt in to copy/move semantics for single-element brace initialization
 - [**JSON_DISABLE_ENUM_SERIALIZATION**](json_disable_enum_serialization.md) - switch off default serialization/deserialization functions for enums
- [**JSON_DISABLE_TUPLE_REFERENCE_CONVERSION**](json_disable_tuple_reference_conversion.md) - switch off conversion from a one-element tuple of a JSON reference
 - [**JSON_USE_IMPLICIT_CONVERSIONS**](json_use_implicit_conversions.md) - control implicit conversions

 ## Comparison behavior
@@ -1,114 +0,0 @@
-# JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
-
-```cpp
-#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION /* value */
-```
-
-When defined to `1`, a `basic_json` value can no longer be constructed from a one-element `std::tuple` whose element is
-a reference to that `basic_json` type, such as `std::tuple<json&>`, `std::tuple<const json&>`, or `std::tuple<json&&>`.
-These are the tuples created by `std::forward_as_tuple(j)`.
-
-## Default definition
-
-The default value is `0` (disabled — existing behavior is preserved).
-
-```cpp
-#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 0
-```
-
-## Notes
-
-!!! note "Background"
-
-    By default, `basic_json` can be constructed from any `std::tuple` whose elements can be converted to JSON; the result
-    is an array. This includes `std::tuple<json&>`, which becomes a one-element array.
-
-    `std::tuple` only converts another tuple element by element if its element type cannot be constructed from the whole
-    source tuple. Because `json` *can* be constructed from `std::tuple<json&>`, `std::tuple` instead converts the whole
-    tuple into a single `json` value. This has two surprising effects:
-
-    ```cpp
-    json j = true;
-
-    // rejected by some standard libraries (e.g., libc++); with others, the
-    // reference binds to a temporary that is destroyed right away
-    std::tuple<const json&> t1(std::forward_as_tuple(j));
-
-    // compiles, but std::get<0>(t2) is [true], not true
-    std::tuple<json> t2(std::forward_as_tuple(j));
-    ```
-
-    Enabling this macro removes the conversion, so both tuples are converted element by element: `std::get<0>(t1)`
-    refers to `j`, and `std::get<0>(t2)` is a copy of `j` (see [#2226](https://github.com/nlohmann/json/issues/2226)).
-
-!!! warning "Opt-in only"
-
-    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
-
-!!! note "Affected conversions"
-
-    Only one-element tuples holding a reference to the **same** `basic_json` type are affected. Constructing a JSON value
-    from them no longer compiles:
-
-    ```cpp
-    json j = true;
-    json a = std::forward_as_tuple(j);  // error with the macro enabled
-    json b = json::array({j});          // use this instead: [true]
-    ```
-
-    Tuples holding a JSON value (`std::make_tuple(j)`), tuples with more than one element, and tuples holding references
-    to other types (including other `basic_json` specializations) are converted to arrays as before.
-
-!!! hint "CMake option"
-
-    This behavior can also be controlled with the CMake option
-    [`JSON_DisableTupleReferenceConversion`](../../integration/cmake.md#json_disabletuplereferenceconversion)
-    (`OFF` by default) which defines `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION` accordingly.
-
-## Examples
-
-??? example "Default behavior (macro not defined)"
-
-    ```cpp
-    #include <nlohmann/json.hpp>
-
-    using json = nlohmann::json;
-
-    int main()
-    {
-        json j = true;
-
-        std::tuple<json> t(std::forward_as_tuple(j));
-        // std::get<0>(t) is [true] -- the whole tuple was converted
-    }
-    ```
-
-??? example "Conversion disabled (macro defined to 1)"
-
-    ```cpp
-    #define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
-    #include <nlohmann/json.hpp>
-
-    using json = nlohmann::json;
-
-    int main()
-    {
-        json j = true;
-
-        std::tuple<json> t(std::forward_as_tuple(j));
-        // std::get<0>(t) is true -- a copy of j
-
-        std::tuple<const json&> r(std::forward_as_tuple(j));
-        // std::get<0>(r) refers to j
-    }
-    ```
-
-## See also
-
- [**basic_json(CompatibleType&&)**](../basic_json/basic_json.md) - the affected constructor
- [:simple-cmake: JSON_DisableTupleReferenceConversion](../../integration/cmake.md#json_disabletuplereferenceconversion) -
-  CMake option to control the macro
-
-## Version history
-
- Added in version 3.13.0.
@@ -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,7 +37,7 @@ 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
@@ -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)
- (destructor)
- **emplace**
- **operator\[\]**
- **at**
- **erase**
- **count**
- **find**
- **insert**
+- [(constructor)](ordered_map.md)
+- [(destructor)](~ordered_map.md)
+- [**operator=**](operator=.md)
+- [**emplace**](emplace.md)
+- [**operator\[\]**](operator[].md)
+- [**at**](at.md)
+- [**erase**](erase.md)
+- [**count**](count.md)
+- [**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
    [`tsl::ordered_map`](https://github.com/Tessil/ordered-map)
    ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)), 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).
@@ -0,0 +1,34 @@
+# <small>nlohmann::ordered_map::</small>key_compare
+
+```cpp
+using key_compare = std::equal_to<Key>;  // until C++14
+
+using key_compare = std::equal_to<>;     // since C++14
+```
+
+The comparator used to determine key equality when looking up elements. Unlike `std::map`, `ordered_map`
+uses linear search with `key_compare` rather than an ordering relation, since element order reflects
+insertion order rather than key order.
+
+Since C++14, the transparent `#!cpp std::equal_to<>` is used, which enables heterogeneous lookup (e.g.
+looking up by a `#!cpp const char*` key without constructing a temporary `Key`).
+
+## Examples
+
+??? example
+
+    The example shows how `key_compare` is used.
+
+    ```cpp
+    --8<-- "examples/ordered_map__key_compare.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/ordered_map__key_compare.output"
+    ```
+
+## Version history
+
+- Added in version 3.11.0.
@@ -0,0 +1,32 @@
+# <small>nlohmann::ordered_map::</small>operator=
+
+```cpp
+// (1)
+ordered_map& operator=(const ordered_map& other);
+
+// (2)
+ordered_map& operator=(ordered_map&& other) noexcept(std::is_nothrow_move_assignable<Container>::value);
+```
+
+1. Copy assignment operator.
+2. Move assignment operator.
+
+## Parameters
+
+`other` (in)
+:   value to assign from
+
+## Return value
+
+`*this`
+
+## Complexity
+
+1. Linear in the size of `other`.
+2. Constant.
+
+<!-- NOLINT Examples -->
+
+## Version history
+
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -0,0 +1,62 @@
+# <small>nlohmann::ordered_map::</small>operator[]
+
+```cpp
+// (1)
+T& operator[](const key_type& key);
+const T& operator[](const key_type& key) const;
+
+// (2)
+template<class KeyType>
+T& operator[](KeyType&& key);
+template<class KeyType>
+const T& operator[](KeyType&& key) const;
+```
+
+1. Returns a reference to the value mapped to `key`, inserting a default-constructed `T` (non-`const`
+   overload only) if no such element exists yet.
+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 or insert
+
+## Return value
+
+reference to the mapped value of the element with key equal to `key`
+
+## Exceptions
+
+The `const` overloads throw `std::out_of_range` if no element with key `key` exists (they delegate to
+[`at`](at.md)).
+
+## Complexity
+
+Linear in the number of elements.
+
+## Examples
+
+??? example
+
+    The example shows how `operator[]` is used.
+
+    ```cpp
+    --8<-- "examples/ordered_map__operator_idx.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/ordered_map__operator_idx.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,66 @@
+# <small>nlohmann::ordered_map::</small>ordered_map
+
+```cpp
+// (1)
+ordered_map() noexcept(noexcept(Container()));
+
+// (2)
+explicit ordered_map(const Allocator& alloc) noexcept(noexcept(Container(alloc)));
+
+// (3)
+template <class It>
+ordered_map(It first, It last, const Allocator& alloc = Allocator());
+
+// (4)
+ordered_map(std::initializer_list<value_type> init, const Allocator& alloc = Allocator());
+
+// (5)
+ordered_map(const ordered_map&) = default;
+
+// (6)
+ordered_map(ordered_map&&) noexcept(std::is_nothrow_move_constructible<Container>::value) = default;
+```
+
+1. Default constructor. Creates an empty `ordered_map`.
+2. Creates an empty `ordered_map` using the given allocator.
+3. Creates an `ordered_map` from the elements in range `[first, last)`, inserted in iteration order.
+4. Creates an `ordered_map` from an initializer list of key/value pairs, inserted in list order.
+5. Copy constructor.
+6. Move constructor.
+
+These constructors are declared explicitly (rather than inherited via `#!cpp using Container::Container`)
+because older compilers (GCC <= 5.5, Xcode <= 9.4) do not handle the inherited constructors correctly.
+
+## Template parameters
+
+`It`
+:   an input iterator type
+
+## Parameters
+
+`alloc` (in)
+:   allocator to use for the underlying container
+
+`first` (in)
+:   iterator to the first element to insert
+
+`last` (in)
+:   iterator one past the last element to insert
+
+`init` (in)
+:   initializer list of key/value pairs to insert
+
+## Complexity
+
+1. Constant.
+2. Constant.
+3. Linear in the distance between `first` and `last`.
+4. Linear in the size of `init`.
+5. Linear in the size of `other`.
+6. Constant.
+
+<!-- NOLINT Examples -->
+
+## Version history
+
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -0,0 +1,17 @@
+# <small>nlohmann::ordered_map::</small>~ordered_map
+
+```cpp
+~ordered_map() = default;
+```
+
+Destroys the `ordered_map` and frees all allocated memory.
+
+## Complexity
+
+Linear in the number of elements.
+
+<!-- NOLINT Examples -->
+
+## Version history
+
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -90,7 +90,7 @@ Note: Some modern features (like C++20 ranges or filesystem support) may be disa
        | GNU 14.2.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
        | GNU 15.1.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
        | GNU 16.1.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
-        | GNU 16.1.0                                   | arm64        | Ubuntu 24.04                      | GitHub    |
+        | GNU 16.1.0                                   | arm64        | Linux 6.1.100                     | Cirrus CI |
        | icpc (ICC) 2021.10.0 20230609                | x86_64       | Ubuntu 22.04 LTS                  | GitHub    |
        | icpx (Intel oneAPI DPC++/C++) 2025.3.2       | x86_64       | Ubuntu 24.04 LTS                  | GitHub    |
        | nvc++ (NVIDIA HPC SDK) 25.5-0                | x86_64       | Ubuntu 22.04 LTS                  | GitHub    |
@@ -132,8 +132,7 @@ Note: Some modern features (like C++20 ranges or filesystem support) may be disa
  [libstdc++](https://gcc.gnu.org/onlinedocs/libstdc++/) to detect subtle differences or incompatibilities.
 - [x] The code checked with [Include What You Use (IWYU)](https://include-what-you-use.org) that all required standard
  headers are included.
- [x] On Windows, the library is compiled with `<Windows.h>` being included to detect and avoid common bugs (see
-  [`unit-windows_h.cpp`](https://github.com/nlohmann/json/blob/develop/tests/src/unit-windows_h.cpp)).
+- [x] On Windows, the library is compiled with `<Windows.h>` being included to detect and avoid common bugs.
 - [x] The library is compiled with exceptions disabled to support alternative means of error handling.

 ## Stable public API
@@ -0,0 +1,21 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // an empty binary value is encoded differently by the two drafts:
+    // draft2 omits the optimized type marker for an empty byte array,
+    // while draft3 always writes it
+    json j = json::binary({});
+
+    // encode using BJData draft2 (the default)
+    auto v_draft2 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft2);
+
+    // encode using BJData draft3
+    auto v_draft3 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft3);
+
+    std::cout << "draft2 size: " << v_draft2.size() << '\n'
+              << "draft3 size: " << v_draft3.size() << std::endl;
+}
@@ -0,0 +1,2 @@
+draft2 size: 4
+draft3 size: 6
@@ -0,0 +1,11 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<byte_container_with_subtype::container_type, std::vector<std::uint8_t>>::value
+              << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,15 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    byte_container_with_subtype c1({0xca, 0xfe});
+    byte_container_with_subtype c2({0xca, 0xfe});
+    byte_container_with_subtype c3({0xca, 0xfe}, 42);
+
+    std::cout << std::boolalpha
+              << "c1 == c2: " << (c1 == c2) << '\n'
+              << "c1 == c3: " << (c1 == c3) << std::endl;
+}
@@ -0,0 +1,2 @@
+c1 == c2: true
+c1 == c3: false
@@ -0,0 +1,15 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    byte_container_with_subtype c1({0xca, 0xfe});
+    byte_container_with_subtype c2({0xca, 0xfe});
+    byte_container_with_subtype c3({0xca, 0xfe}, 42);
+
+    std::cout << std::boolalpha
+              << "c1 != c2: " << (c1 != c2) << '\n'
+              << "c1 != c3: " << (c1 != c3) << std::endl;
+}
@@ -0,0 +1,2 @@
+c1 != c2: false
+c1 != c3: true
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<byte_container_with_subtype::subtype_type, std::uint64_t>::value << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,13 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // an initializer_list_t is what a braced-init-list of JSON values is deduced as
+    json::initializer_list_t init = {"a", 1, 2.0, false};
+
+    json j(init);
+    std::cout << j.dump() << std::endl;
+}
@@ -0,0 +1 @@
+["a",1,2.0,false]
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<json::json_sax_t::binary_t, json::binary_t>::value << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<json::json_sax_t::number_float_t, json::number_float_t>::value << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<json::json_sax_t::number_integer_t, json::number_integer_t>::value << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<json::json_sax_t::number_unsigned_t, json::number_unsigned_t>::value << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<json::json_sax_t::string_t, json::string_t>::value << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << std::is_same<json::json_sax_t, nlohmann::json_sax<json>>::value << std::endl;
+}
@@ -0,0 +1 @@
+true
@@ -0,0 +1,12 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    using Map = nlohmann::ordered_map<std::string, int>;
+
+    std::cout << std::boolalpha
+              << "Container is std::vector<std::pair<const Key, T>>: "
+              << std::is_same<Map::Container, std::vector<std::pair<const std::string, int>>>::value
+              << std::endl;
+}
@@ -0,0 +1 @@
+Container is std::vector<std::pair<const Key, T>>: true
@@ -0,0 +1,26 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    nlohmann::ordered_map<std::string, int> m;
+    m["one"] = 1;
+    m["two"] = 2;
+
+    // access an existing element
+    std::cout << "m.at(\"one\") = " << m.at("one") << std::endl;
+
+    // modify through the reference returned by at()
+    m.at("two") = 22;
+    std::cout << "m.at(\"two\") = " << m.at("two") << std::endl;
+
+    // accessing a missing key throws
+    try
+    {
+        m.at("three");
+    }
+    catch (const std::out_of_range& e)
+    {
+        std::cout << "exception: " << e.what() << std::endl;
+    }
+}
@@ -0,0 +1,3 @@
+m.at("one") = 1
+m.at("two") = 22
+exception: key not found
@@ -0,0 +1,12 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    nlohmann::ordered_map<std::string, int> m;
+    m["one"] = 1;
+
+    std::cout << std::boolalpha
+              << "m.count(\"one\") = " << m.count("one") << '\n'
+              << "m.count(\"two\") = " << m.count("two") << std::endl;
+}
@@ -0,0 +1,2 @@
+m.count("one") = 1
+m.count("two") = 0
@@ -0,0 +1,15 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    nlohmann::ordered_map<std::string, std::string> m;
+
+    // emplace a new element
+    auto res1 = m.emplace("one", "eins");
+    std::cout << std::boolalpha << "inserted: " << res1.second << ", value: " << res1.first->second << std::endl;
+
+    // emplace with an already-existing key: no-op, returns the existing element
+    auto res2 = m.emplace("one", "uno");
+    std::cout << std::boolalpha << "inserted: " << res2.second << ", value: " << res2.first->second << std::endl;
+}
@@ -0,0 +1,2 @@
+inserted: true, value: eins
+inserted: false, value: eins
@@ -0,0 +1,24 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    nlohmann::ordered_map<std::string, int> m;
+    m["one"] = 1;
+    m["two"] = 2;
+    m["three"] = 3;
+
+    // erase by key
+    std::size_t removed = m.erase("two");
+    std::cout << "removed by key: " << removed << std::endl;
+
+    // erase by iterator
+    m.erase(m.begin());
+
+    std::cout << "remaining: ";
+    for (const auto& element : m)
+    {
+        std::cout << element.first << ' ';
+    }
+    std::cout << std::endl;
+}
@@ -0,0 +1,2 @@
+removed by key: 1
+remaining: three 
@@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    nlohmann::ordered_map<std::string, int> m;
+    m["one"] = 1;
+
+    auto it = m.find("one");
+    if (it != m.end())
+    {
+        std::cout << "found: " << it->first << " = " << it->second << std::endl;
+    }
+
+    if (m.find("two") == m.end())
+    {
+        std::cout << "\"two\" not found" << std::endl;
+    }
+}
@@ -0,0 +1,2 @@
+found: one = 1
+"two" not found
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
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
				`@@ -0,0 +1 @@`
				`Container is std::vector<std::pair<const Key, T>>: true`