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

- ordered_map.hpp: develop's refactored members, with this branch's @sa links on every public member - byte_container_with_subtype operator==/!= and ordered_map docs: develop's reviewed text (#5638); drop the now unreferenced examples - basic_json.md: keep both version-history additions - add the docset entries that develop's style check now requires for the 25 API pages this branch adds - regenerate tools/api_checker/api_surface.json for develop's API Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-07 06:57:14 +00:00 · 2026-10-04 17:35:55 +02: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
179 changed files with 72857 additions and 32971 deletions
@@ -16,9 +16,6 @@ only_commits:
 environment:
  matrix:
    # The Visual Studio 2017 jobs compile everything with /std:c++17, so they
    # only build the C++17 variant of each test, split into two jobs each to
    # stay below AppVeyor's 60-minute limit per job.
    - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015
      configuration: Debug
      platform: x86
@@ -37,13 +34,7 @@ environment:
      configuration: Release
      platform: x86
      CXX_FLAGS: "/permissive- /std:c++17 /utf-8 /W4 /WX"
-      CMAKE_OPTIONS: "-DJSON_TestStandards=17 -DJSON_TestShard=0/2"
+      CMAKE_OPTIONS: ""
      GENERATOR: Visual Studio 15 2017
    - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
      configuration: Release
      platform: x86
      CXX_FLAGS: "/permissive- /std:c++17 /utf-8 /W4 /WX"
      CMAKE_OPTIONS: "-DJSON_TestStandards=17 -DJSON_TestShard=1/2"
      GENERATOR: Visual Studio 15 2017
    - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
@@ -64,13 +55,7 @@ environment:
      configuration: Release
      platform: x64
      CXX_FLAGS: "/permissive- /std:c++17 /Zc:__cplusplus /utf-8 /W4 /WX"
-      CMAKE_OPTIONS: "-DJSON_TestStandards=17 -DJSON_TestShard=0/2"
+      CMAKE_OPTIONS: ""
      GENERATOR: Visual Studio 15 2017
    - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
      configuration: Release
      platform: x64
      CXX_FLAGS: "/permissive- /std:c++17 /Zc:__cplusplus /utf-8 /W4 /WX"
      CMAKE_OPTIONS: "-DJSON_TestStandards=17 -DJSON_TestShard=1/2"
      GENERATOR: Visual Studio 15 2017
 init:
@@ -81,7 +66,7 @@ install:
  - if "%platform%"=="x86"    set GENERATOR_PLATFORM=Win32
 before_build:
-  - 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%
+  - 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:
  - cmake --build . --config "%configuration%" --parallel 2
@@ -149,13 +149,6 @@ jobs:
          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]\+')
          # The template is what this check verifies the committed natvis
          # file against, so take it from this PR rather than from the
          # develop checkout: generate_natvis.py loads the template from its
          # own directory, and with develop's copy a PR that changes the
          # template could never pass. Like the macro_builder step above,
          # this only renders PR content in a job without credentials.
          cp tools/generate_natvis/nlohmann_json.natvis.j2 $NATVIS_TOOL_DIR/
          python3 $NATVIS_TOOL_DIR/generate_natvis.py --version "$VERSION_MAJOR.$VERSION_MINOR.$VERSION_PATCH" $MAIN_DIR
      - name: Build patch and check for differences
@@ -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
@@ -107,7 +107,7 @@ jobs:
    container: ubuntu:24.04
    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_delete_deprecated_functions, 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_disabletuplereferenceconversion, 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
@@ -3,6 +3,7 @@
 *.gcno
 *.gcda
 .DS_Store
 __pycache__/
 /.idea
 /cmake-build-*
@@ -45,5 +46,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
@@ -62,7 +62,6 @@ option(JSON_MultipleHeaders                "Use non-amalgamated version of the l
 option(JSON_SystemInclude                  "Include as system headers (skip for clang-tidy)." OFF)
 option(JSON_StrictNulHandling              "Build with strict NUL-byte handling enabled." OFF)
 option(JSON_StrictBinaryUTF8               "Build with UTF-8 checks in the CBOR, UBJSON, BJData, and BSON writers enabled." OFF)
 option(JSON_DeleteDeprecatedFunctions      "Delete the deprecated functions instead of only deprecating them." OFF)
 if (JSON_CI)
    include(ci)
@@ -124,10 +123,6 @@ if (JSON_StrictBinaryUTF8)
    message(STATUS "Strict UTF-8 checks in binary writers enabled (JSON_STRICT_BINARY_UTF8=1)")
 endif()
 if (JSON_DeleteDeprecatedFunctions)
    message(STATUS "Deprecated functions are deleted (JSON_DELETE_DEPRECATED_FUNCTIONS=1)")
 endif()
 if (JSON_Diagnostic_Positions)
    message(STATUS "Diagnostic positions enabled (JSON_DIAGNOSTIC_POSITIONS=1)")
 endif()
@@ -164,7 +159,6 @@ target_compile_definitions(
    $<$<BOOL:${JSON_LegacyDiscardedValueComparison}>:JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1>
    $<$<BOOL:${JSON_StrictNulHandling}>:JSON_STRICT_NUL_HANDLING=1>
    $<$<BOOL:${JSON_StrictBinaryUTF8}>:JSON_STRICT_BINARY_UTF8=1>
    $<$<BOOL:${JSON_DeleteDeprecatedFunctions}>:JSON_DELETE_DEPRECATED_FUNCTIONS=1>
 )
 target_include_directories(
@@ -104,7 +104,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.
@@ -249,20 +249,6 @@ add_custom_target(ci_test_strict_nul_handling
    COMMENT "Compile and test with strict NUL-byte handling enabled"
 )
 ###############################################################################
 # Delete the deprecated functions.
 ###############################################################################
 add_custom_target(ci_test_delete_deprecated_functions
    COMMAND ${CMAKE_COMMAND}
    -DCMAKE_BUILD_TYPE=Debug -GNinja
    -DJSON_BuildTests=ON -DJSON_FastTests=ON -DJSON_DeleteDeprecatedFunctions=ON
    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_delete_deprecated_functions
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_delete_deprecated_functions
    COMMAND cd ${PROJECT_BINARY_DIR}/build_delete_deprecated_functions && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
    COMMENT "Compile and test with the deprecated functions deleted"
 )
 ###############################################################################
 # Disable global UDLs.
 ###############################################################################
@@ -376,7 +362,7 @@ add_custom_target(ci_test_coverage
 # Sanitizers.
 ###############################################################################
-set(CLANG_CXX_FLAGS_SANITIZER "-g -O1 -fsanitize=address -fsanitize=undefined -fsanitize=integer -fsanitize=nullability -fno-omit-frame-pointer -fno-sanitize-recover=all -fno-sanitize=unsigned-integer-overflow -fno-sanitize=unsigned-shift-base -fsanitize-ignorelist=${PROJECT_SOURCE_DIR}/cmake/clang_sanitizer_ignorelist.txt")
+set(CLANG_CXX_FLAGS_SANITIZER "-g -O1 -fsanitize=address -fsanitize=undefined -fsanitize=integer -fsanitize=nullability -fno-omit-frame-pointer -fno-sanitize-recover=all -fno-sanitize=unsigned-integer-overflow -fno-sanitize=unsigned-shift-base")
 add_custom_target(ci_test_clang_sanitizer
    COMMAND CXX=${CLANG_TOOL} CXXFLAGS=${CLANG_CXX_FLAGS_SANITIZER} ${CMAKE_COMMAND}
@@ -719,7 +705,7 @@ 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 JSON_StrictBinaryUTF8 JSON_DeleteDeprecatedFunctions)
+    JSON_StrictNulHandling JSON_StrictBinaryUTF8)
 set(JSON_CMAKE_FLAGS_3_31_6 JSON_BuildTests ${JSON_CMAKE_FLAGS_3_5_0})
 set(JSON_CMAKE_FLAGS_4_0_0 JSON_BuildTests ${JSON_CMAKE_FLAGS_3_5_0})
@@ -1,8 +0,0 @@
 # Sanitizer ignore list for ci_test_clang_sanitizer (-fsanitize-ignorelist).
 #
 # libstdc++ 14's <format> declares `_Scanner(basic_string_view<_CharT>, size_t __nargs = -1)`, so every std::format
 # call converts -1 to size_t, which -fsanitize=integer reports as implicit-integer-sign-change. This is
 # https://gcc.gnu.org/bugzilla/show_bug.cgi?id=119429, not a bug in this library. Only that check and only <format> are
 # excluded, so implicit sign changes in the library and the tests are still reported.
 [implicit-integer-sign-change]
 src:*/include/c++/*/format
@@ -9,11 +9,13 @@ INSERT INTO searchIndex(name, type, path) VALUES ('adl_serializer::to_json', 'Fu
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype', 'Class', 'api/byte_container_with_subtype/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::byte_container_with_subtype', 'Constructor', 'api/byte_container_with_subtype/byte_container_with_subtype/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::clear_subtype', 'Method', 'api/byte_container_with_subtype/clear_subtype/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::container_type', 'Type', 'api/byte_container_with_subtype/container_type/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::has_subtype', 'Method', 'api/byte_container_with_subtype/has_subtype/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::operator!=', 'Operator', 'api/byte_container_with_subtype/operator_ne/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::operator==', 'Operator', 'api/byte_container_with_subtype/operator_eq/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::set_subtype', 'Method', 'api/byte_container_with_subtype/set_subtype/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::subtype', 'Method', 'api/byte_container_with_subtype/subtype/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('byte_container_with_subtype::subtype_type', 'Type', 'api/byte_container_with_subtype/subtype_type/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/basic_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('format_as', 'Function', 'api/basic_json/format_as/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::accept', 'Function', 'api/basic_json/accept/index.html');
@@ -26,6 +28,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::basic_json', 'Con
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::begin', 'Method', 'api/basic_json/begin/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::binary', 'Function', 'api/basic_json/binary/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::binary_t', 'Type', 'api/basic_json/binary_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::bjdata_version_t', 'Enum', 'api/basic_json/bjdata_version_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::boolean_t', 'Type', 'api/basic_json/boolean_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::cbegin', 'Method', 'api/basic_json/cbegin/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::cbor_tag_handler_t', 'Enum', 'api/basic_json/cbor_tag_handler_t/index.html');
@@ -61,6 +64,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::get_binary', 'Met
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::get_ptr', 'Method', 'api/basic_json/get_ptr/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::get_ref', 'Method', 'api/basic_json/get_ref/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::get_to', 'Method', 'api/basic_json/get_to/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::initializer_list_t', 'Type', 'api/basic_json/initializer_list_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::input_format_t', 'Enum', 'api/basic_json/input_format_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::insert', 'Method', 'api/basic_json/insert/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::invalid_iterator', 'Class', 'api/basic_json/invalid_iterator/index.html');
@@ -79,6 +83,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::is_string', 'Meth
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::is_structured', 'Method', 'api/basic_json/is_structured/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::items', 'Method', 'api/basic_json/items/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::json_base_class_t', 'Type', 'api/basic_json/json_base_class_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::json_sax_t', 'Type', 'api/basic_json/json_sax_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::json_serializer', 'Class', 'api/basic_json/json_serializer/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::max_size', 'Method', 'api/basic_json/max_size/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::merge_patch', 'Method', 'api/basic_json/merge_patch/index.html');
@@ -153,24 +158,44 @@ INSERT INTO searchIndex(name, type, path) VALUES ('json_pointer::string_t', 'Typ
 INSERT INTO searchIndex(name, type, path) VALUES ('json_pointer::to_string', 'Method', 'api/json_pointer/to_string/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax', 'Class', 'api/json_sax/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::binary', 'Method', 'api/json_sax/binary/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::binary_t', 'Type', 'api/json_sax/binary_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::boolean', 'Method', 'api/json_sax/boolean/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::end_array', 'Method', 'api/json_sax/end_array/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::end_object', 'Method', 'api/json_sax/end_object/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::json_sax', 'Constructor', 'api/json_sax/json_sax/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::key', 'Method', 'api/json_sax/key/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::null', 'Method', 'api/json_sax/null/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::number_float', 'Method', 'api/json_sax/number_float/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::number_float_t', 'Type', 'api/json_sax/number_float_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::number_integer', 'Method', 'api/json_sax/number_integer/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::number_integer_t', 'Type', 'api/json_sax/number_integer_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::number_unsigned', 'Method', 'api/json_sax/number_unsigned/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::number_unsigned_t', 'Type', 'api/json_sax/number_unsigned_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::operator=', 'Operator', 'api/json_sax/operator=/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::parse_error', 'Method', 'api/json_sax/parse_error/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::start_array', 'Method', 'api/json_sax/start_array/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::start_object', 'Method', 'api/json_sax/start_object/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::string', 'Method', 'api/json_sax/string/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::string_t', 'Type', 'api/json_sax/string_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::~json_sax', 'Method', 'api/json_sax/~json_sax/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json', 'Literal', 'api/operator_literal_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json_pointer', 'Literal', 'api/operator_literal_json_pointer/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator<<', 'Operator', 'api/operator_ltlt/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator>>', 'Operator', 'api/operator_gtgt/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_json', 'Class', 'api/ordered_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map', 'Class', 'api/ordered_map/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::Container', 'Type', 'api/ordered_map/Container/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::at', 'Method', 'api/ordered_map/at/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::count', 'Method', 'api/ordered_map/count/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::emplace', 'Method', 'api/ordered_map/emplace/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::erase', 'Method', 'api/ordered_map/erase/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::find', 'Method', 'api/ordered_map/find/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::insert', 'Method', 'api/ordered_map/insert/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::key_compare', 'Type', 'api/ordered_map/key_compare/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::operator=', 'Operator', 'api/ordered_map/operator=/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::operator[]', 'Operator', 'api/ordered_map/operator[]/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::ordered_map', 'Constructor', 'api/ordered_map/ordered_map/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map::~ordered_map', 'Method', 'api/ordered_map/~ordered_map/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('std::formatter<basic_json>', 'Class', 'api/basic_json/std_formatter/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('std::hash<basic_json>', 'Class', 'api/basic_json/std_hash/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('std::swap<basic_json>', 'Function', 'api/basic_json/std_swap/index.html');
@@ -219,7 +244,6 @@ INSERT INTO searchIndex(name, type, path) VALUES ('Supported Macros', 'Guide', '
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_ASSERT', 'Macro', 'api/macros/json_assert/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_BRACE_INIT_COPY_SEMANTICS', 'Macro', 'api/macros/json_brace_init_copy_semantics/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_CATCH_USER', 'Macro', 'api/macros/json_throw_user/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DELETE_DEPRECATED_FUNCTIONS', 'Macro', 'api/macros/json_delete_deprecated_functions/index.html');
 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');
@@ -250,7 +274,6 @@ INSERT INTO searchIndex(name, type, path) VALUES ('JSON_TRY_USER', 'Macro', 'api
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_GLOBAL_UDLS', 'Macro', 'api/macros/json_use_global_udls/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_IMPLICIT_CONVERSIONS', 'Macro', 'api/macros/json_use_implicit_conversions/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON', 'Macro', 'api/macros/json_use_legacy_discarded_value_comparison/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS', 'Macro', 'api/macros/json_use_objects_for_enum_keyed_maps/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_SIMDUTF', 'Macro', 'api/macros/json_use_simdutf/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('Macros', 'Macro', 'api/macros/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE', 'Macro', 'api/macros/nlohmann_define_derived_type/index.html');
@@ -475,8 +475,10 @@ 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. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
+4. Since version 3.2.0. Also initializes the position reported by
-   version 3.13.0.
+   [`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) from `val` when
   [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is enabled, since version 3.12.0. Explicit
   for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.0.
 5. Since version 1.0.0.
 6. Since version 1.0.0.
 7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
@@ -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.
@@ -8,7 +8,7 @@ static basic_json diff(const basic_json& source,
 Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling
 [`patch`](patch.md) function.
-For two JSON values `source` and `target`, the following code always yields `#!cpp true`:
+For two JSON values `source` and `target`, the following code yields always `#!cpp true`:
 ```cpp
 source.patch(diff(source, target)) == target;
 ```
@@ -27,7 +27,7 @@ a JSON patch to convert the `source` to `target`
 ## Exception safety
-Strong guarantee: `source` and `target` are never modified.
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 ## Complexity
@@ -120,12 +120,3 @@ Linear in the size of the input.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
 - Added `error_handler` parameter in version 3.13.0.
 !!! warning "Deprecation"
    - Overload (2) replaces calls to `from_bjdata` with a pointer and a length as first two parameters, which has been
      deprecated in version 3.13.0. This overload will be removed in version 4.0.0. Please replace all calls like
      `#!cpp from_bjdata(ptr, len, ...);` with `#!cpp from_bjdata(ptr, ptr+len, ...);`.
    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
    function.
@@ -106,12 +106,3 @@ Linear in the size of the input.
 ## Version history
 - Added in version 3.13.0.
 !!! warning "Deprecation"
    - Overload (2) replaces calls to `from_bon8` with a pointer and a length as first two parameters, which has been
      deprecated in version 3.13.0. This overload will be removed in version 4.0.0. Please replace all calls like
      `#!cpp from_bon8(ptr, len, ...);` with `#!cpp from_bon8(ptr, ptr+len, ...);`.
    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
    function.
@@ -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.
@@ -55,10 +55,6 @@ This implementation does exactly follow this approach, as it uses double precisi
 smaller than `-1.79769313486232e+308` and values greater than `1.79769313486232e+308` will be stored as NaN internally
 and be serialized to `null`.
 During deserialization (from JSON text or any of the binary formats), a finite number that does not fit into
 `number_float_t` is rejected with [`out_of_range.406`](../../home/exceptions.md#jsonexceptionout_of_range406), for
 example a double-precision number in a binary format when `number_float_t` is `#!cpp float`.
 ### Storage
 Floating-point number values are stored directly inside a `basic_json` type.
@@ -47,9 +47,8 @@ With the default values for `NumberIntegerType` (`std::int64_t`), the default va
 When the default type is used, the maximal integer number that can be stored is `9223372036854775807` (INT64_MAX) and
 the minimal integer number that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers that are out of
-range will yield over/underflow when used in a constructor. During deserialization (from JSON text or any of the binary
+range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers
-formats), too large or small integer numbers will automatically be stored as [`number_unsigned_t`](number_unsigned_t.md)
+will automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_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
@@ -48,9 +48,8 @@ With the default values for `NumberUnsignedType` (`std::uint64_t`), the default
 When the default type is used, the maximal integer number that can be stored is `18446744073709551615` (UINT64_MAX) and
 the minimal integer number that can be stored is `0`. Integer numbers that are out of range will yield over/underflow
-when used in a constructor. During deserialization (from JSON text or any of the binary formats), too large or small
+when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored
-integer numbers will automatically be stored as [`number_integer_t`](number_integer_t.md) or
+as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).
 [`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
@@ -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.
@@ -92,3 +92,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)).
@@ -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,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.
@@ -58,13 +58,6 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**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
 - [**JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS**](json_use_objects_for_enum_keyed_maps.md) - opt in to storing maps with enum
  keys as objects
 ## Deprecated functions
 - [**JSON_DELETE_DEPRECATED_FUNCTIONS**](json_delete_deprecated_functions.md) - opt in to deleting the deprecated
  functions ahead of their removal in version 4.0.0
 ## Comparison behavior
@@ -1,96 +0,0 @@
 # JSON_DELETE_DEPRECATED_FUNCTIONS
 ```cpp
 #define JSON_DELETE_DEPRECATED_FUNCTIONS /* value */
 ```
 When defined to `1`, all [deprecated functions](../../community/roadmap.md#removal-of-deprecated-functions) of the
 library are declared as deleted (`= delete`) instead of only being marked as deprecated. Code that still calls one of
 them no longer compiles. This way, you can find all calls that need to be replaced before version 4.0.0 removes these
 functions; the [migration guide](../../integration/migration_guide.md#replace-deprecated-functions) describes how.
 A deleted function, unlike a removed one, still takes part in overload resolution. A call that would select it
 therefore fails to compile instead of silently selecting another overload. This matters for the deprecated
 `from_*(ptr, len)` overloads of [`from_cbor`](../basic_json/from_cbor.md), [`from_msgpack`](../basic_json/from_msgpack.md),
 [`from_ubjson`](../basic_json/from_ubjson.md), [`from_bjdata`](../basic_json/from_bjdata.md),
 [`from_bon8`](../basic_json/from_bon8.md), and [`from_bson`](../basic_json/from_bson.md): without them, a call like
 `from_cbor(ptr, len)` would compile, read `ptr` as a NUL-terminated string, and convert `len` to the `strict` parameter.
 The macro does not affect the deprecated legacy comparison of discarded values, which is controlled by
 [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md).
 ## Default definition
 The default value is `0` (disabled, the deprecated functions can still be called, and the compiler warns about it).
 ```cpp
 #define JSON_DELETE_DEPRECATED_FUNCTIONS 0
 ```
 ## Notes
 !!! info "CMake option"
    The macro can also be set with the CMake option
    [`JSON_DeleteDeprecatedFunctions`](../../integration/cmake.md#json_deletedeprecatedfunctions) (`OFF` by default).
 !!! warning "Opt-in only"
    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
    effect. Define it for the whole project to avoid different declarations of the same class in different
    translation units.
 !!! note "ABI compatibility"
    The macro only turns calls that compile into calls that do not; it does not change the layout or the behavior of
    any type. Its value is therefore not encoded in the [namespace](../../features/namespace.md).
 ## Examples
 ??? example "Example: default behavior (macro not defined)"
    Without the macro, the deprecated overload is called, and the compiler warns about it:
    ```cpp
    #include <nlohmann/json.hpp>
    using json = nlohmann::json;
    int main()
    {
        const std::vector<std::uint8_t> v = {0x82, 0x01, 0x02};
        auto j = json::from_cbor(v.data(), v.size());
        // warning: 'from_cbor' is deprecated: Since 3.8.0; use from_cbor(ptr, ptr + len)
    }
    ```
 ??? example "Example: deleted deprecated functions (macro defined to 1)"
    With the macro, the call does not compile:
    ```cpp
    #define JSON_DELETE_DEPRECATED_FUNCTIONS 1
    #include <nlohmann/json.hpp>
    using json = nlohmann::json;
    int main()
    {
        const std::vector<std::uint8_t> v = {0x82, 0x01, 0x02};
        auto j = json::from_cbor(v.data(), v.size());
        // error: call to deleted function 'from_cbor'
    }
    ```
 ## See also
 - [Roadmap: removal of deprecated functions](../../community/roadmap.md#removal-of-deprecated-functions) - the
  deprecated functions and the version they were deprecated in
 - [Migration guide: replace deprecated functions](../../integration/migration_guide.md#replace-deprecated-functions) -
  how to replace each deprecated function
 ## Version history
 - Added in version 3.13.0.
 - Planned to be removed in version 4.0.0, which removes the deprecated functions. The deprecated `from_*(ptr, len)`
  overloads stay deleted in version 4.0.0.
@@ -112,4 +112,3 @@ The default value is `0` (disabled — existing behavior is preserved).
 ## Version history
 - Added in version 3.13.0.
 - Planned to become the default (with the macro removed) in version 4.0.0.
@@ -44,7 +44,7 @@ By default, implicit conversions are enabled.
 ## Examples
-??? example "Example: implicit and explicit conversions"
+??? example "Example: implicit conversion"
    This is an example for an implicit conversion:
@@ -1,139 +0,0 @@
 # JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
 ```cpp
 #define JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS /* value */
 ```
 When defined to `1`, maps whose keys are enums (such as `std::map<E, T>` or `std::unordered_map<E, T>`) are stored as
 JSON objects, using the enum's own conversion for the keys. By default, they are stored as arrays of `[key, value]`
 pairs.
 ## Default definition
 The default value is `0` (disabled — existing behavior is preserved).
 ```cpp
 #define JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS 0
 ```
 ## Notes
 !!! note "Background"
    JSON object keys are strings, so a map is only stored as an object if its keys can be converted to a string type.
    Enums are not, even if [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) maps them to strings, so a
    map with enum keys becomes an array of `[key, value]` pairs:
    ```json
    [["stopped", "aa"], ["completed", "bb"]]
    ```
    With this macro, the same map becomes an object
    (see [#4378](https://github.com/nlohmann/json/issues/4378)):
    ```json
    {"completed": "bb", "stopped": "aa"}
    ```
 !!! note "Maps with non-unique keys"
    Maps that allow duplicate keys, such as `std::multimap<E, T>` or `std::unordered_multimap<E, T>`, are not affected
    by the macro and are still stored as arrays of `[key, value]` pairs, as an object cannot hold duplicate keys.
 !!! note "Reading"
    Reading is not affected by the macro: a map with enum keys can always be read from both an array of pairs and an
    object. For the latter, each key is converted to the enum with its `from_json` function, e.g., the one defined by
    [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md). Data written without the macro can therefore
    still be read after enabling it.
 !!! warning "Keys must serialize to distinct strings"
    Each key is converted with the enum's `to_json` function. If a key is not converted to a string (for instance, an
    enum without [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md), which is stored as an integer, or an
    enumerator mapped to `nullptr`), [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) is thrown.
    If two keys are converted to the same string (for instance, because
    [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) maps an unlisted enumerator to the first entry),
    [`type_error.318`](../../home/exceptions.md#jsonexceptiontype_error318) is thrown. In both cases, the target value
    is not changed.
 !!! warning "Opt-in only"
    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
 !!! note "ABI compatibility"
    The value of this macro is encoded in the [namespace](../../features/namespace.md) (tag `_ekmo`), resulting in
    distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program
    without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.
 ## Examples
 ??? example "Example: default behavior (macro not defined)"
    Without the macro, a map with enum keys is stored as an array of pairs:
    ```cpp
    #include <map>
    #include <nlohmann/json.hpp>
    using json = nlohmann::json;
    enum TaskState { TS_STOPPED, TS_RUNNING, TS_COMPLETED };
    NLOHMANN_JSON_SERIALIZE_ENUM(TaskState, {
        {TS_STOPPED, "stopped"},
        {TS_RUNNING, "running"},
        {TS_COMPLETED, "completed"},
    })
    int main()
    {
        std::map<TaskState, std::string> m = {{TS_STOPPED, "aa"}, {TS_COMPLETED, "bb"}};
        json j = m;
        // j is [["stopped","aa"],["completed","bb"]]
    }
    ```
 ??? example "Example: objects for enum-keyed maps (macro defined to 1)"
    With the macro, the same map is stored as an object:
    ```cpp
    #define JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS 1
    #include <map>
    #include <nlohmann/json.hpp>
    using json = nlohmann::json;
    enum TaskState { TS_STOPPED, TS_RUNNING, TS_COMPLETED };
    NLOHMANN_JSON_SERIALIZE_ENUM(TaskState, {
        {TS_STOPPED, "stopped"},
        {TS_RUNNING, "running"},
        {TS_COMPLETED, "completed"},
    })
    int main()
    {
        std::map<TaskState, std::string> m = {{TS_STOPPED, "aa"}, {TS_COMPLETED, "bb"}};
        json j = m;
        // j is {"completed":"bb","stopped":"aa"}
        auto m2 = j.get<std::map<TaskState, std::string>>();
        // m2 == m
    }
    ```
 ## See also
 - [Specializing enum conversion](../../features/enum_conversion.md)
 - [**NLOHMANN_JSON_SERIALIZE_ENUM**](nlohmann_json_serialize_enum.md) - serialize/deserialize an enum
 - [**NLOHMANN_JSON_SERIALIZE_ENUM_STRICT**](nlohmann_json_serialize_enum_strict.md) - serialize/deserialize an enum with
  exceptions
 ## Version history
 - Added in version 3.13.0.
@@ -41,9 +41,6 @@ inline void from_json(const BasicJsonType& j, type& e);
      conversion. Select this default pair carefully. See example 1 below.
    - If an enum or JSON value is specified in multiple conversions, the first matching conversion from the top of the
      list will be returned when converting to or from JSON. See example 2 below.
    - Maps with enum keys (e.g., `std::map<ENUM_TYPE, T>`) are stored as arrays of `[key, value]` pairs by default.
      Define [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](json_use_objects_for_enum_keyed_maps.md) to store them as objects
      with the converted keys. Such maps can be read from both forms.
 ## Examples
@@ -83,7 +80,6 @@ inline void from_json(const BasicJsonType& j, type& e);
 - [Specializing enum conversion](../../features/enum_conversion.md)
 - [`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT`](./nlohmann_json_serialize_enum_strict.md)
 - [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)
 - [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](json_use_objects_for_enum_keyed_maps.md)
 ## Version history
@@ -44,9 +44,6 @@ inline void from_json(const BasicJsonType& j, type& e);
      `"enum value out of range for <type>"`.
    - If an enum or JSON value is specified in multiple conversions, the first matching conversion from the top of the
      list will be returned when converting to or from JSON. See example 2 below.
    - Maps with enum keys (e.g., `std::map<ENUM_TYPE, T>`) are stored as arrays of `[key, value]` pairs by default.
      Define [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](json_use_objects_for_enum_keyed_maps.md) to store them as objects
      with the converted keys. Such maps can be read from both forms.
 ## Examples
@@ -102,7 +99,6 @@ inline void from_json(const BasicJsonType& j, type& e);
 - [Specializing enum conversion](../../features/enum_conversion.md)
 - [`NLOHMANN_JSON_SERIALIZE_ENUM`](./nlohmann_json_serialize_enum.md)
 - [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)
 - [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](json_use_objects_for_enum_keyed_maps.md)
 ## Version history
@@ -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)
+- [(constructor)](ordered_map.md)
- (destructor)
+- [(destructor)](~ordered_map.md)
- **emplace**
+- [**operator=**](operator=.md)
- **operator\[\]**
+- [**emplace**](emplace.md)
- **at**
+- [**operator\[\]**](operator[].md)
- **erase**
+- [**at**](at.md)
- **count**
+- [**erase**](erase.md)
- **find**
+- [**count**](count.md)
- **insert**
+- [**find**](find.md)
 - [**insert**](insert.md)
 ## Exception safety
@@ -89,7 +90,7 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
 !!! warning "Quadratic cost of building large objects"
    Because every insertion scans all elements inserted so far, building an object of `n` distinct keys costs
-    **O(n²)** in total. This applies to filling an [`ordered_json`](ordered_json.md) object key by key as well as to
+    **O(n²)** in total. This applies to filling an [`ordered_json`](../ordered_json.md) object key by key as well as to
    parsing one, since the parser inserts each key as it is read.
    The cost is negligible for the object sizes typically found in configuration files or API payloads, but it grows
@@ -106,7 +107,7 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
    If key order matters for objects of that size, consider a container with a lookup index, such as
    [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map)
    ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)), as the object type -- see
-    [object order](../features/object_order.md).
+    [object order](../../features/object_order.md).
 ## Examples
@@ -126,10 +127,10 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
 ## See also
- [ordered_json](ordered_json.md)
+- [ordered_json](../ordered_json.md)
 ## Version history
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
 - Added **key_compare** member in version 3.11.0.
 - Changed in version 3.13.0: growing the storage moves the mapped values instead of copying them.
@@ -0,0 +1,63 @@
 # <small>nlohmann::ordered_map::</small>insert
 ```cpp
 // (1)
 std::pair<iterator, bool> insert(value_type&& value);
 std::pair<iterator, bool> insert(const value_type& value);
 // (2)
 template<typename InputIt>
 void insert(InputIt first, InputIt last);
 ```
 1. Inserts `value` if no element with an equal key already exists (per [`key_compare`](key_compare.md)),
   appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
 2. Inserts the elements from range `[first, last)`, in iteration order, applying the same equal-key rule
   as (1) to each element.
 ## Template parameters
 `InputIt`
 :   an input iterator type
 ## Parameters
 `value` (in)
 :   value to insert
 `first` (in)
 :   iterator to the first element to insert
 `last` (in)
 :   iterator one past the last element to insert
 ## Return value
 1. pair of an iterator to the (possibly newly inserted) element, and a `bool` that is `true` if insertion
   took place and `false` if an element with an equal key already existed
 2. (none)
 ## Complexity
 1. Linear in the number of elements.
 2. Linear in the distance between `first` and `last`, times linear in the number of elements.
 ## Examples
 ??? example
    The example shows how `insert` is used.
    ```cpp
    --8<-- "examples/ordered_map__insert.cpp"
    ```
    Output:
    ```
    --8<-- "examples/ordered_map__insert.output"
    ```
 ## Version history
 - Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -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).
@@ -64,8 +64,6 @@ The following macros guard changes that are planned to become the default in ver
 | [`JSON_PRECISE_STREAM_POSITION`](../api/macros/json_precise_stream_position.md)                                  | `0`         | `1`: reading from a stream does not consume the character after a number                                                      | –                                                                                                                  | 3.13.0 |
 | [`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md)                                          | `0`         | `1`: a NUL byte in the input is a parse error instead of the end of input                                                     | [`JSON_StrictNulHandling`](../integration/cmake.md#json_strictnulhandling)                                         | 3.13.0 |
 | [`JSON_STRICT_BINARY_UTF8`](../api/macros/json_strict_binary_utf8.md)                                            | `0`         | `1`: `to_cbor`, `to_ubjson`, `to_bjdata`, and `to_bson` throw for strings that are not valid UTF-8 by default                 | [`JSON_StrictBinaryUTF8`](../integration/cmake.md#json_strictbinaryutf8)                                           | 3.13.0 |
 | [`JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](../api/macros/json_disable_tuple_reference_conversion.md)            | `0`         | `1`: a `basic_json` value can no longer be created from a one-element tuple of a reference to it, such as `std::forward_as_tuple(j)`| [`JSON_DisableTupleReferenceConversion`](../integration/cmake.md#json_disabletuplereferenceconversion)             | 3.13.0 |
 | [`JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md)                          | `0`         | removed: the deprecated functions are removed (see below); the `from_*(ptr, len)` overloads stay deleted                      | [`JSON_DeleteDeprecatedFunctions`](../integration/cmake.md#json_deletedeprecatedfunctions)                         | 3.13.0 |
 For example, the following makes a 3.x release behave like version 4.0 with respect to these changes:
@@ -77,8 +75,6 @@ For example, the following makes a 3.x release behave like version 4.0 with resp
 #define JSON_PRECISE_STREAM_POSITION 1
 #define JSON_STRICT_NUL_HANDLING 1
 #define JSON_STRICT_BINARY_UTF8 1
 #define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
 #define JSON_DELETE_DEPRECATED_FUNCTIONS 1
 #include <nlohmann/json.hpp>
 ```
@@ -88,13 +84,8 @@ way to achieve this.
 ### Removal of deprecated functions
 Version 4.0 will remove all deprecated functions. Compiling with deprecation warnings enabled shows which of them your
-code still uses. Defining [`JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md) to
+code still uses. The [migration guide](../integration/migration_guide.md#replace-deprecated-functions) shows how to
-`1` turns these warnings into errors, as the deprecated functions are then deleted. The
+replace each of them.
 [migration guide](../integration/migration_guide.md#replace-deprecated-functions) shows how to replace each of them.
 The `from_*` overloads taking a pointer and a length are not removed in version 4.0, but stay deleted. Without them, a
 call like `from_cbor(ptr, len)` would still compile: it would read `ptr` as a NUL-terminated string and convert `len`
 to the `strict` parameter.
 | Deprecated                                                                                                                                                                                                                                         | Since  | Migration                                                                        |
 |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------------------------------------------------------------------------------|
@@ -106,7 +97,6 @@ to the `strict` parameter.
 | [`json_pointer::operator string_t`](../api/json_pointer/operator_string_t.md)                                                                                                                                                                      | 3.11.0 | [JSON Pointers](../integration/migration_guide.md#json-pointers)                 |
 | [`json_pointer`](../api/json_pointer/index.md) with a `basic_json` type as template argument, and the overloads of `value`, `contains`, `operator[]`, and `at` accepting such a pointer                                                           | 3.11.0 | [JSON Pointers](../integration/migration_guide.md#json-pointers)                 |
 | Comparing a [`json_pointer`](../api/json_pointer/index.md) with a string via [`operator==`](../api/json_pointer/operator_eq.md) or [`operator!=`](../api/json_pointer/operator_ne.md)                                                              | 3.11.2 | [JSON Pointers](../integration/migration_guide.md#json-pointers)                 |
 | [`from_bjdata`](../api/basic_json/from_bjdata.md) and [`from_bon8`](../api/basic_json/from_bon8.md) with `(ptr, len)`                                                                                                                              | 3.13.0 | [Parsing](../integration/migration_guide.md#parsing)                             |
 The deprecated legacy comparison of discarded values is controlled by a macro and therefore listed in the table above.
@@ -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,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
@@ -0,0 +1,21 @@
 #include <iostream>
 #include <nlohmann/json.hpp>
 int main()
 {
    nlohmann::ordered_map<std::string, int> m;
    // insert a single value
    auto res = m.insert({"one", 1});
    std::cout << std::boolalpha << "inserted: " << res.second << std::endl;
    // insert a range from another container
    std::vector<std::pair<const std::string, int>> more = {{"two", 2}, {"three", 3}};
    m.insert(more.begin(), more.end());
    for (const auto& element : m)
    {
        std::cout << element.first << ':' << element.second << ' ';
    }
    std::cout << std::endl;
 }
@@ -0,0 +1,2 @@
 inserted: true
 one:1 two:2 three:3 
@@ -0,0 +1,12 @@
 #include <iostream>
 #include <nlohmann/json.hpp>
 int main()
 {
    using Map = nlohmann::ordered_map<std::string, int>;
    Map::key_compare compare{};
    std::cout << std::boolalpha
              << "compare(\"a\", \"a\") = " << compare("a", "a") << '\n'
              << "compare(\"a\", \"b\") = " << compare("a", "b") << std::endl;
 }
@@ -0,0 +1,2 @@
 compare("a", "a") = true
 compare("a", "b") = false
@@ -0,0 +1,14 @@
 #include <iostream>
 #include <nlohmann/json.hpp>
 int main()
 {
    nlohmann::ordered_map<std::string, int> m;
    // operator[] inserts a default-constructed value if the key doesn't exist yet
    m["one"] = 1;
    std::cout << "m[\"one\"] = " << m["one"] << std::endl;
    // accessing again just returns the existing value
    std::cout << "m[\"one\"] = " << m["one"] << std::endl;
 }
@@ -0,0 +1,2 @@
 m["one"] = 1
 m["one"] = 1
@@ -168,9 +168,9 @@ The library maps CBOR types to JSON value types as follows:
 !!! warning "Negative integer overflow"
    CBOR negative integers (major type 1) are decoded as `-1 - n`. If the encoded magnitude `n` is too large for the
-    result to fit into `number_integer_t` (`std::int64_t` by default), the result is stored as `number_float_t`, like
+    result to fit into `number_integer_t` (`std::int64_t` by default), parsing fails with a
-    a too small integer in JSON text. For example, `-18446744073709551616` (`0x3B` followed by eight `0xFF` bytes) is
+    [`parse_error.112`](../../home/exceptions.md#jsonexceptionparse_error112) exception rather than overflowing
-    stored as `-1.8446744073709552e+19`.
+    silently.
 !!! warning "Object keys"
@@ -58,23 +58,6 @@ assert(jPi.get<TaskState>() == TS_INVALID );
    --8<-- "examples/nlohmann_json_serialize_enum.output"
    ```
 ## Maps with enum keys
 By default, maps with enum keys, such as `std::map<TaskState, std::string>`, are stored as arrays of `[key, value]`
 pairs, because JSON object keys must be strings. Define
 [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](../api/macros/json_use_objects_for_enum_keyed_maps.md) before including the
 library to store them as objects, with the keys converted by the enum's `to_json()` function:
 ```cpp
 std::map<TaskState, std::string> m = {{TS_STOPPED, "aa"}, {TS_COMPLETED, "bb"}};
 json j = m;
 // default:                                   [["stopped","aa"],["completed","bb"]]
 // with JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS: {"completed":"bb","stopped":"aa"}
 ```
 Either form can be read back, with or without the macro.
 ## Notes
 Just as in [Arbitrary Type Conversions](arbitrary_types.md) above,
@@ -23,17 +23,6 @@ This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/
 See [full documentation of `JSON_CATCH_USER(exception)`](../api/macros/json_throw_user.md).
 ## `JSON_DELETE_DEPRECATED_FUNCTIONS`
 When defined to `1`, all deprecated functions are declared as deleted instead of only being marked as deprecated, so
 code that still calls them no longer compiles. This way, you can find all calls that need to be replaced before version
 4.0.0 removes these functions.
 The macro can also be set with the CMake option
 [`JSON_DeleteDeprecatedFunctions`](../integration/cmake.md#json_deletedeprecatedfunctions) (`OFF` by default).
 See [full documentation of `JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md).
 ## `JSON_DIAGNOSTICS`
 This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable
@@ -97,8 +86,7 @@ See [full documentation of `JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json
 ## `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`
 When defined to `1`, a JSON value can no longer be created from a one-element `std::tuple` holding a reference to a JSON
-value, such as the result of `std::forward_as_tuple(j)`. This lets `std::tuple` convert such tuples element-wise. This
+value, such as the result of `std::forward_as_tuple(j)`. This lets `std::tuple` convert such tuples element-wise.
 is planned to become the default in version 4.0.0.
 See [full documentation of `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](../api/macros/json_disable_tuple_reference_conversion.md).
@@ -210,13 +198,6 @@ default.
 See [full documentation of `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md).
 ## `JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`
 When defined to `1`, maps with enum keys (e.g., `std::map<E, T>`) are stored as objects, using the enum's conversion for
 the keys, instead of arrays of `[key, value]` pairs. It is switched off (`0`) by default.
 See [full documentation of `JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](../api/macros/json_use_objects_for_enum_keyed_maps.md).
 ## `JSON_USE_SIMDUTF`
 When defined, UTF-8 validation of JSON strings read from contiguous byte input is delegated to the
@@ -21,8 +21,6 @@ The complete default namespace name is derived as follows:
    - [`JSON_PRECISE_STREAM_POSITION`](../api/macros/json_precise_stream_position.md) defined non-zero appends `_psp`.
    - [`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md) defined non-zero appends `_snul`.
    - [`JSON_STRICT_BINARY_UTF8`](../api/macros/json_strict_binary_utf8.md) defined non-zero appends `_sbu8`.
    - [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](../api/macros/json_use_objects_for_enum_keyed_maps.md) defined non-zero
      appends `_ekmo`.
 - The inline namespace ends with the suffix `_v` followed by the 3 components of the version number separated by
  underscores. To omit the version component, see [Disabling the version component](#disabling-the-version-component)
  below.
@@ -51,16 +51,16 @@ If you do want to preserve the **insertion order**, you can use the type [`nlohm
    --8<-- "examples/ordered_json.output"
    ```
-Alternatively, [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) also preserves the insertion order and, unlike [`ordered_map`](../api/ordered_map.md), keeps a lookup index, so it does not have the quadratic cost described below. It is used through a small adapter ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
+Alternatively, [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) also preserves the insertion order and, unlike [`ordered_map`](../api/ordered_map/index.md), keeps a lookup index, so it does not have the quadratic cost described below. It is used through a small adapter ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
 If the order does not matter and you only want faster lookup, `boost::unordered_flat_map`, `absl::flat_hash_map`, `absl::node_hash_map`, and several other hash maps work through an adapter that restores the template argument order `basic_json` expects; see [Template Parameter Requirements](types/template_parameters.md#objecttype). Note these are *unordered*, not insertion-ordered.
 [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) cannot be used: its iterators expose the mapped value as `const`, while `basic_json` needs to modify it in place.
-The [`ordered_map`](../api/ordered_map.md) behind `nlohmann::ordered_json` is deliberately minimal and has no lookup
+The [`ordered_map`](../api/ordered_map/index.md) behind `nlohmann::ordered_json` is deliberately minimal and has no lookup
 index, so every key access is a linear scan and building an object of `n` keys costs O(n²). This is unnoticeable at
 typical object sizes but becomes significant for objects with many thousands of keys; see
-[`ordered_map` complexity](../api/ordered_map.md#complexity). The alternatives above keep a lookup index and do not
+[`ordered_map` complexity](../api/ordered_map/index.md#complexity). The alternatives above keep a lookup index and do not
 have this cost.
 ### Notes on parsing
@@ -38,7 +38,7 @@ Requirements are split into two groups:
 | Template parameter                                                | Default                           | Notable substitutes                                                   |
 |-------------------------------------------------------------------|-----------------------------------|-----------------------------------------------------------------------|
-| [`ObjectType`](#objecttype)                                       | `std::map`                        | [`nlohmann::ordered_map`](../../api/ordered_map.md), Abseil hash maps |
+| [`ObjectType`](#objecttype)                                       | `std::map`                        | [`nlohmann::ordered_map`](../../api/ordered_map/index.md), Abseil hash maps |
 | [`ArrayType`](#arraytype)                                         | `std::vector`                     | `#!cpp std::deque`                                                    |
 | [`StringType`](#stringtype)                                       | `std::string`                     | `std::string`-like types over `char`                                  |
 | [`BooleanType`](#booleantype)                                     | `bool`                            | none worth using                                                      |
@@ -231,7 +231,7 @@ The library does not sort or de-duplicate keys itself; the behavior described in
 | Container                                                                        | Notes                                                                         |
 |----------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
 | `#!cpp std::map` (default)                                                       |                                                                               |
-| [`nlohmann::ordered_map`](../../api/ordered_map.md)                              | used by [`ordered_json`](../../api/ordered_json.md); keeps insertion order    |
+| [`nlohmann::ordered_map`](../../api/ordered_map/index.md)                              | used by [`ordered_json`](../../api/ordered_json.md); keeps insertion order    |
 | [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map)                     | keeps insertion order; adapter puts `fifo_map_compare` in the comparator slot |
 | `boost::container::map`, `boost::container::flat_map`                            | no adapter needed                                                             |
 | `#!cpp std::unordered_map`                                                       | through the adapter above; not with libstdc++ 9, see the note                 |
@@ -50,7 +50,7 @@ The public headers are in [`include/nlohmann`](https://github.com/nlohmann/json/
 - [`adl_serializer.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/adl_serializer.hpp), [`byte_container_with_subtype.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/byte_container_with_subtype.hpp), and [`ordered_map.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/ordered_map.hpp) define
  [`adl_serializer`](../api/adl_serializer/index.md),
  [`byte_container_with_subtype`](../api/byte_container_with_subtype/index.md), and
-  [`ordered_map`](../api/ordered_map.md).
+  [`ordered_map`](../api/ordered_map/index.md).
 Everything else lives in [`detail/`](https://github.com/nlohmann/json/tree/develop/include/nlohmann/detail) and namespace `nlohmann::detail`, which is not part of the public API. Paths
 below are relative to `include/nlohmann`.
@@ -97,7 +97,7 @@ is generated from these files with `make amalgamate` and must not be edited by h
 The library provides two specializations:
 - [`json`](../api/json.md) uses all default template arguments.
- [`ordered_json`](../api/ordered_json.md) uses [`ordered_map`](../api/ordered_map.md) as `ObjectType` to keep the
+- [`ordered_json`](../api/ordered_json.md) uses [`ordered_map`](../api/ordered_map/index.md) as `ObjectType` to keep the
  insertion order of object keys.
 The requirements on the template arguments are listed in
Author	SHA1	Message	Date
Niels Lohmann	fe4e78e867	Merge branch 'develop' into claude/todo-191-plan-508110 - ordered_map.hpp: develop's refactored members, with this branch's @sa links on every public member - byte_container_with_subtype operator==/!= and ordered_map docs: develop's reviewed text (#5638); drop the now unreferenced examples - basic_json.md: keep both version-history additions - add the docset entries that develop's style check now requires for the 25 API pages this branch adds - regenerate tools/api_checker/api_surface.json for develop's API Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-10-04 17:35:55 +02:00
Niels Lohmann	9196e92520	Merge branch 'develop' into claude/todo-191-plan-508110 Conflicts: none textual. Follow-up fixes for develop's changes: - docs/mkdocs/docs/api/ordered_map/index.md: develop's new paragraph (#5609) was written for api/ordered_map.md; fixed its relative ordered_json.md link for the page's new location, plus two pre-existing links from an earlier merge (ordered_json.md, features/object_order.md) - tools/api_checker/api_surface.json: regenerated with libclang 18.1.1 on Linux (swap() noexcept now includes json_base_class_t; new integral-key contains/count/find/value overloads) Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-30 20:36:12 +02:00
Niels Lohmann	7d22d865dd	Merge branch 'develop' into claude/todo-191-plan-508110 Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-28 22:22:46 +02:00
Niels Lohmann	4c73319d3b	Use one-line module docstrings in the API checker scripts Codacy runs two docstring checkers with opposite rules for module docstrings: with the summary on the first line it reported D213, with the summary on the second line it reports D212. A one-line docstring satisfies both. Keep the summary as the docstring and move the details into a comment below it; nothing reads the module docstrings. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-28 18:42:34 +02:00
Niels Lohmann	da5097abcd	Restore the CI spelling of json_pointer's operator string_t in the API surface The develop merge regenerated api_surface.json on macOS, whose libclang spells the name of the deprecated conversion operator as "operator nlohmann::json_pointer::string_t_helper<...>::type". CI's pinned libclang 18.1.1 on Linux spells it "operator typename string_t_helper<...>::type", so check_api_docs reported the file as out of date. This restores CI's spelling, which is byte-identical to the file CI regenerated. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 21:37:14 +02:00
Niels Lohmann	2319f6e6f9	Address Codacy findings in the API checker scripts Put multi-line docstring summaries on their own line, as a single sentence followed by a blank line (pydocstyle D205, D209, D213, D415). Annotate the subprocess import and calls with nosec: they only run fixed argument lists, never through a shell (Bandit B404, B603, B607). Do the same for the three broad except clauses in extract_api.py, which deliberately fall through to the next libclang candidate or skip an unresolvable alias (Bandit B110, B112). Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 18:09:03 +02:00
Niels Lohmann	9a0d1c0c47	Merge branch 'develop' into claude/todo-191-plan-508110 Resolve the conflict in docs/mkdocs/docs/home/architecture.md by taking develop's rewritten page and pointing its ordered_map links at the moved api/ordered_map/index.md. Also update the ordered_map.md links develop added in ordered_json.md, object_order.md, and template_parameters.md. Regenerate api_surface.json for the new BON8 functions and the changed comparison operator. Restrict the documented_non_public leak check to @sa URLs into json.nlohmann.me: develop now uses @sa to link GitHub issues from private members such as copy_structured, which is not a documentation leak. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 18:07:00 +02:00
Niels Lohmann	1bbb5d400a	Regenerate api_surface.json after merging develop develop added JSON_HEDLEY_WARN_UNUSED_RESULT to a number of basic_json members (#5520) and reworked operator<<'s output adapter, so the committed API surface no longer matched what extract_api.py produces and the "Check for uncommitted API surface changes" step failed. This is the patch the workflow itself uploads for that purpose; the changes are limited to recorded signatures plus the way libclang spells json_pointer's conversion operator. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-15 10:06:55 +02:00
Niels Lohmann	08d18d5a82	Merge remote-tracking branch 'origin/develop' into HEAD	2026-09-14 21:26:29 +02:00
Niels LohmannandClaude Sonnet 5	a27065bd12	Regenerate api_surface.json after merging develop develop gained iterator+sentinel support for accept()/parse()/sax_parse()/ from_cbor()/from_msgpack()/from_ubjson()/from_bjdata()/from_bson() (#5205) since this branch was created, which check_api_docs.yml's drift check caught immediately: GitHub's pull_request trigger checks out the PR-vs-base merge commit, not the PR branch in isolation, so CI was comparing the committed api_surface.json (generated before that upstream change existed) against a fresh extraction of a json.hpp that already had it. This superseded an earlier, incorrect diagnosis of the same symptom (a JSON_HAS_RANGES cross-environment pin) -- that fix remains in place since it's still a real, independent determinism improvement for three other JSON_HAS_RANGES-gated locations in type_traits.hpp, but it wasn't the actual cause of this particular mismatch: these new overloads turned out to be unconditional (SFINAE-gated via can_compare_ne, not preprocessor-gated), so no environment-detection difference was involved here at all. Signed-off-by: Niels Lohmann <mail@nlohmann.me> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-07-11 23:45:46 +02:00
Niels Lohmann	3940f4b730	Merge remote-tracking branch 'origin/develop' into claude/todo-191-plan-508110	2026-07-11 23:43:30 +02:00
Niels LohmannandClaude Sonnet 5	0663907b68	Fix cross-environment API-surface drift and lint findings from CI extract_api.py's own extraction wasn't deterministic across machines, which CI's drift check caught immediately: JSON_HAS_RANGES auto-detects via the standard library's __cpp_lib_ranges feature-test macro, which isn't reliably gated to C++20 mode by every stdlib -- undefined under -std=c++17 with macOS's libc++, but defined under the identical flag with the Ubuntu stdlib CI uses, so parse()/accept()/from_*() extracted different signatures purely depending on which machine ran the extraction. Pinned to -DJSON_HAS_RANGES=0: the deterministic and safe choice, since pinning to 1 was tried first and found to fail to parse on a stdlib without full <ranges> support even when the macro claims otherwise. Also found and fixed a second, independent source of the same class of drift: get_identity_name() used cursor.spelling verbatim for CONVERSION_FUNCTION cursors, which libclang renders as its own internally-canonicalized form of the return type rather than what's literally written. Confirmed for json_pointer::operator string_t() spelling differently on two machines pinned to the identical libclang==18.1.1 wheel, with the JSON_HAS_RANGES fix above ruled out as the cause. Now derived from the cursor's own raw source text instead, immune to libclang's dependent-type resolution differences and incidentally more readable than the libclang-internal forms it replaces. Bumped SURFACE_FORMAT_VERSION to 3 and regenerated all 27 history snapshots and the committed api_surface.json; both fixes are documented in tools/api_checker/history/README.md's format-history log. Also fixes diff_api.py's format_version guard, which only compared the two loaded surfaces against each other and never against SURFACE_FORMAT_VERSION (what this build actually understands) -- two surfaces on the same, newer-than-expected format_version would have silently passed the guard. Remaining fixes are the concretely actionable findings from Codacy's review of the new tools/api_checker/ files: unused imports/variables, a stray f-string with no placeholders. Left the docstring-formatting nitpicks (pydocstyle D2xx/D4xx) and generic subprocess-usage notices alone -- the former has no established convention elsewhere in this codebase's Python tooling to conform to, and the latter are inherent to a dev tool that shells out to git/clang with developer-controlled arguments, not user input. Signed-off-by: Niels Lohmann <mail@nlohmann.me> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-07-11 18:59:19 +02:00
Niels LohmannandClaude Sonnet 5	f23b3c63a2	Add AST-based public API checker and fix documentation gaps it found (#3691 ) Adds tools/api_checker/: extract_api.py derives the public API surface directly from the libclang AST (independent of documentation status), check_docs.py flags public entries missing @sa links (and @sa on non-public ones), diff_api.py does an overload-aware breaking/feature diff between two refs, check_macros.py cross- checks documented macros against #define sites, and snapshot_release.py backfills immutable per-release surface snapshots into tools/api_checker/history/ (v3.1.0 through v3.12.0) so diff_api.py can compare releases without live extraction. POLICY.md documents what counts as public API and what stability is guaranteed. Running this tooling against the current tree found and fixed a real documentation backlog: ~25 new API doc pages (ordered_map's methods, json_sax's ctor/dtor/ operator=, byte_container_with_subtype's comparison operators, several orphaned type aliases), each with a compiled and output-verified example, plus missing @sa comments and stale/incorrect Version History entries on several existing pages (found by diffing consecutive release pairs and checking whether the resulting change was actually reflected in the target page's history section). Also adds docs/home/api_changes.md, a per-release, per-function reference of public API changes (v3.1.0 through v3.12.0) generated from the history/ snapshots, complementing (not replacing) the existing release notes. Along the way, found and fixed several extractor bugs by testing against real release tags rather than trusting the algorithm in isolation -- most notably an identity-key scheme based on libclang's USR that encoded the enclosing class template's own arity, and a since-renamed ABI inline-namespace pattern (json_v3_11_0 vs. today's json_abi_v3_11_2) that neither of two earlier regex attempts stripped correctly. Both are documented in extract_api.py's docstrings and tools/api_checker/history/README.md so the failure mode doesn't recur silently. .github/workflows/check_api_docs.yml runs extract_api.py + check_docs.py in CI, advisory-only for now (documented backlog may not be at zero for entities this PR didn't touch), plus a blocking drift check on the committed tools/api_checker/api_surface.json. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-07-11 18:59:00 +02:00
		`@@ -0,0 +1 @@`
							`Container is std::vector<std::pair<const Key, T>>: true`
		`@@ -0,0 +1,2 @@`
							`inserted: true, value: eins`
							`inserted: false, value: eins`
		`@@ -0,0 +1,2 @@`
							`compare("a", "a") = true`
							`compare("a", "b") = false`