Merge branch 'develop' into claude/issue-2226-5c9bef

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Skip json reference tuple tests on clang < 4 and GCC < 5
2026-09-29 19:20:30 +00:00 · 2026-09-28 22:22:32 +02:00 · 2026-09-28 18:59:28 +02:00 · 2026-09-28 02:10:24 +02:00 · 2026-09-27 20:57:52 +02:00 · 2026-09-27 17:17:51 +02:00
140 changed files with 365 additions and 72362 deletions
@@ -1,81 +0,0 @@
-name: "Check API documentation"
-
-on:
-  pull_request:
-
-permissions:
-  contents: read
-
-jobs:
-  check_api_docs:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout pull request
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-
-      - name: Install clang
-        # Used only as a subprocess for `clang++ -E -v` system-include-path discovery in
-        # extract_api.py; it does not need to version-match the pinned libclang pip wheel
-        # below, which does the actual AST parsing. Do not "fix" this to be version-matched.
-        run: sudo apt-get update && sudo apt-get install -y clang
-
-      - name: Install Python dependencies
-        run: pip install -r tools/api_checker/requirements.txt
-
-      - name: Extract API and regenerate the committed surface file
-        run: |
-          python3 tools/api_checker/extract_api.py \
-            --header include/nlohmann/json.hpp \
-            --include include \
-            --output /tmp/api_snapshot.json \
-            --surface-output tools/api_checker/api_surface.json
-
-      - name: "Check API documentation (Phase 1: advisory)"
-        # Surfaces missing/broken @sa links without failing the job while the backlog from the
-        # initial AST-based rollout is burned down. See tools/api_checker/POLICY.md and the PR
-        # that introduced this workflow for the two-phase rollout plan.
-        continue-on-error: true
-        run: |
-          python3 tools/api_checker/check_docs.py \
-            --snapshot /tmp/api_snapshot.json
-
-      - name: Check macro documentation (advisory only)
-        # Cross-checks docs/mkdocs/docs/api/macros/ pages against #define sites. Only checks the
-        # documented-macro-still-exists direction; never blocks CI. See POLICY.md.
-        run: python3 tools/api_checker/check_macros.py
-
-      - name: Check for uncommitted API surface changes
-        id: diff
-        run: |
-          mkdir -p ${{ github.workspace }}/patch
-          git diff --patch --no-color -- tools/api_checker/api_surface.json > ${{ github.workspace }}/patch/api_surface.patch
-          if [ -s ${{ github.workspace }}/patch/api_surface.patch ]; then
-            echo "tools/api_checker/api_surface.json is out of date. Diff:"
-            cat ${{ github.workspace }}/patch/api_surface.patch
-            echo "has_diff=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "has_diff=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      # Uploaded so contributors can fix their PR with `git apply api_surface.patch`
-      # instead of installing libclang locally.
-      - name: Upload patch
-        if: steps.diff.outputs.has_diff == 'true'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: api-surface-patch
-          path: patch/api_surface.patch
-
-      - name: Fail if API surface file is not up to date
-        # Unlike the doc-backlog check above, this is purely mechanical regeneration with no
-        # backlog to phase in -- blocking from the start, matching check_amalgamation.yml's
-        # precedent. Contributors who add/remove/rename public API must regenerate and commit
-        # tools/api_checker/api_surface.json as part of their PR.
-        if: steps.diff.outputs.has_diff == 'true'
-        run: exit 1
@@ -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, ci_test_disableenumserialization, ci_test_skiplibraryversioncheck, ci_test_simdutf, ci_test_strict_nul_handling, ci_test_no_thread_local]
+        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls, ci_test_disableenumserialization, ci_test_disabletuplereferenceconversion, ci_test_skiplibraryversioncheck, ci_test_simdutf, ci_test_strict_nul_handling, ci_test_no_thread_local]
    steps:
      - name: Install build-essential
        run: apt-get update ; apt-get install -y build-essential unzip wget git libssl-dev
@@ -3,7 +3,6 @@
 *.gcno
 *.gcda
 .DS_Store
-__pycache__/

 /.idea
 /cmake-build-*
@@ -44,9 +43,5 @@ venv

 nlohmann_json.spdx

-# api_checker: ephemeral, location/doc-status-sensitive working file (not the committed
-# release-tracking artifact -- see tools/api_checker/api_surface.json for that)
-/tools/api_checker/api_snapshot.json
-
 # Bazel-related
 MODULE.bazel.lock
@@ -55,6 +55,7 @@ option(JSON_Diagnostic_Positions           "Enable diagnostic positions." OFF)
 option(JSON_GlobalUDLs                     "Place user-defined string literals in the global namespace." ON)
 option(JSON_ImplicitConversions            "Enable implicit conversions." ON)
 option(JSON_DisableEnumSerialization       "Disable default integer enum serialization." OFF)
+option(JSON_DisableTupleReferenceConversion "Disable conversion from a one-element tuple of a JSON reference." OFF)
 option(JSON_LegacyDiscardedValueComparison "Enable legacy discarded value comparison." OFF)
 option(JSON_Install                        "Install CMake targets during install step." ${MAIN_PROJECT})
 option(JSON_MultipleHeaders                "Use non-amalgamated version of the library." ON)
@@ -101,6 +102,10 @@ if (JSON_DisableEnumSerialization)
    message(STATUS "Enum integer serialization is disabled (JSON_DISABLE_ENUM_SERIALIZATION=1)")
 endif()

+if (JSON_DisableTupleReferenceConversion)
+    message(STATUS "Tuple reference conversion is disabled (JSON_DISABLE_TUPLE_REFERENCE_CONVERSION=1)")
+endif()
+
 if (JSON_LegacyDiscardedValueComparison)
    message(STATUS "Legacy discarded value comparison enabled (JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1)")
 endif()
@@ -143,6 +148,7 @@ target_compile_definitions(
    $<$<NOT:$<BOOL:${JSON_GlobalUDLs}>>:JSON_USE_GLOBAL_UDLS=0>
    $<$<NOT:$<BOOL:${JSON_ImplicitConversions}>>:JSON_USE_IMPLICIT_CONVERSIONS=0>
    $<$<BOOL:${JSON_DisableEnumSerialization}>:JSON_DISABLE_ENUM_SERIALIZATION=1>
+    $<$<BOOL:${JSON_DisableTupleReferenceConversion}>:JSON_DISABLE_TUPLE_REFERENCE_CONVERSION=1>
    $<$<BOOL:${JSON_Diagnostics}>:JSON_DIAGNOSTICS=1>
    $<$<BOOL:${JSON_Diagnostic_Positions}>:JSON_DIAGNOSTIC_POSITIONS=1>
    $<$<BOOL:${JSON_LegacyDiscardedValueComparison}>:JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1>
@@ -106,7 +106,7 @@ Thanks everyone!

 :books: If you want to **learn more** about how to use the library, check out the rest of the [**README**](#examples), have a look at [**code examples**](https://github.com/nlohmann/json/tree/develop/docs/mkdocs/docs/examples), or browse through the [**help pages**](https://json.nlohmann.me).

-:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below. The public API surface is derived mechanically and checked for documentation coverage by the tooling in [`tools/api_checker/`](tools/api_checker/), whose [POLICY.md](tools/api_checker/POLICY.md) defines what counts as public API and what stability is guaranteed.
+:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below.

 :bug: If you found a **bug**, please check the [**FAQ**](https://json.nlohmann.me/home/faq/) if it is a known issue or the result of a design decision. Please also have a look at the [**issue list**](https://github.com/nlohmann/json/issues) before you [**create a new issue**](https://github.com/nlohmann/json/issues/new/choose). Please provide as much information as possible to help us understand and reproduce your issue.

@@ -276,6 +276,20 @@ add_custom_target(ci_test_disableenumserialization
    COMMENT "Compile and test with enum serialization disabled"
 )

+###############################################################################
+# Disable conversion from a one-element tuple of a JSON reference.
+###############################################################################
+
+add_custom_target(ci_test_disabletuplereferenceconversion
+    COMMAND ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON -DJSON_FastTests=ON -DJSON_DisableTupleReferenceConversion=ON
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_disabletuplereferenceconversion
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_disabletuplereferenceconversion
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_disabletuplereferenceconversion && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test with tuple reference conversion disabled"
+)
+
 ###############################################################################
 # Skip the multiple-inclusion library version check.
 ###############################################################################
@@ -210,6 +210,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('JSON_CATCH_USER', 'Macro', 'a
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTICS', 'Macro', 'api/macros/json_diagnostics/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTIC_POSITIONS', 'Macro', 'api/macros/json_diagnostic_positions/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_ENUM_SERIALIZATION', 'Macro', 'api/macros/json_disable_enum_serialization/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_TUPLE_REFERENCE_CONVERSION', 'Macro', 'api/macros/json_disable_tuple_reference_conversion/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_11', 'Macro', 'api/macros/json_has_cpp_11/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_14', 'Macro', 'api/macros/json_has_cpp_11/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_17', 'Macro', 'api/macros/json_has_cpp_11/index.html');
@@ -159,6 +159,8 @@ basic_json(basic_json&& other) noexcept;
    - `CompatibleType` is not `basic_json` (to avoid hijacking copy/move constructors),
    - `CompatibleType` is not a different `basic_json` type (i.e. with different template arguments)
    - `CompatibleType` is not a `basic_json` nested type (e.g., `json_pointer`, `iterator`, etc.)
+    - if [`JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](../macros/json_disable_tuple_reference_conversion.md) is defined
+      to `1`: `CompatibleType` is not a one-element `std::tuple` holding a reference to `basic_json`
    - `json_serializer<U>` (with `U = uncvref_t<CompatibleType>`) has a `to_json(basic_json_t&, CompatibleType&&)`
       method

@@ -420,9 +422,7 @@ basic_json(basic_json&& other) noexcept;
 1. Since version 1.0.0.
 2. Since version 1.0.0.
 3. Since version 2.1.0.
-4. Since version 3.2.0. Also initializes the position reported by
-   [`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) from `val` when
-   [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is enabled, since version 3.12.0.
+4. Since version 3.2.0.
 5. Since version 1.0.0.
 6. Since version 1.0.0.
 7. Since version 1.0.0.
@@ -1,38 +0,0 @@
-# <small>nlohmann::basic_json::</small>bjdata_version_t
-
-```cpp
-enum class bjdata_version_t
-{
-    draft2,
-    draft3,
-};
-```
-
-This enumeration is used in the [`to_bjdata`](to_bjdata.md) function to choose which draft version of
-the BJData specification to encode ND-array extensions for:
-
-draft2
-:   encode using the BJData Draft 2 ND-array format
-
-draft3
-:   encode using the BJData Draft 3 ND-array format
-
-## Examples
-
-??? example
-
-    The example shows how `bjdata_version_t` selects the BJData draft used by `to_bjdata`.
-
-    ```cpp
-    --8<-- "examples/bjdata_version_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/bjdata_version_t.output"
-    ```
-
-## Version history
-
- Added in version 3.12.0.
@@ -1,32 +0,0 @@
-# <small>nlohmann::basic_json::</small>initializer_list_t
-
-```cpp
-using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
-```
-
-The type used for the initializer-list [constructor](basic_json.md) (overload 5) and for functions
-such as [`operator=`](operator=.md) that accept a braced-init-list of JSON values. Each element wraps a
-`basic_json` value or something convertible to one, deferring the decision of whether the list should be
-parsed as a JSON array or a JSON object to the constructor itself.
-
-See the [constructor](basic_json.md) documentation for how `initializer_list_t` values are interpreted.
-
-## Examples
-
-??? example
-
-    The example shows how an `initializer_list_t` is used to construct a JSON value.
-
-    ```cpp
-    --8<-- "examples/initializer_list_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/initializer_list_t.output"
-    ```
-
-## Version history
-
- Since version 1.0.0.
@@ -1,31 +0,0 @@
-# <small>nlohmann::basic_json::</small>json_sax_t
-
-```cpp
-using json_sax_t = json_sax<basic_json>;
-```
-
-The [`json_sax`](../json_sax/index.md) interface bound to this `basic_json` specialization, i.e. with
-`BasicJsonType` fixed to `basic_json`. Used as the SAX interface type by [`sax_parse`](sax_parse.md) and
-other SAX-based parsing functions.
-
-See [`nlohmann::json_sax`](../json_sax/index.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `json_sax_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax_t.output"
-    ```
-
-## Version history
-
- Added in version 3.2.0.
@@ -51,5 +51,3 @@ Linear.
 ## Version history

 - Added in version 1.0.0.
- The `noexcept` specification was extended to also depend on
-  [`json_base_class_t`](json_base_class_t.md)'s move-assignment in version 3.11.3.
@@ -85,8 +85,3 @@ Linear in the size of the JSON value.
 - Since version 1.0.0.
 - Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added
  in version 3.9.0.
- The exclusion of `std::any` from this conversion became conditional on
-  [`JSON_HAS_STATIC_RTTI`](../macros/json_has_static_rtti.md) in version 3.11.3.
- `std::optional<T>` excluded from this conversion in version 3.13.0; use
-  [`get<std::optional<T>>()`](get.md)/[`get_to()`](get_to.md) instead (see
-  [Converting values](../../features/conversions.md)).
@@ -1,32 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>container_type
-
-```cpp
-using container_type = BinaryType;
-```
-
-The type of the underlying binary container, forwarded from the `BinaryType` template parameter that
-`byte_container_with_subtype` is instantiated with. `byte_container_with_subtype` publicly inherits from
-`container_type`.
-
-See [`basic_json::binary_t`](../basic_json/binary_t.md) for the type typically used to instantiate
-`BinaryType`.
-
-## Examples
-
-??? example
-
-    The example shows the type `container_type`.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__container_type.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__container_type.output"
-    ```
-
-## Version history
-
- Since version 3.8.0.
@@ -1,45 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>operator==
-
-```cpp
-bool operator==(const byte_container_with_subtype& rhs) const;
-```
-
-Compares two `byte_container_with_subtype` values for equality by comparing the underlying binary
-container, the subtype, and whether a subtype is set.
-
-## Parameters
-
-`rhs` (in)
-:   value to compare `*this` against
-
-## Return value
-
-whether `*this` and `rhs` are equal
-
-## Exception safety
-
-No-throw guarantee: this function never throws exceptions.
-
-## Complexity
-
-Linear in the size of the underlying binary container.
-
-## Examples
-
-??? example
-
-    The example demonstrates comparing `byte_container_with_subtype` values.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__operator_eq.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__operator_eq.output"
-    ```
-
-## Version history
-
- Since version 3.8.0.
@@ -1,45 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>operator!=
-
-```cpp
-bool operator!=(const byte_container_with_subtype& rhs) const;
-```
-
-Compares two `byte_container_with_subtype` values for inequality. Implemented as the negation of
-[`operator==`](operator_eq.md).
-
-## Parameters
-
-`rhs` (in)
-:   value to compare `*this` against
-
-## Return value
-
-whether `*this` and `rhs` are not equal
-
-## Exception safety
-
-No-throw guarantee: this function never throws exceptions.
-
-## Complexity
-
-Linear in the size of the underlying binary container.
-
-## Examples
-
-??? example
-
-    The example demonstrates comparing `byte_container_with_subtype` values.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__operator_ne.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__operator_ne.output"
-    ```
-
-## Version history
-
- Since version 3.8.0.
@@ -1,28 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>subtype_type
-
-```cpp
-using subtype_type = std::uint64_t;
-```
-
-The type used to store the optional binary subtype tag. See [`subtype`](subtype.md) and
-[`set_subtype`](set_subtype.md).
-
-## Examples
-
-??? example
-
-    The example shows the type `subtype_type`.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__subtype_type.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__subtype_type.output"
-    ```
-
-## Version history
-
- Since version 3.8.0.
@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>binary_t
-
-```cpp
-using binary_t = typename BasicJsonType::binary_t;
-```
-
-The type used by the [`binary`](binary.md) callback for JSON binary values, forwarded from the
-`BasicJsonType` template parameter.
-
-See [`basic_json::binary_t`](../basic_json/binary_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `binary_t` and its relation to `basic_json::binary_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__binary_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__binary_t.output"
-    ```
-
-## Version history
-
- Added in version 3.8.0.
@@ -1,33 +0,0 @@
-# <small>nlohmann::json_sax::</small>json_sax
-
-```cpp
-// (1)
-json_sax() = default;
-
-// (2)
-json_sax(const json_sax&) = default;
-
-// (3)
-json_sax(json_sax&&) noexcept = default;
-```
-
-1. Default constructor.
-2. Copy constructor.
-3. Move constructor.
-
-`json_sax` is a pure abstract base class with no data members of its own, so all three constructors are
-defaulted and only exist to make derived SAX consumers explicitly copyable/movable.
-
-## Exception safety
-
-No-throw guarantee: none of these constructors throw exceptions.
-
-## Complexity
-
-Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
- Added in version 3.2.0.
@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>number_float_t
-
-```cpp
-using number_float_t = typename BasicJsonType::number_float_t;
-```
-
-The type used by the [`number_float`](number_float.md) callback for JSON floating-point numbers,
-forwarded from the `BasicJsonType` template parameter.
-
-See [`basic_json::number_float_t`](../basic_json/number_float_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `number_float_t` and its relation to `basic_json::number_float_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__number_float_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__number_float_t.output"
-    ```
-
-## Version history
-
- Added in version 3.2.0.
@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>number_integer_t
-
-```cpp
-using number_integer_t = typename BasicJsonType::number_integer_t;
-```
-
-The type used by the [`number_integer`](number_integer.md) callback for JSON integer numbers, forwarded
-from the `BasicJsonType` template parameter.
-
-See [`basic_json::number_integer_t`](../basic_json/number_integer_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `number_integer_t` and its relation to `basic_json::number_integer_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__number_integer_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__number_integer_t.output"
-    ```
-
-## Version history
-
- Added in version 3.2.0.
@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>number_unsigned_t
-
-```cpp
-using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
-```
-
-The type used by the [`number_unsigned`](number_unsigned.md) callback for JSON unsigned integer numbers,
-forwarded from the `BasicJsonType` template parameter.
-
-See [`basic_json::number_unsigned_t`](../basic_json/number_unsigned_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `number_unsigned_t` and its relation to `basic_json::number_unsigned_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__number_unsigned_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__number_unsigned_t.output"
-    ```
-
-## Version history
-
- Added in version 3.2.0.
@@ -1,29 +0,0 @@
-# <small>nlohmann::json_sax::</small>operator=
-
-```cpp
-// (1)
-json_sax& operator=(const json_sax&) = default;
-
-// (2)
-json_sax& operator=(json_sax&&) noexcept = default;
-```
-
-1. Copy assignment operator.
-2. Move assignment operator.
-
-`json_sax` is a pure abstract base class with no data members of its own, so both assignment operators
-are defaulted and only exist to make derived SAX consumers explicitly copy-/move-assignable.
-
-## Exception safety
-
-No-throw guarantee: neither operator throws exceptions.
-
-## Complexity
-
-Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
- Added in version 3.2.0.
@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>string_t
-
-```cpp
-using string_t = typename BasicJsonType::string_t;
-```
-
-The type used by the [`string`](string.md) and [`key`](key.md) callbacks for JSON strings and object
-keys, forwarded from the `BasicJsonType` template parameter.
-
-See [`basic_json::string_t`](../basic_json/string_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `string_t` and its relation to `basic_json::string_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__string_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__string_t.output"
-    ```
-
-## Version history
-
- Added in version 3.2.0.
@@ -1,22 +0,0 @@
-# <small>nlohmann::json_sax::</small>~json_sax
-
-```cpp
-virtual ~json_sax() = default;
-```
-
-Destructor. Virtual to allow proper destruction of derived SAX consumer classes through a
-pointer/reference to `json_sax`.
-
-## Exception safety
-
-No-throw guarantee: this destructor never throws exceptions.
-
-## Complexity
-
-Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
- Added in version 3.2.0.
@@ -52,6 +52,7 @@ header. See also the [macro overview page](../../features/macros.md).

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

 ## Comparison behavior
@@ -0,0 +1,114 @@
+# JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+
+```cpp
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION /* value */
+```
+
+When defined to `1`, a `basic_json` value can no longer be constructed from a one-element `std::tuple` whose element is
+a reference to that `basic_json` type, such as `std::tuple<json&>`, `std::tuple<const json&>`, or `std::tuple<json&&>`.
+These are the tuples created by `std::forward_as_tuple(j)`.
+
+## Default definition
+
+The default value is `0` (disabled — existing behavior is preserved).
+
+```cpp
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 0
+```
+
+## Notes
+
+!!! note "Background"
+
+    By default, `basic_json` can be constructed from any `std::tuple` whose elements can be converted to JSON; the result
+    is an array. This includes `std::tuple<json&>`, which becomes a one-element array.
+
+    `std::tuple` only converts another tuple element by element if its element type cannot be constructed from the whole
+    source tuple. Because `json` *can* be constructed from `std::tuple<json&>`, `std::tuple` instead converts the whole
+    tuple into a single `json` value. This has two surprising effects:
+
+    ```cpp
+    json j = true;
+
+    // rejected by some standard libraries (e.g., libc++); with others, the
+    // reference binds to a temporary that is destroyed right away
+    std::tuple<const json&> t1(std::forward_as_tuple(j));
+
+    // compiles, but std::get<0>(t2) is [true], not true
+    std::tuple<json> t2(std::forward_as_tuple(j));
+    ```
+
+    Enabling this macro removes the conversion, so both tuples are converted element by element: `std::get<0>(t1)`
+    refers to `j`, and `std::get<0>(t2)` is a copy of `j` (see [#2226](https://github.com/nlohmann/json/issues/2226)).
+
+!!! warning "Opt-in only"
+
+    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
+
+!!! note "Affected conversions"
+
+    Only one-element tuples holding a reference to the **same** `basic_json` type are affected. Constructing a JSON value
+    from them no longer compiles:
+
+    ```cpp
+    json j = true;
+    json a = std::forward_as_tuple(j);  // error with the macro enabled
+    json b = json::array({j});          // use this instead: [true]
+    ```
+
+    Tuples holding a JSON value (`std::make_tuple(j)`), tuples with more than one element, and tuples holding references
+    to other types (including other `basic_json` specializations) are converted to arrays as before.
+
+!!! hint "CMake option"
+
+    This behavior can also be controlled with the CMake option
+    [`JSON_DisableTupleReferenceConversion`](../../integration/cmake.md#json_disabletuplereferenceconversion)
+    (`OFF` by default) which defines `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION` accordingly.
+
+## Examples
+
+??? example "Default behavior (macro not defined)"
+
+    ```cpp
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        json j = true;
+
+        std::tuple<json> t(std::forward_as_tuple(j));
+        // std::get<0>(t) is [true] -- the whole tuple was converted
+    }
+    ```
+
+??? example "Conversion disabled (macro defined to 1)"
+
+    ```cpp
+    #define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        json j = true;
+
+        std::tuple<json> t(std::forward_as_tuple(j));
+        // std::get<0>(t) is true -- a copy of j
+
+        std::tuple<const json&> r(std::forward_as_tuple(j));
+        // std::get<0>(r) refers to j
+    }
+    ```
+
+## See also
+
+- [**basic_json(CompatibleType&&)**](../basic_json/basic_json.md) - the affected constructor
+- [:simple-cmake: JSON_DisableTupleReferenceConversion](../../integration/cmake.md#json_disabletuplereferenceconversion) -
+  CMake option to control the macro
+
+## Version history
+
+- Added in version 3.13.0.
@@ -8,16 +8,16 @@ This type preserves the insertion order of object keys.

 ## Iterator invalidation

-The type is based on [`ordered_map`](ordered_map/index.md) which in turn uses a `std::vector` to store object elements.
+The type is based on [`ordered_map`](ordered_map.md) which in turn uses a `std::vector` to store object elements.
 Therefore, adding object elements can yield a reallocation in which case all iterators (including the
 [`end()`](basic_json/end.md) iterator) and all references to the elements are invalidated. Also, any iterator or
 reference after the insertion point will point to the same index, which is now a different value.

 ## Complexity

-[`ordered_map`](ordered_map/index.md) has no lookup index: every key-based object operation is a linear scan, so building or
+[`ordered_map`](ordered_map.md) has no lookup index: every key-based object operation is a linear scan, so building or
 parsing an object of `n` keys costs O(n²) rather than O(n log n). See
-[`ordered_map` complexity](ordered_map/index.md#complexity) for the per-operation table and for measured numbers.
+[`ordered_map` complexity](ordered_map.md#complexity) for the per-operation table and for measured numbers.

 ## Examples

@@ -37,7 +37,7 @@ parsing an object of `n` keys costs O(n²) rather than O(n log n). See

 ## See also

- [ordered_map](ordered_map/index.md)
+- [ordered_map](ordered_map.md)
 - [Object Order](../features/object_order.md)

 ## Version history
@@ -6,7 +6,7 @@ template<class Key, class T, class IgnoredLess = std::less<Key>,
 struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
 ```

-A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](../ordered_json.md)
+A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](ordered_json.md)
 (`nlohmann::basic_json<ordered_map>`).

 ## Template parameters
@@ -32,12 +32,12 @@ case all iterators (including the `end()` iterator) and all references to the el

 - **key_type** - key type (`Key`)
 - **mapped_type** - mapped type (`T`)
- [**Container**](Container.md) - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
+- **Container** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
 - **iterator**
 - **const_iterator**
 - **size_type**
 - **value_type**
- [**key_compare**](key_compare.md) - key comparison function
+- **key_compare** - key comparison function
 ```cpp
 std::equal_to<Key>  // until C++14

@@ -46,16 +46,15 @@ std::equal_to<>     // since C++14

 ## Member functions

- [(constructor)](ordered_map.md)
- [(destructor)](~ordered_map.md)
- [**operator=**](operator=.md)
- [**emplace**](emplace.md)
- [**operator\[\]**](operator[].md)
- [**at**](at.md)
- [**erase**](erase.md)
- [**count**](count.md)
- [**find**](find.md)
- [**insert**](insert.md)
+- (constructor)
+- (destructor)
+- **emplace**
+- **operator\[\]**
+- **at**
+- **erase**
+- **count**
+- **find**
+- **insert**

 ## Complexity

@@ -117,9 +116,9 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).

 ## See also

- [ordered_json](../ordered_json.md)
+- [ordered_json](ordered_json.md)

 ## Version history

- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).
 - Added **key_compare** member in version 3.11.0.
@@ -1,28 +0,0 @@
-# <small>nlohmann::ordered_map::</small>Container
-
-```cpp
-using Container = std::vector<std::pair<const Key, T>, Allocator>;
-```
-
-The base container type that `ordered_map` publicly inherits from. Elements are stored in insertion
-order as `#!cpp std::pair<const Key, T>` entries in a `std::vector`.
-
-## Examples
-
-??? example
-
-    The example shows the type `Container`.
-
-    ```cpp
-    --8<-- "examples/ordered_map__Container.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__Container.output"
-    ```
-
-## Version history
-
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -1,61 +0,0 @@
-# <small>nlohmann::ordered_map::</small>at
-
-```cpp
-// (1)
-T& at(const key_type& key);
-const T& at(const key_type& key) const;
-
-// (2)
-template<class KeyType>
-T& at(KeyType&& key);
-template<class KeyType>
-const T& at(KeyType&& key) const;
-```
-
-1. Returns a reference to the value mapped to `key`.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup, e.g. looking up by a `#!cpp const char*` without constructing a temporary
-   `key_type`). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to find
-
-## Return value
-
-reference to the mapped value of the element with key equal to `key`
-
-## Exceptions
-
-Throws `std::out_of_range` if no element with key `key` exists.
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `at` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__at.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__at.output"
-    ```
-
-## Version history
-
- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
- Overload (2) added in version 3.11.0.
@@ -1,53 +0,0 @@
-# <small>nlohmann::ordered_map::</small>count
-
-```cpp
-// (1)
-size_type count(const key_type& key) const;
-
-// (2)
-template<class KeyType>
-size_type count(KeyType&& key) const;
-```
-
-1. Returns the number of elements with key equal to `key` (0 or 1, since keys are unique).
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the elements to count
-
-## Return value
-
-number of elements with key equal to `key` (0 or 1)
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `count` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__count.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__count.output"
-    ```
-
-## Version history
-
- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
- Overload (2) added in version 3.11.0.
@@ -1,58 +0,0 @@
-# <small>nlohmann::ordered_map::</small>emplace
-
-```cpp
-// (1)
-std::pair<iterator, bool> emplace(const key_type& key, T&& t);
-
-// (2)
-template<class KeyType>
-std::pair<iterator, bool> emplace(KeyType&& key, T&& t);
-```
-
-1. Inserts `#!cpp {key, t}` if no element with an equal key already exists (per [`key_compare`](key_compare.md)),
-   appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to insert
-
-`t` (in)
-:   value of the element to insert
-
-## Return value
-
-pair of an iterator to the (possibly newly inserted) element, and a `bool` that is `true` if insertion
-took place and `false` if an element with an equal key already existed
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `emplace` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__emplace.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__emplace.output"
-    ```
-
-## Version history
-
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
- Overload (2) added in version 3.11.0.
@@ -1,75 +0,0 @@
-# <small>nlohmann::ordered_map::</small>erase
-
-```cpp
-// (1)
-size_type erase(const key_type& key);
-
-// (2)
-template<class KeyType>
-size_type erase(KeyType&& key);
-
-// (3)
-iterator erase(iterator pos);
-
-// (4)
-iterator erase(iterator first, iterator last);
-```
-
-1. Removes the element with key equal to `key`, if any, preserving the relative order of the remaining
-   elements.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-3. Removes the element at `pos`.
-4. Removes the elements in range `[first, last)`.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to remove
-
-`pos` (in)
-:   iterator to the element to remove
-
-`first` (in)
-:   iterator to the first element to remove
-
-`last` (in)
-:   iterator one past the last element to remove
-
-## Return value
-
-1. number of elements removed (0 or 1)
-2. number of elements removed (0 or 1)
-3. iterator following the removed element
-4. iterator following the last removed element
-
-## Complexity
-
-Linear in the number of elements (elements after the removed one(s) are shifted to keep storage
-contiguous).
-
-## Examples
-
-??? example
-
-    The example shows how `erase` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__erase.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__erase.output"
-    ```
-
-## Version history
-
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
- Overload (2) added in version 3.11.0.
@@ -1,56 +0,0 @@
-# <small>nlohmann::ordered_map::</small>find
-
-```cpp
-// (1)
-iterator find(const key_type& key);
-const_iterator find(const key_type& key) const;
-
-// (2)
-template<class KeyType>
-iterator find(KeyType&& key);
-template<class KeyType>
-const_iterator find(KeyType&& key) const;
-```
-
-1. Returns an iterator to the element with key equal to `key`, or `end()` if no such element exists.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to find
-
-## Return value
-
-iterator to the element with key equal to `key`, or `end()` if not found
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `find` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__find.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__find.output"
-    ```
-
-## Version history
-
- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
- Overload (2) added in version 3.11.0.
@@ -1,63 +0,0 @@
-# <small>nlohmann::ordered_map::</small>insert
-
-```cpp
-// (1)
-std::pair<iterator, bool> insert(value_type&& value);
-std::pair<iterator, bool> insert(const value_type& value);
-
-// (2)
-template<typename InputIt>
-void insert(InputIt first, InputIt last);
-```
-
-1. Inserts `value` if no element with an equal key already exists (per [`key_compare`](key_compare.md)),
-   appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
-2. Inserts the elements from range `[first, last)`, in iteration order, applying the same equal-key rule
-   as (1) to each element.
-
-## Template parameters
-
-`InputIt`
-:   an input iterator type
-
-## Parameters
-
-`value` (in)
-:   value to insert
-
-`first` (in)
-:   iterator to the first element to insert
-
-`last` (in)
-:   iterator one past the last element to insert
-
-## Return value
-
-1. pair of an iterator to the (possibly newly inserted) element, and a `bool` that is `true` if insertion
-   took place and `false` if an element with an equal key already existed
-2. (none)
-
-## Complexity
-
-1. Linear in the number of elements.
-2. Linear in the distance between `first` and `last`, times linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `insert` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__insert.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__insert.output"
-    ```
-
-## Version history
-
- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -1,34 +0,0 @@
-# <small>nlohmann::ordered_map::</small>key_compare
-
-```cpp
-using key_compare = std::equal_to<Key>;  // until C++14
-
-using key_compare = std::equal_to<>;     // since C++14
-```
-
-The comparator used to determine key equality when looking up elements. Unlike `std::map`, `ordered_map`
-uses linear search with `key_compare` rather than an ordering relation, since element order reflects
-insertion order rather than key order.
-
-Since C++14, the transparent `#!cpp std::equal_to<>` is used, which enables heterogeneous lookup (e.g.
-looking up by a `#!cpp const char*` key without constructing a temporary `Key`).
-
-## Examples
-
-??? example
-
-    The example shows how `key_compare` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__key_compare.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__key_compare.output"
-    ```
-
-## Version history
-
- Added in version 3.11.0.
@@ -1,32 +0,0 @@
-# <small>nlohmann::ordered_map::</small>operator=
-
-```cpp
-// (1)
-ordered_map& operator=(const ordered_map& other);
-
-// (2)
-ordered_map& operator=(ordered_map&& other) noexcept(std::is_nothrow_move_assignable<Container>::value);
-```
-
-1. Copy assignment operator.
-2. Move assignment operator.
-
-## Parameters
-
-`other` (in)
-:   value to assign from
-
-## Return value
-
-`*this`
-
-## Complexity
-
-1. Linear in the size of `other`.
-2. Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -1,62 +0,0 @@
-# <small>nlohmann::ordered_map::</small>operator[]
-
-```cpp
-// (1)
-T& operator[](const key_type& key);
-const T& operator[](const key_type& key) const;
-
-// (2)
-template<class KeyType>
-T& operator[](KeyType&& key);
-template<class KeyType>
-const T& operator[](KeyType&& key) const;
-```
-
-1. Returns a reference to the value mapped to `key`, inserting a default-constructed `T` (non-`const`
-   overload only) if no such element exists yet.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to find or insert
-
-## Return value
-
-reference to the mapped value of the element with key equal to `key`
-
-## Exceptions
-
-The `const` overloads throw `std::out_of_range` if no element with key `key` exists (they delegate to
-[`at`](at.md)).
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `operator[]` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__operator_idx.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__operator_idx.output"
-    ```
-
-## Version history
-
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
- Overload (2) added in version 3.11.0.
@@ -1,66 +0,0 @@
-# <small>nlohmann::ordered_map::</small>ordered_map
-
-```cpp
-// (1)
-ordered_map() noexcept(noexcept(Container()));
-
-// (2)
-explicit ordered_map(const Allocator& alloc) noexcept(noexcept(Container(alloc)));
-
-// (3)
-template <class It>
-ordered_map(It first, It last, const Allocator& alloc = Allocator());
-
-// (4)
-ordered_map(std::initializer_list<value_type> init, const Allocator& alloc = Allocator());
-
-// (5)
-ordered_map(const ordered_map&) = default;
-
-// (6)
-ordered_map(ordered_map&&) noexcept(std::is_nothrow_move_constructible<Container>::value) = default;
-```
-
-1. Default constructor. Creates an empty `ordered_map`.
-2. Creates an empty `ordered_map` using the given allocator.
-3. Creates an `ordered_map` from the elements in range `[first, last)`, inserted in iteration order.
-4. Creates an `ordered_map` from an initializer list of key/value pairs, inserted in list order.
-5. Copy constructor.
-6. Move constructor.
-
-These constructors are declared explicitly (rather than inherited via `#!cpp using Container::Container`)
-because older compilers (GCC <= 5.5, Xcode <= 9.4) do not handle the inherited constructors correctly.
-
-## Template parameters
-
-`It`
-:   an input iterator type
-
-## Parameters
-
-`alloc` (in)
-:   allocator to use for the underlying container
-
-`first` (in)
-:   iterator to the first element to insert
-
-`last` (in)
-:   iterator one past the last element to insert
-
-`init` (in)
-:   initializer list of key/value pairs to insert
-
-## Complexity
-
-1. Constant.
-2. Constant.
-3. Linear in the distance between `first` and `last`.
-4. Linear in the size of `init`.
-5. Linear in the size of `other`.
-6. Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -1,17 +0,0 @@
-# <small>nlohmann::ordered_map::</small>~ordered_map
-
-```cpp
-~ordered_map() = default;
-```
-
-Destroys the `ordered_map` and frees all allocated memory.
-
-## Complexity
-
-Linear in the number of elements.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
@@ -1,21 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // an empty binary value is encoded differently by the two drafts:
-    // draft2 omits the optimized type marker for an empty byte array,
-    // while draft3 always writes it
-    json j = json::binary({});
-
-    // encode using BJData draft2 (the default)
-    auto v_draft2 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft2);
-
-    // encode using BJData draft3
-    auto v_draft3 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft3);
-
-    std::cout << "draft2 size: " << v_draft2.size() << '\n'
-              << "draft3 size: " << v_draft3.size() << std::endl;
-}
@@ -1,2 +0,0 @@
-draft2 size: 4
-draft3 size: 6
@@ -1,11 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<byte_container_with_subtype::container_type, std::vector<std::uint8_t>>::value
-              << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,15 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    byte_container_with_subtype c1({0xca, 0xfe});
-    byte_container_with_subtype c2({0xca, 0xfe});
-    byte_container_with_subtype c3({0xca, 0xfe}, 42);
-
-    std::cout << std::boolalpha
-              << "c1 == c2: " << (c1 == c2) << '\n'
-              << "c1 == c3: " << (c1 == c3) << std::endl;
-}
@@ -1,2 +0,0 @@
-c1 == c2: true
-c1 == c3: false
@@ -1,15 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    byte_container_with_subtype c1({0xca, 0xfe});
-    byte_container_with_subtype c2({0xca, 0xfe});
-    byte_container_with_subtype c3({0xca, 0xfe}, 42);
-
-    std::cout << std::boolalpha
-              << "c1 != c2: " << (c1 != c2) << '\n'
-              << "c1 != c3: " << (c1 != c3) << std::endl;
-}
@@ -1,2 +0,0 @@
-c1 != c2: false
-c1 != c3: true
@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<byte_container_with_subtype::subtype_type, std::uint64_t>::value << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,13 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // an initializer_list_t is what a braced-init-list of JSON values is deduced as
-    json::initializer_list_t init = {"a", 1, 2.0, false};
-
-    json j(init);
-    std::cout << j.dump() << std::endl;
-}
@@ -1 +0,0 @@
-["a",1,2.0,false]
@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::binary_t, json::binary_t>::value << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::number_float_t, json::number_float_t>::value << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::number_integer_t, json::number_integer_t>::value << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::number_unsigned_t, json::number_unsigned_t>::value << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::string_t, json::string_t>::value << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t, nlohmann::json_sax<json>>::value << std::endl;
-}
@@ -1 +0,0 @@
-true
@@ -1,12 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    using Map = nlohmann::ordered_map<std::string, int>;
-
-    std::cout << std::boolalpha
-              << "Container is std::vector<std::pair<const Key, T>>: "
-              << std::is_same<Map::Container, std::vector<std::pair<const std::string, int>>>::value
-              << std::endl;
-}
@@ -1 +0,0 @@
-Container is std::vector<std::pair<const Key, T>>: true
@@ -1,26 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-    m["two"] = 2;
-
-    // access an existing element
-    std::cout << "m.at(\"one\") = " << m.at("one") << std::endl;
-
-    // modify through the reference returned by at()
-    m.at("two") = 22;
-    std::cout << "m.at(\"two\") = " << m.at("two") << std::endl;
-
-    // accessing a missing key throws
-    try
-    {
-        m.at("three");
-    }
-    catch (const std::out_of_range& e)
-    {
-        std::cout << "exception: " << e.what() << std::endl;
-    }
-}
@@ -1,3 +0,0 @@
-m.at("one") = 1
-m.at("two") = 22
-exception: key not found
@@ -1,12 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-
-    std::cout << std::boolalpha
-              << "m.count(\"one\") = " << m.count("one") << '\n'
-              << "m.count(\"two\") = " << m.count("two") << std::endl;
-}
@@ -1,2 +0,0 @@
-m.count("one") = 1
-m.count("two") = 0
@@ -1,15 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, std::string> m;
-
-    // emplace a new element
-    auto res1 = m.emplace("one", "eins");
-    std::cout << std::boolalpha << "inserted: " << res1.second << ", value: " << res1.first->second << std::endl;
-
-    // emplace with an already-existing key: no-op, returns the existing element
-    auto res2 = m.emplace("one", "uno");
-    std::cout << std::boolalpha << "inserted: " << res2.second << ", value: " << res2.first->second << std::endl;
-}
@@ -1,2 +0,0 @@
-inserted: true, value: eins
-inserted: false, value: eins
@@ -1,24 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-    m["two"] = 2;
-    m["three"] = 3;
-
-    // erase by key
-    std::size_t removed = m.erase("two");
-    std::cout << "removed by key: " << removed << std::endl;
-
-    // erase by iterator
-    m.erase(m.begin());
-
-    std::cout << "remaining: ";
-    for (const auto& element : m)
-    {
-        std::cout << element.first << ' ';
-    }
-    std::cout << std::endl;
-}
@@ -1,2 +0,0 @@
-removed by key: 1
-remaining: three 
@@ -1,19 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-
-    auto it = m.find("one");
-    if (it != m.end())
-    {
-        std::cout << "found: " << it->first << " = " << it->second << std::endl;
-    }
-
-    if (m.find("two") == m.end())
-    {
-        std::cout << "\"two\" not found" << std::endl;
-    }
-}
@@ -1,2 +0,0 @@
-found: one = 1
-"two" not found
@@ -1,21 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-
-    // insert a single value
-    auto res = m.insert({"one", 1});
-    std::cout << std::boolalpha << "inserted: " << res.second << std::endl;
-
-    // insert a range from another container
-    std::vector<std::pair<const std::string, int>> more = {{"two", 2}, {"three", 3}};
-    m.insert(more.begin(), more.end());
-
-    for (const auto& element : m)
-    {
-        std::cout << element.first << ':' << element.second << ' ';
-    }
-    std::cout << std::endl;
-}
@@ -1,2 +0,0 @@
-inserted: true
-one:1 two:2 three:3 
@@ -1,12 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    using Map = nlohmann::ordered_map<std::string, int>;
-    Map::key_compare compare{};
-
-    std::cout << std::boolalpha
-              << "compare(\"a\", \"a\") = " << compare("a", "a") << '\n'
-              << "compare(\"a\", \"b\") = " << compare("a", "b") << std::endl;
-}
@@ -1,2 +0,0 @@
-compare("a", "a") = true
-compare("a", "b") = false
@@ -1,14 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-
-    // operator[] inserts a default-constructed value if the key doesn't exist yet
-    m["one"] = 1;
-    std::cout << "m[\"one\"] = " << m["one"] << std::endl;
-
-    // accessing again just returns the existing value
-    std::cout << "m[\"one\"] = " << m["one"] << std::endl;
-}
@@ -1,2 +0,0 @@
-m["one"] = 1
-m["one"] = 1
@@ -83,6 +83,13 @@ When defined, default parse and serialize functions for enums are excluded and h

 See [full documentation of `JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md).

+## `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`
+
+When defined to `1`, a JSON value can no longer be created from a one-element `std::tuple` holding a reference to a JSON
+value, such as the result of `std::forward_as_tuple(j)`. This lets `std::tuple` convert such tuples element-wise.
+
+See [full documentation of `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](../api/macros/json_disable_tuple_reference_conversion.md).
+
 ## `JSON_NO_IO`

 When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions
@@ -51,16 +51,16 @@ If you do want to preserve the **insertion order**, you can use the type [`nlohm
    --8<-- "examples/ordered_json.output"
    ```

-Alternatively, [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) also preserves the insertion order and, unlike [`ordered_map`](../api/ordered_map/index.md), keeps a lookup index, so it does not have the quadratic cost described below. It is used through a small adapter ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
+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.

-The [`ordered_map`](../api/ordered_map/index.md) behind `nlohmann::ordered_json` is deliberately minimal and has no lookup
+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
 typical object sizes but becomes significant for objects with many thousands of keys; see
-[`ordered_map` complexity](../api/ordered_map/index.md#complexity). The alternatives above keep a lookup index and do not
+[`ordered_map` complexity](../api/ordered_map.md#complexity). The alternatives above keep a lookup index and do not
 have this cost.

 ### Notes on parsing
@@ -37,7 +37,7 @@ Requirements are split into two groups:

 | Template parameter                                                | Default                           | Notable substitutes                                                   |
 |-------------------------------------------------------------------|-----------------------------------|-----------------------------------------------------------------------|
-| [`ObjectType`](#objecttype)                                       | `std::map`                        | [`nlohmann::ordered_map`](../../api/ordered_map/index.md), Abseil hash maps |
+| [`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                                                      |
@@ -230,7 +230,7 @@ The library does not sort or de-duplicate keys itself; the behavior described in
 | Container                                                                        | Notes                                                                         |
 |----------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
 | `#!cpp std::map` (default)                                                       |                                                                               |
-| [`nlohmann::ordered_map`](../../api/ordered_map/index.md)                              | used by [`ordered_json`](../../api/ordered_json.md); keeps insertion order    |
+| [`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                 |
@@ -50,7 +50,7 @@ The public headers are in [`include/nlohmann`](https://github.com/nlohmann/json/
 - [`adl_serializer.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/adl_serializer.hpp), [`byte_container_with_subtype.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/byte_container_with_subtype.hpp), and [`ordered_map.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/ordered_map.hpp) define
  [`adl_serializer`](../api/adl_serializer/index.md),
  [`byte_container_with_subtype`](../api/byte_container_with_subtype/index.md), and
-  [`ordered_map`](../api/ordered_map/index.md).
+  [`ordered_map`](../api/ordered_map.md).

 Everything else lives in [`detail/`](https://github.com/nlohmann/json/tree/develop/include/nlohmann/detail) and namespace `nlohmann::detail`, which is not part of the public API. Paths
 below are relative to `include/nlohmann`.
@@ -97,7 +97,7 @@ is generated from these files with `make amalgamate` and must not be edited by h
 The library provides two specializations:

 - [`json`](../api/json.md) uses all default template arguments.
- [`ordered_json`](../api/ordered_json.md) uses [`ordered_map`](../api/ordered_map/index.md) as `ObjectType` to keep the
+- [`ordered_json`](../api/ordered_json.md) uses [`ordered_map`](../api/ordered_map.md) as `ObjectType` to keep the
  insertion order of object keys.

 The requirements on the template arguments are listed in
@@ -2,8 +2,7 @@

 This page summarizes the notable changes of every release and links to the relevant documentation.
 The **complete release notes** — including all changes, the download files, and their checksums — are
-published on the [GitHub releases page](https://github.com/nlohmann/json/releases). For a raw,
-signature-level diff of the public API between releases, see [API Changes](api_changes.md).
+published on the [GitHub releases page](https://github.com/nlohmann/json/releases).

 ## v3.12.0 (2025-04-11)

@@ -169,6 +169,12 @@ Enable position diagnostics by defining macro [`JSON_DIAGNOSTIC_POSITIONS`](../a
 Disable default `enum` serialization by defining the macro
 [`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md). This option is `OFF` by default.

+### `JSON_DisableTupleReferenceConversion`
+
+Disable the conversion from a one-element `std::tuple` holding a reference to a JSON value by defining the macro
+[`JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](../api/macros/json_disable_tuple_reference_conversion.md). This option is
+`OFF` by default.
+
 ### `JSON_FastTests`

 Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JSON_BuildTests`.
@@ -52,7 +52,6 @@ nav:
      - "FAQ": home/faq.md
      - home/exceptions.md
      - home/releases.md
-      - home/api_changes.md
      - home/design_goals.md
      - home/architecture.md
      - home/customers.md
@@ -120,7 +119,6 @@ nav:
          - 'begin': api/basic_json/begin.md
          - 'binary': api/basic_json/binary.md
          - 'binary_t': api/basic_json/binary_t.md
-          - 'bjdata_version_t': api/basic_json/bjdata_version_t.md
          - 'boolean_t': api/basic_json/boolean_t.md
          - 'cbegin': api/basic_json/cbegin.md
          - 'cbor_tag_handler_t': api/basic_json/cbor_tag_handler_t.md
@@ -159,7 +157,6 @@ nav:
          - 'get_to': api/basic_json/get_to.md
          - 'std::formatter&lt;basic_json&gt;': api/basic_json/std_formatter.md
          - 'std::hash&lt;basic_json&gt;': api/basic_json/std_hash.md
-          - 'initializer_list_t': api/basic_json/initializer_list_t.md
          - 'input_format_t': api/basic_json/input_format_t.md
          - 'insert': api/basic_json/insert.md
          - 'invalid_iterator': api/basic_json/invalid_iterator.md
@@ -178,7 +175,6 @@ nav:
          - 'is_structured': api/basic_json/is_structured.md
          - 'items': api/basic_json/items.md
          - 'json_base_class_t': api/basic_json/json_base_class_t.md
-          - 'json_sax_t': api/basic_json/json_sax_t.md
          - 'json_serializer': api/basic_json/json_serializer.md
          - 'max_size': api/basic_json/max_size.md
          - 'meta': api/basic_json/meta.md
@@ -236,13 +232,9 @@ nav:
          - 'Overview': api/byte_container_with_subtype/index.md
          - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md
          - 'clear_subtype': api/byte_container_with_subtype/clear_subtype.md
-          - 'container_type': api/byte_container_with_subtype/container_type.md
          - 'has_subtype': api/byte_container_with_subtype/has_subtype.md
-          - 'operator==': api/byte_container_with_subtype/operator_eq.md
-          - 'operator!=': api/byte_container_with_subtype/operator_ne.md
          - 'set_subtype': api/byte_container_with_subtype/set_subtype.md
          - 'subtype': api/byte_container_with_subtype/subtype.md
-          - 'subtype_type': api/byte_container_with_subtype/subtype_type.md
      - adl_serializer:
          - 'Overview': api/adl_serializer/index.md
          - 'from_json': api/adl_serializer/from_json.md
@@ -268,46 +260,25 @@ nav:
          - 'to_string': api/json_pointer/to_string.md
      - json_sax:
          - 'Overview': api/json_sax/index.md
-          - '(Constructor)': api/json_sax/json_sax.md
-          - '(Destructor)': api/json_sax/~json_sax.md
-          - 'operator=': api/json_sax/operator=.md
          - 'binary': api/json_sax/binary.md
-          - 'binary_t': api/json_sax/binary_t.md
          - 'boolean': api/json_sax/boolean.md
          - 'end_array': api/json_sax/end_array.md
          - 'end_object': api/json_sax/end_object.md
          - 'key': api/json_sax/key.md
          - 'null': api/json_sax/null.md
          - 'number_float': api/json_sax/number_float.md
-          - 'number_float_t': api/json_sax/number_float_t.md
          - 'number_integer': api/json_sax/number_integer.md
-          - 'number_integer_t': api/json_sax/number_integer_t.md
          - 'number_unsigned': api/json_sax/number_unsigned.md
-          - 'number_unsigned_t': api/json_sax/number_unsigned_t.md
          - 'parse_error': api/json_sax/parse_error.md
          - 'start_array': api/json_sax/start_array.md
          - 'start_object': api/json_sax/start_object.md
          - 'string': api/json_sax/string.md
-          - 'string_t': api/json_sax/string_t.md
      - 'operator<<(basic_json), operator<<(json_pointer)': api/operator_ltlt.md
      - 'operator>>(basic_json)': api/operator_gtgt.md
      - 'operator""_json': api/operator_literal_json.md
      - 'operator""_json_pointer': api/operator_literal_json_pointer.md
      - 'ordered_json': api/ordered_json.md
-      - ordered_map:
-          - 'Overview': api/ordered_map/index.md
-          - '(Constructor)': api/ordered_map/ordered_map.md
-          - '(Destructor)': api/ordered_map/~ordered_map.md
-          - 'operator=': api/ordered_map/operator=.md
-          - 'at': api/ordered_map/at.md
-          - 'Container': api/ordered_map/Container.md
-          - 'count': api/ordered_map/count.md
-          - 'emplace': api/ordered_map/emplace.md
-          - 'erase': api/ordered_map/erase.md
-          - 'find': api/ordered_map/find.md
-          - 'insert': api/ordered_map/insert.md
-          - 'key_compare': api/ordered_map/key_compare.md
-          - 'operator[]': api/ordered_map/operator[].md
+      - 'ordered_map': api/ordered_map.md
      - macros:
          - 'Overview': api/macros/index.md
          - 'JSON_ASSERT': api/macros/json_assert.md
@@ -316,6 +287,7 @@ nav:
          - 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md
          - 'JSON_DIAGNOSTIC_POSITIONS': api/macros/json_diagnostic_positions.md
          - 'JSON_DISABLE_ENUM_SERIALIZATION': api/macros/json_disable_enum_serialization.md
+          - 'JSON_DISABLE_TUPLE_REFERENCE_CONVERSION': api/macros/json_disable_tuple_reference_conversion.md
          - 'JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20': api/macros/json_has_cpp_11.md
          - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM, JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md
          - 'JSON_HAS_RANGES': api/macros/json_has_ranges.md
@@ -22,9 +22,7 @@ template<typename BinaryType>
 class byte_container_with_subtype : public BinaryType
 {
  public:
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/container_type/
    using container_type = BinaryType;
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype_type/
    using subtype_type = std::uint64_t;

    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
@@ -56,14 +54,12 @@ class byte_container_with_subtype : public BinaryType
        , m_has_subtype(true)
    {}

-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/operator_eq/
    bool operator==(const byte_container_with_subtype& rhs) const
    {
        return std::tie(static_cast<const BinaryType&>(*this), m_subtype, m_has_subtype) ==
               std::tie(static_cast<const BinaryType&>(rhs), rhs.m_subtype, rhs.m_has_subtype);
    }

-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/operator_ne/
    bool operator!=(const byte_container_with_subtype& rhs) const
    {
        return !(rhs == *this);
@@ -471,11 +471,13 @@ inline void to_json_tuple_impl(BasicJsonType& j, const Tuple& t, index_sequence<
    j = { std::get<Idx>(t)... };
 }

-#if JSON_BRACE_INIT_COPY_SEMANTICS
-// JSON_BRACE_INIT_COPY_SEMANTICS makes a one-element braced list copy its
-// element instead of wrapping it, which would serialize std::tuple<int>{5} as 5
-// rather than [5]. Build what the default deduction builds instead: an object
-// if the element is a [string, value] pair, a one-element array otherwise.
+// A one-element braced list does not reliably wrap its element: with
+// JSON_BRACE_INIT_COPY_SEMANTICS it copies it, which would serialize
+// std::tuple<int>{5} as 5 rather than [5], and some compilers (e.g., Apple clang
+// 15 and 16) copy an element that is itself a basic_json even without it, so
+// std::tuple<json>{true} became true rather than [true]. Build what the default
+// deduction builds instead: an object if the element is a [string, value] pair,
+// a one-element array otherwise.
 template<typename BasicJsonType, typename Tuple>
 inline void to_json_tuple_impl(BasicJsonType& j, const Tuple& t, index_sequence<0> /*unused*/)
 {
@@ -493,7 +495,6 @@ inline void to_json_tuple_impl(BasicJsonType& j, const Tuple& t, index_sequence<
        j = BasicJsonType::array({std::move(element)});
    }
 }
-#endif

 template<typename BasicJsonType, typename Tuple>
 inline void to_json_tuple_impl(BasicJsonType& j, const Tuple& /*unused*/, index_sequence<> /*unused*/)
@@ -33,21 +33,15 @@ input.
 template<typename BasicJsonType>
 struct json_sax
 {
-    /// @sa https://json.nlohmann.me/api/json_sax/number_integer_t/
    using number_integer_t = typename BasicJsonType::number_integer_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/number_unsigned_t/
    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/number_float_t/
    using number_float_t = typename BasicJsonType::number_float_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/string_t/
    using string_t = typename BasicJsonType::string_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/binary_t/
    using binary_t = typename BasicJsonType::binary_t;

    /*!
    @brief a null value was read
    @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/null/
    */
    virtual bool null() = 0;

@@ -55,7 +49,6 @@ struct json_sax
    @brief a boolean value was read
    @param[in] val  boolean value
    @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/boolean/
    */
    virtual bool boolean(bool val) = 0;

@@ -63,7 +56,6 @@ struct json_sax
    @brief an integer number was read
    @param[in] val  integer value
    @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_integer/
    */
    virtual bool number_integer(number_integer_t val) = 0;

@@ -71,7 +63,6 @@ struct json_sax
    @brief an unsigned integer number was read
    @param[in] val  unsigned integer value
    @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_unsigned/
    */
    virtual bool number_unsigned(number_unsigned_t val) = 0;

@@ -80,7 +71,6 @@ struct json_sax
    @param[in] val  floating-point value
    @param[in] s    raw token value
    @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_float/
    */
    virtual bool number_float(number_float_t val, const string_t& s) = 0;

@@ -89,7 +79,6 @@ struct json_sax
    @param[in] val  string value
    @return whether parsing should proceed
    @note It is safe to move the passed string value.
-    @sa https://json.nlohmann.me/api/json_sax/string/
    */
    virtual bool string(string_t& val) = 0;

@@ -98,7 +87,6 @@ struct json_sax
    @param[in] val  binary value
    @return whether parsing should proceed
    @note It is safe to move the passed binary value.
-    @sa https://json.nlohmann.me/api/json_sax/binary/
    */
    virtual bool binary(binary_t& val) = 0;

@@ -107,7 +95,6 @@ struct json_sax
    @param[in] elements  number of object elements or -1 if unknown
    @return whether parsing should proceed
    @note binary formats may report the number of elements
-    @sa https://json.nlohmann.me/api/json_sax/start_object/
    */
    virtual bool start_object(std::size_t elements) = 0;

@@ -116,14 +103,12 @@ struct json_sax
    @param[in] val  object key
    @return whether parsing should proceed
    @note It is safe to move the passed string.
-    @sa https://json.nlohmann.me/api/json_sax/key/
    */
    virtual bool key(string_t& val) = 0;

    /*!
    @brief the end of an object was read
    @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/end_object/
    */
    virtual bool end_object() = 0;

@@ -132,14 +117,12 @@ struct json_sax
    @param[in] elements  number of array elements or -1 if unknown
    @return whether parsing should proceed
    @note binary formats may report the number of elements
-    @sa https://json.nlohmann.me/api/json_sax/start_array/
    */
    virtual bool start_array(std::size_t elements) = 0;

    /*!
    @brief the end of an array was read
    @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/end_array/
    */
    virtual bool end_array() = 0;

@@ -149,23 +132,16 @@ struct json_sax
    @param[in] last_token  the last read token
    @param[in] ex          an exception object describing the error
    @return whether parsing should proceed (must return false)
-    @sa https://json.nlohmann.me/api/json_sax/parse_error/
    */
    virtual bool parse_error(std::size_t position,
                             const std::string& last_token,
                             const detail::exception& ex) = 0;

-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
    json_sax() = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
    json_sax(const json_sax&) = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
    json_sax(json_sax&&) noexcept = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/operator=/
    json_sax& operator=(const json_sax&) = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/operator=/
    json_sax& operator=(json_sax&&) noexcept = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/~json_sax/
    virtual ~json_sax() = default;
 };

@@ -56,7 +56,6 @@ class json_pointer

  public:
    // for backwards compatibility accept BasicJsonType
-    /// @sa https://json.nlohmann.me/api/json_pointer/string_t/
    using string_t = typename string_t_helper<RefStringType>::type;

    /// @brief create JSON pointer
@@ -916,6 +916,10 @@ void templated_json_throw(ExceptionType exception)
    #define JSON_DISABLE_ENUM_SERIALIZATION 0
 #endif

+#ifndef JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+    #define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 0
+#endif
+
 #ifndef JSON_USE_GLOBAL_UDLS
    #define JSON_USE_GLOBAL_UDLS 1
 #endif
@@ -25,6 +25,7 @@
 #undef JSON_INLINE_VARIABLE
 #undef JSON_NO_UNIQUE_ADDRESS
 #undef JSON_DISABLE_ENUM_SERIALIZATION
+#undef JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
 #undef JSON_USE_GLOBAL_UDLS

 #ifndef JSON_TEST_KEEP_MACROS
@@ -636,6 +636,18 @@ template<typename BasicJsonType, typename CompatibleType>
 struct is_compatible_type
    : is_compatible_type_impl<BasicJsonType, CompatibleType> {};

+// a one-element std::tuple holding a reference to BasicJsonType, as created by
+// std::forward_as_tuple(j); see JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+template<typename BasicJsonType, typename T>
+struct is_basic_json_reference_tuple : std::false_type {};
+
+template<typename BasicJsonType, typename T>
+struct is_basic_json_reference_tuple<BasicJsonType, std::tuple<T>>
+{
+    static constexpr bool value =
+        std::is_reference<T>::value && std::is_same<uncvref_t<T>, BasicJsonType>::value;
+};
+
 template<typename BasicJsonType, typename CompatibleArrayType>
 struct is_compatible_binary_type
 {
@@ -202,31 +202,22 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    using serializer = ::nlohmann::detail::serializer<basic_json>;

  public:
-    /// @brief the type of the JSON value
-    /// @sa https://json.nlohmann.me/api/basic_json/value_t/
    using value_t = detail::value_t;
    /// JSON Pointer, see @ref nlohmann::json_pointer
    using json_pointer = ::nlohmann::json_pointer<StringType>;
    template<typename T, typename SFINAE>
    using json_serializer = JSONSerializer<T, SFINAE>;
    /// how to treat decoding errors
-    /// @sa https://json.nlohmann.me/api/basic_json/error_handler_t/
    using error_handler_t = detail::error_handler_t;
    /// how to treat CBOR tags
-    /// @sa https://json.nlohmann.me/api/basic_json/cbor_tag_handler_t/
    using cbor_tag_handler_t = detail::cbor_tag_handler_t;
    /// how to encode BJData
-    /// @sa https://json.nlohmann.me/api/basic_json/bjdata_version_t/
    using bjdata_version_t = detail::bjdata_version_t;
    /// helper type for initializer lists of basic_json values
-    /// @sa https://json.nlohmann.me/api/basic_json/initializer_list_t/
    using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;

-    /// @brief the type of the SAX interface used to parse and serialize the JSON value
-    /// @sa https://json.nlohmann.me/api/basic_json/input_format_t/
    using input_format_t = detail::input_format_t;
    /// SAX interface type, see @ref nlohmann::json_sax
-    /// @sa https://json.nlohmann.me/api/basic_json/json_sax_t/
    using json_sax_t = json_sax<basic_json>;

    ////////////////
@@ -368,19 +359,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    /// the template arguments passed to class @ref basic_json.
    /// @{

-#if defined(JSON_HAS_CPP_14)
    /// @brief default object key comparator type
    /// The actual object key comparator type (@ref object_comparator_t) may be
    /// different.
    /// @sa https://json.nlohmann.me/api/basic_json/default_object_comparator_t/
+#if defined(JSON_HAS_CPP_14)
    // use of transparent comparator avoids unnecessary repeated construction of temporaries
    // in functions involving lookup by key with types other than object_t::key_type (aka. StringType)
    using default_object_comparator_t = std::less<>;
 #else
-    /// @brief default object key comparator type
-    /// The actual object key comparator type (@ref object_comparator_t) may be
-    /// different.
-    /// @sa https://json.nlohmann.me/api/basic_json/default_object_comparator_t/
    using default_object_comparator_t = std::less<StringType>;
 #endif

@@ -1608,7 +1595,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    template < typename CompatibleType,
               typename U = detail::uncvref_t<CompatibleType>,
               detail::enable_if_t <
-                   !detail::is_basic_json<U>::value && detail::is_compatible_type<basic_json_t, U>::value, int > = 0 >
+                   !detail::is_basic_json<U>::value && detail::is_compatible_type<basic_json_t, U>::value
+#if JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+                   // see https://github.com/nlohmann/json/issues/2226
+                   && !detail::is_basic_json_reference_tuple<basic_json_t, U>::value
+#endif
+                   , int > = 0 >
    basic_json(CompatibleType && val) noexcept(noexcept( // NOLINT(bugprone-forwarding-reference-overload,bugprone-exception-escape)
                JSONSerializer<U>::to_json(std::declval<basic_json_t&>(),
                                           std::forward<CompatibleType>(val))))
@@ -1926,7 +1918,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    // other constructors and destructor //
    ///////////////////////////////////////

-    /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
    template<typename JsonRef,
             detail::enable_if_t<detail::conjunction<detail::is_json_ref<JsonRef>,
                                 std::is_same<typename JsonRef::value_type, basic_json>>::value, int> = 0 >
@@ -2510,8 +2501,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    @throw what @ref json_serializer<ValueType> `from_json()` method throws if conversion is required

    @since version 2.1.0
-
-    @sa https://json.nlohmann.me/api/basic_json/get/
    */
    template < typename ValueTypeCV, typename ValueType = detail::uncvref_t<ValueTypeCV>>
 #if defined(JSON_HAS_CPP_14)
@@ -2555,8 +2544,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    @sa see @ref get_ptr() for explicit pointer-member access

    @since version 1.0.0
-
-    @sa https://json.nlohmann.me/api/basic_json/get/
    */
    template<typename PointerType, typename std::enable_if<
                 std::is_pointer<PointerType>::value, int>::type = 0>
@@ -2583,7 +2570,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec

    // specialization to allow calling get_to with a basic_json value
    // see https://github.com/nlohmann/json/issues/2175
-    /// @sa https://json.nlohmann.me/api/basic_json/get_to/
    template<typename ValueType,
             detail::enable_if_t <
                 detail::is_basic_json<ValueType>::value,
@@ -2594,7 +2580,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return v;
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/get_to/
    template <
        typename T, std::size_t N,
        typename Array = T (&)[N], // NOLINT(cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
@@ -2659,7 +2644,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec

    @since version 1.0.0
    */
-    /// @sa https://json.nlohmann.me/api/basic_json/operator_ValueType/
    template < typename ValueType, typename std::enable_if <
                   detail::conjunction <
                       detail::negation<std::is_pointer<ValueType>>,
@@ -2932,14 +2916,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec

    // these two functions resolve a (const) char * ambiguity affecting Clang and MSVC
    // (they seemingly cannot be constrained to resolve the ambiguity)
-    /// @sa https://json.nlohmann.me/api/basic_json/operator[]/
    template<typename T>
    reference operator[](T* key)
    {
        return operator[](typename object_t::key_type(key));
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/operator[]/
    template<typename T>
    const_reference operator[](T* key) const
    {
@@ -3149,7 +3131,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        JSON_THROW(type_error::create(306, detail::concat("cannot use value() with ", type_name()), this));
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/value/
    template < class ValueType, class BasicJsonType, detail::enable_if_t <
                   detail::is_basic_json<BasicJsonType>::value
                   && detail::is_getable<basic_json_t, ValueType>::value
@@ -3160,7 +3141,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return value(ptr.convert(), default_value);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/value/
    template < class ValueType, class BasicJsonType, class ReturnType = typename value_return_type<ValueType>::type,
               detail::enable_if_t <
                   detail::is_basic_json<BasicJsonType>::value
@@ -3540,7 +3520,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return ptr.contains(this);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/contains/
    template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
@@ -4960,7 +4939,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return result;
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/parse/
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, parse(ptr, ptr + len))
    static basic_json parse(detail::span_input_adapter&& i,
@@ -4997,7 +4975,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return parser(detail::input_adapter(std::move(first), std::move(last)), nullptr, false, ignore_comments, ignore_trailing_commas, true).accept(true);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/accept/
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, accept(ptr, ptr + len))
    static bool accept(detail::span_input_adapter&& i,
@@ -5381,7 +5358,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return result;
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
    template<typename T>
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_cbor(ptr, ptr + len))
@@ -5393,7 +5369,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return from_cbor(ptr, ptr + len, strict, allow_exceptions, tag_handler);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_cbor(ptr, ptr + len))
    static basic_json from_cbor(detail::span_input_adapter&& i,
@@ -5449,7 +5424,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return result;
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
    template<typename T>
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
@@ -5460,7 +5434,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return from_msgpack(ptr, ptr + len, strict, allow_exceptions);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
    static basic_json from_msgpack(detail::span_input_adapter&& i,
@@ -5515,7 +5488,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return result;
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
    template<typename T>
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_ubjson(ptr, ptr + len))
@@ -5526,7 +5498,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return from_ubjson(ptr, ptr + len, strict, allow_exceptions);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_ubjson(ptr, ptr + len))
    static basic_json from_ubjson(detail::span_input_adapter&& i,
@@ -5655,7 +5626,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return result;
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
    template<typename T>
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_bson(ptr, ptr + len))
@@ -5666,7 +5636,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return from_bson(ptr, ptr + len, strict, allow_exceptions);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
    JSON_HEDLEY_WARN_UNUSED_RESULT
    JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_bson(ptr, ptr + len))
    static basic_json from_bson(detail::span_input_adapter&& i,
@@ -5699,7 +5668,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return ptr.get_unchecked(this);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
    template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
    JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
    reference operator[](const ::nlohmann::json_pointer<BasicJsonType>& ptr)
@@ -5714,7 +5682,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return ptr.get_unchecked(this);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
    template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
    JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
    const_reference operator[](const ::nlohmann::json_pointer<BasicJsonType>& ptr) const
@@ -5729,7 +5696,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return ptr.get_checked(this);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/at/
    template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
    JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
    reference at(const ::nlohmann::json_pointer<BasicJsonType>& ptr)
@@ -5744,7 +5710,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
        return ptr.get_checked(this);
    }

-    /// @sa https://json.nlohmann.me/api/basic_json/at/
    template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
    JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
    const_reference at(const ::nlohmann::json_pointer<BasicJsonType>& ptr) const
@@ -30,41 +30,30 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
 {
    using key_type = Key;
    using mapped_type = T;
-    /// @sa https://json.nlohmann.me/api/ordered_map/Container/
    using Container = std::vector<std::pair<const Key, T>, Allocator>;
    using iterator = typename Container::iterator;
    using const_iterator = typename Container::const_iterator;
    using size_type = typename Container::size_type;
    using value_type = typename Container::value_type;
 #ifdef JSON_HAS_CPP_14
-    /// @sa https://json.nlohmann.me/api/ordered_map/key_compare/
    using key_compare = std::equal_to<>;
 #else
-    /// @sa https://json.nlohmann.me/api/ordered_map/key_compare/
    using key_compare = std::equal_to<Key>;
 #endif

    // Explicit constructors instead of `using Container::Container`
    // otherwise older compilers choke on it (GCC <= 5.5, xcode <= 9.4)
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
    ordered_map() noexcept(noexcept(Container())) : Container{} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
    explicit ordered_map(const Allocator& alloc) noexcept(noexcept(Container(alloc))) : Container{alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
    template <class It>
    ordered_map(It first, It last, const Allocator& alloc = Allocator())
        : Container{first, last, alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
    ordered_map(std::initializer_list<value_type> init, const Allocator& alloc = Allocator() )
        : Container{init, alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
    ordered_map(const ordered_map&) = default;
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
    ordered_map(ordered_map&&) noexcept(std::is_nothrow_move_constructible<Container>::value) = default;
-    /// @sa https://json.nlohmann.me/api/ordered_map/~ordered_map/
    ~ordered_map() = default;

-    /// @sa https://json.nlohmann.me/api/ordered_map/operator=/
    ordered_map& operator=(const ordered_map& other)
    {
        if (this != &other)
@@ -75,14 +64,12 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return *this;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/operator=/
    ordered_map& operator=(ordered_map&& other) noexcept(std::is_nothrow_move_assignable<Container>::value)
    {
        Container::operator=(std::move(static_cast<Container&>(other)));
        return *this;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/emplace/
    std::pair<iterator, bool> emplace(const key_type& key, T&& t)
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -96,7 +83,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return {std::prev(this->end()), true};
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/emplace/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    std::pair<iterator, bool> emplace(KeyType && key, T && t)
@@ -112,13 +98,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return {std::prev(this->end()), true};
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
    T& operator[](const key_type& key)
    {
        return emplace(key, T{}).first->second;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    T & operator[](KeyType && key)
@@ -126,13 +110,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return emplace(std::forward<KeyType>(key), T{}).first->second;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
    const T& operator[](const key_type& key) const
    {
        return at(key);
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    const T & operator[](KeyType && key) const
@@ -140,7 +122,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return at(std::forward<KeyType>(key));
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
    T& at(const key_type& key)
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -154,7 +135,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        JSON_THROW(std::out_of_range("key not found"));
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    T & at(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -170,7 +150,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        JSON_THROW(std::out_of_range("key not found"));
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
    const T& at(const key_type& key) const
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -184,7 +163,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        JSON_THROW(std::out_of_range("key not found"));
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    const T & at(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -200,7 +178,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        JSON_THROW(std::out_of_range("key not found"));
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
    size_type erase(const key_type& key)
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -220,7 +197,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return 0;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    size_type erase(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -242,13 +218,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return 0;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
    iterator erase(iterator pos)
    {
        return erase(pos, std::next(pos));
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
    iterator erase(iterator first, iterator last)
    {
        if (first == last)
@@ -302,7 +276,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return Container::begin() + offset;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/count/
    size_type count(const key_type& key) const
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -315,7 +288,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return 0;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/count/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    size_type count(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -330,7 +302,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return 0;
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
    iterator find(const key_type& key)
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -343,7 +314,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return Container::end();
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    iterator find(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -358,7 +328,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return Container::end();
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
    const_iterator find(const key_type& key) const
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -371,7 +340,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return Container::end();
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
    template<class KeyType, detail::enable_if_t<
                 detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
    const_iterator find(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -386,13 +354,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
        return Container::end();
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
    std::pair<iterator, bool> insert( value_type&& value )
    {
        return emplace(value.first, std::move(value.second));
    }

-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
    std::pair<iterator, bool> insert( const value_type& value )
    {
        for (auto it = this->begin(); it != this->end(); ++it)
@@ -410,7 +376,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
    using require_input_iter = typename std::enable_if<std::is_convertible<typename std::iterator_traits<InputIt>::iterator_category,
        std::input_iterator_tag>::value>::type;

-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
    template<typename InputIt, typename = require_input_iter<InputIt>>
    void insert(InputIt first, InputIt last)
    {
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Niels Lohmann	df0dad135c	Merge branch 'develop' into claude/issue-2226-5c9bef Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-28 22:22:32 +02:00
Niels Lohmann	55670233ea	Skip json reference tuple tests on clang < 4 and GCC < 5 ci_test_compilers_gcc_old (4.8) and ci_test_compilers_clang (3.4) could not compile the new tuple tests. Creating a std::tuple of basic_json references, e.g. std::forward_as_tuple(j), makes these compilers instantiate basic_json's conversion operator for libstdc++'s internal tuple bases, which fails hard. This happens with and without JSON_DISABLE_TUPLE_REFERENCE_CONVERSION, so it is a limitation of these compilers, not of the new option. Tested with the CI images: clang 3.4 to 3.9 and GCC 4.8 and 4.9 fail, clang 4, 5, and 6 and GCC 5 and 6 compile all cases. Skip only the checks that create such tuples; the is_constructible checks still run. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-28 18:59:28 +02:00
Niels Lohmann	82667aadff	Convert one-element tuples to arrays on every compiler to_json for std::tuple assigns a braced list, j = { std::get<Idx>(t)... }. With a single element that is itself a basic_json, Apple clang 15 and 16 treat j = {x} as a copy of x, so std::tuple<json>{true} became true instead of [true]. The macOS jobs (Xcode 15.1, 16.1) failed the new checks in unit-disable-tuple-reference-conversion and unit-regression2. The one-element overload that already handles JSON_BRACE_INIT_COPY_SEMANTICS builds the array (or object, for a [string, value] element) explicitly, the same way the initializer-list constructor does. Use it unconditionally. The output is unchanged on compilers that already wrapped the element. Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-28 02:10:24 +02:00
Niels Lohmann	bc69ff786d	Merge branch 'develop' into claude/issue-2226-5c9bef Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 20:57:52 +02:00
Niels Lohmann	c5f1694b01	Add JSON_DISABLE_TUPLE_REFERENCE_CONVERSION to fix std::tuple conversions basic_json can be constructed from std::tuple<json&>, which it turns into a one-element array. Because of this, std::tuple picks its converting constructor that converts the whole source tuple instead of the element-wise one. As a result, std::tuple<const json&> built from std::forward_as_tuple(j) binds to a temporary (a compile error with libc++, a dangling reference with other standard libraries), and std::tuple<json> built the same way holds [j] instead of a copy of j. The new opt-in macro JSON_DISABLE_TUPLE_REFERENCE_CONVERSION (CMake option JSON_DisableTupleReferenceConversion) removes the conversion from a one-element tuple holding a reference to the same basic_json type, so std::tuple converts element-wise. It is off by default, so existing behavior is unchanged. It does not change any function body and therefore is not part of the ABI tag. Fixes #2226 Signed-off-by: Niels Lohmann <mail@nlohmann.me>	2026-09-27 17:17:51 +02:00
				`@@ -1 +0,0 @@`
				`Container is std::vector<std::pair<const Key, T>>: true`