Use the shared descent bookkeeping rather than a second set

Comparing kept a thread_local count, a limit and a guard of its own beside the ones copying already had, all three the same thing under a different name. They are gone; the shared count, limit and guard do the work. The guard grows a second constructor here, because the comparison operators are written as a macro and a macro cannot use the preprocessor: it cannot look the count up behind an #ifdef the way copy_structured does, so the guard looks it up for it. nesting_depth_exhausted() arrives for the same reason - whether an operator descends at all is a constant at every call site, and testing it there is what MSVC reports as C4127. Also say in compare_leaves what happens to a pair that is an array on one side and an object on the other, since the answer is not obvious from the code: an operator only descends into two values of the same type, so such a pair is told apart by its types alone - unequal, and ordered the way the types are - exactly as it is above the bound. And record what the explicit stack costs: the comparison operators are noexcept and the container comparison this replaces allocated nothing, so running out of memory here ends the process instead of throwing. It takes a value nested past the bound and an exhausted heap to reach, and the same comparison used to exhaust the call stack, but it is a new way to fail. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Parenthesise the reserve() computation in the comparison test
2026-08-29 04:17:32 +00:00 · 2026-08-21 12:30:56 +02:00 · 2026-08-21 12:25:05 +02:00 · 2026-08-21 12:25:05 +02:00 · 2026-08-21 12:25:05 +02:00 · 2026-08-21 12:25:05 +02:00
69 changed files with 3324 additions and 3272 deletions
@@ -108,7 +108,9 @@ The tests are located in [`tests/src/unit-*.cpp`](https://github.com/nlohmann/js
 are structured along the features of the library or the nature of the tests. Usually, it should be clear from the
 context which existing file needs to be extended, and only very few cases require creating new test files.

-When fixing a bug, edit `unit-regression2.cpp` and add a section referencing the fixed issue.
+When fixing a bug, edit `unit-regression3.cpp` and add a test case referencing the fixed issue. Its predecessors
+`unit-regression1.cpp` and `unit-regression2.cpp` stay as they are: the MinGW linker fails on the object a file this
+size produces, which is why the tests are spread over several files in the first place.

 #### Exceptions

@@ -11,7 +11,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -34,7 +34,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -9,7 +9,7 @@ jobs:
    runs-on: ubuntu-22.04
    steps:
    - name: Harden Runner
-      uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+      uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
      with:
        egress-policy: audit

@@ -27,7 +27,7 @@ jobs:

    steps:
    - name: Harden Runner
-      uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+      uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
      with:
        egress-policy: audit

@@ -38,14 +38,14 @@ jobs:

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
-      uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+      uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
      with:
        languages: c-cpp

    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
    # If this step fails, then you should remove it and run the build manually (see below)
    - name: Autobuild
-      uses: github/codeql-action/autobuild@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+      uses: github/codeql-action/autobuild@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6

    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+      uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
@@ -19,7 +19,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -17,7 +17,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -27,7 +27,7 @@ jobs:
      security-events: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -43,6 +43,6 @@ jobs:
          output: 'flawfinder_results.sarif'

      - name: Upload analysis results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
        with:
          sarif_file: ${{github.workspace}}/flawfinder_results.sarif
@@ -17,7 +17,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -26,7 +26,7 @@ jobs:
    runs-on: ubuntu-22.04
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -36,7 +36,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -76,6 +76,6 @@ jobs:

      # Upload the results to GitHub's code scanning dashboard.
      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
        with:
          sarif_file: results.sarif
@@ -32,7 +32,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -61,7 +61,7 @@ jobs:

      # Upload SARIF file generated in previous step
      - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
        with:
          sarif_file: semgrep.sarif
        if: always()
@@ -16,7 +16,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -35,7 +35,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -60,7 +60,7 @@ jobs:
        target: [ci_test_amalgamation, ci_test_single_header, ci_cppcheck, ci_cpplint, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata, ci_reuse_compliance, ci_test_valgrind]
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -100,7 +100,7 @@ jobs:
    container: ubuntu:focal
    strategy:
      matrix:
-        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls]
+        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_no_thread_local]
    steps:
      - name: Install build-essential
        run: apt-get update ; apt-get install -y build-essential unzip wget git libssl-dev
@@ -118,7 +118,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -369,7 +369,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -392,7 +392,7 @@ jobs:
        target: [ci_test_examples, ci_test_build_documentation]
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
        with:
          egress-policy: audit

@@ -158,6 +158,10 @@ jobs:
      # to fit: IMAGE_REL_AMD64_SECREL against `.debug_line'" because the
      # MinGW linker cannot relocate the debug sections this test produces.
      # The tests are only built and run here, so the debug info is not used.
+      # Do not add -O1 here to shrink the objects further: it does make them
+      # link, but the binaries clang 11.0.1 and clang 18.1.8 then produce crash
+      # before doctest prints its first line - 39 of 102 tests on clang 18.
+      # Keep the objects small by splitting the test files instead.
      - name: Run CMake
        run: cmake -S . -B build ^
             -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang++.exe" ^
@@ -242,6 +242,25 @@ add_custom_target(ci_test_noglobaludls
    COMMENT "Compile and test with global UDLs disabled"
 )

+###############################################################################
+# Disable thread-local storage.
+###############################################################################
+
+# Without thread-local storage, copying and comparing cannot bound their
+# descent and handle every object and array without the call stack. Those paths
+# are otherwise only reached by values nested deeper than the bound, so this
+# target is what runs the whole test suite through them.
+add_custom_target(ci_test_no_thread_local
+    COMMAND ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON
+    -DCMAKE_CXX_FLAGS=-DJSON_NO_THREAD_LOCAL
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_no_thread_local
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_no_thread_local
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_no_thread_local && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test without thread-local storage"
+)
+
 ###############################################################################
 # Coverage.
 ###############################################################################
@@ -14,11 +14,7 @@ To store objects in C++, a type is defined by the template parameters explained
 ## Template parameters

 `ArrayType`
-:   container type to store arrays. It must be a vector-like container: the library uses `operator[]`, `at()`, and
-    `resize()`, and requires random-access iterators. `#!cpp std::vector` and `#!cpp std::deque` qualify;
-    `#!cpp std::list` does not. See
-    [Template Parameter Requirements](../../features/types/template_parameters.md#arraytype) for the full list of
-    requirements.
+:   container type to store arrays (e.g., `std::vector` or `std::list`)

 `AllocatorType`
 :   the allocator to use for objects (e.g., `std::allocator`)
@@ -70,4 +66,3 @@ Arrays are stored as pointers in a `basic_json` type. That is, for any access to
 ## Version history

 - Added in version 1.0.0.
- Made `capacity()` optional, so that array types such as `#!cpp std::deque` can be used, in version 3.13.0.
@@ -42,9 +42,7 @@ represent a byte array in modern C++.
    `value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary
    serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via
    `reinterpret_cast`, which is only correct for byte-sized elements -- a container like
-    `#!cpp std::vector<std::intptr_t>` will not work as `BinaryType`. The elements must be stored contiguously, and
-    the binary readers additionally require `resize()` and `operator[]`. See
-    [Template Parameter Requirements](../../features/types/template_parameters.md#binarytype) for the full list.
+    `#!cpp std::vector<std::intptr_t>` will not work as `BinaryType`.

 ## Notes

@@ -52,11 +50,6 @@ represent a byte array in modern C++.

 The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`.

-#### Supported byte types
-
-`#!cpp std::vector<std::uint8_t>`, `#!cpp std::vector<char>`, and `#!cpp std::vector<std::byte>` are supported.
-Regardless of which of them is configured, [`dump`](dump.md) writes the bytes as the numbers 0..255.
-
 #### Custom BinaryType behavior

 When a custom `BinaryType` is configured (other than the default `#!cpp std::vector<std::uint8_t>`), you can assign
@@ -133,6 +126,3 @@ type `#!cpp binary_t*` must be dereferenced.
 ## Version history

 - Added in version 3.8.0. Changed the type of subtype to `std::uint64_t` in version 3.10.0.
- Fixed [`dump`](dump.md), [`std::hash`](std_hash.md), and [`to_ubjson`](to_ubjson.md) for byte types that are not
-  integers (e.g., `#!cpp std::byte`) in version 3.13.0. `dump` now writes the bytes of a signed byte type (e.g.,
-  `#!cpp char`) as 0..255 rather than as negative numbers.
@@ -11,14 +11,6 @@ literals `#!json true` and `#!json false`.

 To store boolean values in C++, a type is defined by the template parameter  `BooleanType` which chooses the type to use.

-## Template parameters
-
-`BooleanType`
-:   the type to store booleans. As it is stored directly inside a `basic_json` value (in a union), it must be a
-    trivially default-constructible, trivially copyable, and trivially destructible type that is convertible to and
-    from `#!cpp bool`. See
-    [Template Parameter Requirements](../../features/types/template_parameters.md#booleantype).
-
 ## Notes

 #### Default type
@@ -35,10 +35,6 @@ class basic_json;
 | `BinaryType`         | type for binary arrays                                                    | [`binary_t`](binary_t.md)                   |
 | `CustomBaseClass`    | extension point for user code                                             | [`json_base_class_t`](json_base_class_t.md) |

-The library imposes a number of requirements on these types that are not expressed as C++ concepts, such as the
-container operations `object_t` and `array_t` must provide, or the fact that `StringType` must be `char`-based. They
-are collected in [Template Parameter Requirements](../../features/types/template_parameters.md).
-
 ## Specializations

 - [**json**](../json.md) - default specialization
@@ -21,11 +21,8 @@ The default value for `CustomBaseClass` is `void`. In this case, an

 #### Limitations

-The type `CustomBaseClass` has to be a default-constructible, non-`final` class.
+The type `CustomBaseClass` has to be a default-constructible class.
 `basic_json` only supports copy/move construction/assignment if `CustomBaseClass` does so as well.
-A `CustomBaseClass` with non-static data members forfeits `basic_json`'s
-[standard layout](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType) guarantee. See
-[Template Parameter Requirements](../../features/types/template_parameters.md#custombaseclass).

 ## Examples

@@ -19,12 +19,6 @@ using json_serializer = JSONSerializer<T, SFINAE>;

 The default values for `json_serializer` is [`adl_serializer`](../adl_serializer/index.md).

-#### Requirements
-
-A custom serializer must provide `#!cpp static void to_json(basic_json&, T)` for every type it serializes, and either
-`#!cpp static void from_json(const basic_json&, T&)` or `#!cpp static T from_json(const basic_json&)` for every type it
-deserializes. See [Template Parameter Requirements](../../features/types/template_parameters.md#jsonserializer).
-
 ## Examples

 ??? example
@@ -20,16 +20,6 @@ used.
 To store floating-point numbers in C++, a type is defined by the template parameter `NumberFloatType` which chooses the
 type to use.

-## Template parameters
-
-`NumberFloatType`
-:   the type to store floating-point numbers. Parsing and serialization are implemented in terms of
-    `#!cpp std::strtof`/`#!cpp std::strtod`/`#!cpp std::strtold` and `#!cpp std::snprintf`, so the type must be
-    `#!cpp float`, `#!cpp double`, or `#!cpp long double`. The
-    [binary formats](../../features/binary_formats/index.md) additionally require `#!cpp float` or `#!cpp double`,
-    because they have no encoding for `#!cpp long double`. See
-    [Template Parameter Requirements](../../features/types/template_parameters.md#numberfloattype).
-
 ## Notes

 #### Default type
@@ -20,13 +20,6 @@ used.
 To store integer numbers in C++, a type is defined by the template parameter `NumberIntegerType` which chooses the type
 to use.

-## Template parameters
-
-`NumberIntegerType`
-:   the type to store signed integers. It must be a **signed integral** type (`#!cpp std::is_integral`) with a
-    `#!cpp std::numeric_limits` specialization, and it is stored directly inside a `basic_json` value. See
-    [Template Parameter Requirements](../../features/types/template_parameters.md#numberintegertype-and-numberunsignedtype).
-
 ## Notes

 #### Default type
@@ -20,14 +20,6 @@ used.
 To store unsigned integer numbers in C++, a type is defined by the template parameter `NumberUnsignedType` which chooses
 the type to use.

-## Template parameters
-
-`NumberUnsignedType`
-:   the type to store unsigned integers. It must be an **unsigned integral** type (`#!cpp std::is_integral`) with a
-    `#!cpp std::numeric_limits` specialization, and it must be able to represent the absolute value of every
-    [`number_integer_t`](number_integer_t.md) value. See
-    [Template Parameter Requirements](../../features/types/template_parameters.md#numberintegertype-and-numberunsignedtype).
-
 ## Notes

 #### Default type
@@ -30,5 +30,3 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
 - Added in version 3.0.0.
 - Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in
  version 3.11.0.
- Fixed the fallback to `default_object_comparator_t`, which previously failed to compile for object types without a
-  `key_compare` member type, in version 3.13.0.
@@ -18,11 +18,7 @@ To store objects in C++, a type is defined by the template parameters described
 ## Template parameters

 `ObjectType`
-:   the container to store objects. Its template parameters must have the same order and meaning as those of
-    `std::map`; in particular, the third parameter is a comparator. `#!cpp std::unordered_map`, whose third parameter
-    is a hash function, therefore needs an adapter -- see
-    [Template Parameter Requirements](../../features/types/template_parameters.md#objecttype) for the full list of
-    requirements, an adapter example, and the containers that are known to work.
+:   the container to store objects (e.g., `std::map` or `std::unordered_map`)

 `StringType`
 :   the type of the keys or names (e.g., `std::string`). The comparison function `std::less<StringType>` is used to
@@ -126,4 +122,3 @@ the object is silently converted as an array of key-value pairs, which is incorr
 ## Version history

 - Added in version 1.0.0.
- Allowed object types whose `erase(iterator)` returns `#!cpp void` in version 3.13.0.
@@ -23,11 +23,6 @@ JSON class into byte-sized characters during deserialization.
    `StringType`. To work with wide-character data, convert it to/from UTF-8 at the boundary instead -- see the
    FAQ's [wide string handling](../../home/faq.md#wide-string-handling) section for a conversion recipe.

-    Beyond the character type, the library expects a substantial part of the `#!cpp std::string` interface (contiguous
-    null-terminated `data()`, `substr()`, `find()`, `append()`, ...). See
-    [Template Parameter Requirements](../../features/types/template_parameters.md#stringtype) for the full list and
-    for the string types that are known to work.
-
 ## Notes

 #### Default type
@@ -83,5 +78,3 @@ and an example.
 ## Version history

 - Added in version 1.0.0.
- Removed the requirement that `string_t` be implicitly convertible from `#!cpp std::string`, which the BSON writer and
-  the UBJSON reader relied on, in version 3.13.0.
@@ -52,11 +52,6 @@ optional, `#!cpp bjdata_version_t::draft2` by default.

 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

-## Exceptions
-
- Throws [`other_error.502`](../../home/exceptions.md#jsonexceptionother_error502) if `use_type` is true and `use_size`
-  is false.
-
 ## Complexity

 Linear in the size of the JSON value `j`.
@@ -46,9 +46,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va

 ## Complexity

-Proportional to the size of the JSON value `j` multiplied by its maximum nesting
-depth, `O(n × d)`. BSON length prefixes are computed recursively before nested
-values are written.
+Linear in the size of the JSON value `j`.

 ## Examples

@@ -45,11 +45,6 @@ The exact mapping and its limitations are described on a [dedicated page](../../

 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

-## Exceptions
-
- Throws [`other_error.502`](../../home/exceptions.md#jsonexceptionother_error502) if `use_type` is true and `use_size`
-  is false.
-
 ## Complexity

 Linear in the size of the JSON value `j`.
@@ -37,14 +37,7 @@ Linear in the size of the JSON value.
 ## Notes

 Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and cannot unflattened to
-their original type.
-
-A flattened array and a flattened object whose keys are array indices are indistinguishable, because both are
-described by the same JSON pointers. A value is therefore restored as an array if and only if one of its keys is the
-reference token `0`, and as an object otherwise: `#!json {"2": 1}` is restored unchanged, whereas `#!json {"0": 1}` is
-restored as `#!json [1]`. This decision does not depend on the order in which the flattened object is iterated.
-
-Apart from these two cases, for a JSON value `j`, the following is always true:
+their original type. Apart from this example, for a JSON value `j`, the following is always true:
 `#!cpp j == j.flatten().unflatten()`.

 ## Examples
@@ -70,4 +63,3 @@ Apart from these two cases, for a JSON value `j`, the following is always true:
 ## Version history

 - Added in version 2.0.0.
- Made the array/object decision independent of the object's iteration order in version 3.13.0.
@@ -22,6 +22,7 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_HAS_STD_FORMAT**](json_has_std_format.md) - control `std::format`/`std::formatter` support
 - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
+- [**JSON_NO_THREAD_LOCAL**](json_no_thread_local.md) - switch off the use of `thread_local` storage
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
 - [**JSON_USE_GLOBAL_UDLS**](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace

@@ -0,0 +1,48 @@
+# JSON_NO_THREAD_LOCAL
+
+```cpp
+#define JSON_NO_THREAD_LOCAL
+```
+
+When defined, the library does not use `#!cpp thread_local` storage. This is relevant for the few environments whose
+toolchain does not support it.
+
+Copying a value and comparing two values both descend into the first levels by letting the containers copy or compare
+themselves, and finish whatever is nested deeper than that without the call stack, so that neither can exhaust the stack
+however deeply the values are nested. Each counts the levels it has descended into in a `#!cpp thread_local` variable, as
+a counter shared between threads would be raced.
+
+Without those counters, no descent can be bounded safely, so objects and arrays are copied and compared without the call
+stack right away. Both keep working exactly as they do otherwise - the same values come out, the same comparisons hold,
+and deeply nested values are handled just as safely - but both are slower, because the containers no longer copy or
+compare themselves. Copying the benchmark documents takes 9% (`canada.json`) to 34% (`twitter.json`) longer, and
+comparing two equal ones 10% (`citm_catalog.json`) to 90% (`canada.json`) longer.
+
+## Default definition
+
+By default, `#!cpp JSON_NO_THREAD_LOCAL` is not defined.
+
+```cpp
+#undef JSON_NO_THREAD_LOCAL
+```
+
+The library defines it by itself for Clang targeting MinGW, which does not survive the `#!cpp thread_local` storage:
+copying a value segfaults there, with both old and current Clang versions, while GCC targeting MinGW is unaffected.
+Copying and comparing fall back to working without the call stack there, as they do whenever the macro is defined.
+
+## Examples
+
+??? example
+
+    The code below forces the library not to use `#!cpp thread_local` storage.
+
+    ```cpp
+    #define JSON_NO_THREAD_LOCAL 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
+## Version history
+
+- Added in version 3.12.1.
@@ -12,11 +12,9 @@
 Controls how exceptions are handled by the library.

 1. This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library.
-   The argument is the type of the exception to catch. The library uses it in a single place: to swallow any exception
-   escaping the parent-pointer check that [`JSON_DIAGNOSTICS`](json_diagnostics.md) adds to the class invariant. The
-   places where the library catches its own [`json::out_of_range`](../../home/exceptions.md#out-of-range) exceptions
-   use `JSON_INTERNAL_CATCH` instead, which `JSON_CATCH_USER` also overrides unless `JSON_INTERNAL_CATCH_USER` is
-   defined. The macro is always followed by a scope.
+   The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range`
+   exceptions internally to rethrow them as [`json::out_of_range`](../../home/exceptions.md#out-of-range) exceptions.
+   The macro is always followed by a scope.
 2. This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that
   `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield
   undefined behavior.
@@ -98,17 +98,6 @@ The library maps BSON record types to JSON value types as follows:
    This library deserializes BSON type `0x11` (Timestamp) as a `number_unsigned` value. The 64-bit value is preserved,
    but the Timestamp type information is not.

-!!! warning "Lenient BSON input handling"
-
-    The BSON reader is lenient in a few areas where the BSON specification is more restrictive:
-
-    - array element keys are not checked against the required decimal sequence (`0`, `1`, `2`, ...),
-    - any non-zero byte is accepted as `true` for the boolean type, and
-    - the payload for binary subtype `0x02` is returned as-is, including its inner length prefix.
-
-    If BSON input must be validated for strict specification compliance, validate it separately before passing it to
-    `from_bson()`.
-
 ??? example

    ```cpp
@@ -54,30 +54,6 @@ json j = {1.0, "hello", 42};
 auto t = j.get<std::tuple<double, std::string, int>>();  // {1.0, "hello", 42}
 ```

-!!! warning "Serializing a `std::pair`/`std::tuple` whose every element is a string-keyed pair"
-
-    When *every* element of a `#!cpp std::pair` or `#!cpp std::tuple` is itself a two-element array whose first
-    element is a string (for example `#!cpp std::pair<std::string, int>`), serializing it produces a JSON **object**
-    instead of the expected array:
-
-    ```cpp
-    using kv = std::pair<std::string, int>;
-    json j = std::pair<kv, kv>{{"a", 1}, {"b", 2}};  // {"a":1,"b":2}, not [["a",1],["b",2]]
-    ```
-
-    This is a consequence of the [brace-initializer object-detection rule](creating_values.md): the same rule that
-    lets `#!cpp json{{"a", 1}, {"b", 2}}` create an object also fires here. The resulting object cannot be read back
-    into the original type (`#!cpp get<std::pair<kv, kv>>()` throws [`type_error.302`](../home/exceptions.md#jsonexceptiontype_error302)),
-    and duplicate keys collapse into one, losing elements. This only affects `#!cpp std::pair`/`#!cpp std::tuple`
-    themselves; a `#!cpp std::vector<std::pair<std::string, int>>`, or a pair/tuple with at least one element that is
-    not a string-keyed pair, serializes to an array as expected. To force an array, build one explicitly from the
-    elements with [`array`](../api/basic_json/array.md):
-
-    ```cpp
-    std::pair<kv, kv> p{{"a", 1}, {"b", 2}};
-    json a = json::array({p.first, p.second});  // [["a",1],["b",2]]
-    ```
-
 !!! info "Extracting references into a tuple"

    A tuple type may also hold references (e.g. `#!cpp std::tuple<double&, std::string&>`) to avoid copying: `get`
@@ -91,6 +91,14 @@ security reasons (e.g., Intel Software Guard Extensions (SGX)).

 See [full documentation of `JSON_NO_IO`](../api/macros/json_no_io.md).

+## `JSON_NO_THREAD_LOCAL`
+
+When defined, the library does not use `#!cpp thread_local` storage. Copying a value and comparing two values then
+always avoid the call stack rather than descending into a bounded number of levels first, which is slower but yields the
+same values and the same comparisons.
+
+See [full documentation of `JSON_NO_THREAD_LOCAL`](../api/macros/json_no_thread_local.md).
+
 ## `JSON_SKIP_LIBRARY_VERSION_CHECK`

 When defined, the library will not create a compiler warning when a different version of the library was already
@@ -51,11 +51,7 @@ 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)).
-
-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.
+Alternatively, you can use a more sophisticated ordered map like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).

 The [`ordered_map`](../api/ordered_map.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
@@ -79,8 +79,7 @@ template<
    class NumberFloatType = double,
    template<typename U> class AllocatorType = std::allocator,
    template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer,
-    class BinaryType = std::vector<std::uint8_t>,
-    class CustomBaseClass = void
+    class BinaryType = std::vector<std::uint8_t>
 >
 class basic_json;
 ```
@@ -107,10 +106,6 @@ using number_float_t = NumberFloatType;
 using binary_t = nlohmann::byte_container_with_subtype<BinaryType>;
 ```

-Not every type can be passed for these template arguments: the library uses the resulting types in ways that imply a
-number of requirements, for instance that `StringType` is `char`-based or that `ArrayType` is vector-like. These
-requirements are collected in [Template Parameter Requirements](template_parameters.md).
-

 ## Objects

@@ -1,663 +0,0 @@
-# Template Parameter Requirements
-
-Class [`basic_json`](../../api/basic_json/index.md) is configurable through eleven template parameters. The library
-never formally states what a type passed for one of these parameters has to provide -- the requirements are implied by
-the way the library uses the resulting [`object_t`](../../api/basic_json/object_t.md),
-[`array_t`](../../api/basic_json/array_t.md), [`string_t`](../../api/basic_json/string_t.md), etc. This page collects
-these requirements so they do not have to be discovered by trial and error. Each section lists the concrete types
-that are known to work for that parameter and the ones that do not, checked against Boost 1.83, Abseil 20250127.0,
-Folly, EASTL 3.21, `ankerl::unordered_dense`, `phmap`, `gtl`, `robin_hood`, `tsl::ordered_map`, and Qt 6.
-
-## How to read this page
-
-Requirements are split into two groups:
-
- **Always required** -- needed to instantiate `basic_json` at all, or needed by functions that virtually every program
-  uses (construction, element access, [`dump`](../../api/basic_json/dump.md)).
- **Required for ...** -- only needed when a particular part of the API is instantiated. Member function templates are
-  only instantiated when they are used, so a type may be perfectly usable even though it does not satisfy these
-  requirements, as long as the corresponding functions are never called.
-
-!!! warning "Requirements are not checked"
-
-    Apart from a `#!cpp static_assert` on the array iterator category, the requirements below are not diagnosed with
-    dedicated error messages. Violating most of them results in a compiler error somewhere inside the library. Six
-    violations are not caught at compile time at all:
-
-    - A [`StringType`](#stringtype) whose `data()` is not null-terminated compiles and silently misparses numbers,
-      because the lexer hands the buffer to `#!cpp std::strtoull`/`#!cpp std::strtoll`/`#!cpp std::strtod`.
-    - A [`BinaryType`](#binarytype) whose `value_type` is wider than one byte compiles and silently produces wrong
-      results, because the readers and writers reinterpret its storage as raw bytes.
-    - A stateful [`AllocatorType`](#allocatortype) compiles and silently ignores its state: allocation, deallocation,
-      and [`get_allocator()`](../../api/basic_json/get_allocator.md) each use a different default-constructed instance.
-    - A [`NumberUnsignedType`](#numberintegertype-and-numberunsignedtype) too narrow to hold the absolute value of
-      every `NumberIntegerType` value silently corrupts: with `#!cpp std::int64_t`/`#!cpp std::uint32_t`,
-      `#!cpp basic_json(INT64_MIN).dump()` yields `#!json -0`.
-    - The two [cross-specialization conversions](#cross-specialization-conversions) below. These abort on an assertion
-      in a normal build, and only fail silently under `#!cpp NDEBUG`.
-
-## Overview
-
-| Template parameter                                                | Default                           | Notable substitutes                                                    |
-|-------------------------------------------------------------------|-----------------------------------|------------------------------------------------------------------------|
-| [`ObjectType`](#objecttype)                                       | `std::map`                        | [`nlohmann::ordered_map`](../../api/ordered_map.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                                                       |
-| [`NumberIntegerType`](#numberintegertype-and-numberunsignedtype)  | `std::int64_t`                    | any signed integer type                                                |
-| [`NumberUnsignedType`](#numberintegertype-and-numberunsignedtype) | `std::uint64_t`                   | any unsigned integer type                                              |
-| [`NumberFloatType`](#numberfloattype)                             | `double`                          | `float` (`long double`: no binary formats)                             |
-| [`AllocatorType`](#allocatortype)                                 | `std::allocator`                  | stateless allocators                                                   |
-| [`JSONSerializer`](#jsonserializer)                               | `adl_serializer`                  | serializers with the same interface                                    |
-| [`BinaryType`](#binarytype)                                       | `#!cpp std::vector<std::uint8_t>` | `#!cpp std::vector<char>`                                              |
-| [`CustomBaseClass`](#custombaseclass)                             | `void`                            | any default-constructible class                                        |
-
-!!! warning "Third-party containers and incomplete types"
-
-    `object_t` is instantiated inside the definition of `basic_json` -- it is probed for a `key_compare` member to
-    form [`object_comparator_t`](../../api/basic_json/object_comparator_t.md) -- i.e. while `basic_json` is still an
-    incomplete type. `#!cpp std::map` is required by the standard to support incomplete mapped types; most
-    third-party maps are not, and inspecting the mapped type at class scope (for instance with
-    `#!cpp std::is_trivially_move_assignable`) makes them unusable as `ObjectType`, no matter how their template
-    arguments are adapted. This rules out `absl::btree_map`, `phmap::btree_map`, `gtl::btree_map`,
-    `robin_hood::unordered_node_map`, `folly::F14FastMap`, and `eastl::hash_map`.
-
-    `array_t` is only *named* in the class definition and is not instantiated until `basic_json` is complete, so an
-    `ArrayType` that inspects its value type at class scope is generally fine -- `boost::container::small_vector` and
-    `static_vector` both reject incomplete value types yet work here. `absl::InlinedVector` is the exception: the
-    `#!cpp std::is_trivially_move_assignable<basic_json>` it evaluates while instantiating itself re-enters the
-    library's own trait machinery mid-instantiation.
-
-!!! note "Folly requires C++20"
-
-    Folly's headers use `#!cpp consteval` and `#!cpp std::type_identity`, so any `basic_json` specialization that
-    names a Folly type has to be compiled as C++20 or later, whatever the rest of the library supports.
-
-## `ObjectType`
-
-`ObjectType` is instantiated as
-
-```cpp
-using object_t = ObjectType<StringType,                                    // key_type
-                            basic_json,                                    // mapped_type
-                            default_object_comparator_t,                   // key_compare
-                            AllocatorType<std::pair<const StringType,
-                                                    basic_json>>>;         // allocator_type
-```
-
-i.e., the template arguments follow the order and meaning of `std::map`.
-
-### Always required
-
- The template must be usable with **four** type arguments in the order shown above. The third argument is a
-  **comparator**; containers that expect something else in this position (e.g., a hash function) need an alias template
-  or wrapper -- see [Notes](#notes).
- An optional member type `key_compare`. If it is present it becomes
-  [`object_comparator_t`](../../api/basic_json/object_comparator_t.md); otherwise
-  [`default_object_comparator_t`](../../api/basic_json/default_object_comparator_t.md) is used.
- Member types `key_type`, `mapped_type`, `value_type`, and `iterator`.
- `value_type` must behave like `#!cpp std::pair<const key_type, mapped_type>`; the library accesses `.first` and
-  `.second` on it.
- `iterator` must be default-constructible and satisfy
-  [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator). The type returned
-  by `cbegin()`/`cend()` must satisfy the same requirements.
- Constructors: default, copy, move, and from an iterator range `(first, last)`.
- Member functions `begin()`, `end()`, `cbegin()`, `cend()`, `empty()`, `size()`, `max_size()`, `clear()`,
-  `find(key)`, `count(key)`, `emplace(key, value)`, `insert(value_type)`, `insert(first, last)`, `operator[](key)`,
-  `erase(iterator)`, and `erase(first, last)`. `erase(iterator)` may return the following iterator or `#!cpp void`;
-  in the latter case the library computes the successor itself, before erasing.
- `erase(key)` is **optional**: if the container does not provide one, the library falls back to `find(key)` followed
-  by `erase(iterator)`.
- `at(key)` is required only by [`to_ubjson`](../../api/basic_json/to_ubjson.md) and
-  [`to_bjdata`](../../api/basic_json/to_bjdata.md), but every container tried here provides it.
- `emplace` and `insert(value_type)` must return `#!cpp std::pair<iterator, bool>` and must have **unique-key**
-  semantics; multimaps cannot be used.
- The type must be swappable (via `std::swap` or an ADL `swap`).
- The comparison operators `==` and `<`; `!=`, `<=`, `>`, and `>=` are derived from them. Where the library uses
-  three-way comparison (C++20), `==` and `<=>` are required **instead** -- the six two-way operators do not satisfy
-  it. They implement [`basic_json`'s comparison operators](../../api/basic_json/operator_eq.md).
-
-### Required for heterogeneous key lookup
-
-The overloads of [`at`](../../api/basic_json/at.md), [`operator[]`](../../api/basic_json/operator%5B%5D.md),
-[`find`](../../api/basic_json/find.md), [`contains`](../../api/basic_json/contains.md),
-[`count`](../../api/basic_json/count.md), [`erase`](../../api/basic_json/erase.md), and
-[`value`](../../api/basic_json/value.md) that accept a key type other than `object_t::key_type` require
-
- a **transparent** comparator, i.e. [`object_comparator_t`](../../api/basic_json/object_comparator_t.md) has a member
-  type `is_transparent` (this is why the default comparator is `#!cpp std::less<>` since C++14), and
- corresponding heterogeneous `find`, `count`, `erase`, and `operator[]` overloads on the container.
-
-### Notes
-
-#### `std::unordered_map` needs an adapter
-
-`#!cpp std::unordered_map` cannot be passed directly: its third template parameter is a hash function, but
-`basic_json` passes a comparator in that position. An alias template or wrapper that restores the expected argument
-order makes it usable:
-
-```cpp
-template<class Key, class T, class IgnoredCompare, class Allocator>
-struct unordered_map_object
-    : std::unordered_map<Key, T, std::hash<Key>, std::equal_to<Key>, Allocator>
-{
-    using base_t = std::unordered_map<Key, T, std::hash<Key>, std::equal_to<Key>, Allocator>;
-    using base_t::base_t;
-};
-
-using unordered_json = nlohmann::basic_json<unordered_map_object>;
-```
-
-Whether `#!cpp std::unordered_map` can be instantiated at all depends on the standard library: `object_t` is formed
-while `basic_json` is still incomplete (see the warning above), and libstdc++ 9 needs the size of the mapped type to
-instantiate the hash map's node type, so the adapter does not compile there. Newer libstdc++ versions, and the hash
-maps listed below, do not have that problem.
-
-The adapter above works verbatim for Abseil's, Boost's, `phmap`'s and `gtl`'s hash maps, which all place the hash
-function third and take a `#!cpp std::pair<const Key, T>` allocator fifth. Two need a different adapter:
-
- `ankerl::unordered_dense` expects an allocator over `#!cpp std::pair<Key, T>` (non-const key), so the allocator has
-  to be rebound to that or dropped.
- `robin_hood`'s fifth parameter is the non-type `MaxLoadFactor100`, so its adapter must drop the allocator entirely.
-
-None of these hash maps defines `key_compare`, so all of them additionally rely on `object_comparator_t` falling back
-to [`default_object_comparator_t`](../../api/basic_json/default_object_comparator_t.md); see
-[`object_comparator_t`](../../api/basic_json/object_comparator_t.md).
-
-#### Abseil hash maps
-
-`absl::flat_hash_map` and `absl::node_hash_map` tolerate an incomplete value type, but they take a hash function as
-their third template argument. The same adapter as for `#!cpp std::unordered_map` makes them usable:
-
-```cpp
-template<class Key, class T, class IgnoredCompare, class Allocator>
-struct flat_hash_object
-    : absl::flat_hash_map<Key, T, absl::Hash<Key>, std::equal_to<Key>, Allocator>
-{
-    using base_t = absl::flat_hash_map<Key, T, absl::Hash<Key>, std::equal_to<Key>, Allocator>;
-    using base_t::base_t;
-};
-
-using flat_hash_json = nlohmann::basic_json<flat_hash_object>;
-```
-
-`absl::node_hash_map` keeps references to the mapped values valid across insertions; `absl::flat_hash_map` does not,
-which makes it behave like [`ordered_json`](../../api/ordered_json.md) with respect to
-[iterator invalidation](../../api/basic_json/index.md#iterator-invalidation). Both expose a `capacity()` member
-function, so [`JSON_DIAGNOSTICS`](../../api/macros/json_diagnostics.md) treats them conservatively and keeps the
-parent pointers correct either way.
-
-#### Iteration order
-
-The library never relies on the container's iteration order for correctness; it does determine the order in which
-object keys are serialized by [`dump`](../../api/basic_json/dump.md) and visited by
-[`items`](../../api/basic_json/items.md). See [Object Order](../object_order.md).
-
-#### `capacity()` marks a container as insertion-ordered
-
-With [`JSON_DIAGNOSTICS`](../../api/macros/json_diagnostics.md) enabled, the library detects insertion-ordered maps by
-probing for a `capacity()` member function (`nlohmann::ordered_map` inherits it from `std::vector`) and refreshes all
-parent pointers after every insertion. An `ObjectType` that happens to have a `capacity()` member is therefore treated
-conservatively -- this is correct, but slower.
-
-#### Key order and duplicate keys
-
-The library does not sort or de-duplicate keys itself; the behavior described in
-[`object_t`](../../api/basic_json/object_t.md) is entirely the behavior of the chosen container.
-
-### Compatible containers
-
-| 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::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            |
-| `boost::unordered_map`, `boost::unordered_flat_map`, `boost::unordered_node_map`                              | through the adapter above                                                |
-| `absl::flat_hash_map`, `absl::node_hash_map`                                                                  | through the adapter above; `flat_hash_map` moves mapped values on rehash  |
-| `phmap::flat_hash_map`, `phmap::node_hash_map`, `gtl::flat_hash_map`                                          | through the adapter above                                                |
-| `ankerl::unordered_dense::map` and `segmented_map`                                                            | adapter must rebind or drop the allocator                                |
-| `robin_hood::unordered_flat_map`                                                                              | adapter must drop the allocator                                          |
-| `folly::F14NodeMap`                                                                                           | through the adapter above; requires C++20, see the note above            |
-| `folly::sorted_vector_map`                                                                                    | alias must drop the allocator, whose value type it disagrees on          |
-
-### Containers that cannot be used
-
-| Container                                                                                                     | Reason                                                                   |
-|---------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
-| `absl::btree_map`, `phmap::btree_map`, `gtl::btree_map`, `robin_hood::unordered_node_map`, `folly::F14FastMap`, `eastl::hash_map` | require a complete mapped type                          |
-| `eastl::map`                                                                                                  | EASTL iterators do not work with `#!cpp std::iterator_traits`            |
-| `tsl::ordered_map`                                                                                            | its iterators expose the mapped value as `#!cpp const`                   |
-| `QMap`                                                                                                        | no `value_type` member type                                              |
-| `QHash`                                                                                                       | its `value_type` is the mapped type rather than a key/value pair, and its iterators dereference to the mapped value |
-| `#!cpp std::multimap`, `#!cpp std::unordered_multimap`                                                         | `emplace` does not return `#!cpp std::pair<iterator, bool>`              |
-
-## `ArrayType`
-
-`ArrayType` is instantiated as
-
-```cpp
-using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
-```
-
-### Always required
-
- The template must be usable with **two** type arguments (value type and allocator).
- Member types `value_type` and `iterator`.
- Constructors: default, copy, and move; and from an iterator range `(first, last)`.
- Member functions `begin()`, `end()`, `cbegin()`, `cend()`, `empty()`, `size()`, `max_size()`, `clear()`,
-  `operator[](size_type)`, `back()`, `push_back()`, `emplace_back()`, `pop_back()`, `resize()`,
-  `insert()` (single element, count, and range), `erase(pos)`, and `erase(first, last)`.
-  `basic_json::insert(pos, initializer_list)` goes through the range overload, so no initializer-list `insert` is
-  needed. `at(size_type)` is **not** required: [`basic_json::at(size_type)`](../../api/basic_json/at.md) checks the
-  index itself and then uses `operator[]`.
- `iterator` must be default-constructible, and it as well as the type returned by `cbegin()`/`cend()` must satisfy
-  [LegacyRandomAccessIterator](https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator).
-  A `#!cpp static_assert` only checks for
-  [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator), but
-  [`dump`](../../api/basic_json/dump.md) (`cend() - 1`),
-  [`erase(idx)`](../../api/basic_json/erase.md) (`begin() + idx`), and the random-access operations of
-  [`basic_json::iterator`](../../api/basic_json/begin.md) require random access.
- The comparison operators, as for [`ObjectType`](#objecttype): `==` and `<`, or `==` and `<=>` under C++20.
-
-### Required for individual functions
-
- A member type `value_type`, for [`to_bson`](../../api/basic_json/to_bson.md) of an array.
- A constructor from `(count, value)`, for
-  [`basic_json(size_type, const basic_json&)`](../../api/basic_json/basic_json.md).
- Swappability, via `#!cpp std::swap` or an ADL `swap`, for [`swap(array_t&)`](../../api/basic_json/swap.md).
-
-!!! note "`capacity()` is optional"
-
-    With [`JSON_DIAGNOSTICS`](../../api/macros/json_diagnostics.md) enabled, the library reads `array_t::capacity()`
-    to find out whether adding an element reallocated the array and moved its elements, which would invalidate the
-    parent pointers. An array type without a `capacity()` member function is handled conservatively: the parent
-    pointers of all elements are refreshed after every insertion, which makes adding *n* elements cost O(*n*²). Only
-    diagnostics builds pay this; without them `capacity()` is never called.
-
-### Compatible containers
-
-| Container                                                                               | Notes                                                    |
-|-------------------------------------------------------------------------------------------|----------------------------------------------------------|
-| `#!cpp std::vector` (default)                                                           |                                                          |
-| `#!cpp std::deque`                                                                      | references survive appends, but not insertions elsewhere; see the `capacity()` note above |
-| `#!cpp std::pmr::vector`                                                                | through an alias, as the allocator comes from `AllocatorType` instead |
-| `boost::container::vector`, `deque`, `devector`                                         |                                                          |
-| `boost::container::stable_vector`                                                       | the only one tried that keeps references valid across *every* insertion |
-| `boost::container::small_vector`, `folly::small_vector`                                 | through an alias that fixes the inline capacity          |
-| `boost::container::static_vector`                                                       | through the same kind of alias, for arrays that stay within the fixed capacity |
-| `folly::fbvector`                                                                       | requires C++20, see the note above                       |
-
-### Containers that cannot be used
-
-| Container                        | Reason                                                                                       |
-|----------------------------------|----------------------------------------------------------------------------------------------|
-| `#!cpp std::list`                | no `operator[]`, and no random-access iterators                                              |
-| `eastl::vector`, `QList`, `QVector` | no `max_size()`; they handle the incomplete value type fine                                |
-| `absl::InlinedVector`            | requires a complete value type, see the note above                                            |
-| `absl::FixedArray`               | the size is fixed at construction, so `resize`, `push_back`, `insert` and `erase` are missing |
-
-## `StringType`
-
-`StringType` is used **both** for JSON string values and for the keys of JSON objects
-(`string_t` and `object_t::key_type`).
-
-### Always required
-
- A member type `value_type` that is one byte wide and `char`-compatible. The library stores and processes UTF-8
-  encoded `char` data and hands `data()` to `#!cpp std::strtoull`/`#!cpp std::strtoll`.
-  `#!cpp std::wstring`, `#!cpp std::u16string`, and `#!cpp std::u32string` are **not** valid choices; see the FAQ on
-  [wide string handling](../../home/faq.md#wide-string-handling).
- Constructors: default, copy, move, from `#!cpp const char*` (which must not be `#!cpp explicit`), from
-  `#!cpp (const char*, size_type)`, and from `#!cpp (size_type, char)`; and copy or move assignment.
- Member functions `size()`, `clear()`, `resize(n, c)`, `data()`, `push_back(char)`, and `operator[]`
-  (const and non-const, returning references). `c_str()` and `back()` are **not** required.
- `data()` must return a pointer to a contiguous, **null-terminated** buffer -- the parser hands it to
-  `#!cpp std::strtoull`. A type whose `data()` is not null-terminated does not fail to compile; it silently
-  misparses numbers.
- `append(const char*, size_type)`, used by [`dump`](../../api/basic_json/dump.md), and `append(const StringType&)`,
-  used by the CBOR reader for indefinite-length strings. The library's internal string concatenation additionally has
-  to append a `#!cpp char` and a `#!cpp const char*`; for each it selects between `append(arg)`, `#!cpp operator+=`,
-  `append(first, last)`, and `append(data, size)`.
- The comparison operator `==` against another `StringType`, and `<` for use as a key of the chosen
-  [`ObjectType`](#objecttype) (with the default comparator, `#!cpp std::less<>` must be able to compare two
-  `StringType` values, and a `StringType` with the key types used for lookup). `!=` is never applied to a
-  `StringType`, and `==` against `#!cpp const char*` is resolved by the implicit `#!cpp const char*` constructor.
-
-### Required for the binary formats
-
- `resize(n)`, used by the readers to make room for a block of bytes.
- Non-const `operator[]`, into which the readers `#!cpp std::memcpy` those bytes.
-
-### Required for JSON Pointer, `flatten`, and `diff`
-
- A static member `npos` and the member function `find_first_of(char, size_type)` -- together with `data()`,
-  `reserve(n)`, and `append(const char*, size_type)` they implement the escaping and unescaping of reference tokens
-  described in RFC 6901. Neither `find(const StringType&, size_type)`, nor `substr(pos, count)`, nor
-  `replace(pos, count, const StringType&)` is required.
- `empty()`.
- `begin()` and `end()` -- used by
-  [`operator[](const json_pointer&)`](../../api/basic_json/operator%5B%5D.md) to decide whether a reference token
-  denotes an array index.
-
-### Required for other functionality
-
-| Functionality                                                                                                    | Additional requirement                                                              |
-|--------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
-| [`diff`](../../api/basic_json/diff.md), [`items`](../../api/basic_json/items.md), [`std::hash`](../../api/basic_json/std_hash.md) | conversion of a `#!cpp std::size_t` to `StringType`: either assignability from the result of `#!cpp std::to_string`, or an ADL overload `#!cpp void int_to_string(StringType&, std::size_t)` |
-| [`std::hash<basic_json>`](../../api/basic_json/std_hash.md)                                                      | additionally a specialization of `#!cpp std::hash<StringType>`                        |
-| [`to_bson`](../../api/basic_json/to_bson.md)                                                                    | `find(value_type)` and `npos`                                                         |
-| [`parse`](../../api/basic_json/parse.md) from a `string_t`                                                      | the input adapters must accept it; otherwise pass a character range                   |
-| `#!cpp operator<<(std::ostream&, const json_pointer&)`                                                           | streamability to `#!cpp std::ostream`                                                 |
-| exception messages                                                                                               | `data()` and `size()`, or `begin()` and `end()`                                       |
-
-### Compatible types
-
-| Type                                                            | Notes                                                                     |
-|-------------------------------------------------------------------|---------------------------------------------------------------------------|
-| `#!cpp std::string` (default)                                   |                                                                           |
-| `#!cpp std::basic_string` with a custom **stateless** allocator |                                                                           |
-| `#!cpp std::pmr::string`                                        | see the warning below before relying on the memory resource               |
-| `boost::container::string`                                      | needs a user-supplied `#!cpp std::hash` specialization (Boost provides `boost::hash` instead) |
-| `folly::fbstring`                                               | requires C++20, see the note above                                        |
-| `eastl::string`                                                 | needs a user-supplied `#!cpp std::hash` and an ADL `int_to_string` (it is not assignable from a `#!cpp std::string`); [`parse`](../../api/basic_json/parse.md) does not accept it directly -- pass a character range or a `#!cpp std::string` |
-| a custom string class in a user-defined namespace               | if the requirements above are met                                          |
-
-### Types that cannot be used
-
-| Type                                                                | Reason                                                                |
-|-----------------------------------------------------------------------|-----------------------------------------------------------------------|
-| `#!cpp std::wstring`, `#!cpp std::u16string`, `#!cpp std::u32string` | the character type is not one byte wide                               |
-| `#!cpp std::u8string`                                               | one byte wide, but `#!cpp char8_t` is not `#!cpp char`-compatible      |
-| `absl::Cord`                                                        | no `value_type`, and the storage is not contiguous                    |
-| `QString`                                                           | no `append(const char*, size_type)`; its `QChar` is also two bytes wide, though that is never diagnosed |
-
-!!! warning "A `std::pmr::string` mostly does not use the memory resource you choose"
-
-    `basic_json` cannot be given an allocator or a memory resource. `AllocatorType` is default-constructed at every
-    allocation and has to be stateless (see [`AllocatorType`](#allocatortype)), and string values the library creates
-    are constructed with their own default allocator. So:
-
-    - Every string the library itself produces -- from [`parse`](../../api/basic_json/parse.md), from
-      [`dump`](../../api/basic_json/dump.md), or by default construction -- allocates from
-      `#!cpp std::pmr::get_default_resource()`.
-    - **Copying** an arena-backed string into a value silently drops its memory resource: the copy lands on the
-      default resource, because `#!cpp std::pmr::polymorphic_allocator` does not propagate on copy construction.
-      Nothing warns about this.
-    - **Moving** one in does keep it, and later growth still allocates from that arena -- but it does not survive a
-      copy of the enclosing `basic_json`.
-    - Passing `#!cpp std::pmr::polymorphic_allocator` as `AllocatorType` does not work around any of this; it does
-      not compile.
-
-    Apart from moving a string in, the only way to redirect these allocations is the process-global
-    `#!cpp std::pmr::set_default_resource()`.
-
-!!! tip "Reference implementation"
-
-    The unit test `tests/src/unit-alt-string.cpp` contains `alt_string`, a minimal string type that satisfies the
-    requirements needed for the tested subset of the API. It is a good starting point for a custom `StringType`.
-
-## `BooleanType`
-
-`boolean_t` is stored **directly** inside `basic_json`, as a member of an anonymous union.
-
-### Always required
-
- A literal type that is trivially default-constructible, trivially copyable, and trivially destructible; otherwise the
-  union's special member functions are deleted.
- **Implicitly** convertible from `#!cpp bool` -- an `#!cpp explicit` constructor is not enough, because the
-  `to_json` overload for a custom `BooleanType` is constrained on `#!cpp std::is_convertible` -- and contextually
-  convertible to `#!cpp bool` (here an `#!cpp explicit operator bool` is fine).
- Comparison operators `==`, `!=`, `<`, `<=`, `>`, `>=` (or `<=>`).
- Convertible from and to `#!cpp bool` through the serializer, because
-  [`get<bool>()`](../../api/basic_json/get.md) is used internally.
-
-There is little reason to use anything other than `#!cpp bool` here.
-
-### Compatible types
-
-`#!cpp bool` is the only usable choice. Another trivially copyable type that is implicitly convertible to and from
-`#!cpp bool` -- `#!cpp std::uint8_t`, say -- does compile, and JSON booleans still round-trip, but the type then
-serves as both `boolean_t` and an ordinary integer: `basic_json` can no longer be constructed or assigned from a
-`#!cpp std::uint8_t` at all (the boolean and unsigned-integer `to_json` overloads become ambiguous), and
-[`get<std::uint8_t>()`](../../api/basic_json/get.md) on a number throws
-[`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) instead of returning the value.
-
-## `NumberIntegerType` and `NumberUnsignedType`
-
-Both types are stored **directly** inside `basic_json`'s union.
-
-### Always required
-
- `#!cpp std::is_integral` must be satisfied: `NumberIntegerType` must be a **signed** integer type,
-  `NumberUnsignedType` an **unsigned** integer type. Class types are not supported -- among others, the constructors
-  taking integer values are constrained on `#!cpp std::is_integral`.
- Trivially default-constructible, trivially copyable, and trivially destructible (union member).
- `#!cpp std::numeric_limits` must be specialized for both types.
- `NumberUnsignedType` must be able to represent the absolute value of every `NumberIntegerType` value; serialization
-  of negative numbers converts the value to `NumberUnsignedType`.
- Both types must fit into the internal 64-character number buffer used by
-  [`dump`](../../api/basic_json/dump.md), which is the case for all standard integer types.
- [`std::hash<basic_json>`](../../api/basic_json/std_hash.md) additionally requires `#!cpp std::hash` specializations.
-
-### Notes
-
-The number types influence what the parser accepts: an integer literal that does not round-trip through the chosen type
-is stored as [`number_float_t`](../../api/basic_json/number_float_t.md) instead. Choosing types narrower than 64 bits
-therefore silently changes parse results rather than raising an error. See
-[Number Handling](number_handling.md) for details.
-
-### Compatible types
-
-| Type pair                                                                                    | Support                                                             |
-|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
-| `#!cpp std::int64_t` / `#!cpp std::uint64_t` (default)                                       | full                                                                |
-| `#!cpp std::int32_t` / `#!cpp std::uint32_t`, `#!cpp long long` / `#!cpp unsigned long long` | full; narrower types change which literals the parser can represent |
-| any other pair of standard signed/unsigned integer types                                     | full                                                                |
-| class types, enumerations                                                                    | not usable; `#!cpp std::is_integral` must hold                      |
-| `#!cpp bool`, or a type already used for another member of the union                         | not usable; `#!cpp std::is_integral<bool>` is in fact `#!cpp true`, but the `get_impl_ptr` overloads for `boolean_t`, `number_integer_t`, `number_unsigned_t` and `number_float_t` would collide |
-
-## `NumberFloatType`
-
-`number_float_t` is stored **directly** inside `basic_json`'s union.
-
-### Always required
-
- Trivially default-constructible, trivially copyable, and trivially destructible (union member).
- `#!cpp std::numeric_limits` must be specialized; `max_digits10` is used to size the conversion.
- `#!cpp std::isfinite` must be applicable to the type.
-
-### Required for parsing and serialization
-
-`NumberFloatType` must be one of `#!cpp float`, `#!cpp double`, or `#!cpp long double`:
-
- The [parser](../parsing/index.md) converts number literals with `#!cpp std::strtof`, `#!cpp std::strtod`, or
-  `#!cpp std::strtold`; the library provides overloads for exactly these three types.
- [`dump`](../../api/basic_json/dump.md) falls back to `#!cpp std::snprintf` with the `%g` and `%Lg` conversion
-  specifiers, for which the library likewise provides only `#!cpp double` and `#!cpp long double` overloads
-  (`#!cpp float` is promoted to `#!cpp double`).
-
-If `#!cpp std::numeric_limits<NumberFloatType>` describes an IEEE 754 binary32 or binary64 number, `dump` uses the
-Grisu2 algorithm, which produces the shortest representation that round-trips. Otherwise the `snprintf` fallback with
-`max_digits10` digits is used.
-
-### Required for the binary formats
-
-`NumberFloatType` must be `#!cpp float` or `#!cpp double`. The writers for
-[CBOR, MessagePack, UBJSON, BJData, and BSON](../binary_formats/index.md) map a floating-point value onto an IEEE 754
-binary32 or binary64 field and have no encoding for `#!cpp long double`.
-
-### Compatible types
-
-| Type                        | Support                                                                                             |
-|-----------------------------|-----------------------------------------------------------------------------------------------------|
-| `#!cpp double` (default)    | full; short round-trip output through Grisu2                                                        |
-| `#!cpp float`               | full; short round-trip output through Grisu2                                                        |
-| `#!cpp long double`         | `dump` and `parse` only; the binary format writers do not compile, as they only handle IEEE 754 binary32 and binary64 |
-| any other type              | not usable                                                                                          |
-
-## `AllocatorType`
-
-`AllocatorType` is instantiated with **one** argument, for each of `object_t`, `array_t`, `string_t`, `binary_t`,
-`basic_json`, and `#!cpp std::pair<const StringType, basic_json>`.
-
-### Always required
-
- The template must be usable with exactly one type argument. The library instantiates `AllocatorType<T>` directly and
-  never uses `#!cpp std::allocator_traits<...>::rebind_alloc`.
- It must satisfy the [Allocator](https://en.cppreference.com/w/cpp/named_req/Allocator) named requirement so that
-  `#!cpp std::allocator_traits` can be used with it.
- It must be **default-constructible and stateless**. Objects are allocated with a default-constructed allocator and
-  deallocated with a *different* default-constructed allocator, and
-  [`get_allocator()`](../../api/basic_json/get_allocator.md) returns a default-constructed instance. Allocators
-  carrying state are not supported, so there is no way to tell a `basic_json` where to allocate from; see the note
-  under [`StringType`](#stringtype) for what that means in practice. A stateful allocator is **not diagnosed**: it
-  compiles and silently ignores the state.
- It must support **incomplete types**: `AllocatorType<basic_json>` is instantiated inside the definition of
-  `basic_json` itself.
- `#!cpp std::allocator_traits<AllocatorType<basic_json>>::pointer` becomes
-  [`basic_json::pointer`](../../api/basic_json/index.md#container-types), and iterators are constructed from raw
-  `#!cpp basic_json*` values. The `pointer` type must therefore be a plain pointer; fancy pointers are not supported.
-
-### Compatible types
-
-| Type                                                            | Support                                            |
-|-----------------------------------------------------------------|----------------------------------------------------|
-| `#!cpp std::allocator` (default)                                | full                                               |
-| a custom stateless allocator template                           | full                                               |
-| stateful allocators, e.g. `#!cpp std::pmr::polymorphic_allocator`| not usable; see the requirements above             |
-
-## `JSONSerializer`
-
-`JSONSerializer` is instantiated as `JSONSerializer<T, void>` and defaults to
-[`adl_serializer`](../../api/adl_serializer/index.md).
-
-### Always required
-
- The template must accept **two** type arguments. It does not have to give the second one a default -- `basic_json`
-  declares the parameter as `#!cpp template<typename T, typename SFINAE = void> class JSONSerializer`, so uses such as
-  `#!cpp JSONSerializer<T>` inside the library supply `#!cpp void` themselves. The second parameter exists so that
-  partial specializations can be constrained by SFINAE.
- For every type `T` that is converted **to** a JSON value, a static member function
-  `#!cpp static void to_json(basic_json&, T)` must exist.
- For every type `T` that is converted **from** a JSON value, either
-  `#!cpp static void from_json(const basic_json&, T&)` or `#!cpp static T from_json(const basic_json&)` must exist.
-  The latter form is required for types that are not default-constructible; see
-  [Arbitrary Types Conversions](../arbitrary_types.md).
- To support the [converting constructor](../../api/basic_json/basic_json.md) between different `basic_json`
-  specializations, `to_json` must be available for `boolean_t`, `number_integer_t`, `number_unsigned_t`,
-  `number_float_t`, `string_t`, `object_t`, `array_t`, and `binary_t` of the *source* specialization.
-
-### Compatible types
-
-| Type                                                              | Support                                                                 |
-|-------------------------------------------------------------------|-------------------------------------------------------------------------|
-| [`nlohmann::adl_serializer`](../../api/adl_serializer/index.md) (default) | full                                                             |
-| a class template deriving from `adl_serializer`                   | full; the usual way to change behavior while keeping the defaults        |
-| an unrelated template with the same interface                     | full, but it has to handle every type the library converts               |
-
-## `BinaryType`
-
-`BinaryType` is not a JSON type; it is used for the byte strings of the
-[binary formats](../binary_formats/index.md). It is wrapped as
-
-```cpp
-using binary_t = nlohmann::byte_container_with_subtype<BinaryType>;
-```
-
-### Always required
-
- A non-`final` class type -- [`byte_container_with_subtype`](../../api/byte_container_with_subtype/index.md) derives
-  from it publicly.
- A member type `value_type` that is **exactly one byte** wide (e.g., `#!cpp std::uint8_t`, `#!cpp char`, or
-  `#!cpp std::byte`). Readers and writers reinterpret the container's storage as raw bytes. A wider `value_type` is
-  **not diagnosed**: it compiles and silently produces wrong results.
- Contiguous storage: the binary readers `#!cpp std::memcpy` into `#!cpp &binary[n]`, the writers `reinterpret_cast`
-  `data()`.
- Default-constructible, copy-constructible, and move-constructible.
- Member functions `size()`, `empty()`, `data()`, `resize()`, `operator[]`, `back()`, `begin()`, `end()`, `cbegin()`,
-  and `cend()` with random-access iterators, and `insert(pos, first, last)`, which the CBOR reader uses to join the
-  chunks of an indefinite-length byte string. `push_back()` is **not** required.
- Comparison operators: `==` is used by
-  [`byte_container_with_subtype`](../../api/byte_container_with_subtype/index.md), the relational operators by
-  [`basic_json`'s comparison operators](../../api/basic_json/operator_le.md).
-
-### Required for individual functions
-
- `clear()`, for [`basic_json::clear()`](../../api/basic_json/clear.md).
-
-`max_size()`, `at()`, `reserve()`, `erase()`, `pop_back()`, and `emplace_back()` are **not** used at all.
-
-See [`binary_t`](../../api/basic_json/binary_t.md) for how a non-default `BinaryType` changes the meaning of assigning
-such a container to a `basic_json` value.
-
-### Compatible containers
-
-| Container                                                                                                                  | Notes                                                              |
-|------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
-| `#!cpp std::vector<std::uint8_t>` (default)                                                                                |                                                                    |
-| `#!cpp std::vector<char>`, `#!cpp std::vector<std::byte>`                                                                  | `dump()` writes the bytes as 0..255 whichever is used              |
-| `boost::container::vector<std::uint8_t>`, `boost::container::small_vector<std::uint8_t, N>`                                |                                                                    |
-| `absl::InlinedVector<std::uint8_t, N>`                                                                                     | usable here, unlike as an `ArrayType`, because the value type is complete |
-| `eastl::vector<std::uint8_t>`                                                                                              | usable here, unlike as an `ArrayType`, because `max_size()` is not needed |
-| `folly::fbvector<std::uint8_t>`                                                                                            | requires C++20, see the note above                                 |
-
-### Containers that cannot be used
-
-| Container                                            | Reason                                                                                  |
-|--------------------------------------------------------|-----------------------------------------------------------------------------------------|
-| `QByteArray`                                         | no `empty()` (it spells that `isEmpty()`); its `insert` takes an index rather than an iterator; and it converts to `string_t`, which makes `to_json` ambiguous between a string and a binary value |
-| `#!cpp std::string`                                  | `binary_t::container_type` and `string_t` would be the same type, so the two [`swap`](../../api/basic_json/swap.md) overloads collide and `basic_json` cannot be instantiated at all |
-| `#!cpp std::deque<std::uint8_t>`                     | storage is not contiguous, so there is no `data()`                                       |
-| containers whose `value_type` is wider than one byte | see above -- accepted by the compiler, wrong at runtime                                  |
-
-## `CustomBaseClass`
-
-`CustomBaseClass` is an extension point: unless it is `#!cpp void` (the default, which selects the empty
-`nlohmann::json_default_base`), `basic_json` publicly derives from it.
-
-### Always required
-
- A non-`final`, default-constructible class type.
- `basic_json` is copy-/move-constructible and copy-/move-assignable only if `CustomBaseClass` is.
-
-### Notes
-
-`basic_json` is documented to be a
-[StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType). Because `basic_json` has
-non-static data members of its own, a `CustomBaseClass` with non-static data members forfeits this guarantee.
-
-Note the namespace of `CustomBaseClass` becomes an associated namespace of `basic_json` for the purpose of
-argument-dependent lookup.
-
-See [`json_base_class_t`](../../api/basic_json/json_base_class_t.md) for an example.
-
-### Compatible types
-
-| Type                                                     | Support                                                      |
-|----------------------------------------------------------|--------------------------------------------------------------|
-| `#!cpp void` (default)                                   | an empty base class is used; no effect on `basic_json`        |
-| any default-constructible, non-`final` class             | full; see [`json_base_class_t`](../../api/basic_json/json_base_class_t.md) |
-
-## Cross-specialization conversions
-
-Converting a value from one `basic_json` specialization into another (see the
-[converting constructor](../../api/basic_json/basic_json.md)) imposes two additional requirements that are not
-diagnosed at compile time. With assertions enabled they abort on the `#!cpp JSON_ASSERT` at the end of the converting
-constructor; under `#!cpp NDEBUG` they fail **silently** at runtime:
-
- The target `string_t` must be directly constructible from the source `string_t`. Otherwise the string is converted to
-  an array of character codes.
- The target `object_t::key_type` must be directly constructible from the source object's key type. Otherwise the
-  object is converted to an array of key/value pairs.
-
-See [issue #3425](https://github.com/nlohmann/json/issues/3425), [`string_t`](../../api/basic_json/string_t.md), and
-[`object_t`](../../api/basic_json/object_t.md).
-
-## See also
-
- [Types](index.md) -- overview of how JSON values are stored
- [Number Handling](number_handling.md) -- how the number types affect parsing and serialization
- [Object Order](../object_order.md) -- using an insertion-ordered `ObjectType`
- [`basic_json`](../../api/basic_json/index.md) -- API documentation of the class template
@@ -965,19 +965,3 @@ A JSON Patch operation 'test' failed. The unsuccessful operation is also printed
    ```
    [json.exception.other_error.501] unsuccessful: {"op":"test","path":"/baz","value":"bar"}
    ```
-
-### json.exception.other_error.502
-
-[`to_ubjson`](../api/basic_json/to_ubjson.md) and [`to_bjdata`](../api/basic_json/to_bjdata.md) were called with
-`use_type = true` but `use_size = false`. UBJSON requires a size marker (`#`) after a type marker (`$`).
-
-!!! failure "Example message"
-
-    ```
-    [json.exception.other_error.502] use_type requires use_size = true
-    ```
-
-!!! note
-
-    This exception was added in version 3.13.0. Before that, debug builds aborted on an assertion and release builds
-    wrote a `$` marker without `#`, which [`from_ubjson`](../api/basic_json/from_ubjson.md) then rejected.
@@ -98,7 +98,6 @@ nav:
      - Types:
          - features/types/index.md
          - features/types/number_handling.md
-          - features/types/template_parameters.md
  - Integration:
      - integration/index.md
      - integration/migration_guide.md
@@ -292,6 +291,7 @@ nav:
          - 'JSON_HAS_THREE_WAY_COMPARISON': api/macros/json_has_three_way_comparison.md
          - 'JSON_NOEXCEPTION': api/macros/json_noexception.md
          - 'JSON_NO_IO': api/macros/json_no_io.md
+          - 'JSON_NO_THREAD_LOCAL': api/macros/json_no_thread_local.md
          - 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md
          - 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
          - 'JSON_USE_GLOBAL_UDLS': api/macros/json_use_global_udls.md
@@ -101,10 +101,7 @@ class exception : public std::exception
                    {
                        if (&element.second == current)
                        {
-                            // data() is null-terminated, so a key containing
-                            // a null byte is cut short here rather than
-                            // truncating the whole message at what()
-                            tokens.emplace_back(element.first.data());
+                            tokens.emplace_back(element.first.c_str());
                            break;
                        }
                    }
@@ -114,9 +114,7 @@ std::size_t hash(const BasicJsonType& j)
            seed = combine(seed, static_cast<std::size_t>(j.get_binary().subtype()));
            for (const auto byte : j.get_binary())
            {
-                // the cast is needed for binary types whose value type is not
-                // an integer (e.g., std::byte)
-                seed = combine(seed, std::hash<std::uint8_t> {}(static_cast<std::uint8_t>(byte)));
+                seed = combine(seed, std::hash<std::uint8_t> {}(byte));
            }
            return seed;
        }
@@ -2899,10 +2899,7 @@ class binary_reader
                               number_string,
                               out_of_range::create(406, concat("number overflow parsing '", number_string, '\''), nullptr));
                }
-                // number_string is a std::string, while the SAX interface takes a
-                // string_t; convert explicitly, as the two are only implicitly
-                // convertible for some string types
-                return sax->number_float(parsed_float, string_t(number_string.data(), number_string.size()));
+                return sax->number_float(parsed_float, std::move(number_string));
            }
            case token_type::uninitialized:
            case token_type::literal_true:
@@ -88,13 +88,8 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci

    iter_impl() = default;
    ~iter_impl() = default;
-    // the exception specification is left to be computed rather than declared:
-    // an array or object type whose iterator is not nothrow move constructible
-    // (std::deque's is not before libstdc++ 11) would make a declared noexcept
-    // differ from the implicit one, which deletes the function -- and is an
-    // error outright with older compilers
-    iter_impl(iter_impl&&) = default; // NOLINT(hicpp-noexcept-move,performance-noexcept-move-constructor,cppcoreguidelines-noexcept-move-operations)
-    iter_impl& operator=(iter_impl&&) = default; // NOLINT(hicpp-noexcept-move,performance-noexcept-move-constructor,cppcoreguidelines-noexcept-move-operations)
+    iter_impl(iter_impl&&) noexcept = default;
+    iter_impl& operator=(iter_impl&&) noexcept = default;

    /*!
    @brief constructor for a given JSON instance
@@ -17,7 +17,6 @@
 #endif  // JSON_NO_IO
 #include <limits> // max
 #include <numeric> // accumulate
-#include <set> // set
 #include <string> // string
 #include <utility> // move
 #include <vector> // vector
@@ -72,7 +71,7 @@ class json_pointer
                               string_t{},
                               [](const string_t& a, const string_t& b)
        {
-            return detail::concat<string_t>(a, '/', detail::escape(b));
+            return detail::concat(a, '/', detail::escape(b));
        });
    }

@@ -266,7 +265,7 @@ class json_pointer
            JSON_THROW(detail::parse_error::create(109, 0, detail::concat("array index '", s, "' is not a number"), nullptr));
        }

-        const char* p = s.data();
+        const char* p = s.c_str();
        char* p_end = nullptr; // NOLINT(misc-const-correctness)
        errno = 0; // strtoull doesn't reset errno
        const unsigned long long res = std::strtoull(p, &p_end, 10); // NOLINT(runtime/int)
@@ -301,35 +300,19 @@ class json_pointer
    }

  private:
-    /*!
-    @brief the reference token sequences that denote arrays
-
-    @ref unflatten collects the pointer prefixes that have a reference token 0
-    among their children; @ref get_and_create creates arrays exactly below
-    those prefixes and objects everywhere else. Deciding this up front keeps
-    the result independent of the order in which the flattened object is
-    iterated, which is unspecified for some object types.
-    */
-    using array_parents_t = std::set<std::vector<string_t>>;
-
    /*!
    @brief create and return a reference to the pointed to value

    @complexity Linear in the number of reference tokens.

-    @throw parse_error.106 if an array index begins with '0'
    @throw parse_error.109 if array index is not a number
    @throw type_error.313 if value cannot be unflattened
    */
    template<typename BasicJsonType>
-    BasicJsonType& get_and_create(BasicJsonType& j, const array_parents_t& array_parents) const
+    BasicJsonType& get_and_create(BasicJsonType& j) const
    {
        auto* result = &j;

-        // the reference tokens that have been consumed so far; used to look up
-        // whether the value to be created below is an array or an object
-        std::vector<string_t> prefix;
-
        // in case no reference tokens exist, return a reference to the JSON value
        // j which will be overwritten by a primitive value
        for (const auto& reference_token : reference_tokens)
@@ -338,11 +321,10 @@ class json_pointer
            {
                case detail::value_t::null:
                {
-                    if (array_parents.find(prefix) != array_parents.end())
+                    if (reference_token == "0")
                    {
-                        // some reference token below this position is 0, so the
-                        // value is an array
-                        result = &result->operator[](array_index<BasicJsonType>(reference_token));
+                        // start a new array if the reference token is 0
+                        result = &result->operator[](0);
                    }
                    else
                    {
@@ -382,8 +364,6 @@ class json_pointer
                default:
                    JSON_THROW(detail::type_error::create(313, "invalid value to unflatten", &j));
            }
-
-            prefix.push_back(reference_token);
        }

        return *result;
@@ -843,8 +823,7 @@ class json_pointer
        {
            // use the text between the beginning of the reference token
            // (start) and the last slash (slash).
-            const auto count = (slash == string_t::npos ? reference_string.size() : slash) - start;
-            auto reference_token = string_t(reference_string.data() + start, count);
+            auto reference_token = reference_string.substr(start, slash - start);

            // check reference tokens are properly escaped
            for (std::size_t pos = reference_token.find_first_of('~');
@@ -960,24 +939,6 @@ class json_pointer

        BasicJsonType result;

-        // collect the pointer prefixes that have a reference token 0 among
-        // their children; the values below them are arrays, all others are
-        // objects (see array_parents_t)
-        array_parents_t array_parents;
-        for (const auto& element : *value.m_data.m_value.object)
-        {
-            json_pointer ptr(element.first);
-            std::vector<string_t> prefix;
-            for (auto& reference_token : ptr.reference_tokens)
-            {
-                if (reference_token == "0")
-                {
-                    array_parents.insert(prefix);
-                }
-                prefix.push_back(std::move(reference_token));
-            }
-        }
-
        // iterate the JSON object values
        for (const auto& element : *value.m_data.m_value.object)
        {
@@ -990,7 +951,7 @@ class json_pointer
            // that if the JSON pointer is "" (i.e., points to the whole value),
            // function get_and_create returns a reference to the result itself.
            // An assignment will then create a primitive value.
-            json_pointer(element.first).get_and_create(result, array_parents) = element.second;
+            json_pointer(element.first).get_and_create(result) = element.second;
        }

        return result;
@@ -186,6 +186,15 @@
    #define JSON_NO_UNIQUE_ADDRESS
 #endif

+// Clang targeting MinGW does not survive the thread_local storage the copy
+// constructor uses to bound its descent: every test that copies a value
+// segfaults with clang 11.0.1 and clang 18.1.8, while the same tests pass with
+// GCC targeting MinGW and with every other toolchain the library is tested on.
+// Copying works the same way without the counter, only more slowly.
+#if !defined(JSON_NO_THREAD_LOCAL) && defined(__clang__) && defined(__MINGW32__)
+    #define JSON_NO_THREAD_LOCAL 1
+#endif
+
 // disable documentation warnings on clang
 #if defined(__clang__)
    #pragma clang diagnostic push
@@ -172,18 +172,17 @@ struct has_to_json < BasicJsonType, T, enable_if_t < !is_basic_json<T>::value >>
 template<typename T>
 using detect_key_compare = typename T::key_compare;

-// obtains the actual object key comparator: object_t::key_compare if the
-// object type defines it, and default_object_comparator_t otherwise
-//
-// note detected_or_t is used rather than std::conditional, because the latter
-// names both of its type arguments eagerly; object_t::key_compare would then
-// be a hard error for an object type that does not define it
+template<typename T>
+struct has_key_compare : std::integral_constant<bool, is_detected<detect_key_compare, T>::value> {};
+
+// obtains the actual object key comparator
 template<typename BasicJsonType>
 struct actual_object_comparator
 {
    using object_t = typename BasicJsonType::object_t;
    using object_comparator_t = typename BasicJsonType::default_object_comparator_t;
-    using type = detected_or_t<object_comparator_t, detect_key_compare, object_t>;
+    using type = typename std::conditional < has_key_compare<object_t>::value,
+          typename object_t::key_compare, object_comparator_t>::type;
 };

 template<typename BasicJsonType>
@@ -779,13 +778,6 @@ using has_erase_with_key_type = typename std::conditional <
                                std::true_type,
                                std::false_type >::type;

-template<typename T>
-using detect_capacity = decltype(std::declval<const T&>().capacity());
-
-// type trait to check if a type has a capacity() member function
-template<typename T>
-struct has_capacity : std::integral_constant<bool, is_detected<detect_capacity, T>::value> {};
-
 // a naive helper to check if a type is an ordered_map (exploits the fact that
 // ordered_map inherits capacity() from std::vector)
 template <typename T>
@@ -261,7 +261,7 @@ class binary_writer

                // step 2: write the string
                oa->write_characters(
-                    reinterpret_cast<const CharType*>(j.m_data.m_value.string->data()),
+                    reinterpret_cast<const CharType*>(j.m_data.m_value.string->c_str()),
                    j.m_data.m_value.string->size());
                break;
            }
@@ -581,7 +581,7 @@ class binary_writer

                // step 2: write the string
                oa->write_characters(
-                    reinterpret_cast<const CharType*>(j.m_data.m_value.string->data()),
+                    reinterpret_cast<const CharType*>(j.m_data.m_value.string->c_str()),
                    j.m_data.m_value.string->size());
                break;
            }
@@ -798,7 +798,7 @@ class binary_writer
                }
                write_number_with_ubjson_prefix(j.m_data.m_value.string->size(), true, use_bjdata);
                oa->write_characters(
-                    reinterpret_cast<const CharType*>(j.m_data.m_value.string->data()),
+                    reinterpret_cast<const CharType*>(j.m_data.m_value.string->c_str()),
                    j.m_data.m_value.string->size());
                break;
            }
@@ -813,10 +813,7 @@ class binary_writer
                bool prefix_required = true;
                if (use_type && !j.m_data.m_value.array->empty())
                {
-                    if (!use_count)
-                    {
-                        JSON_THROW(other_error::create(502, "use_type requires use_size = true", &j));
-                    }
+                    JSON_ASSERT(use_count);
                    const CharType first_prefix = ubjson_prefix(j.front(), use_bjdata);
                    const bool same_prefix = std::all_of(j.begin() + 1, j.end(),
                                                         [this, first_prefix, use_bjdata](const BasicJsonType & v)
@@ -862,10 +859,7 @@ class binary_writer

                if (use_type && (bjdata_draft3 || !j.m_data.m_value.binary->empty()))
                {
-                    if (!use_count)
-                    {
-                        JSON_THROW(other_error::create(502, "use_type requires use_size = true", &j));
-                    }
+                    JSON_ASSERT(use_count);
                    oa->write_character(to_char_type('$'));
                    oa->write_character(bjdata_draft3 ? 'B' : 'U');
                }
@@ -887,9 +881,7 @@ class binary_writer
                    for (size_t i = 0; i < j.m_data.m_value.binary->size(); ++i)
                    {
                        oa->write_character(to_char_type(bjdata_draft3 ? 'B' : 'U'));
-                        // the cast is needed for binary types whose value type
-                        // is not an integer (e.g., std::byte)
-                        oa->write_character(to_char_type(static_cast<std::uint8_t>(j.m_data.m_value.binary->data()[i])));
+                        oa->write_character(to_char_type(j.m_data.m_value.binary->data()[i]));
                    }
                }

@@ -919,10 +911,7 @@ class binary_writer
                bool prefix_required = true;
                if (use_type && !j.m_data.m_value.object->empty())
                {
-                    if (!use_count)
-                    {
-                        JSON_THROW(other_error::create(502, "use_type requires use_size = true", &j));
-                    }
+                    JSON_ASSERT(use_count);
                    const CharType first_prefix = ubjson_prefix(j.front(), use_bjdata);
                    const bool same_prefix = std::all_of(j.begin(), j.end(),
                                                         [this, first_prefix, use_bjdata](const BasicJsonType & v)
@@ -950,7 +939,7 @@ class binary_writer
                {
                    write_number_with_ubjson_prefix(el.first.size(), true, use_bjdata);
                    oa->write_characters(
-                        reinterpret_cast<const CharType*>(el.first.data()),
+                        reinterpret_cast<const CharType*>(el.first.c_str()),
                        el.first.size());
                    write_ubjson(el.second, use_count, use_type, prefix_required, use_bjdata, bjdata_version);
                }
@@ -1013,11 +1002,8 @@ class binary_writer
    {
        oa->write_character(to_char_type(element_type));
        oa->write_characters(
-            reinterpret_cast<const CharType*>(name.data()),
-            name.size());
-        // the terminating null byte is written explicitly rather than taken
-        // from the buffer, so that string_t::data() need not be null-terminated
-        oa->write_character(to_char_type(0x00));
+            reinterpret_cast<const CharType*>(name.c_str()),
+            name.size() + 1u);
    }

    /*!
@@ -1058,9 +1044,8 @@ class binary_writer

        write_number<std::int32_t>(to_bson_length(value.size() + 1ul), true);
        oa->write_characters(
-            reinterpret_cast<const CharType*>(value.data()),
-            value.size());
-        oa->write_character(to_char_type(0x00));
+            reinterpret_cast<const CharType*>(value.c_str()),
+            value.size() + 1);
    }

    /*!
@@ -1151,8 +1136,7 @@ class binary_writer

        const std::size_t embedded_document_size = std::accumulate(std::begin(value), std::end(value), static_cast<std::size_t>(0), [&array_index](std::size_t result, const typename BasicJsonType::array_t::value_type & el)
        {
-            const auto key = std::to_string(array_index++);
-            return result + calc_bson_element_size(string_t(key.data(), key.size()), el);
+            return result + calc_bson_element_size(std::to_string(array_index++), el);
        });

        return sizeof(std::int32_t) + embedded_document_size + 1ul;
@@ -1179,11 +1163,7 @@ class binary_writer

        for (const auto& el : value)
        {
-            // the index is built as a std::string, while write_bson_element takes
-            // a string_t; convert explicitly, as the two are only implicitly
-            // convertible for some string types
-            const auto key = std::to_string(array_index++);
-            write_bson_element(string_t(key.data(), key.size()), el);
+            write_bson_element(std::to_string(array_index++), el);
        }

        oa->write_character(to_char_type(0x00));
@@ -135,7 +135,7 @@ class serializer
                    auto i = val.m_data.m_value.object->cbegin();
                    for (std::size_t cnt = 0; cnt < val.m_data.m_value.object->size() - 1; ++cnt, ++i)
                    {
-                        o->write_characters(indent_string.data(), new_indent);
+                        o->write_characters(indent_string.c_str(), new_indent);
                        o->write_character('\"');
                        dump_escaped(i->first, ensure_ascii);
                        o->write_characters("\": ", 3);
@@ -146,14 +146,14 @@ class serializer
                    // last element
                    JSON_ASSERT(i != val.m_data.m_value.object->cend());
                    JSON_ASSERT(std::next(i) == val.m_data.m_value.object->cend());
-                    o->write_characters(indent_string.data(), new_indent);
+                    o->write_characters(indent_string.c_str(), new_indent);
                    o->write_character('\"');
                    dump_escaped(i->first, ensure_ascii);
                    o->write_characters("\": ", 3);
                    dump(i->second, true, ensure_ascii, indent_step, new_indent);

                    o->write_character('\n');
-                    o->write_characters(indent_string.data(), current_indent);
+                    o->write_characters(indent_string.c_str(), current_indent);
                    o->write_character('}');
                }
                else
@@ -208,18 +208,18 @@ class serializer
                    for (auto i = val.m_data.m_value.array->cbegin();
                            i != val.m_data.m_value.array->cend() - 1; ++i)
                    {
-                        o->write_characters(indent_string.data(), new_indent);
+                        o->write_characters(indent_string.c_str(), new_indent);
                        dump(*i, true, ensure_ascii, indent_step, new_indent);
                        o->write_characters(",\n", 2);
                    }

                    // last element
                    JSON_ASSERT(!val.m_data.m_value.array->empty());
-                    o->write_characters(indent_string.data(), new_indent);
+                    o->write_characters(indent_string.c_str(), new_indent);
                    dump(val.m_data.m_value.array->back(), true, ensure_ascii, indent_step, new_indent);

                    o->write_character('\n');
-                    o->write_characters(indent_string.data(), current_indent);
+                    o->write_characters(indent_string.c_str(), current_indent);
                    o->write_character(']');
                }
                else
@@ -265,7 +265,7 @@ class serializer
                        indent_string.resize(indent_string.size() * 2, ' ');
                    }

-                    o->write_characters(indent_string.data(), new_indent);
+                    o->write_characters(indent_string.c_str(), new_indent);

                    o->write_characters("\"bytes\": [", 10);

@@ -274,14 +274,14 @@ class serializer
                        for (auto i = val.m_data.m_value.binary->cbegin();
                                i != val.m_data.m_value.binary->cend() - 1; ++i)
                        {
-                            dump_integer(to_byte_value(*i));
+                            dump_integer(*i);
                            o->write_characters(", ", 2);
                        }
-                        dump_integer(to_byte_value(val.m_data.m_value.binary->back()));
+                        dump_integer(val.m_data.m_value.binary->back());
                    }

                    o->write_characters("],\n", 3);
-                    o->write_characters(indent_string.data(), new_indent);
+                    o->write_characters(indent_string.c_str(), new_indent);

                    o->write_characters("\"subtype\": ", 11);
                    if (val.m_data.m_value.binary->has_subtype())
@@ -293,7 +293,7 @@ class serializer
                        o->write_characters("null", 4);
                    }
                    o->write_character('\n');
-                    o->write_characters(indent_string.data(), current_indent);
+                    o->write_characters(indent_string.c_str(), current_indent);
                    o->write_character('}');
                }
                else
@@ -305,10 +305,10 @@ class serializer
                        for (auto i = val.m_data.m_value.binary->cbegin();
                                i != val.m_data.m_value.binary->cend() - 1; ++i)
                        {
-                            dump_integer(to_byte_value(*i));
+                            dump_integer(*i);
                            o->write_character(',');
                        }
-                        dump_integer(to_byte_value(val.m_data.m_value.binary->back()));
+                        dump_integer(val.m_data.m_value.binary->back());
                    }

                    o->write_characters("],\"subtype\":", 12);
@@ -596,7 +596,7 @@ class serializer
            {
                case error_handler_t::strict:
                {
-                    JSON_THROW(type_error::create(316, concat("incomplete UTF-8 string; last byte: 0x", hex_bytes(static_cast<std::uint8_t>(s[s.size() - 1] | 0))), nullptr));
+                    JSON_THROW(type_error::create(316, concat("incomplete UTF-8 string; last byte: 0x", hex_bytes(static_cast<std::uint8_t>(s.back() | 0))), nullptr));
                }

                case error_handler_t::ignore:
@@ -703,19 +703,6 @@ class serializer
        pos += 6;
    }

-    /*!
-    @brief convert a single element of a binary value to its byte value
-
-    The elements of a binary value are dumped as the numbers 0..255, regardless
-    of the value type of the configured BinaryType: that type may be signed
-    (`char`), unsigned (`std::uint8_t`), or not an integer at all
-    (`std::byte`), none of which @ref dump_integer can handle uniformly.
-    */
-    static std::uint8_t to_byte_value(binary_char_t x) noexcept
-    {
-        return static_cast<std::uint8_t>(x);
-    }
-
    // templates to avoid warnings about useless casts
    template <typename NumberType, enable_if_t<std::is_signed<NumberType>::value, int> = 0>
    bool is_negative_number(NumberType x)
@@ -741,7 +728,8 @@ class serializer
    template < typename NumberType, detail::enable_if_t <
                   std::is_integral<NumberType>::value ||
                   std::is_same<NumberType, number_unsigned_t>::value ||
-                   std::is_same<NumberType, number_integer_t>::value,
+                   std::is_same<NumberType, number_integer_t>::value ||
+                   std::is_same<NumberType, binary_char_t>::value,
                   int > = 0 >
    void dump_integer(NumberType x)
    {
@@ -8,56 +8,50 @@

 #pragma once

-#include <cstddef> // size_t
-
 #include <nlohmann/detail/abi_macros.hpp>

 NLOHMANN_JSON_NAMESPACE_BEGIN
 namespace detail
 {

+/*!
+@brief replace all occurrences of a substring by another string
+
+@param[in,out] s  the string to manipulate; changed so that all
+               occurrences of @a f are replaced with @a t
+@param[in]     f  the substring to replace with @a t
+@param[in]     t  the string to replace @a f
+
+@pre The search string @a f must not be empty. **This precondition is
+enforced with an assertion.**
+
+@since version 2.0.0
+*/
+template<typename StringType>
+inline void replace_substring(StringType& s, const StringType& f,
+                              const StringType& t)
+{
+    JSON_ASSERT(!f.empty());
+    for (auto pos = s.find(f);                // find the first occurrence of f
+            pos != StringType::npos;          // make sure f was found
+            s.replace(pos, f.size(), t),      // replace with t, and
+            pos = s.find(f, pos + t.size()))  // find the next occurrence of f
+    {}
+}
+
 /*!
 * @brief string escaping as described in RFC 6901 (Sect. 4)
 * @param[in] s string to escape
 * @return    escaped string
 *
 * Note the order of escaping "~" to "~0" and "/" to "~1" is important.
- *
- * The string is rebuilt in a single pass, appending whole runs between the
- * characters that need escaping. Scanning with find_first_of() keeps the
- * common case -- nothing to escape -- as fast as a single search, while
- * repeated replace() calls would move the tail of the string once per
- * escaped character.
 */
 template<typename StringType>
-inline StringType escape(const StringType& s)
+inline StringType escape(StringType s)
 {
-    auto next_special = [&s](std::size_t from)
-    {
-        const auto tilde = s.find_first_of('~', from);
-        const auto slash = s.find_first_of('/', from);
-        return tilde < slash ? tilde : slash; // npos is the largest value
-    };
-
-    auto pos = next_special(0);
-    if (pos == StringType::npos)
-    {
-        return s;
-    }
-
-    StringType result;
-    result.reserve(s.size() + 2);
-
-    std::size_t run = 0;
-    while (pos != StringType::npos)
-    {
-        result.append(s.data() + run, pos - run);
-        result.append(s[pos] == '~' ? "~0" : "~1", 2);
-        run = pos + 1;
-        pos = next_special(run);
-    }
-    result.append(s.data() + run, s.size() - run);
-    return result;
+    replace_substring(s, StringType{"~"}, StringType{"~0"});
+    replace_substring(s, StringType{"/"}, StringType{"~1"});
+    return s;
 }

 /*!
@@ -66,43 +60,12 @@ inline StringType escape(const StringType& s)
 * @return    unescaped string
 *
 * Note the order of escaping "~1" to "/" and "~0" to "~" is important.
- *
- * Rebuilt in a single pass, see @ref escape. A "~" that is followed by
- * neither "0" nor "1" is passed through unchanged; @ref json_pointer rejects
- * such input before it gets here.
 */
 template<typename StringType>
 inline void unescape(StringType& s)
 {
-    auto pos = s.find_first_of('~', 0);
-    if (pos == StringType::npos)
-    {
-        return;
-    }
-
-    StringType result;
-    result.reserve(s.size());
-
-    std::size_t run = 0;
-    while (pos != StringType::npos)
-    {
-        result.append(s.data() + run, pos - run);
-
-        const auto next = pos + 1;
-        if (next < s.size() && (s[next] == '0' || s[next] == '1'))
-        {
-            result.append(s[next] == '0' ? "~" : "/", 1);
-            run = pos + 2;
-        }
-        else
-        {
-            result.append("~", 1);
-            run = pos + 1;
-        }
-        pos = s.find_first_of('~', run);
-    }
-    result.append(s.data() + run, s.size() - run);
-    s = result;
+    replace_substring(s, StringType{"~1"}, StringType{"/"});
+    replace_substring(s, StringType{"~0"}, StringType{"~"});
 }

 }  // namespace detail
@@ -216,6 +216,57 @@ TEST_CASE("controlled bad_alloc")
            CHECK_THROWS_AS(my_json(s), std::bad_alloc&);
            next_construct_fails = false;
        }
+
+        SECTION("basic_json(const basic_json&) of a deeply nested value (#5387)")
+        {
+            // Copying a value nested deeper than the descent bound builds the
+            // copy from the top down: every value whose own copy has not been
+            // made yet stays a null value until it is. Failing an allocation
+            // part-way through is what proves such a half-built copy can still
+            // be destroyed.
+            //
+            // Which path the failure lands in depends on the build: the first
+            // allocation of a copy belongs to the outermost level, so here it
+            // is the descending one. Built with JSON_NO_THREAD_LOCAL - as the
+            // ci_test_no_thread_local target builds the whole suite - no
+            // descent is made at all and the very same failure lands in the
+            // iterative path instead, part-way through its worklist.
+            const auto check_deep_copy = [](bool objects)
+            {
+                CAPTURE(objects);
+
+                next_construct_fails = false;
+
+                // deeper than the 128 levels the copy constructor descends into
+                const std::size_t depth = 300;
+
+                my_json j = 1;
+                for (std::size_t i = 0; i < depth; ++i)
+                {
+                    if (objects)
+                    {
+                        my_json wrapper = my_json::object();
+                        wrapper["a"] = std::move(j);
+                        j = std::move(wrapper);
+                    }
+                    else
+                    {
+                        j = my_json::array({std::move(j)});
+                    }
+                }
+
+                // NOLINTNEXTLINE(performance-unnecessary-copy-initialization): the copy is what is tested
+                CHECK_NOTHROW(my_json(j));
+
+                next_construct_fails = true;
+                // NOLINTNEXTLINE(performance-unnecessary-copy-initialization): the copy is what is tested
+                CHECK_THROWS_AS(my_json(j), std::bad_alloc&);
+                next_construct_fails = false;
+            };
+
+            check_deep_copy(false);
+            check_deep_copy(true);
+        }
    }
 }

@@ -11,10 +11,8 @@

 #include <nlohmann/json.hpp>

-#include <cstdint>
 #include <string>
 #include <utility>
-#include <vector>

 /* forward declarations */
 class alt_string;
@@ -24,10 +22,6 @@ void int_to_string(alt_string& target, std::size_t value); // NOLINT(misc-use-in
 /*
 * This is virtually a string class.
 * It covers std::string under the hood.
- *
- * It deliberately does not provide c_str(), back(), find(str, pos), replace(),
- * or substr(): the library must not rely on them. Do not add members here
- * without checking that the library actually needs them.
 */
 class alt_string
 {
@@ -112,6 +106,11 @@ class alt_string
        return str_impl < op.str_impl;
    }

+    const char* c_str() const
+    {
+        return str_impl.c_str();
+    }
+
    char& operator[](std::size_t index)
    {
        return str_impl[index];
@@ -122,6 +121,16 @@ class alt_string
        return str_impl[index];
    }

+    char& back()
+    {
+        return str_impl.back();
+    }
+
+    const char& back() const
+    {
+        return str_impl.back();
+    }
+
    void clear()
    {
        str_impl.clear();
@@ -137,11 +146,28 @@ class alt_string
        return str_impl.empty();
    }

+    std::size_t find(const alt_string& str, std::size_t pos = 0) const
+    {
+        return str_impl.find(str.str_impl, pos);
+    }
+
    std::size_t find_first_of(char c, std::size_t pos = 0) const
    {
        return str_impl.find_first_of(c, pos);
    }

+    alt_string substr(std::size_t pos = 0, std::size_t count = npos) const
+    {
+        const std::string s = str_impl.substr(pos, count);
+        return {s.data(), s.size()};
+    }
+
+    alt_string& replace(std::size_t pos, std::size_t count, const alt_string& str)
+    {
+        str_impl.replace(pos, count, str.str_impl);
+        return *this;
+    }
+
    void reserve( std::size_t new_cap = 0 )
    {
        str_impl.reserve(new_cap);
@@ -176,31 +202,6 @@ bool operator<(const char* op1, const alt_string& op2) noexcept

 TEST_CASE("alternative string type")
 {
-    SECTION("binary formats")
-    {
-        alt_json doc;
-        doc["pi"] = 3.141;
-        doc["happy"] = true;
-        doc["list"] = {1, 2, 3};
-
-        CHECK(alt_json::from_cbor(alt_json::to_cbor(doc)) == doc);
-        CHECK(alt_json::from_msgpack(alt_json::to_msgpack(doc)) == doc);
-        // BSON is not covered: it additionally needs string_t::find(value_type),
-        // which alt_string does not provide
-        CHECK(alt_json::from_ubjson(alt_json::to_ubjson(doc)) == doc);
-
-        // a UBJSON high-precision number is parsed into a std::string that the
-        // reader has to hand to the SAX interface as an alt_string
-        const std::vector<uint8_t> high_precision =
-        {
-            'H', 'i', 0x16, '3', '.', '1', '4', '1', '5', '9', '2', '6', '5', '3',
-            '5', '8', '9', '7', '9', '3', '2', '3', '8', '4', '6'
-        };
-        const auto number = alt_json::from_ubjson(high_precision);
-        CHECK(number.is_number_float());
-        CHECK(number.get<double>() == doctest::Approx(3.14159265358979323846));
-    }
-
    SECTION("dump")
    {
        {
@@ -331,15 +332,6 @@ TEST_CASE("alternative string type")

        CHECK(j.at(alt_json::json_pointer("/foo/0")) == j["foo"][0]);
        CHECK(j.at(alt_json::json_pointer("/foo/1")) == j["foo"][1]);
-
-        // RFC 6901 escaping works without string_t::find(str, pos), replace(),
-        // and substr()
-        auto j2 = alt_json::parse(R"({"a/b": 1, "m~n": 2, "~/~~//": 3})");
-        CHECK(j2.at(alt_json::json_pointer("/a~1b")) == 1);
-        CHECK(j2.at(alt_json::json_pointer("/m~0n")) == 2);
-        CHECK(j2.at(alt_json::json_pointer("/~0~1~0~0~1~1")) == 3);
-        CHECK(alt_json::json_pointer("/~0~1~0~0~1~1").to_string() == alt_string("/~0~1~0~0~1~1"));
-        CHECK(j2.flatten().unflatten() == j2);
    }

    SECTION("patch")
@@ -3843,48 +3843,6 @@ TEST_CASE("all BJData first bytes")
 }
 #endif

-TEST_CASE("BJData use_type requires use_size")
-{
-    SECTION("non-empty object throws other_error.502")
-    {
-        const json j = {{"a", 1}, {"b", 2}};
-        CHECK_THROWS_WITH_AS(json::to_bjdata(j, false, true),
-                             "[json.exception.other_error.502] use_type requires use_size = true",
-                             json::other_error&);
-    }
-
-    SECTION("non-empty array throws other_error.502")
-    {
-        const json j = {1, 2, 3};
-        CHECK_THROWS_WITH_AS(json::to_bjdata(j, false, true),
-                             "[json.exception.other_error.502] use_type requires use_size = true",
-                             json::other_error&);
-    }
-
-    SECTION("scalars do not throw with use_type=true, use_count=false")
-    {
-        CHECK_NOTHROW(json::to_bjdata(42, false, true));
-        CHECK_NOTHROW(json::to_bjdata(3.14, false, true));
-        CHECK_NOTHROW(json::to_bjdata("hello", false, true));
-        CHECK_NOTHROW(json::to_bjdata(true, false, true));
-        CHECK_NOTHROW(json::to_bjdata(nullptr, false, true));
-    }
-
-    SECTION("empty containers do not throw with use_type=true, use_count=false")
-    {
-        CHECK_NOTHROW(json::to_bjdata(json::array(), false, true));
-        CHECK_NOTHROW(json::to_bjdata(json::object(), false, true));
-    }
-
-    SECTION("valid combinations on non-empty containers")
-    {
-        const json j = {{"a", 1}, {"b", 2}};
-        CHECK_NOTHROW(json::to_bjdata(j, false, false));
-        CHECK_NOTHROW(json::to_bjdata(j, true, false));
-        CHECK_NOTHROW(json::to_bjdata(j, true, true));
-    }
-}
-
 TEST_CASE("BJData roundtrips" * doctest::skip())
 {
    SECTION("input from self-generated BJData files")
@@ -1,136 +0,0 @@
-//     __ _____ _____ _____
-//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
-// |  |  |__   |  |  | | | |  version 3.12.0
-// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
-//
-// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
-// SPDX-License-Identifier: MIT
-
-#include "doctest_compatibility.h"
-
-#include <nlohmann/json.hpp>
-
-#include <deque>
-#include <map>
-#include <memory>
-#include <string>
-#include <type_traits>
-#include <vector>
-
-namespace
-{
-
-// std::deque has no capacity() member function, which the library only needs
-// to detect a reallocation for JSON_DIAGNOSTICS
-using deque_json = nlohmann::basic_json<std::map, std::deque>;
-
-// a std::vector whose at() is hidden: the library performs its own bounds
-// check and must not fall back to the container's checked accessor
-template<class T, class Allocator = std::allocator<T>>
-class vector_without_at : public std::vector<T, Allocator>
-{
-  public:
-    using std::vector<T, Allocator>::vector;
-
-    void at() = delete;
-};
-
-using no_at_json = nlohmann::basic_json<std::map, vector_without_at>;
-
-} // namespace
-
-TEST_CASE("array type without capacity()")
-{
-    SECTION("the iterators of the default configuration stay nothrow movable")
-    {
-        // basic_json's iterators take their exception specification from the
-        // container iterators; std::deque's is not nothrow move constructible
-        // with older standard libraries, which must not cost the default
-        // configuration its noexcept
-        CHECK(std::is_nothrow_move_constructible<nlohmann::json::iterator>::value);
-        CHECK(std::is_nothrow_move_assignable<nlohmann::json::iterator>::value);
-        CHECK(std::is_nothrow_move_constructible<nlohmann::json::const_iterator>::value);
-        CHECK(std::is_move_constructible<deque_json::iterator>::value);
-        CHECK(std::is_move_assignable<deque_json::iterator>::value);
-    }
-
-    SECTION("adding elements")
-    {
-        deque_json j = deque_json::array();
-        j.push_back(1);
-        j.push_back("two");
-        j.emplace_back(3);
-        j += 4;
-
-        CHECK(j.size() == 4);
-        CHECK(j == deque_json({1, "two", 3, 4}));
-        CHECK(j.back() == 4);
-        CHECK(j.front() == 1);
-    }
-
-    SECTION("accessing and modifying elements")
-    {
-        auto j = deque_json::parse(R"([1,2,3])");
-
-        CHECK(j[1] == 2);
-        CHECK(j.at(2) == 3);
-
-        // growing through operator[] fills up with null values
-        j[5] = 6;
-        CHECK(j.size() == 6);
-        CHECK(j[4].is_null());
-        CHECK(j[5] == 6);
-
-        j.erase(0);
-        CHECK(j == deque_json({2, 3, nullptr, nullptr, 6}));
-
-        auto it = j.erase(j.begin());
-        CHECK(*it == 3);
-
-        j.insert(j.begin(), 1);
-        CHECK(j.front() == 1);
-    }
-
-    SECTION("serialization and deserialization")
-    {
-        const auto j = deque_json::parse(R"({"a":[1,[2,3]],"b":[]})");
-        CHECK(j.dump() == R"({"a":[1,[2,3]],"b":[]})");
-        CHECK(deque_json::parse(j.dump()) == j);
-        CHECK(deque_json::from_cbor(deque_json::to_cbor(j)) == j);
-
-        // empty containers are flattened to null and cannot be restored
-        const auto nested = deque_json::parse(R"({"a":[1,[2,3]]})");
-        CHECK(nested.flatten().unflatten() == nested);
-    }
-
-    SECTION("references stay valid while the array grows")
-    {
-        deque_json j = deque_json::array();
-        j.push_back(1);
-        auto& first = j[0];
-        for (int i = 0; i < 100; ++i)
-        {
-            j.push_back(i);
-        }
-        CHECK(&first == &j[0]);
-        CHECK(first == 1);
-    }
-}
-
-TEST_CASE("array type without at()")
-{
-    // built in memory rather than parsed, so that the exception message does
-    // not gain a byte range with JSON_DIAGNOSTIC_POSITIONS
-    no_at_json j = {1, 2, 3};
-    const auto& jc = j;
-
-    CHECK(j.at(0) == 1);
-    CHECK(j.at(2) == 3);
-    CHECK(jc.at(2) == 3);
-
-    CHECK_THROWS_WITH_AS(j.at(3), "[json.exception.out_of_range.401] array index 3 is out of range", no_at_json::out_of_range);
-    CHECK_THROWS_WITH_AS(jc.at(3), "[json.exception.out_of_range.401] array index 3 is out of range", no_at_json::out_of_range);
-
-    CHECK(j.at(no_at_json::json_pointer("/1")) == 2);
-    CHECK_THROWS_AS(j.at(no_at_json::json_pointer("/3")), no_at_json::out_of_range);
-}
@@ -1,79 +0,0 @@
-//     __ _____ _____ _____
-//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
-// |  |  |__   |  |  | | | |  version 3.12.0
-// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
-//
-// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
-// SPDX-License-Identifier: MIT
-
-#include "doctest_compatibility.h"
-
-#include <nlohmann/json.hpp>
-
-#include <cstdint>
-#include <functional>
-#include <map>
-#include <memory>
-#include <string>
-#include <vector>
-
-#ifdef JSON_HAS_CPP_17
-    #include <cstddef>
-#endif
-
-namespace
-{
-
-// a BinaryType whose value type is signed: the elements must still be
-// processed as the numbers 0..255
-using char_binary_json = nlohmann::basic_json <
-                         std::map, std::vector, std::string, bool, std::int64_t, std::uint64_t,
-                         double, std::allocator, nlohmann::adl_serializer, std::vector<char>, void >;
-
-#ifdef JSON_HAS_CPP_17
-    // a BinaryType whose value type is not an integer type at all
-    using byte_binary_json = nlohmann::basic_json <
-    std::map, std::vector, std::string, bool, std::int64_t, std::uint64_t,
-    double, std::allocator, nlohmann::adl_serializer, std::vector<std::byte>, void >;
-#endif
-
-} // namespace
-
-TEST_CASE("binary type whose value type is not std::uint8_t")
-{
-    SECTION("a signed value type does not dump negative numbers")
-    {
-        const std::vector<char> chars{'\0', '\x01', '\xFF'};
-        CHECK(char_binary_json::binary(chars).dump() == R"({"bytes":[0,1,255],"subtype":null})");
-        CHECK(char_binary_json::binary(chars, 42).dump() == R"({"bytes":[0,1,255],"subtype":42})");
-        CHECK(char_binary_json::binary({}).dump() == R"({"bytes":[],"subtype":null})");
-    }
-
-    SECTION("the default binary type is unchanged")
-    {
-        CHECK(nlohmann::json::binary({0, 1, 255}, 42).dump() == R"({"bytes":[0,1,255],"subtype":42})");
-    }
-
-#ifdef JSON_HAS_CPP_17
-    SECTION("dumping a value type that is not an integer")
-    {
-        const std::vector<std::byte> bytes{std::byte{0}, std::byte{1}, std::byte{0xFF}};
-        CHECK(byte_binary_json::binary(bytes).dump() == R"({"bytes":[0,1,255],"subtype":null})");
-        CHECK(byte_binary_json::binary(bytes, 42).dump() == R"({"bytes":[0,1,255],"subtype":42})");
-        CHECK(byte_binary_json::binary({}).dump() == R"({"bytes":[],"subtype":null})");
-    }
-
-    SECTION("hashing and the binary formats")
-    {
-        const std::vector<std::byte> bytes{std::byte{0}, std::byte{1}, std::byte{0xFF}};
-        const auto j = byte_binary_json::binary(bytes);
-
-        CHECK(std::hash<byte_binary_json> {}(j) == std::hash<byte_binary_json> {}(j));
-        CHECK(byte_binary_json::from_cbor(byte_binary_json::to_cbor(j)) == j);
-        CHECK(byte_binary_json::from_msgpack(byte_binary_json::to_msgpack(j)) == j);
-
-        // UBJSON has no binary type, so binary values are written as an array
-        CHECK(byte_binary_json::from_ubjson(byte_binary_json::to_ubjson(j)) == byte_binary_json({0, 1, 255}));
-    }
-#endif
-}
@@ -1,187 +0,0 @@
-//     __ _____ _____ _____
-//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
-// |  |  |__   |  |  | | | |  version 3.12.0
-// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
-//
-// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
-// SPDX-License-Identifier: MIT
-
-#include "doctest_compatibility.h"
-
-#include <nlohmann/json.hpp>
-
-#include <cstdint>
-#include <map>
-#include <string>
-#include <type_traits>
-#include <utility>
-#include <vector>
-
-namespace
-{
-
-// An ObjectType that does *not* define a key_compare member type, which is
-// what every hash map looks like to the library.
-//
-// A hash map is deliberately not used here: object_t is probed for
-// key_compare inside the definition of basic_json, that is, while basic_json
-// is still an incomplete type, and whether a hash map can be instantiated
-// with an incomplete mapped type depends on the standard library (libstdc++ 9
-// needs the size of the mapped type for its node type and rejects it). So the
-// object type is built from std::map, and the inherited key_compare member
-// type is shadowed by an entity that is not a type -- the library's probe
-// then finds no type, exactly as for a hash map.
-template<class Key, class T, class Compare, class Allocator>
-struct no_key_compare_map : std::map<Key, T, Compare, Allocator>
-{
-    using base_t = std::map<Key, T, Compare, Allocator>;
-    using base_t::base_t;
-
-    // shadows base_t::key_compare, which is a type; never defined or called
-    void key_compare();
-};
-
-using no_key_compare_json = nlohmann::basic_json<no_key_compare_map>;
-
-// An ObjectType whose erase(iterator) returns void rather than the following
-// iterator, as for instance Abseil's hash maps do
-template<class Key, class T, class Compare, class Allocator>
-struct void_erase_map : std::map<Key, T, Compare, Allocator>
-{
-    using base_t = std::map<Key, T, Compare, Allocator>;
-    using base_t::base_t;
-    using iterator = typename base_t::iterator;
-    using base_t::erase;
-
-    void erase(iterator pos)
-    {
-        base_t::erase(pos);
-    }
-};
-
-using void_erase_json = nlohmann::basic_json<void_erase_map>;
-
-} // namespace
-
-TEST_CASE("object type whose erase() returns void")
-{
-    SECTION("erasing every element through the returned iterator")
-    {
-        void_erase_json j;
-        for (int i = 0; i < 8; ++i)
-        {
-            j["k" + std::to_string(i)] = i;
-        }
-
-        std::size_t erased = 0;
-        for (auto it = j.begin(); it != j.end(); ++erased)
-        {
-            it = j.erase(it);
-        }
-        CHECK(erased == 8);
-        CHECK(j.empty());
-    }
-
-    SECTION("erasing in the middle returns the following element")
-    {
-        void_erase_json j;
-        for (int i = 0; i < 4; ++i)
-        {
-            j["k" + std::to_string(i)] = i;
-        }
-
-        auto it = j.begin();
-        ++it;
-        const auto after = j.erase(it);
-        CHECK(j.size() == 3);
-        CHECK(after.key() == "k2");
-        CHECK(after.value() == 2);
-        CHECK(!j.contains("k1"));
-    }
-
-    SECTION("the other erase overloads are unaffected")
-    {
-        void_erase_json j;
-        j["a"] = 1;
-        j["b"] = 2;
-        j["c"] = 3;
-
-        CHECK(j.erase("a") == 1);
-        CHECK(j.erase("nope") == 0);
-        j.erase(j.begin(), j.end());
-        CHECK(j.empty());
-    }
-}
-
-TEST_CASE("object type without key_compare")
-{
-    SECTION("object_comparator_t falls back to default_object_comparator_t")
-    {
-        CHECK(std::is_same < no_key_compare_json::object_comparator_t,
-              no_key_compare_json::default_object_comparator_t >::value);
-    }
-
-    SECTION("object types defining key_compare are unaffected")
-    {
-        CHECK(std::is_same<nlohmann::json::object_comparator_t,
-              nlohmann::json::object_t::key_compare>::value);
-        CHECK(std::is_same<nlohmann::ordered_json::object_comparator_t,
-              nlohmann::ordered_json::object_t::key_compare>::value);
-    }
-
-    SECTION("creating and accessing values")
-    {
-        no_key_compare_json j;
-        j["one"] = 1;
-        j["two"] = "zwei";
-        j["three"]["nested"] = true;
-
-        CHECK(j.size() == 3);
-        CHECK(j.at("one") == 1);
-        CHECK(j["two"] == "zwei");
-        CHECK(j["three"]["nested"] == true);
-        CHECK(j.contains("one"));
-        CHECK(!j.contains("four"));
-        CHECK(j.find("one") != j.end());
-        CHECK(j.count("one") == 1);
-        CHECK(j.erase("one") == 1);
-        CHECK(j.size() == 2);
-    }
-
-    SECTION("serialization and deserialization")
-    {
-        const auto j = no_key_compare_json::parse(R"({"a":[1,2,3],"b":{"c":null}})");
-        CHECK(j["a"].size() == 3);
-        CHECK(j["a"][2] == 3);
-        CHECK(j["b"]["c"].is_null());
-        CHECK(no_key_compare_json::parse(j.dump()) == j);
-    }
-
-    SECTION("binary formats")
-    {
-        const auto j = no_key_compare_json::parse(R"({"a":[1,2,3],"b":"x"})");
-        CHECK(no_key_compare_json::from_cbor(no_key_compare_json::to_cbor(j)) == j);
-        CHECK(no_key_compare_json::from_msgpack(no_key_compare_json::to_msgpack(j)) == j);
-    }
-
-    SECTION("flatten and unflatten")
-    {
-        // "o" has a key that looks like an array index, so unflatten() must
-        // not turn it into an array
-        const auto j = no_key_compare_json::parse(
-                           R"({"c":[1,2,3],"d":{"e":"s"},"n":[[0,1],[2]],"o":{"2":"x"}})");
-        CHECK(j.flatten().unflatten() == j);
-    }
-
-    SECTION("conversion to and from nlohmann::json")
-    {
-        const auto j = no_key_compare_json::parse(R"({"a":1,"b":[true,null]})");
-        const nlohmann::json converted(j);
-
-        CHECK(converted.is_object());
-        CHECK(converted["a"] == 1);
-        CHECK(converted["b"][0] == true);
-        CHECK(converted["b"][1].is_null());
-        CHECK(no_key_compare_json(converted) == j);
-    }
-}
@@ -68,6 +68,72 @@ TEST_CASE("Better diagnostics with positions")
        CHECK(j.end_pos() == root.size());
    }

+    SECTION("copying keeps the positions of nested values (#5387)")
+    {
+        // Values nested deeper than the copy constructor's descent bound are
+        // copied without the call stack, on a path that has to carry the
+        // positions over itself; shallower ones copy their containers, which
+        // bring the positions along. Both sides of the bound are checked here.
+        const auto check_copy = [](std::size_t depth, bool objects)
+        {
+            CAPTURE(depth)
+            CAPTURE(objects)
+
+            const std::string opening = objects ? R"({"a":)" : "[";
+            const std::string closing = objects ? "}" : "]";
+
+            std::string text;
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                text += opening;
+            }
+            text += "12";
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                text += closing;
+            }
+
+            const json original = json::parse(text);
+            const json copy(original); // NOLINT(performance-unnecessary-copy-initialization)
+
+            const json* o = &original;
+            const json* c = &copy;
+            for (std::size_t level = 0; level <= depth; ++level)
+            {
+                CAPTURE(level)
+                REQUIRE(c->start_pos() == o->start_pos());
+                REQUIRE(c->end_pos() == o->end_pos());
+
+                if (level < depth)
+                {
+                    o = objects ? &o->at("a") : &o->at(0);
+                    c = objects ? &c->at("a") : &c->at(0);
+                }
+            }
+        };
+
+        const auto check_arrays = [&check_copy](std::size_t depth)
+        {
+            check_copy(depth, false);
+        };
+        const auto check_objects = [&check_copy](std::size_t depth)
+        {
+            check_copy(depth, true);
+        };
+
+        check_arrays(1);
+        check_arrays(127);
+        check_arrays(128);
+        check_arrays(129);
+        check_arrays(300);
+
+        check_objects(1);
+        check_objects(127);
+        check_objects(128);
+        check_objects(129);
+        check_objects(300);
+    }
+
    SECTION("JSON patch add to primitive parent (#4292)")
    {
        // the JSON Patch "add" target /foo/bar/baz has a string parent
@@ -273,5 +273,62 @@ TEST_CASE("Regression tests for extended diagnostics")
        CHECK(j1["numbers"]["two"] == 2);
        CHECK(j1["string"] == "t");
    }
+
+    SECTION("Regression test for issue #5387 - copying keeps the parents of nested values")
+    {
+        // A value nested deeper than the copy constructor's descent bound is
+        // copied without the call stack. Every container that path creates has
+        // to have the parents of its children set, or the JSON Pointer in the
+        // diagnostic is cut short.
+        const std::size_t depth = 300;
+
+        SECTION("objects")
+        {
+            json j = "not a number";
+            std::string pointer;
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                j = json{{"a", j}};
+                pointer += "/a";
+            }
+
+            json const copy(j); // NOLINT(performance-unnecessary-copy-initialization)
+
+            const json* inner = &copy;
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                inner = &inner->at("a");
+            }
+
+            std::string const expected = "[json.exception.type_error.302] (" + pointer + ") type must be number, but is string";
+            int i = 0;
+            CHECK_THROWS_WITH_AS(i = inner->get<int>(), expected.c_str(), json::type_error);
+            CHECK(i == 0);
+        }
+
+        SECTION("arrays")
+        {
+            json j = "not a number";
+            std::string pointer;
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                j = json::array({j});
+                pointer += "/0";
+            }
+
+            json const copy(j); // NOLINT(performance-unnecessary-copy-initialization)
+
+            const json* inner = &copy;
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                inner = &inner->at(0);
+            }
+
+            std::string const expected = "[json.exception.type_error.302] (" + pointer + ") type must be number, but is string";
+            int i = 0;
+            CHECK_THROWS_WITH_AS(i = inner->get<int>(), expected.c_str(), json::type_error);
+            CHECK(i == 0);
+        }
+    }
 }

@@ -465,16 +465,6 @@ TEST_CASE("JSON pointers")
        // explicit roundtrip check
        CHECK(j.flatten().unflatten() == j);

-        // an object is only unflattened to an array if one of its keys is the
-        // reference token 0; this must not depend on which key is seen first
-        CHECK(json({{"/2", "x"}}).unflatten() == json({{"2", "x"}}));
-        CHECK(json({{"/10", "y"}, {"/2", "z"}}).unflatten() == json({{"10", "y"}, {"2", "z"}}));
-        CHECK(json({{"/0", 1}, {"/1", 2}}).unflatten() == json({1, 2}));
-        CHECK(json({{"/1", 2}, {"/0", 1}}).unflatten() == json({1, 2}));
-        CHECK(json({{"/0", 1}, {"/2", 3}}).unflatten() == json({1, nullptr, 3}));
-        CHECK(json({{"/a/1", 2}, {"/a/0", 1}}).unflatten() == json({{"a", {1, 2}}}));
-        CHECK(json({{"/a/1", 2}, {"/a/x", 1}}).unflatten() == json({{"a", {{"1", 2}, {"x", 1}}}}));
-
        // roundtrip for primitive values
        json j_null;
        CHECK(j_null.flatten().unflatten() == j_null);
@@ -12,6 +12,7 @@
 using nlohmann::json;

 #include <algorithm>
+#include <string>

 TEST_CASE("tests on very large JSONs")
 {
@@ -27,3 +28,201 @@ TEST_CASE("tests on very large JSONs")
    }
 }

+namespace
+{
+
+// Descend a chain of single-element containers and return the value at its end,
+// reporting the number of levels traversed in @a depth.
+//
+// The values in the test case below are nested far deeper than the call stack
+// can follow, so they must not be inspected with operator== or dump(): both are
+// still recursive and would overflow the stack themselves.
+const json* innermost_value(const json& j, std::size_t& depth)
+{
+    const json* current = &j;
+    depth = 0;
+
+    while ((current->is_array() || current->is_object()) && !current->empty())
+    {
+        current = current->is_array()
+                  ? &current->front()
+                  : &current->begin().value();
+        ++depth;
+    }
+
+    return current;
+}
+
+} // namespace
+
+TEST_CASE("tests on deeply nested JSONs")
+{
+    // deep enough to exhaust the call stack, but small enough to stay cheap:
+    // parsing is iterative, so building the values below costs little
+    const std::size_t depth = 100000;
+
+    SECTION("issue #5387 - stack overflow in the copy constructor")
+    {
+        SECTION("array")
+        {
+            const json j = json::parse(std::string(depth, '[') + '0' + std::string(depth, ']'));
+
+            const json copy(j); // NOLINT(performance-unnecessary-copy-initialization): the copy is what is tested
+
+            std::size_t copy_depth = 0;
+            CHECK(*innermost_value(copy, copy_depth) == 0);
+            CHECK(copy_depth == depth);
+        }
+
+        SECTION("object")
+        {
+            std::string s;
+            s.reserve((6 * depth) + 1);
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                s += "{\"a\":";
+            }
+            s += '1';
+            s.append(depth, '}');
+
+            const json j = json::parse(s);
+
+            const json copy(j); // NOLINT(performance-unnecessary-copy-initialization): the copy is what is tested
+
+            std::size_t copy_depth = 0;
+            CHECK(*innermost_value(copy, copy_depth) == 1);
+            CHECK(copy_depth == depth);
+        }
+
+        SECTION("copy assignment")
+        {
+            // operator=(basic_json) takes its argument by value, so the deep
+            // copy happens in the copy constructor
+            const json j = json::parse(std::string(depth, '[') + '0' + std::string(depth, ']'));
+
+            json target;
+            target = j;
+
+            std::size_t target_depth = 0;
+            CHECK(*innermost_value(target, target_depth) == 0);
+            CHECK(target_depth == depth);
+        }
+
+        SECTION("depths around the bound of the recursive descent")
+        {
+            // The copy constructor descends into a bounded number of levels and
+            // completes whatever is below that without the call stack. Cover
+            // every depth around that bound, so that the two ways of copying
+            // are known to meet cleanly - wherever the bound is set.
+            for (std::size_t d = 1; d <= 300; ++d)
+            {
+                CAPTURE(d);
+
+                const json array = json::parse(std::string(d, '[') + '0' + std::string(d, ']'));
+                const json array_copy(array); // NOLINT(performance-unnecessary-copy-initialization): the copy is what is tested
+                std::size_t array_depth = 0;
+                CHECK(*innermost_value(array_copy, array_depth) == 0);
+                CHECK(array_depth == d);
+
+                std::string object_text;
+                for (std::size_t i = 0; i < d; ++i)
+                {
+                    object_text += "{\"a\":";
+                }
+                object_text += '1';
+                object_text.append(d, '}');
+
+                const json object = json::parse(object_text);
+                const json object_copy(object); // NOLINT(performance-unnecessary-copy-initialization): the copy is what is tested
+                std::size_t object_depth = 0;
+                CHECK(*innermost_value(object_copy, object_depth) == 1);
+                CHECK(object_depth == d);
+            }
+        }
+
+        SECTION("a value that is deep in one place only")
+        {
+            json j = json::object();
+            j["shallow"] = 1;
+            j["deep"] = json::parse(std::string(depth, '[') + '0' + std::string(depth, ']'));
+            j["also_shallow"] = json::array({1, 2, 3});
+
+            const json copy(j);
+
+            CHECK(copy["shallow"] == 1);
+            CHECK(copy["also_shallow"] == json::array({1, 2, 3}));
+
+            std::size_t deep_depth = 0;
+            CHECK(*innermost_value(copy["deep"], deep_depth) == 0);
+            CHECK(deep_depth == depth);
+        }
+
+        SECTION("comparing")
+        {
+            // Comparing used to descend once per level, and an ordered
+            // comparison used to compare every pair of elements twice, once in
+            // each direction, which took exponentially long in the nesting
+            // depth. Both are gone: these finish in milliseconds, where the
+            // second used to take longer than anyone would wait even for a
+            // value nested only a few dozen levels deep.
+            const std::string text = std::string(depth, '[') + '0' + std::string(depth, ']');
+            const json j = json::parse(text);
+            const json same = json::parse(text);
+            const json larger = json::parse(std::string(depth, '[') + '1' + std::string(depth, ']'));
+
+            CHECK(j == same);
+            CHECK_FALSE(j == larger);
+            CHECK(j != larger);
+
+            CHECK(j < larger);
+            CHECK_FALSE(larger < j);
+            CHECK(larger > j);
+            CHECK(j <= same);
+            CHECK(j >= same);
+
+            // a value that ends earlier is the smaller one
+            const json shorter = json::parse(std::string(depth - 1, '[') + '0' + std::string(depth - 1, ']'));
+            CHECK_FALSE(j == shorter);
+        }
+
+        SECTION("comparing objects")
+        {
+            std::string text;
+            text.reserve((6 * depth) + 1);
+            for (std::size_t i = 0; i < depth; ++i)
+            {
+                text += "{\"a\":";
+            }
+            text += '1';
+            text.append(depth, '}');
+
+            const json j = json::parse(text);
+            const json same = json::parse(text);
+
+            CHECK(j == same);
+            CHECK_FALSE(j != same);
+            CHECK(j <= same);
+            CHECK(j >= same);
+        }
+
+        SECTION("the copy is independent of the original")
+        {
+            const json j = json::parse(std::string(depth, '[') + '0' + std::string(depth, ']'));
+
+            json copy(j);
+
+            // reach the innermost value without recursing and replace it
+            json* current = &copy;
+            while (current->is_array() && !current->empty())
+            {
+                current = &current->front();
+            }
+            *current = 42;
+
+            std::size_t unused = 0;
+            CHECK(*innermost_value(copy, unused) == 42);
+            CHECK(*innermost_value(j, unused) == 0);
+        }
+    }
+}
+
@@ -801,30 +801,6 @@ TEST_CASE("modifiers")
                    j1.update(j2, true);
                    CHECK(j1 == json({{"string", "t"}, {"numbers", 1}}));
                }
-
-                SECTION("overwrite primitive with object")
-                {
-                    json j1 = {{"k", 1}};
-                    json const j2 = {{"k", {{"x", 2}}}};
-                    j1.update(j2, true);
-                    CHECK(j1 == json({{"k", {{"x", 2}}}}));
-                }
-
-                SECTION("overwrite array with object")
-                {
-                    json j1 = {{"k", {1, 2}}};
-                    json const j2 = {{"k", {{"x", 2}}}};
-                    j1.update(j2, true);
-                    CHECK(j1 == json({{"k", {{"x", 2}}}}));
-                }
-
-                SECTION("overwrite nested primitive with object")
-                {
-                    json j1 = {{"k", {{"inner", 1}}}};
-                    json const j2 = {{"k", {{"inner", {{"x", 2}}}}}};
-                    j1.update(j2, true);
-                    CHECK(j1 == json({{"k", {{"inner", {{"x", 2}}}}}}));
-                }
            }
        }
    }
@@ -81,3 +81,37 @@ TEST_CASE("regression test for issue #3732 - iteration_proxy_value<iter_impl<ord
    };
    static_cast<void>(fn);
 }
+
+TEST_CASE("copying an ordered_json with nested values")
+{
+    // ordered_map is backed by a vector, so copying an object that has
+    // structured values takes a different route than copying a std::map-backed
+    // one; see https://github.com/nlohmann/json/issues/5387
+    ordered_json oj;
+    oj["z"] = 1;
+    oj["a"]["y"] = 2;
+    oj["a"]["b"]["x"] = 3;
+    oj["m"] = {1, 2, {{"w", 4}}};
+
+    const ordered_json copy(oj);
+
+    SECTION("the copy is equal to the original")
+    {
+        CHECK(copy == oj);
+        CHECK(copy.dump() == oj.dump());
+    }
+
+    SECTION("the key order is preserved at every level")
+    {
+        CHECK(copy.dump() == R"({"z":1,"a":{"y":2,"b":{"x":3}},"m":[1,2,{"w":4}]})");
+    }
+
+    SECTION("the copy is independent of the original")
+    {
+        ordered_json mutated(oj);
+        mutated["a"]["b"]["x"] = 99;
+
+        CHECK(oj["a"]["b"]["x"] == 3);
+        CHECK(mutated["a"]["b"]["x"] == 99);
+    }
+}
@@ -2503,48 +2503,6 @@ TEST_CASE("all UBJSON first bytes")
 }
 #endif

-TEST_CASE("UBJSON use_type requires use_size")
-{
-    SECTION("non-empty array throws other_error.502")
-    {
-        const json j = {1, 2, 3};
-        CHECK_THROWS_WITH_AS(json::to_ubjson(j, false, true),
-                             "[json.exception.other_error.502] use_type requires use_size = true",
-                             json::other_error&);
-    }
-
-    SECTION("non-empty object throws other_error.502")
-    {
-        const json j = {{"a", 1}, {"b", 2}};
-        CHECK_THROWS_WITH_AS(json::to_ubjson(j, false, true),
-                             "[json.exception.other_error.502] use_type requires use_size = true",
-                             json::other_error&);
-    }
-
-    SECTION("scalars do not throw with use_type=true, use_count=false")
-    {
-        CHECK_NOTHROW(json::to_ubjson(42, false, true));
-        CHECK_NOTHROW(json::to_ubjson(3.14, false, true));
-        CHECK_NOTHROW(json::to_ubjson("hello", false, true));
-        CHECK_NOTHROW(json::to_ubjson(true, false, true));
-        CHECK_NOTHROW(json::to_ubjson(nullptr, false, true));
-    }
-
-    SECTION("empty containers do not throw with use_type=true, use_count=false")
-    {
-        CHECK_NOTHROW(json::to_ubjson(json::array(), false, true));
-        CHECK_NOTHROW(json::to_ubjson(json::object(), false, true));
-    }
-
-    SECTION("valid combinations on non-empty containers")
-    {
-        const json j = {1, 2, 3};
-        CHECK_NOTHROW(json::to_ubjson(j, false, false));
-        CHECK_NOTHROW(json::to_ubjson(j, true, false));
-        CHECK_NOTHROW(json::to_ubjson(j, true, true));
-    }
-}
-
 TEST_CASE("UBJSON roundtrips" * doctest::skip())
 {
    SECTION("input from self-generated UBJSON files")
Author	SHA1	Message	Date
Niels Lohmann	596e33c319	Use the shared descent bookkeeping rather than a second set Comparing kept a thread_local count, a limit and a guard of its own beside the ones copying already had, all three the same thing under a different name. They are gone; the shared count, limit and guard do the work. The guard grows a second constructor here, because the comparison operators are written as a macro and a macro cannot use the preprocessor: it cannot look the count up behind an #ifdef the way copy_structured does, so the guard looks it up for it. nesting_depth_exhausted() arrives for the same reason - whether an operator descends at all is a constant at every call site, and testing it there is what MSVC reports as C4127. Also say in compare_leaves what happens to a pair that is an array on one side and an object on the other, since the answer is not obvious from the code: an operator only descends into two values of the same type, so such a pair is told apart by its types alone - unequal, and ordered the way the types are - exactly as it is above the bound. And record what the explicit stack costs: the comparison operators are noexcept and the container comparison this replaces allocated nothing, so running out of memory here ends the process instead of throwing. It takes a value nested past the bound and an exhausted heap to reach, and the same comparison used to exhaust the call stack, but it is a new way to fail. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:30:56 +02:00
Niels Lohmann	5fe4cd288a	Parenthesise the reserve() computation in the comparison test clang-tidy reports the mixed * and + as readability-math-missing- parentheses, as it does for the identical line in the copy test. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:25:05 +02:00
Niels Lohmann	616b395f71	Note the comparison fallback in the no-thread-local documentation The macro page describes what the library defines JSON_NO_THREAD_LOCAL for by itself in terms of copying alone; comparing falls back the same way. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:25:05 +02:00
Niels Lohmann	6392d99a73	Take the descent flag as an argument rather than testing it MSVC reports the test of a constant as C4127 ("conditional expression is constant"), which the Windows builds treat as an error: may_descend is false for operator<, so the operand short-circuits the whole condition. Passing it to compare_descent_exhausted() puts the test where the value is an ordinary parameter, and leaves the call sites with no condition of their own. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:25:05 +02:00
Niels Lohmann	0e9754d772	Describe comparison in the no-thread-local docs and CI target Comparing two values now bounds its descent with a thread_local counter just as copying does, so the JSON_NO_THREAD_LOCAL page, the macro overview and the ci_test_no_thread_local target cover both rather than copying alone. Also record what switching the macro on costs a comparison: on the benchmark documents, comparing two equal values takes 10% to 90% longer. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:25:05 +02:00
Niels Lohmann	e8b9ec8ff8	Compare values without recursing, and without comparing them twice Comparing two values compared their containers, which compare their elements, which brought the comparison back once per nesting level. Two values nested deeply enough exhausted the call stack and terminated the process with a segmentation fault - the same bug as #5387, in the last operation that still had it. Worse, an ordered comparison took exponentially long in the nesting depth before C++20. std::vector's operator< is a lexicographical comparison, which asks whether an element is less than its counterpart and then whether the counterpart is less than it - two full comparisons of everything below that element, at every level. Comparing two equal values nested 30 levels deep, which is nothing unusual, took 3.8 seconds; 40 levels would have taken an hour, and nothing about the value has to be pathological to get there. C++20 is unaffected: std::lexicographical_compare_three_way asks once. Compare a value that is nested too deeply to descend into on an explicit stack instead, in a single pass that yields less, equal, greater or unordered at once. Equality and the three-way comparison descend as they always did for the first 128 levels, which nothing measurable costs them; an ordered comparison no longer descends at all, which is what takes the exponent out of it. Objects and arrays that are not nested deeply are otherwise compared exactly as before. The results are unchanged for every pair of values: 68121 comparisons of a corpus that covers NaN, discarded values, mixed number types, binary values, empty containers and both object types are identical to develop, in C++11, C++17 and C++20, with and without thread_local storage and legacy discarded comparison. Reproducing that meant reproducing two subtleties: a lexicographic comparison steps over a pair it cannot order, where a three-way comparison stops at it, and an object compares its keys with < where its entries are ordered but with == where they are only checked for equality - not with the object's own comparator, which for nlohmann::ordered_map tells equality. Equality needs no ordering, so it no longer asks for any: a key or string type that can only be compared for equality still works. Measured (medians of 7 interleaved runs, clang -O3, C++11): comparing two equal values nested 30 levels deep 3778 ms -> 0.002 ms; ordering flat objects -33.6%; ordering flat arrays of numbers +27.3%, the one shape that pays for the single pass; equality unchanged throughout. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:25:05 +02:00
Niels Lohmann	bc01db0c14	Name the test's locals so Flawfinder stops matching them The code scanning job reports CWE-362 - "check when opening files" - for a test that opens no files: Flawfinder matched a local variable called open. Rename it and its partner. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:24:30 +02:00
Niels Lohmann	eae15bbeb1	Check that an abandoned copy can still be destroyed Copying a value without the call stack builds the copy from the top down, and every value whose own copy has not been made yet stays a null value until it is. That is what lets a copy be abandoned half-built: the destructor finds nothing but complete values and null ones. Nothing tested it. Failing an allocation part-way through a copy of a deeply nested value does, with the allocator the file already has for exactly this kind of test. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:24:30 +02:00
Niels Lohmann	cb1073469e	Keep the descent bookkeeping in one place Copying carried a depth count, a depth limit and a guard of its own, and the comparison in the follow-up added a second set beside them. Neither operation needs its own: they are never nested inside one another by the library - copying a value does not compare one, and comparing two values does not copy them - and where user code nests them anyway, sharing the count only ends a descent sooner than it had to. So there is now one nesting_depth(), one nesting_depth_limit() and one nesting_depth_guard, which the follow-up uses instead of adding its own. Inverting the test in copy_structured leaves the too-deep case and the no-thread-local case as the same code. The guard takes the count rather than looking it up, because the caller has looked it up already to test it against the limit, and reaching thread-local storage twice on the path that is taken almost every time is worth avoiding. The switch that copies the value of anything that is not an object or an array was written twice - once in the copy constructor, once in copy_shallow - so that adding a value_t meant editing both, and missing one would have been silent. It is copy_leaf_value now, and inlined: both callers have already sorted the containers out, and folding that test into the switch is what keeps a value made mostly of numbers copying as fast as it did. Copying canada.json, citm_catalog.json and twitter.json is within 0.6% of what it was before, measured as a paired ratio over 18 interleaved rounds against a run-to-run spread of 0.3%. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 12:24:30 +02:00
Niels Lohmann	e66a55066e	Include <span> where the split moved its only use The #2546 test case guards itself with __has_include(<span>), but the include itself sat in unit-regression2.cpp's preamble and stayed behind, so the section compiled without a declaration wherever the guard passed - which nvhpc reported and libc++ builds do not, as they skip the section altogether. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 03:19:53 +02:00
Niels Lohmann	02013c7f0d	Move the #4804 alias to the file that uses it The split left the json_4804 alias behind in unit-regression2.cpp while the test case that uses it went to unit-regression3.cpp, which does not build for C++17 and C++20 as a result. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 03:00:18 +02:00
Niels Lohmann	cdf24bccde	Split the regression tests far enough to leave room The first split left unit-regression2.cpp 0.7% below the size develop links at, which the comparison change in the follow-up immediately used up: the MinGW linker fails on test-regression2_cpp20 again, naming copy_shallow and to_partial_ordering among the relocations it cannot fit. Move the sections from "issue #2067" on, and the helper types they use, so that the file stops being the one that decides whether the tests can be linked at all. At -O0 and C++20, unit-regression2.cpp is now 2,964,944 bytes against develop's 4,708,248, and 3,070,568 bytes with the follow-up applied - roughly a third smaller either way, rather than a fraction of a percent larger. The 135 assertions are the same ones as before, now spread over three test cases in two files. Also silence the clang-tidy findings the deep-nesting tests draw: the copies they make are what is being tested, and the reserve() computation gets its parentheses. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 02:53:10 +02:00
Niels Lohmann	9d75c87de5	Check both shapes without a C-style array clang-tidy rejects the array the two shapes were iterated over (cppcoreguidelines-avoid-c-arrays). The array only existed because astyle reformats a range-for over a braced initializer list into something unreadable; naming the two cases avoids both. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 01:41:05 +02:00
Niels Lohmann	4fd940f91b	Balance the warning suppression the split separated unit-regression2.cpp opens a DOCTEST_CLANG_SUPPRESS_WARNING_PUSH block at the top and closed it at the very bottom, which the split moved into unit-regression3.cpp: one file was left with a push and no pop, the other with a pop and no push, which clang reports as an error. Give each file the pair it needs. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 01:01:57 +02:00
Niels Lohmann	540f6d11cc	Do not use thread_local storage with Clang targeting MinGW Every test that copies a value segfaults there - 42 of 105 on clang 11.0.1, 39 of 102 on clang 18.1.8 - while the same tests pass with GCC targeting MinGW, with Clang targeting MSVC, and with every other toolchain the library is tested on. The counter that bounds the copy constructor's descent is the library's first use of thread_local, so that job had never exercised it before. JSON_NO_THREAD_LOCAL already covers toolchains without thread_local storage, and copying yields the same values with it, only more slowly. Define it for this one automatically. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 00:48:42 +02:00
Niels Lohmann	6305cc9f72	Split the regression tests so that they keep linking Linking test-regression2 fails with "relocation truncated to fit: IMAGE_REL_AMD64_REL32 against `.rdata'" once its object grows past what the MinGW linker copes with, and the copy constructor's helpers push it over: the object grows by 6.3%, from 4,654,128 to 4,944,920 bytes at -O0, and develop links at the smaller of the two. Building the tests optimized shrinks the object enough to link, but the binaries clang 11.0.1 and clang 18.1.8 then produce crash before doctest prints its first line - 39 of 102 tests on clang 18 - so the objects have to become smaller rather than denser. Moving the test cases that follow "regression tests 2" into a file of their own brings that object to 4,687,888 bytes, which is 0.7% above the size that links today rather than 6.3%. Both files still build for C++11, C++17 and C++20, and run the same 9 test cases and 135 assertions as before, now spread over two binaries. New regression tests belong in unit-regression3.cpp from here on, which is what CONTRIBUTING.md now says. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 00:36:05 +02:00
Niels Lohmann	fa9b76283a	Test the copy constructor's iterative path in CI The copy constructor descends into 128 levels before it finishes a value without the call stack, so the iterative path is otherwise only reached by the few tests that nest deeper than that. JSON_NO_THREAD_LOCAL switches the descent off, which sends every value down that path. Running the whole test suite that way covers it with every object type, string type, allocator, and base class the suite already exercises. The new ci_test_no_thread_local target does that; the macro had no build coverage at all before. Copying a nested value also has to carry over what the element-wise copy constructor would have copied: the parents that JSON_DIAGNOSTICS relies on, and the positions that JSON_DIAGNOSTIC_POSITIONS reports. Both are now checked on either side of the descent bound, for objects and arrays. Neither was tested before, and dropping either one makes the new tests fail. Also quantify what JSON_NO_THREAD_LOCAL costs a copy instead of calling it "measurably slower". Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-21 00:35:45 +02:00
Niels Lohmann	e486005583	Bound the descent of the copy constructor basic_json's copy constructor copied objects and arrays by handing the container to its own copy constructor, which copy-constructs every element and so reaches this constructor again, once per nesting level. A value nested deeply enough exhausted the call stack and terminated the process with a segmentation fault - no exception, nothing the caller could catch. Parsing such a value works, as the parser is iterative, and so does destroying one, as #1436 made destruction iterative. Bound how far the copy descends rather than take the call stack away from it. The first levels are copied exactly as they were - the containers copy their own elements, which is by far the fastest way to fill them - and only once the copy has descended 128 levels is the value below it finished without the call stack, through an explicit worklist. Copying can therefore no longer exhaust the stack, however deeply a value is nested, while a value nested less deeply than the bound - all but a vanishing minority - is copied by the very same code as before and pays only for one counter. That counter lives in thread_local storage, as one shared between threads would be raced. JSON_NO_THREAD_LOCAL switches it off for toolchains without thread_local; copying then goes through the worklist right away, which yields the same values but is measurably slower. The deferred values are completed before the copy they belong to returns, so a value copied while another copy is going on - by a custom base class, say - is unaffected by the copy it is nested in. operator= takes its argument by value, so copy assignment is fixed as well. Copying is as fast as it was, within measurement noise (medians of 9 interleaved runs, clang -O3): -1.3% for an array of strings, +0.0% for a flat object, +0.1% for a flat array of numbers, +0.3% for nested arrays, +0.6% for nested objects and +1.2% for a twitter-like document. Copying a three-key object costs about ten nanoseconds more, the counter. Deferring every level instead, rather than only those below the bound, measured between 3% and 9% slower depending on the shape of the value. This fixes #5387 for the copy constructor. dump() is still recursive. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-08-20 19:22:16 +02:00