Merge branch 'develop' into claude/pr-3899-merge-requirements-e1932e

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/docset/docSet.sql

@@ -16,6 +16,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/ba
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::accept', 'Function', 'api/basic_json/accept/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::array', 'Function', 'api/basic_json/array/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::array_t', 'Type', 'api/basic_json/array_t/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::as_base_class', 'Method', 'api/basic_json/as_base_class/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::at', 'Method', 'api/basic_json/at/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::back', 'Method', 'api/basic_json/back/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::basic_json', 'Constructor', 'api/basic_json/basic_json/index.html');

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

@@ -0,0 +1,53 @@
+# <small>nlohmann::basic_json::</small>as_base_class
+
+```cpp
+json_base_class_t& as_base_class() noexcept;
+const json_base_class_t& as_base_class() const noexcept;
+```
+
+Returns a reference to this object as its custom base class [`json_base_class_t`](json_base_class_t.md). No copy is
+made.
+
+Since `basic_json` derives from `json_base_class_t`, a member of `basic_json` hides any member of the custom base class
+with the same name. This function makes such hidden members accessible again.
+
+## Return value
+
+reference to this object as [`json_base_class_t`](json_base_class_t.md)
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+The function is equivalent to `static_cast<json_base_class_t&>(j)` (or `static_cast<const json_base_class_t&>(j)`).
+
+## Examples
+
+??? example
+
+    The example shows how to use `as_base_class` to access members of the custom base class that are hidden by members
+    of `basic_json`.
+    
+    ```cpp
+    --8<-- "examples/as_base_class.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/as_base_class.output"
+    ```
+
+## See also
+
+- [json_base_class_t](json_base_class_t.md) - type of the custom base class
+
+## Version history
+
+- Added in version 3.13.0.

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

@@ -200,6 +200,7 @@ Direct access to the stored value of a JSON value.
 - [**get_ref**](get_ref.md) - get a reference value
 - [**operator ValueType**](operator_ValueType.md) - get a value
 - [**get_binary**](get_binary.md) - get a binary value
+- [**as_base_class**](as_base_class.md) - access the custom base class
 
 ### Element access
 

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

@@ -27,6 +27,18 @@ A `CustomBaseClass` with non-static data members forfeits `basic_json`'s
 [standard layout](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType) guarantee. See
 [Template Parameter Requirements](../../features/types/template_parameters.md#custombaseclass).
 
+#### Name conflicts
+
+Since `basic_json` derives from `CustomBaseClass`, members of `basic_json` hide members of `CustomBaseClass` with the
+same name. Hidden members remain accessible via [`as_base_class`](as_base_class.md) or by casting the value to
+`json_base_class_t`.
+
+!!! warning "Avoid generic member names"
+
+    Future versions of the library may add members to `basic_json` that hide members of `CustomBaseClass` that are
+    accessible today. To reduce the risk of such conflicts, avoid generic names for the members of `CustomBaseClass`,
+    for instance by using a distinctive prefix.
+
 ## Examples
 
 ??? example
@@ -43,6 +55,11 @@ A `CustomBaseClass` with non-static data members forfeits `basic_json`'s
     --8<-- "examples/json_base_class_t.output"
     ```
 
+## See also
+
+- [as_base_class](as_base_class.md) - access the custom base class
+
 ## Version history
 
 - Added in version 3.12.0.
+- Made a public member type in version 3.13.0; it was private before, so it could not be named outside the class.

docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md

@@ -50,11 +50,9 @@ The default value is `0` (disabled — existing behavior is preserved).
     ```
 
     Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one
-    element, and a single `[string, value]` pair *written as a braced list*, such as `{{"key", "value"}}`, which still
-    creates an object, are not affected. This exception is based on how the pair is written, not on the shape of its
-    value: an existing JSON value that happens to be a two-element array with a string as its first element, such as
-    `json arr = {"key", 42};`, is still copied by `json j{arr};` rather than turned into an object. The library's own
-    conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
+    element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not
+    affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes
+    `[5]`.
 
 !!! note "ABI compatibility"
 

docs/mkdocs/docs/examples/as_base_class.cpp

@@ -0,0 +1,41 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+class base_class_with_hidden_members
+{
+  public:
+    const char* type_name() const noexcept
+    {
+        return "my_type_name";
+    }
+
+    std::size_t size() const noexcept
+    {
+        return 42;
+    }
+};
+
+using json = nlohmann::basic_json <
+             std::map,
+             std::vector,
+             std::string,
+             bool,
+             std::int64_t,
+             std::uint64_t,
+             double,
+             std::allocator,
+             nlohmann::adl_serializer,
+             std::vector<std::uint8_t>,
+             base_class_with_hidden_members
+             >;
+
+int main()
+{
+    json j = {1, 2, 3};
+
+    // the members of basic_json hide the members of the base class
+    std::cout << j.type_name() << ' ' << j.size() << '\n';
+
+    // access the hidden members of the base class
+    std::cout << j.as_base_class().type_name() << ' ' << j.as_base_class().size() << '\n';
+}

docs/mkdocs/docs/examples/as_base_class.output

@@ -0,0 +1,2 @@
+array 3
+my_type_name 42

docs/mkdocs/mkdocs.yml

@@ -114,6 +114,7 @@ nav:
           - 'accept': api/basic_json/accept.md
           - 'array': api/basic_json/array.md
           - 'array_t': api/basic_json/array_t.md
+          - 'as_base_class': api/basic_json/as_base_class.md
           - 'at': api/basic_json/at.md
           - 'back': api/basic_json/back.md
           - 'begin': api/basic_json/begin.md

include/nlohmann/detail/json_ref.hpp

@@ -34,7 +34,6 @@ class json_ref
 
     json_ref(std::initializer_list<json_ref> init)
         : owned_value(init)
-        , braced_list(true)
     {}
 
     template <
@@ -70,17 +69,9 @@ class json_ref
         return &** this;
     }
 
-    /// whether the value was written as a braced list, such as {"key", 1},
-    /// rather than given as a value
-    bool is_braced_list() const noexcept
-    {
-        return braced_list;
-    }
-
   private:
     mutable value_type owned_value = nullptr;
     value_type const* value_ref = nullptr;
-    bool braced_list = false;
 };
 
 }  // namespace detail

include/nlohmann/json.hpp

@@ -153,7 +153,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     /// workaround type for MSVC
     using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
-    using json_base_class_t = ::nlohmann::detail::json_base_class<CustomBaseClass>;
 
   JSON_PRIVATE_UNLESS_TESTED:
     // convenience aliases for types residing in namespace detail;
@@ -213,6 +212,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     using cbor_tag_handler_t = detail::cbor_tag_handler_t;
     /// how to encode BJData
     using bjdata_version_t = detail::bjdata_version_t;
+    /// base class used to inject custom functionality into each instance of basic_json
+    /// @sa https://json.nlohmann.me/api/basic_json/json_base_class_t/
+    using json_base_class_t = ::nlohmann::detail::json_base_class<CustomBaseClass>;
     /// helper type for initializer lists of basic_json values
     using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
 
@@ -1672,18 +1674,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                bool type_deduction = true,
                value_t manual_type = value_t::array)
     {
-#if JSON_BRACE_INIT_COPY_SEMANTICS
-        // a single element that is a value rather than a braced list is
-        // copied or moved as is, whatever its content looks like
-        if (type_deduction && init.size() == 1 && !init.begin()->is_braced_list())
-        {
-            *this = init.begin()->moved_or_copied();
-            set_parents();
-            assert_invariant();
-            return;
-        }
-#endif
-
         // check if each element is an array with two elements whose first
         // element is a string
         bool is_an_object = std::all_of(init.begin(), init.end(),
@@ -2702,6 +2692,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return *get_ptr<const binary_t*>();
     }
 
+    /// @brief access the custom base class
+    /// @sa https://json.nlohmann.me/api/basic_json/as_base_class/
+    json_base_class_t& as_base_class() noexcept
+    {
+        return static_cast<json_base_class_t&>(*this);
+    }
+
+    /// @brief access the custom base class
+    /// @sa https://json.nlohmann.me/api/basic_json/as_base_class/
+    const json_base_class_t& as_base_class() const noexcept
+    {
+        return static_cast<const json_base_class_t&>(*this);
+    }
+
     /// @}
 
     ////////////////////

single_include/nlohmann/json.hpp

@@ -20047,7 +20047,6 @@ class json_ref
 
     json_ref(std::initializer_list<json_ref> init)
         : owned_value(init)
-        , braced_list(true)
     {}
 
     template <
@@ -20083,17 +20082,9 @@ class json_ref
         return &** this;
     }
 
-    /// whether the value was written as a braced list, such as {"key", 1},
-    /// rather than given as a value
-    bool is_braced_list() const noexcept
-    {
-        return braced_list;
-    }
-
   private:
     mutable value_type owned_value = nullptr;
     value_type const* value_ref = nullptr;
-    bool braced_list = false;
 };
 
 }  // namespace detail
@@ -26243,7 +26234,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     /// workaround type for MSVC
     using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
-    using json_base_class_t = ::nlohmann::detail::json_base_class<CustomBaseClass>;
 
   JSON_PRIVATE_UNLESS_TESTED:
     // convenience aliases for types residing in namespace detail;
@@ -26303,6 +26293,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     using cbor_tag_handler_t = detail::cbor_tag_handler_t;
     /// how to encode BJData
     using bjdata_version_t = detail::bjdata_version_t;
+    /// base class used to inject custom functionality into each instance of basic_json
+    /// @sa https://json.nlohmann.me/api/basic_json/json_base_class_t/
+    using json_base_class_t = ::nlohmann::detail::json_base_class<CustomBaseClass>;
     /// helper type for initializer lists of basic_json values
     using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
 
@@ -27762,18 +27755,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                bool type_deduction = true,
                value_t manual_type = value_t::array)
     {
-#if JSON_BRACE_INIT_COPY_SEMANTICS
-        // a single element that is a value rather than a braced list is
-        // copied or moved as is, whatever its content looks like
-        if (type_deduction && init.size() == 1 && !init.begin()->is_braced_list())
-        {
-            *this = init.begin()->moved_or_copied();
-            set_parents();
-            assert_invariant();
-            return;
-        }
-#endif
-
         // check if each element is an array with two elements whose first
         // element is a string
         bool is_an_object = std::all_of(init.begin(), init.end(),
@@ -28792,6 +28773,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return *get_ptr<const binary_t*>();
     }
 
+    /// @brief access the custom base class
+    /// @sa https://json.nlohmann.me/api/basic_json/as_base_class/
+    json_base_class_t& as_base_class() noexcept
+    {
+        return static_cast<json_base_class_t&>(*this);
+    }
+
+    /// @brief access the custom base class
+    /// @sa https://json.nlohmann.me/api/basic_json/as_base_class/
+    const json_base_class_t& as_base_class() const noexcept
+    {
+        return static_cast<const json_base_class_t&>(*this);
+    }
+
     /// @}
 
     ////////////////////

tests/src/unit-brace-init-copy-semantics.cpp

@@ -72,28 +72,6 @@ TEST_CASE("JSON_BRACE_INIT_COPY_SEMANTICS")
         CHECK(j7 == json::array({1, 2}));
     }
 
-    SECTION("single-element brace initialization copies a pair-shaped array value (#5662)")
-    {
-        // a JSON value that happens to be a 2-element array whose first
-        // element is a string must still be copied, not turned into an
-        // object; only a braced list written in the source, such as the
-        // inner {"key", "value"} of {{"key", "value"}}, describes an object
-        json const pair_shaped = json::array({"key", 42});
-
-        json const j1{pair_shaped};
-        CHECK(j1.is_array());
-        CHECK(j1 == pair_shaped);
-
-        json const j2 = {pair_shaped};
-        CHECK(j2.is_array());
-        CHECK(j2 == pair_shaped);
-
-        // the same holds for an rvalue of the same shape
-        json const j3{json::array({"key", 42})};
-        CHECK(j3.is_array());
-        CHECK(j3 == pair_shaped);
-    }
-
     SECTION("what the macro does not change")
     {
         // lists with more than one element are unaffected

tests/src/unit-custom-base-class.cpp

@@ -9,6 +9,8 @@
 #include <set>
 #include <sstream>
 #include <string>
+#include <type_traits>
+#include <utility>
 
 #include "doctest_compatibility.h"
 
@@ -333,3 +335,71 @@ TEST_CASE("JSON Visit Node")
         );
     CHECK(expected.empty());
 }
+
+// Test accessing members of a custom base class that are hidden by members of nlohmann::basic_json
+class base_class_with_hidden_members
+{
+  public:
+    const char* type_name() const noexcept // NOLINT(readability-convert-member-functions-to-static)
+    {
+        return "custom type_name";
+    }
+
+    std::size_t size() const noexcept
+    {
+        return m_size;
+    }
+
+    std::size_t m_size = 42;
+};
+
+using json_with_hidden_base_members =
+    nlohmann::basic_json <
+    std::map,
+    std::vector,
+    std::string,
+    bool,
+    std::int64_t,
+    std::uint64_t,
+    double,
+    std::allocator,
+    nlohmann::adl_serializer,
+    std::vector<std::uint8_t>,
+    base_class_with_hidden_members
+    >;
+
+TEST_CASE("JSON Node as_base_class")
+{
+    using json = json_with_hidden_base_members;
+
+    static_assert(std::is_same<decltype(std::declval<json&>().as_base_class()), json::json_base_class_t&>::value, "");
+    static_assert(std::is_same<decltype(std::declval<const json&>().as_base_class()), const json::json_base_class_t&>::value, "");
+    static_assert(noexcept(std::declval<json&>().as_base_class()), "");
+    static_assert(noexcept(std::declval<const json&>().as_base_class()), "");
+
+    SECTION("non-const")
+    {
+        json j = {1, 2, 3};
+
+        CHECK(std::string(j.type_name()) == "array");
+        CHECK(j.size() == 3);
+        CHECK(std::string(j.as_base_class().type_name()) == "custom type_name");
+        CHECK(j.as_base_class().size() == 42);
+        CHECK(&j.as_base_class() == &static_cast<json::json_base_class_t&>(j));
+
+        j.as_base_class().m_size = 7;
+        CHECK(j.as_base_class().size() == 7);
+        CHECK(j.size() == 3);
+    }
+
+    SECTION("const")
+    {
+        const json j = {1, 2, 3};
+
+        CHECK(std::string(j.type_name()) == "array");
+        CHECK(j.size() == 3);
+        CHECK(std::string(j.as_base_class().type_name()) == "custom type_name");
+        CHECK(j.as_base_class().size() == 42);
+        CHECK(&j.as_base_class() == &static_cast<const json::json_base_class_t&>(j));
+    }
+}