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>

.github/workflows/ubuntu.yml

@@ -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

CMakeLists.txt

@@ -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>

cmake/ci.cmake

@@ -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.
 ###############################################################################

docs/docset/docSet.sql

@@ -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');

docs/mkdocs/docs/api/basic_json/basic_json.md

@@ -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
 

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -86,9 +86,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
     - Throws [`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) if an array index in the passed
       JSON pointer `ptr` exceeds the range of `size_type` (e.g., on 32-bit platforms).
 
-    For the **const** version, an object key or array index in `ptr` that does not exist is not reported by an
-    exception, but is undefined behavior (see the notes below). Use [`at`](at.md) for checked access.
-
 ## Complexity
 
 1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
@@ -103,12 +100,9 @@ Strong exception safety: if an exception occurs, the original value stays intact
     The following cases apply to the **const** overloads; the non-const overloads instead insert the missing element
     (see the notes below).
 
-    1. If the element at index `idx` does not exist, the behavior is undefined and is **guarded by a
+    1. If the element at index `idx` does not exist, the behavior is undefined.
-       [runtime assertion](../../features/assertions.md)**!
     2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by a
        [runtime assertion](../../features/assertions.md)**!
-    3. If the JSON pointer `ptr` refers to an object key or an array index that does not exist, the behavior is
-       undefined and is **guarded by a [runtime assertion](../../features/assertions.md)**!
 
 1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the
    array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In
@@ -263,11 +257,9 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ## Version history
 
-1. Added in version 1.0.0. A missing index in the const version is guarded by a runtime assertion since version
+1. Added in version 1.0.0.
-   3.13.0.
 2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3)
    in version 3.11.0.
 3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
    already supported by [`at`](at.md), [`value`](value.md), [`find`](find.md), and other lookup functions.
-4. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since
+4. Added in version 2.0.0.
-   version 3.13.0.

docs/mkdocs/docs/api/macros/index.md

@@ -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

docs/mkdocs/docs/api/macros/json_disable_tuple_reference_conversion.md

@@ -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.

docs/mkdocs/docs/features/assertions.md

@@ -16,15 +16,14 @@ before including the `json.hpp` header.
 
 ## Function with runtime assertions
 
-### Unchecked access to a const value
+### Unchecked object access to a const value
 
-Function [`operator[]`](../api/basic_json/operator%5B%5D.md) implements unchecked access for arrays and objects. Whereas
+Function [`operator[]`](../api/basic_json/operator%5B%5D.md) implements unchecked access for objects. Whereas a missing
-a missing element is added in the case of non-const values, accessing a const value with a missing object key or an
+key is added in the case of non-const objects, accessing a const object with a missing key is undefined behavior (think
-invalid array index is undefined behavior (think of a dereferenced null pointer) and yields a runtime assertion. This
+of a dereferenced null pointer) and yields a runtime assertion.
-also applies to a [JSON pointer](json_pointer.md) that refers to a missing key or an invalid index.
 
-If you are not sure whether an element exists, use checked access with the [`at` function](../api/basic_json/at.md)
+If you are not sure whether an element in an object exists, use checked access with the
-or call the [`contains` function](../api/basic_json/contains.md) before.
+[`at` function](../api/basic_json/at.md) or call the [`contains` function](../api/basic_json/contains.md) before.
 
 See also the documentation on [element access](element_access/index.md).
 
@@ -47,30 +46,7 @@ See also the documentation on [element access](element_access/index.md).
     Output:
 
     ```
-    Assertion failed: (it != m_data.m_value.object->end()), function operator[], file json.hpp, line 28795.
+    Assertion failed: (m_value.object->find(key) != m_value.object->end()), function operator[], file json.hpp, line 2144.
-    ```
-
-??? example "Example 2: Invalid array index in a JSON pointer"
-
-    The following code will trigger an assertion at runtime:
-
-    ```cpp
-    #include <nlohmann/json.hpp>
-    
-    using json = nlohmann::json;
-    using namespace nlohmann::literals;
-    
-    int main()
-    {
-        const json j = {{"array", {1, 2, 3}}};
-        auto v = j["/array/5"_json_pointer];
-    }
-    ```
-
-    Output:
-
-    ```
-    Assertion failed: (idx < m_data.m_value.array->size()), function operator[], file json.hpp, line 28758.
     ```
 
 ### Constructing from an uninitialized iterator range

docs/mkdocs/docs/features/macros.md

@@ -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

docs/mkdocs/docs/integration/cmake.md

@@ -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`.

docs/mkdocs/mkdocs.yml

@@ -287,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

include/nlohmann/detail/conversions/to_json.hpp

@@ -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
+// A one-element braced list does not reliably wrap its element: with
-// JSON_BRACE_INIT_COPY_SEMANTICS makes a one-element braced list copy its
+// JSON_BRACE_INIT_COPY_SEMANTICS it copies it, which would serialize
-// element instead of wrapping it, which would serialize std::tuple<int>{5} as 5
+// std::tuple<int>{5} as 5 rather than [5], and some compilers (e.g., Apple clang
-// rather than [5]. Build what the default deduction builds instead: an object
+// 15 and 16) copy an element that is itself a basic_json even without it, so
-// if the element is a [string, value] pair, a one-element array otherwise.
+// 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*/)

include/nlohmann/detail/json_pointer.hpp

@@ -535,10 +535,6 @@ class json_pointer
     @return const reference to the JSON value pointed to by the JSON
     pointer
 
-    @pre Every object key and array index the pointer refers to exists.
-         Like the const operator[] for keys and indices, a missing one is
-         undefined behavior, guarded by a runtime assertion.
-
     @throw parse_error.106   if an array index begins with '0'
     @throw parse_error.109   if an array index was not a number
     @throw out_of_range.402  if the array index '-' is used
@@ -553,8 +549,7 @@ class json_pointer
             {
                 case detail::value_t::object:
                 {
-                    // use unchecked object access; the const operator[]
+                    // use unchecked object access
-                    // asserts that the key exists
                     ptr = &ptr->operator[](reference_token);
                     break;
                 }
@@ -567,8 +562,7 @@ class json_pointer
                         JSON_THROW(detail::out_of_range::create(402, detail::concat("array index '-' (", std::to_string(ptr->m_data.m_value.array->size()), ") is out of range"), ptr));
                     }
 
-                    // use unchecked array access; the const operator[]
+                    // use unchecked array access
-                    // asserts that the index exists
                     ptr = &ptr->operator[](array_index<BasicJsonType>(reference_token));
                     break;
                 }

include/nlohmann/detail/macro_scope.hpp

@@ -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

include/nlohmann/detail/macro_unscope.hpp

@@ -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

include/nlohmann/detail/meta/type_traits.hpp

@@ -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
 {

include/nlohmann/json.hpp

@@ -1595,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))))
@@ -2866,7 +2871,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         // const operator[] only works for arrays
         if (JSON_HEDLEY_LIKELY(is_array()))
         {
-            JSON_ASSERT(idx < m_data.m_value.array->size());
             return m_data.m_value.array->operator[](idx);
         }
 

single_include/nlohmann/json.hpp

@@ -3327,6 +3327,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
@@ -4646,6 +4650,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
 {
@@ -7000,11 +7016,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
+// A one-element braced list does not reliably wrap its element: with
-// JSON_BRACE_INIT_COPY_SEMANTICS makes a one-element braced list copy its
+// JSON_BRACE_INIT_COPY_SEMANTICS it copies it, which would serialize
-// element instead of wrapping it, which would serialize std::tuple<int>{5} as 5
+// std::tuple<int>{5} as 5 rather than [5], and some compilers (e.g., Apple clang
-// rather than [5]. Build what the default deduction builds instead: an object
+// 15 and 16) copy an element that is itself a basic_json even without it, so
-// if the element is a [string, value] pair, a one-element array otherwise.
+// 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*/)
 {
@@ -7022,7 +7040,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*/)
@@ -19179,10 +19196,6 @@ class json_pointer
     @return const reference to the JSON value pointed to by the JSON
     pointer
 
-    @pre Every object key and array index the pointer refers to exists.
-         Like the const operator[] for keys and indices, a missing one is
-         undefined behavior, guarded by a runtime assertion.
-
     @throw parse_error.106   if an array index begins with '0'
     @throw parse_error.109   if an array index was not a number
     @throw out_of_range.402  if the array index '-' is used
@@ -19197,8 +19210,7 @@ class json_pointer
             {
                 case detail::value_t::object:
                 {
-                    // use unchecked object access; the const operator[]
+                    // use unchecked object access
-                    // asserts that the key exists
                     ptr = &ptr->operator[](reference_token);
                     break;
                 }
@@ -19211,8 +19223,7 @@ class json_pointer
                         JSON_THROW(detail::out_of_range::create(402, detail::concat("array index '-' (", std::to_string(ptr->m_data.m_value.array->size()), ") is out of range"), ptr));
                     }
 
-                    // use unchecked array access; the const operator[]
+                    // use unchecked array access
-                    // asserts that the index exists
                     ptr = &ptr->operator[](array_index<BasicJsonType>(reference_token));
                     break;
                 }
@@ -27484,7 +27495,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))))
@@ -28755,7 +28771,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         // const operator[] only works for arrays
         if (JSON_HEDLEY_LIKELY(is_array()))
         {
-            JSON_ASSERT(idx < m_data.m_value.array->size());
             return m_data.m_value.array->operator[](idx);
         }
 
@@ -32535,6 +32550,7 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
 #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

tests/src/unit-disable-tuple-reference-conversion.cpp

@@ -0,0 +1,93 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#include "doctest_compatibility.h"
+
+// This file tests the opt-in JSON_DISABLE_TUPLE_REFERENCE_CONVERSION, so it
+// defines the macro itself rather than relying on a -D flag, and runs in every
+// build.
+#ifdef JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+    #undef JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+#endif
+
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
+
+#include <nlohmann/json.hpp>
+using nlohmann::json;
+using nlohmann::ordered_json;
+
+#include <string>
+#include <tuple>
+#include <type_traits>
+#include <utility>
+
+// clang before 4 and GCC before 5 cannot create a std::tuple of basic_json
+// references at all, with or without JSON_DISABLE_TUPLE_REFERENCE_CONVERSION:
+// the tuple constructors make them instantiate basic_json's conversion operator
+// for libstdc++'s internal tuple bases, which fails hard
+#if (defined(__clang__) && __clang_major__ < 4) || (!defined(__clang__) && defined(__GNUC__) && __GNUC__ < 5)
+    #define SKIP_TESTS_FOR_JSON_REFERENCE_TUPLES
+#endif
+
+TEST_CASE("JSON_DISABLE_TUPLE_REFERENCE_CONVERSION")
+{
+    SECTION("json is not constructible from a one-element tuple of a json reference")
+    {
+        CHECK_FALSE(std::is_constructible<json, std::tuple<json&>>::value);
+        CHECK_FALSE(std::is_constructible<json, std::tuple<const json&>>::value);
+        CHECK_FALSE(std::is_constructible < json, std::tuple < json && >>::value);
+        CHECK_FALSE(std::is_constructible<json, const std::tuple<json&>&>::value);
+        CHECK_FALSE(std::is_constructible<ordered_json, std::tuple<ordered_json&>>::value);
+    }
+
+#ifndef SKIP_TESTS_FOR_JSON_REFERENCE_TUPLES
+    SECTION("issue #2226 - tuple<const json&> from tuple<json&> keeps the reference")
+    {
+        json j = true;
+        const std::tuple<const json&> tup(std::forward_as_tuple(j));
+        CHECK(&std::get<0>(tup) == &j);
+    }
+
+    SECTION("tuple<json> from tuple<json&> copies the element")
+    {
+        const json j = {{"key", "value"}};
+        const std::tuple<json> t1(std::forward_as_tuple(j));
+        CHECK(std::get<0>(t1) == j);
+
+        json j2 = "text";
+        const std::tuple<json> t2(std::forward_as_tuple(std::move(j2)));
+        CHECK(std::get<0>(t2) == "text");
+    }
+#endif
+
+    SECTION("other tuple conversions are not affected")
+    {
+        const json j = true;
+
+        // one-element tuple holding a json value
+        CHECK(json(std::make_tuple(j)) == json::array({true}));
+
+        // tuples with more than one element, even when holding references
+        int i = 1;
+#ifndef SKIP_TESTS_FOR_JSON_REFERENCE_TUPLES
+        CHECK(json(std::forward_as_tuple(i, j)) == json::array({1, true}));
+        CHECK(json(std::forward_as_tuple(j, j)) == json::array({true, true}));
+#endif
+
+        // one-element tuples holding references to other types
+        std::string s = "text";
+        CHECK(json(std::forward_as_tuple(s)) == json::array({"text"}));
+        CHECK(json(std::forward_as_tuple(i)) == json::array({1}));
+
+#ifndef SKIP_TESTS_FOR_JSON_REFERENCE_TUPLES
+        // a reference to a different basic_json specialization
+        ordered_json oj = true;
+        CHECK(json(std::forward_as_tuple(oj)) == json::array({true}));
+#endif
+    }
+}

tests/src/unit-regression2.cpp

@@ -18,6 +18,19 @@
 // for some reason including this after the json header leads to linker errors with VS 2017...
 #include <locale>
 
+// skip tests if JSON_DISABLE_TUPLE_REFERENCE_CONVERSION=1 (#2226)
+#if defined(JSON_DISABLE_TUPLE_REFERENCE_CONVERSION) && (JSON_DISABLE_TUPLE_REFERENCE_CONVERSION == 1)
+    #define SKIP_TESTS_FOR_TUPLE_REFERENCE_CONVERSION
+#endif
+
+// clang before 4 and GCC before 5 cannot create a std::tuple of basic_json
+// references at all, with or without JSON_DISABLE_TUPLE_REFERENCE_CONVERSION:
+// the tuple constructors make them instantiate basic_json's conversion operator
+// for libstdc++'s internal tuple bases, which fails hard
+#if (defined(__clang__) && __clang_major__ < 4) || (!defined(__clang__) && defined(__GNUC__) && __GNUC__ < 5)
+    #define SKIP_TESTS_FOR_JSON_REFERENCE_TUPLES
+#endif
+
 #define JSON_TESTS_PRIVATE
 #include <nlohmann/json.hpp>
 using json = nlohmann::json;
@@ -28,6 +41,7 @@ using ordered_json = nlohmann::ordered_json;
 
 #include <cstdio>
 #include <list>
+#include <tuple>
 #include <type_traits>
 #include <utility>
 
@@ -542,6 +556,20 @@ TEST_CASE("regression tests 2")
                       )));
     }
 
+#ifndef SKIP_TESTS_FOR_TUPLE_REFERENCE_CONVERSION
+    SECTION("issue #2226 - std::tuple dangling reference - implicit conversion")
+    {
+        // by default, a one-element tuple holding a json reference converts to
+        // a one-element array; JSON_DISABLE_TUPLE_REFERENCE_CONVERSION removes
+        // this conversion (see unit-disable-tuple-reference-conversion.cpp)
+        const json j = true;
+        CHECK(std::is_constructible<json, std::tuple<const json&>>::value);
+#ifndef SKIP_TESTS_FOR_JSON_REFERENCE_TUPLES
+        CHECK(json(std::forward_as_tuple(j)) == json::array({true}));
+#endif
+    }
+#endif
+
     SECTION("PR #2181 - regression bug with lvalue")
     {
         // see https://github.com/nlohmann/json/pull/2181#issuecomment-653326060