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/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/recursion_depth_limit.hpp

@@ -19,17 +19,11 @@ namespace detail
 /*!
 @brief the number of nesting levels an operation recurses into
 
-Operations that walk a value (copying, comparing, serializing, hashing, merging,
-...) recurse once
+Operations that walk a value (serializing, hashing, merging, ...) recurse once
 per nesting level, which is fastest, but a value nested deeply enough would
 exhaust the call stack. So they recurse only this many levels deep and finish
 whatever lies below with an explicit stack. All of them share this limit.
 
-Most of them pass the depth down as an argument. The copy constructor and the
-comparison operators cannot, as their signatures are fixed, so they count it
-in basic_json::nesting_depth() instead, a byte per thread; the limit must
-therefore stay below 255.
-
 @sa https://github.com/nlohmann/json/issues/5387
 */
 constexpr std::size_t recursion_depth_limit() noexcept

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>>;
 
@@ -898,8 +900,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     }
 
 #ifndef JSON_NO_THREAD_LOCAL
-    // nesting_depth() is a byte and may exceed the limit by one level
-    static_assert(detail::recursion_depth_limit() < 255, "the nesting depth count must fit in a byte");
+    /// the number of levels an operation descends into before it finishes the
+    /// value below it without the call stack
+    static constexpr std::uint8_t nesting_depth_limit()
+    {
+        return 128;
+    }
 
     /*!
     @brief how many levels the operation going on in this thread has descended into
@@ -941,7 +947,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         static_cast<void>(may_descend);
         return true;
 #else
-        return !may_descend || nesting_depth() >= detail::recursion_depth_limit();
+        return !may_descend || nesting_depth() >= nesting_depth_limit();
 #endif
     }
 
@@ -965,7 +971,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 #ifdef JSON_NO_THREAD_LOCAL
             : m_okay(false)
 #else
-            : m_okay(nesting_depth() < detail::recursion_depth_limit())
+            : m_okay(nesting_depth() < nesting_depth_limit())
 #endif
         {
 #ifndef JSON_NO_THREAD_LOCAL
@@ -1169,7 +1175,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     The values whose copy has not been created yet are kept on an explicit
     worklist rather than on the call stack. This is only reached for values
-    nested deeper than @ref detail::recursion_depth_limit levels, which is why it copies
+    nested deeper than @ref nesting_depth_limit levels, which is why it copies
     every container by hand instead of letting the container do it: the fast
     ways of doing so would descend into the elements and defeat the purpose.
     */
@@ -1235,7 +1241,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     Copying a container copies its elements, so a value nested deeply enough
     used to exhaust the call stack. The descent is bounded here: the first
-    @ref detail::recursion_depth_limit levels are copied by the containers themselves, just
+    @ref nesting_depth_limit levels are copied by the containers themselves, just
     as they always were, and anything below that is copied without the call
     stack by @ref copy_iteratively. Copying a value can therefore no longer
     exhaust the stack, however deeply it is nested, just like destroying one
@@ -1373,7 +1379,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /*!
     @brief compare @a lhs and @a rhs without descending into them
 
-    Reached once a comparison has descended @ref detail::recursion_depth_limit levels, so
+    Reached once a comparison has descended @ref nesting_depth_limit levels, so
     that comparing values cannot exhaust the call stack however deeply they are
     nested. The two values are walked in lockstep on an explicit stack and
     compared lexicographically, element by element in the order the containers
@@ -2686,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

@@ -7281,17 +7281,11 @@ namespace detail
 /*!
 @brief the number of nesting levels an operation recurses into
 
-Operations that walk a value (copying, comparing, serializing, hashing, merging,
-...) recurse once
+Operations that walk a value (serializing, hashing, merging, ...) recurse once
 per nesting level, which is fastest, but a value nested deeply enough would
 exhaust the call stack. So they recurse only this many levels deep and finish
 whatever lies below with an explicit stack. All of them share this limit.
 
-Most of them pass the depth down as an argument. The copy constructor and the
-comparison operators cannot, as their signatures are fixed, so they count it
-in basic_json::nesting_depth() instead, a byte per thread; the limit must
-therefore stay below 255.
-
 @sa https://github.com/nlohmann/json/issues/5387
 */
 constexpr std::size_t recursion_depth_limit() noexcept
@@ -26240,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;
@@ -26300,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>>;
 
@@ -26985,8 +26981,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     }
 
 #ifndef JSON_NO_THREAD_LOCAL
-    // nesting_depth() is a byte and may exceed the limit by one level
-    static_assert(detail::recursion_depth_limit() < 255, "the nesting depth count must fit in a byte");
+    /// the number of levels an operation descends into before it finishes the
+    /// value below it without the call stack
+    static constexpr std::uint8_t nesting_depth_limit()
+    {
+        return 128;
+    }
 
     /*!
     @brief how many levels the operation going on in this thread has descended into
@@ -27028,7 +27028,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         static_cast<void>(may_descend);
         return true;
 #else
-        return !may_descend || nesting_depth() >= detail::recursion_depth_limit();
+        return !may_descend || nesting_depth() >= nesting_depth_limit();
 #endif
     }
 
@@ -27052,7 +27052,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 #ifdef JSON_NO_THREAD_LOCAL
             : m_okay(false)
 #else
-            : m_okay(nesting_depth() < detail::recursion_depth_limit())
+            : m_okay(nesting_depth() < nesting_depth_limit())
 #endif
         {
 #ifndef JSON_NO_THREAD_LOCAL
@@ -27256,7 +27256,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     The values whose copy has not been created yet are kept on an explicit
     worklist rather than on the call stack. This is only reached for values
-    nested deeper than @ref detail::recursion_depth_limit levels, which is why it copies
+    nested deeper than @ref nesting_depth_limit levels, which is why it copies
     every container by hand instead of letting the container do it: the fast
     ways of doing so would descend into the elements and defeat the purpose.
     */
@@ -27322,7 +27322,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     Copying a container copies its elements, so a value nested deeply enough
     used to exhaust the call stack. The descent is bounded here: the first
-    @ref detail::recursion_depth_limit levels are copied by the containers themselves, just
+    @ref nesting_depth_limit levels are copied by the containers themselves, just
     as they always were, and anything below that is copied without the call
     stack by @ref copy_iteratively. Copying a value can therefore no longer
     exhaust the stack, however deeply it is nested, just like destroying one
@@ -27460,7 +27460,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /*!
     @brief compare @a lhs and @a rhs without descending into them
 
-    Reached once a comparison has descended @ref detail::recursion_depth_limit levels, so
+    Reached once a comparison has descended @ref nesting_depth_limit levels, so
     that comparing values cannot exhaust the call stack however deeply they are
     nested. The two values are walked in lockstep on an explicit stack and
     compared lexicographically, element by element in the order the containers
@@ -28773,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-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));
+    }
+}