Construct the JSON Patch exceptions out of line

patch_inplace() built its error messages inline. In particular get_value()
concatenated the context-sensitive "operation 'x'" string on every call, even
when nothing was wrong. The patch exceptions now come from NEVER_INLINE
helpers: the index and key errors reuse basic_json's existing
throw_array_index_out_of_range/throw_key_not_found, and the seven
patch-specific messages get one helper each in detail/exceptions.hpp. Ids
and messages are unchanged, and unit-throw_messages pins them (with and
without JSON_DIAGNOSTICS).

citm_catalog patch: -6.6 % (Apple clang), -9.5 % (GCC 16).
The other remaining throw sites (parser::syntax_error, binary_writer,
serializer, input_adapters, enum_key_duplicate, format_error) were prototyped
and measured: no gain beyond noise, so they stay as they are.

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

include/nlohmann/detail/exceptions.hpp

@@ -428,7 +428,7 @@ void templated_json_throw(ExceptionType exception)
 @throw type_error.302 always
 */
 template<typename BasicJsonType>
-JSON_HEDLEY_NO_RETURN inline void throw_type_must_be(const char* expected, const BasicJsonType& j)
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_type_must_be(const char* expected, const BasicJsonType& j)
 {
     static_cast<void>(expected); // unused when JSON_NOEXCEPTION is defined
     static_cast<void>(j);
@@ -443,7 +443,7 @@ JSON_HEDLEY_NO_RETURN inline void throw_type_must_be(const char* expected, const
 @throw type_error always
 */
 template<typename BasicJsonType>
-JSON_HEDLEY_NO_RETURN inline void throw_cannot_use_with(const exception_id id_, const char* operation, const BasicJsonType& j)
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_cannot_use_with(const exception_id id_, const char* operation, const BasicJsonType& j)
 {
     static_cast<void>(id_); // unused when JSON_NOEXCEPTION is defined
     static_cast<void>(operation);
@@ -451,6 +451,77 @@ JSON_HEDLEY_NO_RETURN inline void throw_cannot_use_with(const exception_id id_,
     JSON_THROW(type_error::create(id_, concat("cannot use ", operation, " with ", j.type_name()), &j));
 }
 
+/*!
+@brief throws ExceptionType with a fixed message; kept out of line so that callers do not carry the exception construction
+*/
+template<typename ExceptionType, typename BasicJsonContext>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_literal(const exception_id id_, const char* what_arg, BasicJsonContext context)
+{
+    static_cast<void>(id_); // unused when JSON_NOEXCEPTION is defined
+    static_cast<void>(what_arg);
+    static_cast<void>(context);
+    JSON_THROW(ExceptionType::create(id_, what_arg, context));
+}
+
+// JSON Patch errors; constructed out of line so that patch_inplace() does not carry them
+
+template<typename BasicJsonType>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_patch_add_parent(const BasicJsonType& parent)
+{
+    static_cast<void>(parent);
+    JSON_THROW(out_of_range::create(exception_id::patch_add_parent_not_container, concat("cannot add value: the JSON Patch 'add' target's parent is of type ", parent.type_name(), ", but must be an object or array"), &parent));
+}
+
+template<typename BasicJsonType>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_patch_remove_parent(const BasicJsonType& parent)
+{
+    static_cast<void>(parent);
+    JSON_THROW(out_of_range::create(exception_id::patch_remove_parent_not_container, concat("cannot remove value: the JSON Patch 'remove' target's parent is of type ", parent.type_name(), ", but must be an object or array"), &parent));
+}
+
+template<typename BasicJsonType>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_patch_not_an_array(const BasicJsonType& j)
+{
+    static_cast<void>(j);
+    JSON_THROW(parse_error::create(exception_id::patch_not_an_array, 0, "JSON patch must be an array of objects", &j));
+}
+
+template<typename StringType, typename BasicJsonType>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_patch_missing_member(const StringType& op, const StringType& member, const bool string_type, const BasicJsonType& val)
+{
+    static_cast<void>(op);
+    static_cast<void>(member);
+    static_cast<void>(string_type);
+    static_cast<void>(val);
+    // context-sensitive error message
+    const std::string error_msg = (op == "op") ? std::string("operation") : concat("operation '", op, '\'');
+    JSON_THROW(parse_error::create(exception_id::patch_invalid_operation, 0, concat(error_msg, string_type ? " must have string member '" : " must have member '", member, "'"), &val));
+}
+
+template<typename StringType, typename BasicJsonType>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_patch_move_into_child(const StringType& from_path, const StringType& path, const BasicJsonType& result)
+{
+    static_cast<void>(from_path);
+    static_cast<void>(path);
+    static_cast<void>(result);
+    JSON_THROW(out_of_range::create(exception_id::patch_move_into_child, concat("cannot move value: 'from' path '", from_path, "' is a proper prefix of 'path' '", path, "'"), &result));
+}
+
+template<typename BasicJsonType>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_patch_test_failed(const BasicJsonType& val)
+{
+    static_cast<void>(val);
+    JSON_THROW(other_error::create(exception_id::patch_test_failed, concat("unsuccessful: ", val.dump()), &val));
+}
+
+template<typename StringType, typename BasicJsonType>
+JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_patch_invalid_operation(const StringType& op, const BasicJsonType& val)
+{
+    static_cast<void>(op);
+    static_cast<void>(val);
+    JSON_THROW(parse_error::create(exception_id::patch_invalid_operation, 0, concat("operation value '", op, "' is invalid"), &val));
+}
+
 }  // namespace detail
 NLOHMANN_JSON_NAMESPACE_END
 

include/nlohmann/detail/input/binary_reader.hpp

@@ -195,7 +195,7 @@ class binary_reader
 
             if (JSON_HEDLEY_UNLIKELY(current != char_traits<char_type>::eof()))
             {
-                return last_byte_error(exception_id::unexpected_end_of_input, concat("expected end of input; last byte: 0x", get_token_string()), "value");
+                return last_byte_error(exception_id::unexpected_end_of_input, "expected end of input", "value", "");
             }
         }
 
@@ -317,7 +317,7 @@ class binary_reader
     {
         if (JSON_HEDLEY_UNLIKELY(document_size < 0 || static_cast<std::size_t>(document_size) != chars_read - document_start))
         {
-            return last_byte_error(exception_id::unexpected_byte, concat("document size ", std::to_string(document_size), " does not match the number of bytes read (", std::to_string(chars_read - document_start), ")"), "document");
+            return bson_document_size_error(document_size, chars_read - document_start);
         }
         return true;
     }
@@ -509,7 +509,7 @@ class binary_reader
     {
         if (JSON_HEDLEY_UNLIKELY(len < 1))
         {
-            return last_byte_error(exception_id::unexpected_byte, concat("string length must be at least 1, is ", std::to_string(len)), "string");
+            return bson_length_error("string length must be at least 1, is ", len, "string");
         }
 
         if (JSON_HEDLEY_UNLIKELY(!get_string(len - static_cast<NumberType>(1), result)))
@@ -539,7 +539,7 @@ class binary_reader
     {
         if (JSON_HEDLEY_UNLIKELY(len < 0))
         {
-            return last_byte_error(exception_id::unexpected_byte, concat("byte array length cannot be negative, is ", std::to_string(len)), "binary");
+            return bson_length_error("byte array length cannot be negative, is ", len, "binary");
         }
 
         // All BSON binary values have a subtype
@@ -629,9 +629,7 @@ class binary_reader
 
             default: // anything else is not supported (yet)
             {
-                const std::string cr_str = hex_byte(static_cast<std::uint8_t>(element_type));
-                return sax->parse_error(element_type_parse_position, cr_str,
-                                        parse_error::create(exception_id::bson_unsupported_type, element_type_parse_position, concat("Unsupported BSON record type 0x", cr_str), nullptr));
+                return bson_unsupported_type_error(element_type_parse_position, element_type);
             }
         }
     }
@@ -1060,6 +1058,7 @@ class binary_reader
     @param[in] context  parsing context for the error message
     @return whether the SAX consumer accepts the parse error
     */
+    JSON_HEDLEY_NEVER_INLINE
     bool cbor_indefinite_string_error(const char* type_name, const char* context)
     {
         return last_byte_error(exception_id::invalid_string_or_size, concat("indefinite-length ", type_name, " is not allowed inside indefinite-length ", type_name, "; last byte: 0x", get_token_string()), context);
@@ -1139,7 +1138,7 @@ class binary_reader
 
             default:
             {
-                return last_byte_error(exception_id::invalid_string_or_size, concat("expected length specification (0x60-0x7B)", inside_indefinite ? "" : " or indefinite string type (0x7F)", "; last byte: 0x", get_token_string()), "string");
+                return last_byte_error(exception_id::invalid_string_or_size, "expected length specification (0x60-0x7B)", "string", inside_indefinite ? "" : " or indefinite string type (0x7F)");
             }
         }
     }
@@ -1269,7 +1268,7 @@ class binary_reader
                 break;
         }
 
-        return last_byte_error(exception_id::invalid_string_or_size, concat("only string keys are supported, but found ", found, "; last byte: 0x", get_token_string()), "object key");
+        return last_byte_error(exception_id::invalid_string_or_size, "only string keys are supported, but found ", "object key", found);
     }
 
     /*!
@@ -1350,7 +1349,7 @@ class binary_reader
 
             default:
             {
-                return last_byte_error(exception_id::invalid_string_or_size, concat("expected length specification (0x40-0x5B)", inside_indefinite ? "" : " or indefinite binary array type (0x5F)", "; last byte: 0x", get_token_string()), "binary");
+                return last_byte_error(exception_id::invalid_string_or_size, "expected length specification (0x40-0x5B)", "binary", inside_indefinite ? "" : " or indefinite binary array type (0x5F)");
             }
         }
     }
@@ -1496,8 +1495,7 @@ class binary_reader
     {
         if (JSON_HEDLEY_UNLIKELY(!value_in_range_of<std::size_t>(len) || len == detail::unknown_size()))
         {
-            return sax->parse_error(chars_read, get_token_string(), out_of_range::create(exception_id::container_too_large,
-                                    exception_message(concat("excessive ", context, " size"), "size"), nullptr));
+            return container_size_error(context);
         }
         result = conditional_static_cast<std::size_t>(len);
         return true;
@@ -2065,7 +2063,7 @@ class binary_reader
 
             default:
             {
-                return last_byte_error(exception_id::invalid_string_or_size, concat("expected length specification (0xA0-0xBF, 0xD9-0xDB); last byte: 0x", get_token_string()), "string");
+                return last_byte_error(exception_id::invalid_string_or_size, "expected length specification (0xA0-0xBF, 0xD9-0xDB)", "string", "");
             }
         }
     }
@@ -2157,7 +2155,7 @@ class binary_reader
                 break;
         }
 
-        return last_byte_error(exception_id::invalid_string_or_size, concat("only string keys are supported, but found ", found, "; last byte: 0x", get_token_string()), "object key");
+        return last_byte_error(exception_id::invalid_string_or_size, "only string keys are supported, but found ", "object key", found);
     }
 
     /*!
@@ -2655,8 +2653,7 @@ class binary_reader
         }
         if (JSON_HEDLEY_UNLIKELY(!value_in_range_of<std::size_t>(number)))
         {
-            return sax->parse_error(chars_read, get_token_string(), out_of_range::create(exception_id::container_too_large,
-                                    exception_message("integer value overflow", "size"), nullptr));
+            return out_of_range_error(exception_id::container_too_large, "integer value overflow", "size");
         }
         result = static_cast<std::size_t>(number); // NOLINT(bugprone-signed-char-misuse,cert-str34-c): number is not a char
         return true;
@@ -2753,8 +2750,7 @@ class binary_reader
                 }
                 if (!value_in_range_of<std::size_t>(number))
                 {
-                    return sax->parse_error(chars_read, get_token_string(), out_of_range::create(exception_id::container_too_large,
-                                            exception_message("integer value overflow", "size"), nullptr));
+                    return out_of_range_error(exception_id::container_too_large, "integer value overflow", "size");
                 }
                 result = detail::conditional_static_cast<std::size_t>(number);
                 return true;
@@ -2832,7 +2828,7 @@ class binary_reader
                         // or SIZE_MAX.
                         if (JSON_HEDLEY_UNLIKELY(result > (std::numeric_limits<std::size_t>::max)() / i))
                         {
-                            return sax->parse_error(chars_read, get_token_string(), out_of_range::create(exception_id::container_too_large, exception_message("excessive ndarray size caused overflow", "size"), nullptr));
+                            return out_of_range_error(exception_id::container_too_large, "excessive ndarray size caused overflow", "size");
                         }
                         result *= i;
                         // the pre-check above already rules out result becoming 0
@@ -2841,7 +2837,7 @@ class binary_reader
                         // unknown-size container (see get_ubjson_size_type())
                         if (result == npos)
                         {
-                            return sax->parse_error(chars_read, get_token_string(), out_of_range::create(exception_id::container_too_large, exception_message("excessive ndarray size caused overflow", "size"), nullptr));
+                            return out_of_range_error(exception_id::container_too_large, "excessive ndarray size caused overflow", "size");
                         }
                         if (JSON_HEDLEY_UNLIKELY(!emit_unsigned(i)))
                         {
@@ -2891,7 +2887,7 @@ class binary_reader
             if (input_format == input_format_t::bjdata
                     && JSON_HEDLEY_UNLIKELY(is_bjd_excluded_optimized_type(result.second)))
             {
-                return last_byte_error(exception_id::unexpected_byte, concat("marker 0x", get_token_string(), " is not a permitted optimized array type"), "type");
+                return optimized_type_error();
             }
 
             if (JSON_HEDLEY_UNLIKELY(!unexpect_eof("type")))
@@ -2906,7 +2902,7 @@ class binary_reader
                 {
                     return false;
                 }
-                return last_byte_error(exception_id::unexpected_byte, concat("expected '#' after type information; last byte: 0x", get_token_string()), "size");
+                return last_byte_error(exception_id::unexpected_byte, "expected '#' after type information", "size", "");
             }
 
             const bool is_error = get_ubjson_size_value(result.first, is_ndarray, 0, result.second);
@@ -3057,7 +3053,7 @@ class binary_reader
                 }
                 if (JSON_HEDLEY_UNLIKELY(current > 127))
                 {
-                    return last_byte_error(exception_id::invalid_string_or_size, concat("byte after 'C' must be in range 0x00..0x7F; last byte: 0x", get_token_string()), "char");
+                    return last_byte_error(exception_id::invalid_string_or_size, "byte after 'C' must be in range 0x00..0x7F", "char", "");
                 }
                 string_t s(1, static_cast<typename string_t::value_type>(current));
                 return sax->string(s);
@@ -3141,8 +3137,7 @@ class binary_reader
             if (JSON_HEDLEY_UNLIKELY((size_and_type.second == 'Z' || size_and_type.second == 'T' || size_and_type.second == 'F')
                                      && size_and_type.first > max_valueless_container_size))
             {
-                return sax->parse_error(chars_read, get_token_string(), out_of_range::create(exception_id::container_too_large,
-                                        exception_message("excessive array size", "size"), nullptr));
+                return out_of_range_error(exception_id::container_too_large, "excessive array size", "size");
             }
 
             if (JSON_HEDLEY_UNLIKELY(!enter_array(size_and_type.first, size_and_type.second)))
@@ -3854,7 +3849,7 @@ class binary_reader
         {
             // in case of failure, advance position by 1 to report the failing location
             ++chars_read;
-            sax->parse_error(chars_read, "<end of file>", parse_error::create(exception_id::unexpected_end_of_input, chars_read, exception_message("unexpected end of input", context), nullptr));
+            static_cast<void>(report_eof(context));
             return false;
         }
         return true;
@@ -4007,8 +4002,7 @@ class binary_reader
         const auto result = static_cast<number_float_t>(number);
         if (JSON_HEDLEY_UNLIKELY(std::isfinite(number) && !std::isfinite(result)))
         {
-            return sax->parse_error(chars_read, get_token_string(),
-                                    out_of_range::create(exception_id::number_overflow, exception_message("number overflow", "value"), nullptr));
+            return out_of_range_error(exception_id::number_overflow, "number overflow", "value");
         }
         return sax->number_float(result, "");
     }
@@ -4223,22 +4217,82 @@ class binary_reader
     {
         if (JSON_HEDLEY_UNLIKELY(current == char_traits<char_type>::eof()))
         {
-            return sax->parse_error(chars_read, "<end of file>",
-                                    parse_error::create(exception_id::unexpected_end_of_input, chars_read, exception_message("unexpected end of input", context), nullptr));
+            return report_eof(context);
         }
         return true;
     }
 
+    /*!
+    @brief reports an unexpected end of input (out of line to keep the exception
+           construction out of the hot reading functions)
+    @param[in] context  further context information (for diagnostics)
+    @return the result of the SAX parser's parse_error()
+    */
+    JSON_HEDLEY_NON_NULL(2)
+    JSON_HEDLEY_NEVER_INLINE
+    bool report_eof(const char* context) const
+    {
+        return sax->parse_error(chars_read, "<end of file>",
+                                parse_error::create(exception_id::unexpected_end_of_input, chars_read, exception_message("unexpected end of input", context), nullptr));
+    }
+
+    /*!
+    @brief reports an out_of_range error at the last read byte (out of line)
+    */
+    JSON_HEDLEY_NEVER_INLINE
+    bool out_of_range_error(const exception_id id_, const char* detail, const char* context) const
+    {
+        return sax->parse_error(chars_read, get_token_string(), out_of_range::create(id_, exception_message(detail, context), nullptr));
+    }
+
+    JSON_HEDLEY_NEVER_INLINE
+    bool container_size_error(const char* what) const
+    {
+        return sax->parse_error(chars_read, get_token_string(), out_of_range::create(exception_id::container_too_large,
+                                exception_message(concat("excessive ", what, " size"), "size"), nullptr));
+    }
+
+    JSON_HEDLEY_NEVER_INLINE
+    bool optimized_type_error() const
+    {
+        return last_byte_error(exception_id::unexpected_byte, concat("marker 0x", get_token_string(), " is not a permitted optimized array type"), "type");
+    }
+
+    template<typename NumberType>
+    JSON_HEDLEY_NEVER_INLINE
+    bool bson_length_error(const char* prefix, const NumberType len, const char* context) const
+    {
+        return last_byte_error(exception_id::unexpected_byte, concat(prefix, std::to_string(len)), context);
+    }
+
+    JSON_HEDLEY_NEVER_INLINE
+    bool bson_document_size_error(const std::int32_t document_size, const std::size_t bytes_read) const
+    {
+        return last_byte_error(exception_id::unexpected_byte, concat("document size ", std::to_string(document_size), " does not match the number of bytes read (", std::to_string(bytes_read), ")"), "document");
+    }
+
+    JSON_HEDLEY_NEVER_INLINE
+    bool bson_unsupported_type_error(const std::size_t position, const char element_type) const
+    {
+        const std::string cr_str = hex_byte(static_cast<std::uint8_t>(element_type));
+        return sax->parse_error(position, cr_str,
+                                parse_error::create(exception_id::bson_unsupported_type, position, concat("Unsupported BSON record type 0x", cr_str), nullptr));
+    }
+
     /*!
     @brief reports a parse error at the last read byte
     @param[in] id_      the id of the parse_error exception
     @param[in] detail   a detailed error message
     @param[in] context  further context information
+    @param[in] tail     optional text appended to the detail, followed by "; last byte: 0x<token>"
     @return the result of the SAX parser's parse_error()
     */
-    bool last_byte_error(const exception_id id_, const std::string& detail, const std::string& context) const
+    JSON_HEDLEY_NEVER_INLINE
+    bool last_byte_error(const exception_id id_, const std::string& detail, const char* context, const char* tail = nullptr) const
     {
-        return sax->parse_error(chars_read, get_token_string(), parse_error::create(id_, chars_read, exception_message(detail, context), nullptr));
+        // with a tail, the message reads "<detail><tail>; last byte: 0x<token>"
+        return sax->parse_error(chars_read, get_token_string(), parse_error::create(id_, chars_read,
+                                exception_message(tail == nullptr ? detail : concat(detail, tail, "; last byte: 0x", get_token_string()), context), nullptr));
     }
 
     /*!
@@ -4247,7 +4301,8 @@ class binary_reader
     @param[in] context  further context information
     @return the result of the SAX parser's parse_error()
     */
-    bool unexpected_byte(const char* detail, const std::string& context) const
+    JSON_HEDLEY_NEVER_INLINE
+    bool unexpected_byte(const char* detail, const char* context) const
     {
         return last_byte_error(exception_id::unexpected_byte, concat(detail, ": 0x", get_token_string()), context);
     }
@@ -4258,6 +4313,7 @@ class binary_reader
     @param[in] context   further context information
     @return the result of the SAX parser's parse_error()
     */
+    JSON_HEDLEY_NEVER_INLINE
     bool length_type_error(const char* position, const char* context) const
     {
         const char* types = input_format == input_format_t::bjdata ? "U, i, u, I, m, l, M, L" : "U, i, I, l, L";

include/nlohmann/detail/input/json_sax.hpp

@@ -187,12 +187,19 @@ Shared by json_sax_dom_parser and json_sax_dom_callback_parser.
 @param[in] ref   the object or array that was just created
 @return whether parsing should continue (false after reporting out_of_range.408)
 */
+template<typename SAX, typename BasicJsonType>
+JSON_HEDLEY_NEVER_INLINE
+bool container_too_large_error(SAX& sax, std::size_t len, const char* kind, BasicJsonType* ref)
+{
+    return sax.parse_error(0, "", out_of_range::create(exception_id::container_too_large, concat("excessive ", kind, " size: ", std::to_string(len)), ref));
+}
+
 template<typename SAX, typename BasicJsonType>
 bool check_container_size(SAX& sax, std::size_t len, const char* kind, BasicJsonType* ref)
 {
     if (JSON_HEDLEY_UNLIKELY(len != detail::unknown_size() && len > ref->max_size()))
     {
-        return sax.parse_error(0, "", out_of_range::create(exception_id::container_too_large, concat("excessive ", kind, " size: ", std::to_string(len)), ref));
+        return container_too_large_error(sax, len, kind, ref);
     }
     return true;
 }

include/nlohmann/detail/iterators/iter_impl.hpp

@@ -280,7 +280,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
     }
 
     /// @throw invalid_iterator.214 always
-    JSON_HEDLEY_NO_RETURN void throw_cannot_get_value() const
+    JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE void throw_cannot_get_value() const
     {
         JSON_THROW(invalid_iterator::create(exception_id::iterator_value_unavailable, "cannot get value", m_object));
     }
@@ -294,40 +294,25 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
     {
         JSON_ASSERT(m_object != nullptr);
 
-        switch (m_object->m_data.m_type)
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::array))
         {
-            case value_t::object:
-            {
-                JSON_ASSERT(m_it.object_iterator != m_object->m_data.m_value.object->end());
-                return m_it.object_iterator->second;
-            }
-
-            case value_t::array:
-            {
-                JSON_ASSERT(m_it.array_iterator != m_object->m_data.m_value.array->end());
-                return *m_it.array_iterator;
-            }
-
-            case value_t::null:
-                throw_cannot_get_value();
-
-            case value_t::string:
-            case value_t::boolean:
-            case value_t::number_integer:
-            case value_t::number_unsigned:
-            case value_t::number_float:
-            case value_t::binary:
-            case value_t::discarded:
-            default:
-            {
-                if (JSON_HEDLEY_LIKELY(m_it.primitive_iterator.is_begin()))
-                {
-                    return *m_object;
-                }
-
-                throw_cannot_get_value();
-            }
+            JSON_ASSERT(m_it.array_iterator != m_object->m_data.m_value.array->end());
+            return *m_it.array_iterator;
         }
+
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::object))
+        {
+            JSON_ASSERT(m_it.object_iterator != m_object->m_data.m_value.object->end());
+            return m_it.object_iterator->second;
+        }
+
+        // neither array nor object: a primitive value (null has no value to point to)
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type != value_t::null && m_it.primitive_iterator.is_begin()))
+        {
+            return *m_object;
+        }
+
+        throw_cannot_get_value();
     }
 
     /*!
@@ -338,38 +323,25 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
     {
         JSON_ASSERT(m_object != nullptr);
 
-        switch (m_object->m_data.m_type)
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::array))
         {
-            case value_t::object:
-            {
-                JSON_ASSERT(m_it.object_iterator != m_object->m_data.m_value.object->end());
-                return &(m_it.object_iterator->second);
-            }
-
-            case value_t::array:
-            {
-                JSON_ASSERT(m_it.array_iterator != m_object->m_data.m_value.array->end());
-                return &*m_it.array_iterator;
-            }
-
-            case value_t::null:
-            case value_t::string:
-            case value_t::boolean:
-            case value_t::number_integer:
-            case value_t::number_unsigned:
-            case value_t::number_float:
-            case value_t::binary:
-            case value_t::discarded:
-            default:
-            {
-                if (JSON_HEDLEY_LIKELY(m_it.primitive_iterator.is_begin()))
-                {
-                    return m_object;
-                }
-
-                throw_cannot_get_value();
-            }
+            JSON_ASSERT(m_it.array_iterator != m_object->m_data.m_value.array->end());
+            return &*m_it.array_iterator;
         }
+
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::object))
+        {
+            JSON_ASSERT(m_it.object_iterator != m_object->m_data.m_value.object->end());
+            return &(m_it.object_iterator->second);
+        }
+
+        // neither array nor object: a primitive value
+        if (JSON_HEDLEY_LIKELY(m_it.primitive_iterator.is_begin()))
+        {
+            return m_object;
+        }
+
+        throw_cannot_get_value();
     }
 
     /*!
@@ -391,35 +363,20 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
     {
         JSON_ASSERT(m_object != nullptr);
 
-        switch (m_object->m_data.m_type)
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::array))
         {
-            case value_t::object:
-            {
-                std::advance(m_it.object_iterator, 1);
-                break;
-            }
-
-            case value_t::array:
-            {
-                std::advance(m_it.array_iterator, 1);
-                break;
-            }
-
-            case value_t::null:
-            case value_t::string:
-            case value_t::boolean:
-            case value_t::number_integer:
-            case value_t::number_unsigned:
-            case value_t::number_float:
-            case value_t::binary:
-            case value_t::discarded:
-            default:
-            {
-                ++m_it.primitive_iterator;
-                break;
-            }
+            ++m_it.array_iterator;
+            return *this;
         }
 
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::object))
+        {
+            std::advance(m_it.object_iterator, 1);
+            return *this;
+        }
+
+        // neither array nor object: a primitive value
+        ++m_it.primitive_iterator;
         return *this;
     }
 
@@ -442,35 +399,20 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
     {
         JSON_ASSERT(m_object != nullptr);
 
-        switch (m_object->m_data.m_type)
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::array))
         {
-            case value_t::object:
-            {
-                std::advance(m_it.object_iterator, -1);
-                break;
-            }
-
-            case value_t::array:
-            {
-                std::advance(m_it.array_iterator, -1);
-                break;
-            }
-
-            case value_t::null:
-            case value_t::string:
-            case value_t::boolean:
-            case value_t::number_integer:
-            case value_t::number_unsigned:
-            case value_t::number_float:
-            case value_t::binary:
-            case value_t::discarded:
-            default:
-            {
-                --m_it.primitive_iterator;
-                break;
-            }
+            --m_it.array_iterator;
+            return *this;
         }
 
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::object))
+        {
+            std::advance(m_it.object_iterator, -1);
+            return *this;
+        }
+
+        // neither array nor object: a primitive value
+        --m_it.primitive_iterator;
         return *this;
     }
 
@@ -484,7 +426,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
         // if objects are not the same, the comparison is undefined
         if (JSON_HEDLEY_UNLIKELY(m_object != other.m_object))
         {
-            JSON_THROW(invalid_iterator::create(exception_id::iterators_compare_different_values, "cannot compare iterators of different containers", m_object));
+            throw_literal<invalid_iterator>(exception_id::iterators_compare_different_values, "cannot compare iterators of different containers", m_object);
         }
 
         // value-initialized forward iterators can be compared, and must compare equal to other value-initialized iterators of the same type #4493
@@ -493,25 +435,18 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
             return true;
         }
 
-        switch (m_object->m_data.m_type)
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::array))
         {
-            case value_t::object:
-                return (m_it.object_iterator == other.m_it.object_iterator);
-
-            case value_t::array:
-                return (m_it.array_iterator == other.m_it.array_iterator);
-
-            case value_t::null:
-            case value_t::string:
-            case value_t::boolean:
-            case value_t::number_integer:
-            case value_t::number_unsigned:
-            case value_t::number_float:
-            case value_t::binary:
-            case value_t::discarded:
-            default:
-                return (m_it.primitive_iterator == other.m_it.primitive_iterator);
+            return (m_it.array_iterator == other.m_it.array_iterator);
         }
+
+        if (JSON_HEDLEY_LIKELY(m_object->m_data.m_type == value_t::object))
+        {
+            return (m_it.object_iterator == other.m_it.object_iterator);
+        }
+
+        // neither array nor object: a primitive value
+        return (m_it.primitive_iterator == other.m_it.primitive_iterator);
     }
 
     /*!
@@ -533,7 +468,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
         // if objects are not the same, the comparison is undefined
         if (JSON_HEDLEY_UNLIKELY(m_object != other.m_object))
         {
-            JSON_THROW(invalid_iterator::create(exception_id::iterators_compare_different_values, "cannot compare iterators of different containers", m_object));
+            throw_literal<invalid_iterator>(exception_id::iterators_compare_different_values, "cannot compare iterators of different containers", m_object);
         }
 
         // value-initialized forward iterators can be compared, and must compare equal to other value-initialized iterators of the same type #4493
@@ -546,7 +481,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
         switch (m_object->m_data.m_type)
         {
             case value_t::object:
-                JSON_THROW(invalid_iterator::create(exception_id::iterator_order_on_object, "cannot compare order of object iterators", m_object));
+                throw_literal<invalid_iterator>(exception_id::iterator_order_on_object, "cannot compare order of object iterators", m_object);
 
             case value_t::array:
                 return (m_it.array_iterator < other.m_it.array_iterator);
@@ -602,7 +537,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
         switch (m_object->m_data.m_type)
         {
             case value_t::object:
-                JSON_THROW(invalid_iterator::create(exception_id::iterator_arithmetic_on_object, "cannot use offsets with object iterators", m_object));
+                throw_literal<invalid_iterator>(exception_id::iterator_arithmetic_on_object, "cannot use offsets with object iterators", m_object);
 
             case value_t::array:
             {
@@ -681,7 +616,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
         switch (m_object->m_data.m_type)
         {
             case value_t::object:
-                JSON_THROW(invalid_iterator::create(exception_id::iterator_arithmetic_on_object, "cannot use offsets with object iterators", m_object));
+                throw_literal<invalid_iterator>(exception_id::iterator_arithmetic_on_object, "cannot use offsets with object iterators", m_object);
 
             case value_t::array:
                 return m_it.array_iterator - other.m_it.array_iterator;
@@ -710,7 +645,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
         switch (m_object->m_data.m_type)
         {
             case value_t::object:
-                JSON_THROW(invalid_iterator::create(exception_id::iterator_subscript_on_object, "cannot use operator[] for object iterators", m_object));
+                throw_literal<invalid_iterator>(exception_id::iterator_subscript_on_object, "cannot use operator[] for object iterators", m_object);
 
             case value_t::array:
                 return *std::next(m_it.array_iterator, n);
@@ -750,7 +685,7 @@ class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-speci
             return m_it.object_iterator->first;
         }
 
-        JSON_THROW(invalid_iterator::create(exception_id::iterator_key_not_object, "cannot use key() for non-object iterators", m_object));
+        throw_literal<invalid_iterator>(exception_id::iterator_key_not_object, "cannot use key() for non-object iterators", m_object);
     }
 
     /*!

include/nlohmann/ordered_map.hpp

@@ -92,13 +92,19 @@ private:
 
     /// @brief shared implementation of the const and non-const at() overloads
     /// @throw std::out_of_range if @a key is not found
+    JSON_HEDLEY_NO_RETURN JSON_HEDLEY_NEVER_INLINE
+    static void throw_key_not_found()
+    {
+        JSON_THROW(std::out_of_range("key not found"));
+    }
+
     template<typename Self, typename KeyType>
     static auto at_impl(Self& self, const KeyType& key) -> decltype((self.begin()->second))
     {
         const auto it = find_impl(self, key);
         if (it == self.end())
         {
-            JSON_THROW(std::out_of_range("key not found"));
+            throw_key_not_found();
         }
         return it->second;
     }

tests/src/unit-comparison.cpp

@@ -19,6 +19,7 @@
 
 #include <cctype>
 #include <cstdint>
+#include <limits>
 #include <map>
 #include <string>
 #include <utility>
@@ -1149,3 +1150,157 @@ TEST_CASE("operator<=> of binary values with a different subtype does not depend
     }
 }
 #endif
+
+TEST_CASE("comparison of scalars (inline fast path)")
+{
+    const json::number_integer_t neg = -1;
+    const json::number_integer_t pos = 5;
+    const json::number_unsigned_t big = (std::numeric_limits<json::number_unsigned_t>::max)();
+
+    SECTION("same type")
+    {
+        CHECK(json(pos) == json(pos));
+        CHECK(json(pos) != json(neg));
+        CHECK(json(neg) < json(pos));
+        CHECK_FALSE(json(pos) < json(neg));
+        CHECK_FALSE(json(pos) < json(pos));
+        CHECK(json(pos) <= json(pos));
+
+        CHECK(json(1u) == json(1u));
+        CHECK(json(1u) < json(2u));
+        CHECK_FALSE(json(2u) < json(1u));
+
+        CHECK(json(1.5) == json(1.5));
+        CHECK(json(1.5) < json(2.5));
+        CHECK_FALSE(json(2.5) < json(1.5));
+        CHECK(json(-0.0) == json(0.0));
+    }
+
+    SECTION("mixed number types")
+    {
+        // negative signed vs unsigned must not wrap around
+        CHECK(json(neg) < json(1u));
+        CHECK(json(1u) > json(neg));
+        CHECK(json(neg) != json(big));
+        CHECK(json(neg) < json(big));
+        CHECK_FALSE(json(big) < json(neg));
+
+        CHECK(json(pos) == json(5u));
+        CHECK(json(5u) == json(pos));
+        CHECK(json(pos) < json(6u));
+        CHECK(json(pos) == json(5.0));
+        CHECK(json(5.0) == json(pos));
+        CHECK(json(5u) == json(5.0));
+        CHECK(json(neg) < json(0.5));
+        CHECK(json(0.5) < json(1u));
+    }
+
+    SECTION("boolean and null")
+    {
+        CHECK(json(true) == json(true));
+        CHECK(json(true) != json(false));
+        CHECK(json(false) < json(true));
+        CHECK_FALSE(json(true) < json(false));
+        CHECK_FALSE(json(true) < json(true));
+
+        CHECK(json(nullptr) == json(nullptr));
+        CHECK_FALSE(json(nullptr) < json(nullptr));
+        CHECK(json(nullptr) <= json(nullptr));
+        CHECK(json(nullptr) < json(false));
+        CHECK(json(nullptr) != json(false));
+        CHECK(json(nullptr) != json(0));
+    }
+
+    SECTION("string vs number")
+    {
+        CHECK(json("5") != json(5));
+        CHECK(json(5) != json("5"));
+        CHECK(json(5) < json("5")); // number < string by type order
+        CHECK_FALSE(json("5") < json(5));
+        CHECK(json(1.5) < json(""));
+        CHECK(json("a") == json("a"));
+        CHECK(json("a") < json("b"));
+    }
+
+    SECTION("NaN")
+    {
+        const json nan = std::numeric_limits<json::number_float_t>::quiet_NaN();
+        const json one = 1.0;
+
+        CHECK_FALSE(nan == nan);
+        CHECK(nan != nan);
+        CHECK_FALSE(nan < nan);
+        CHECK_FALSE(nan <= nan);
+        CHECK_FALSE(nan >= nan);
+        CHECK_FALSE(nan > nan);
+
+        CHECK_FALSE(nan == one);
+        CHECK_FALSE(one == nan);
+        CHECK_FALSE(nan < one);
+        CHECK_FALSE(one < nan);
+        CHECK_FALSE(nan <= one);
+        CHECK_FALSE(one <= nan);
+        CHECK_FALSE(nan >= one);
+        CHECK_FALSE(one >= nan);
+
+        // NaN against other number types
+        CHECK_FALSE(nan == json(1));
+        CHECK_FALSE(json(1) == nan);
+        CHECK_FALSE(nan < json(1u));
+        CHECK_FALSE(json(1u) < nan);
+
+#if JSON_HAS_THREE_WAY_COMPARISON
+        CHECK((nan <=> nan) == std::partial_ordering::unordered); // *NOPAD*
+        CHECK((nan <=> one) == std::partial_ordering::unordered); // *NOPAD*
+        CHECK((one <=> nan) == std::partial_ordering::unordered); // *NOPAD*
+        CHECK((one <=> json(2.0)) == std::partial_ordering::less); // *NOPAD*
+        CHECK((json(2.0) <=> one) == std::partial_ordering::greater); // *NOPAD*
+        CHECK((one <=> one) == std::partial_ordering::equivalent); // *NOPAD*
+        CHECK((json(neg) <=> json(1u)) == std::partial_ordering::less); // *NOPAD*
+        CHECK((json(nullptr) <=> json(nullptr)) == std::partial_ordering::equivalent); // *NOPAD*
+        CHECK((json(true) <=> json(false)) == std::partial_ordering::greater); // *NOPAD*
+#endif
+    }
+
+    SECTION("discarded")
+    {
+        const json d(json::value_t::discarded);
+
+        CHECK_FALSE(d == d);
+        CHECK_FALSE(d < d);
+        CHECK_FALSE(d == json(1));
+        CHECK_FALSE(json(1) == d);
+        CHECK_FALSE(d < json(1));
+        CHECK_FALSE(json(1) < d);
+        CHECK_FALSE(d == json(nullptr));
+        CHECK_FALSE(json(nullptr) == d);
+
+#if JSON_HAS_THREE_WAY_COMPARISON
+        CHECK((d <=> d) == std::partial_ordering::unordered); // *NOPAD*
+        CHECK((d <=> json(1)) == std::partial_ordering::unordered); // *NOPAD*
+        CHECK((json(1) <=> d) == std::partial_ordering::unordered); // *NOPAD*
+#endif
+    }
+
+    SECTION("scalar overloads")
+    {
+        CHECK(json(5) == 5);
+        CHECK(5 == json(5));
+        CHECK(json(5) < 6);
+        CHECK(4 < json(5));
+        CHECK(json(1.5) == 1.5);
+        CHECK(json(true) == true);
+        CHECK(json(5) != 6);
+        CHECK(json(1u) == 1.0);
+    }
+
+    SECTION("structured values still compare")
+    {
+        CHECK(json({1, 2}) == json({1, 2}));
+        CHECK(json({1, 2}) < json({1, 3}));
+        CHECK(json({{"a", 1}}) == json({{"a", 1}}));
+        CHECK(json::binary({1, 2}) == json::binary({1, 2}));
+        CHECK(json(1) < json::array());
+        CHECK(json::object() < json::array());
+    }
+}

tests/src/unit-constructor2.cpp

@@ -8,6 +8,9 @@
 
 #include "doctest_compatibility.h"
 
+#include <string>
+#include <vector>
+
 #include <nlohmann/json.hpp>
 using nlohmann::json;
 
@@ -184,3 +187,193 @@ TEST_CASE("other constructors and destructor")
         }
     }
 }
+
+TEST_CASE("copy constructor and destructor across value types")
+{
+    SECTION("copy of a scalar is independent of the source")
+    {
+        const json src_null = nullptr;
+        const json src_bool = true;
+        const json src_int = -7;
+        const json src_uint = 7u;
+        const json src_float = 2.5;
+
+        json c_null(src_null);
+        json c_bool(src_bool);
+        json c_int(src_int);
+        json c_uint(src_uint);
+        json c_float(src_float);
+
+        CHECK(c_null.is_null());
+        CHECK(c_bool == true);
+        CHECK(c_int == -7);
+        CHECK(c_uint == 7u);
+        CHECK(c_float == 2.5);
+
+        c_int = 8;
+        c_float = 3.5;
+        CHECK(src_int == -7);
+        CHECK(src_float == 2.5);
+    }
+
+    SECTION("copy of an owning value, then mutate the copy")
+    {
+        const json src_string = "hello";
+        const json src_array = {1, 2, 3};
+        const json src_object = {{"a", 1}, {"b", {{"c", 2}}}};
+        const json src_binary = json::binary({1, 2, 3});
+
+        json c_string(src_string);
+        json c_array(src_array);
+        json c_object(src_object);
+        json c_binary(src_binary);
+
+        CHECK(c_string == src_string);
+        CHECK(c_array == src_array);
+        CHECK(c_object == src_object);
+        CHECK(c_binary == src_binary);
+
+        c_string.get_ref<json::string_t&>() += " world";
+        c_array.push_back(4);
+        c_object["b"]["c"] = 3;
+        c_object["d"] = 4;
+        c_binary.get_binary().push_back(4);
+
+        CHECK(src_string == "hello");
+        CHECK(src_array.size() == 3);
+        CHECK(src_object["b"]["c"] == 2);
+        CHECK_FALSE(src_object.contains("d"));
+        CHECK(src_binary.get_binary().size() == 3);
+
+        CHECK(c_string == "hello world");
+        CHECK(c_array.size() == 4);
+        CHECK(c_object["b"]["c"] == 3);
+        CHECK(c_binary.get_binary().size() == 4);
+    }
+
+    SECTION("copy keeps parent pointers valid (JSON_DIAGNOSTICS)")
+    {
+        const json src = {{"a", {1, 2}}, {"b", "x"}};
+        json c(src);
+        c["a"].push_back(3);
+        CHECK(c["a"].size() == 3);
+        CHECK(src["a"].size() == 2);
+    }
+
+    SECTION("vector of mixed types: build, copy, and destroy")
+    {
+        {
+            std::vector<json> v;
+            for (int i = 0; i < 70; ++i)
+            {
+                switch (i % 9)
+                {
+                    case 0:
+                        v.emplace_back(nullptr);
+                        break;
+                    case 1:
+                        v.emplace_back(i % 2 == 0);
+                        break;
+                    case 2:
+                        v.emplace_back(-i);
+                        break;
+                    case 3:
+                        v.emplace_back(static_cast<json::number_unsigned_t>(i));
+                        break;
+                    case 4:
+                        v.emplace_back(i * 0.5);
+                        break;
+                    case 5:
+                        v.emplace_back(std::string(static_cast<std::size_t>(i), 'x'));
+                        break;
+                    case 6:
+                        v.emplace_back(json::array({i, "s", nullptr}));
+                        break;
+                    case 7:
+                        v.emplace_back(json::object({{"k", i}}));
+                        break;
+                    default:
+                        v.emplace_back(json::binary({1, 2, 3}));
+                        break;
+                }
+            }
+            REQUIRE(v.size() == 70);
+
+            std::vector<json> copy(v);
+            CHECK(copy == v);
+
+            // mutating the copy leaves the original alone
+            copy[5] = "changed";
+            copy[6].push_back(1);
+            CHECK(copy != v);
+            CHECK(v[5] == std::string(5, 'x'));
+            CHECK(v[6].size() == 3);
+
+            v.erase(v.begin(), v.begin() + 10);
+            CHECK(v.size() == 60);
+        }
+
+        // destroying the discarded and default-constructed values
+        std::vector<json> w(4);
+        w.emplace_back(json::value_t::discarded);
+        w.emplace_back(json::value_t::object);
+        w.emplace_back(json::value_t::array);
+        w.emplace_back(json::value_t::string);
+        w.emplace_back(json::value_t::binary);
+        CHECK(w.size() == 9);
+    }
+}
+
+TEST_CASE_TEMPLATE("destructor of nested containers", Json, nlohmann::json, nlohmann::ordered_json)
+{
+    SECTION("empty containers")
+    {
+        {
+            Json j = Json::array();
+        }
+        {
+            Json j = Json::object();
+        }
+        {
+            Json j = Json::array({Json::array(), Json::object(), Json::array({Json::array()})});
+        }
+    }
+
+    SECTION("leaves mixed with nested containers")
+    {
+        Json j = Json::object();
+        j["leaf"] = 1;
+        j["str"] = "text";
+        j["empty_a"] = Json::array();
+        j["empty_o"] = Json::object();
+        j["arr"] = Json::array({1, "a", Json::array({1, 2}), Json::object({{"k", Json::array({Json::object()})}}), nullptr});
+        j["obj"] = Json::object({{"x", Json::object({{"y", Json::array({1, Json::object({{"z", 1}})})}})}, {"w", 2}});
+        Json copy = j;
+        CHECK(copy == j);
+        j = Json::array({std::move(copy), j, 3, Json::array()});
+    }
+
+    SECTION("deep nesting")
+    {
+        for (int kind = 0; kind < 3; ++kind)
+        {
+            Json j = 1;
+            for (int i = 0; i < 5000; ++i)
+            {
+                switch (kind)
+                {
+                    case 0:
+                        j = Json::array({std::move(j)});
+                        break;
+                    case 1:
+                        j = Json::object({{"k", std::move(j)}});
+                        break;
+                    default:
+                        // siblings next to the nested child
+                        j = (i % 2 == 0) ? Json::array({1, Json::array(), std::move(j)}) : Json::object({{"a", 1}, {"b", Json::object()}, {"c", std::move(j)}});
+                        break;
+                }
+            }
+        }
+    }
+}

tests/src/unit-diagnostics.cpp

@@ -13,9 +13,11 @@
 #endif
 
 #define JSON_DIAGNOSTICS 1
+#define JSON_TESTS_PRIVATE
 
 #include <nlohmann/json.hpp>
 using nlohmann::json;
+using nlohmann::ordered_json;
 
 #include <map>
 #include <unordered_map>
@@ -631,3 +633,175 @@ TEST_CASE("Better diagnostics past the descent bound of update(), merge_patch()
         CHECK_THROWS_WITH_AS(p->at("y").at(0), expected_y.c_str(), json::type_error);
     }
 }
+
+namespace
+{
+// check that every child's parent pointer points to the containing value
+template<typename BasicJsonType>
+bool parents_consistent(const BasicJsonType& j)
+{
+    bool ok = true;
+    if (j.is_array() || j.is_object())
+    {
+        for (const auto& child : j)
+        {
+            ok = ok && child.m_parent == &j && parents_consistent(child);
+        }
+    }
+    return ok;
+}
+} // namespace
+
+TEST_CASE_TEMPLATE("Parent pointers stay consistent", J, json, ordered_json)
+{
+    SECTION("parse, copy, move, assign, swap")
+    {
+        J j = J::parse(R"({"a":[1,{"b":[2,3]},[4]],"c":{"d":{"e":[]}}})");
+        CHECK(parents_consistent(j));
+
+        J copy(j);
+        CHECK(parents_consistent(copy));
+
+        J moved(std::move(copy));
+        CHECK(parents_consistent(moved));
+
+        J assigned;
+        assigned = j;
+        CHECK(parents_consistent(assigned));
+
+        J other = {1, 2, {{"k", J::array({1, 2})}}};
+        other.swap(assigned);
+        CHECK(parents_consistent(other));
+        CHECK(parents_consistent(assigned));
+    }
+
+    SECTION("push_back growth")
+    {
+        J arr = J::array();
+        for (int i = 0; i < 500; ++i)
+        {
+            arr.push_back(J::array({i}));
+        }
+        CHECK(parents_consistent(arr));
+
+        J obj = J::object();
+        for (int i = 0; i < 500; ++i)
+        {
+            obj.push_back({std::to_string(i), J::array({i})});
+        }
+        CHECK(parents_consistent(obj));
+    }
+
+    SECTION("emplace_back and emplace growth")
+    {
+        J arr = J::array();
+        J obj = J::object();
+        for (int i = 0; i < 500; ++i)
+        {
+            arr.emplace_back(J::array({i}));
+            obj.emplace(std::to_string(i), J::array({i}));
+        }
+        CHECK(parents_consistent(arr));
+        CHECK(parents_consistent(obj));
+    }
+
+    SECTION("operator[] growth and at()")
+    {
+        J obj = J::object();
+        for (int i = 0; i < 500; ++i)
+        {
+            obj[std::to_string(i)] = J::array({i});
+            CHECK(obj[std::to_string(i / 2)].m_parent == &obj);
+        }
+        CHECK(parents_consistent(obj));
+
+        J arr = J::array();
+        for (int i = 0; i < 500; ++i)
+        {
+            arr[static_cast<size_t>(i)] = J::object({{"x", i}});
+        }
+        for (size_t i = 0; i < 500; ++i)
+        {
+            CHECK(arr.at(i).m_parent == &arr);
+        }
+        CHECK(obj.at("3").m_parent == &obj);
+        CHECK(parents_consistent(arr));
+        CHECK(parents_consistent(obj));
+    }
+}
+
+TEST_CASE_TEMPLATE("update() and merge_patch() keep parent pointers and diagnostic paths", J, json, ordered_json)
+{
+    // enough keys to make the vector behind ordered_json reallocate several times
+    const auto make_object = [](int first, int last)
+    {
+        J o = J::object();
+        for (int i = first; i < last; ++i)
+        {
+            o[std::to_string(i)] = J::object({{"x", J::array({i})}});
+        }
+        return o;
+    };
+
+    // const access, so operator[] cannot repair the parent pointers
+    const auto check_path = [](const J & j, const std::string & key)
+    {
+        const std::string expected = "[json.exception.type_error.304] (/" + key + "/x) cannot use at() with array";
+        CHECK_THROWS_WITH_AS(j[key]["x"].at("y"), expected.c_str(), json::type_error);
+    };
+
+    SECTION("update(const_reference)")
+    {
+        J j = make_object(0, 200);
+        j.update(make_object(100, 400));
+        CHECK(j.size() == 400);
+        CHECK(parents_consistent(j));
+        check_path(j, "0");
+        check_path(j, "150");
+        check_path(j, "399");
+    }
+
+    SECTION("update(const_reference, merge_objects)")
+    {
+        J j = make_object(0, 200);
+        j["50"]["y"] = 1;
+        J other = make_object(100, 400);
+        other["50"] = J::object({{"z", J::array({1})}});
+        j.update(other, true);
+        CHECK(j.size() == 400);
+        CHECK(j["50"].size() == 3);
+        CHECK(parents_consistent(j));
+        check_path(j, "0");
+        check_path(j, "399");
+    }
+
+    SECTION("update(first, last)")
+    {
+        J j = make_object(0, 200);
+        J other = make_object(100, 400);
+        j.update(other.begin(), other.end());
+        CHECK(j.size() == 400);
+        CHECK(parents_consistent(j));
+        check_path(j, "0");
+        check_path(j, "399");
+
+        J k = make_object(0, 200);
+        k.update(other.begin(), other.end(), true);
+        CHECK(k.size() == 400);
+        CHECK(parents_consistent(k));
+        check_path(k, "399");
+    }
+
+    SECTION("merge_patch()")
+    {
+        J j = make_object(0, 200);
+        J patch = make_object(100, 400);
+        patch["0"] = nullptr;
+        j.merge_patch(patch);
+        CHECK(j.size() == 399);
+        CHECK_FALSE(j.contains("0"));
+        CHECK(parents_consistent(j));
+        check_path(j, "1");
+        check_path(j, "399");
+    }
+}

tests/src/unit-iterators1.cpp

@@ -10,6 +10,8 @@
 
 #define JSON_TESTS_PRIVATE
 #include <nlohmann/json.hpp>
+#include <string>
+#include <vector>
 using nlohmann::json;
 
 TEST_CASE("iterators 1")
@@ -1628,3 +1630,108 @@ TEST_CASE("iterators 1")
         }
     }
 }
+
+TEST_CASE_TEMPLATE("reverse iteration and member access", Json, nlohmann::json, nlohmann::ordered_json)
+{
+    SECTION("array: -- and rbegin/rend")
+    {
+        Json j = {1, 2, 3, 4};
+
+        auto it = j.end();
+        std::vector<int> seen;
+        while (it != j.begin())
+        {
+            --it;
+            seen.push_back(it->template get<int>());
+        }
+        CHECK(seen == std::vector<int> {4, 3, 2, 1});
+
+        auto it2 = j.end();
+        auto old = it2--;
+        CHECK(old == j.end());
+        CHECK(*it2 == 4);
+
+        seen.clear();
+        for (auto r = j.rbegin(); r != j.rend(); ++r)
+        {
+            seen.push_back(r->template get<int>());
+        }
+        CHECK(seen == std::vector<int> {4, 3, 2, 1});
+
+        seen.clear();
+        for (auto r = j.crbegin(); r != j.crend(); ++r)
+        {
+            seen.push_back(*r);
+        }
+        CHECK(seen == std::vector<int> {4, 3, 2, 1});
+    }
+
+    SECTION("object: -- and rbegin/rend")
+    {
+        Json j = {{"a", 1}, {"b", 2}, {"c", 3}};
+        // order of keys depends on the object type; use the forward order as reference
+        std::vector<std::string> fwd;
+        for (auto it = j.begin(); it != j.end(); ++it)
+        {
+            fwd.push_back(it.key());
+        }
+        std::vector<std::string> rev(fwd.rbegin(), fwd.rend());
+
+        std::vector<std::string> seen;
+        auto it = j.end();
+        while (it != j.begin())
+        {
+            --it;
+            seen.push_back(it.key());
+        }
+        CHECK(seen == rev);
+
+        auto it2 = j.end();
+        auto old = it2--;
+        CHECK(old == j.end());
+        CHECK(it2.key() == rev.front());
+
+        seen.clear();
+        for (auto r = j.rbegin(); r != j.rend(); ++r)
+        {
+            seen.push_back(r.key());
+        }
+        CHECK(seen == rev);
+    }
+
+    SECTION("object: operator-> reads and writes the mapped value")
+    {
+        Json j = {{"a", 1}, {"s", "str"}};
+        auto it = j.find("s");
+        REQUIRE(it != j.end());
+        CHECK(it->is_string());
+        CHECK(it->size() == 1);
+        *it = Json::array({1, 2});
+        CHECK(it->is_array());
+        it->push_back(3);
+        CHECK(j["s"].size() == 3);
+
+        const Json& cj = j;
+        auto cit = cj.find("a");
+        REQUIRE(cit != cj.end());
+        CHECK(cit->is_number_integer());
+        CHECK(cit->template get<int>() == 1);
+    }
+
+    SECTION("primitives: -- and ->")
+    {
+        Json j = 42;
+        auto it = j.end();
+        --it;
+        CHECK(it == j.begin());
+        CHECK(it->template get<int>() == 42);
+    }
+
+    SECTION("comparing iterators of different containers throws")
+    {
+        Json a = {1, 2};
+        Json b = {1, 2};
+        CHECK_THROWS_WITH_AS(a.begin() == b.begin(), "[json.exception.invalid_iterator.212] cannot compare iterators of different containers", nlohmann::json::invalid_iterator);
+        CHECK_THROWS_WITH_AS(a.begin() < b.begin(), "[json.exception.invalid_iterator.212] cannot compare iterators of different containers", nlohmann::json::invalid_iterator);
+    }
+}

tests/src/unit-json_patch.cpp

@@ -2066,3 +2066,40 @@ TEST_CASE("JSON patch - every operation on ordered_json")
         }
     }
 }
+
+TEST_CASE_TEMPLATE("JSON patch - diff round trip on hand-made documents", Json, nlohmann::json, nlohmann::ordered_json)
+{
+    const auto roundtrip = [](const Json & a, const Json & b)
+    {
+        CAPTURE(a.dump())
+        CAPTURE(b.dump())
+        const Json p = Json::diff(a, b);
+        CHECK(a.patch(p) == b);
+        CHECK(Json::diff(b, b).empty());
+    };
+
+    SECTION("reordered keys")
+    {
+        const Json a = Json::parse(R"({"x":1,"y":2,"z":{"p":1,"q":2}})");
+        const Json b = Json::parse(R"({"z":{"q":2,"p":1},"y":2,"x":1})");
+        roundtrip(a, b);
+        roundtrip(b, a);
+    }
+
+    SECTION("nested add, remove and replace")
+    {
+        const Json a = Json::parse(R"({"a":[1,2,{"k":"v","gone":true}],"b":{"c":{"d":1}},"e":"s"})");
+        const Json b = Json::parse(R"({"a":[1,3,{"k":"w","new":[]}],"b":{"c":{"d":[1,2]}},"f":null})");
+        roundtrip(a, b);
+        roundtrip(b, a);
+    }
+
+    SECTION("arrays of different length and type changes")
+    {
+        roundtrip(Json::parse("[1,2,3,4,5]"), Json::parse("[1,3]"));
+        roundtrip(Json::parse("[1]"), Json::parse("[1,[2],{\"a\":3}]"));
+        roundtrip(Json::parse("[]"), Json::parse("{}"));
+        roundtrip(Json::parse("{\"a\":[]}"), Json::parse("{\"a\":{}}"));
+        roundtrip(Json(1), Json::parse("[1]"));
+    }
+}

tests/src/unit-throw_messages.cpp

@@ -0,0 +1,135 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#include "doctest_compatibility.h"
+
+#include <nlohmann/json.hpp>
+using nlohmann::json;
+
+#include <string>
+
+// The exceptions in hot core functions are constructed out of line. These tests pin the
+// exact what() texts of the sites that moved, so the refactoring cannot change them.
+
+#define CHECK_MSG(expr, msg) CHECK_THROWS_WITH(expr, msg)
+
+TEST_CASE("exception messages of out-of-line throw sites")
+{
+    json arr = {1, 2, 3};
+    json arr2 = {4, 5};
+    json obj = {{"a", 1}, {"b", 2}};
+    json obj2 = {{"c", 3}};
+    json num = 1;
+
+    SECTION("iterators")
+    {
+        CHECK_MSG((void)(arr.begin() == arr2.begin()), "[json.exception.invalid_iterator.212] cannot compare iterators of different containers");
+        CHECK_MSG((void)(arr.begin() < arr2.begin()), "[json.exception.invalid_iterator.212] cannot compare iterators of different containers");
+        CHECK_MSG((void)(obj.begin() < obj.end()), "[json.exception.invalid_iterator.213] cannot compare order of object iterators");
+        CHECK_MSG(obj.begin() += 1, "[json.exception.invalid_iterator.209] cannot use offsets with object iterators");
+        CHECK_MSG((void)(obj.begin() - 1), "[json.exception.invalid_iterator.209] cannot use offsets with object iterators");
+        CHECK_MSG((void)obj.begin()[0], "[json.exception.invalid_iterator.208] cannot use operator[] for object iterators");
+        CHECK_MSG((void)arr.begin().key(), "[json.exception.invalid_iterator.207] cannot use key() for non-object iterators");
+        json null;
+        CHECK_MSG((void)*null.end(), "[json.exception.invalid_iterator.214] cannot get value");
+    }
+
+    SECTION("constructors")
+    {
+        CHECK_MSG(json(arr.begin(), arr2.end()), "[json.exception.invalid_iterator.201] iterators are not compatible");
+        CHECK_MSG(json(num.begin() + 1, num.end() + 1), "[json.exception.invalid_iterator.204] iterators out of range");
+        CHECK_MSG(json(json::initializer_list_t{1, 2}, false, json::value_t::object), "[json.exception.type_error.301] cannot create object from initializer list");
+    }
+
+    SECTION("get_ref and operator[]")
+    {
+        CHECK_MSG((void)num.get_ref<std::string&>(), "[json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is number");
+        CHECK_MSG((void)num[0], "[json.exception.type_error.305] cannot use operator[] with a numeric argument with number");
+    }
+
+    SECTION("at")
+    {
+        const json carr = arr;
+        const json cobj = obj;
+        CHECK_MSG((void)arr.at(static_cast<json::size_type>(10)), "[json.exception.out_of_range.401] array index 10 is out of range");
+        CHECK_MSG((void)carr.at(static_cast<json::size_type>(3)), "[json.exception.out_of_range.401] array index 3 is out of range");
+        CHECK_MSG((void)num.at(static_cast<json::size_type>(0)), "[json.exception.type_error.304] cannot use at() with number");
+        CHECK_MSG((void)obj.at("z"), "[json.exception.out_of_range.403] key 'z' not found");
+        CHECK_MSG((void)cobj.at("z"), "[json.exception.out_of_range.403] key 'z' not found");
+        CHECK_MSG((void)obj.at(std::string("zz")), "[json.exception.out_of_range.403] key 'zz' not found");
+        CHECK_MSG((void)num.at("a"), "[json.exception.type_error.304] cannot use at() with number");
+
+        nlohmann::ordered_json oobj = {{"a", 1}};
+        const nlohmann::ordered_json coobj = oobj;
+        CHECK_MSG((void)oobj.at("z"), "[json.exception.out_of_range.403] key 'z' not found");
+        CHECK_MSG((void)coobj.at("z"), "[json.exception.out_of_range.403] key 'z' not found");
+        CHECK_MSG((void)coobj.at(std::string("zz")), "[json.exception.out_of_range.403] key 'zz' not found");
+    }
+
+    SECTION("erase")
+    {
+        CHECK_MSG(arr.erase(arr2.begin()), "[json.exception.invalid_iterator.202] iterator does not fit current value");
+        CHECK_MSG(num.erase(num.end()), "[json.exception.invalid_iterator.205] iterator out of range");
+        CHECK_MSG(arr.erase(arr.begin(), arr2.end()), "[json.exception.invalid_iterator.203] iterators do not fit current value");
+        CHECK_MSG(num.erase(num.begin() + 1, num.end()), "[json.exception.invalid_iterator.204] iterators out of range");
+        CHECK_MSG(arr.erase(static_cast<json::size_type>(10)), "[json.exception.out_of_range.401] array index 10 is out of range");
+    }
+
+    SECTION("insert")
+    {
+        CHECK_MSG(arr.insert(arr2.begin(), 1), "[json.exception.invalid_iterator.202] iterator does not fit current value");
+        CHECK_MSG(arr.insert(arr2.begin(), 2, 1), "[json.exception.invalid_iterator.202] iterator does not fit current value");
+        CHECK_MSG(arr.insert(arr2.begin(), arr2.begin(), arr2.end()), "[json.exception.invalid_iterator.202] iterator does not fit current value");
+        CHECK_MSG(arr.insert(arr.begin(), arr.begin(), arr2.end()), "[json.exception.invalid_iterator.210] iterators do not fit");
+        CHECK_MSG(arr.insert(arr.begin(), arr.begin(), arr.end()), "[json.exception.invalid_iterator.211] passed iterators may not belong to container");
+        CHECK_MSG(arr.insert(arr.begin(), obj.begin(), obj.end()), "[json.exception.invalid_iterator.202] iterators first and last must point to arrays");
+        CHECK_MSG(arr.insert(arr2.begin(), {1, 2}), "[json.exception.invalid_iterator.202] iterator does not fit current value");
+        CHECK_MSG(obj.insert(obj2.begin(), arr.end()), "[json.exception.invalid_iterator.210] iterators do not fit");
+        CHECK_MSG(obj.insert(arr.begin(), arr.end()), "[json.exception.invalid_iterator.202] iterators first and last must point to objects");
+        CHECK_MSG(obj.update(arr.begin(), arr2.end()), "[json.exception.invalid_iterator.210] iterators do not fit");
+    }
+
+    SECTION("patch")
+    {
+        const auto patch_msg = [](const char* doc, const char* patch)
+        {
+            try
+            {
+                json d = json::parse(doc);
+                d.patch(json::parse(patch));
+            }
+            catch (const json::exception& e)
+            {
+                // with JSON_DIAGNOSTICS, what() names the offending value like "(/0) "; drop it
+                std::string msg = e.what();
+                const auto pos = msg.find(" (/");
+                if (pos != std::string::npos)
+                {
+                    msg.erase(pos + 1, msg.find(") ", pos) - pos + 1);
+                }
+                return msg;
+            }
+            return std::string();
+        };
+
+        CHECK(patch_msg("{}", "{}") == "[json.exception.parse_error.104] parse error: JSON patch must be an array of objects");
+        CHECK(patch_msg("{}", "[1]") == "[json.exception.parse_error.104] parse error: JSON patch must be an array of objects");
+        CHECK(patch_msg("{}", "[{}]") == "[json.exception.parse_error.105] parse error: operation must have member 'op'");
+        CHECK(patch_msg("{}", "[{\"op\":1}]") == "[json.exception.parse_error.105] parse error: operation must have string member 'op'");
+        CHECK(patch_msg("{}", "[{\"op\":\"add\"}]") == "[json.exception.parse_error.105] parse error: operation 'add' must have member 'path'");
+        CHECK(patch_msg("{}", "[{\"op\":\"add\",\"path\":1}]") == "[json.exception.parse_error.105] parse error: operation 'add' must have string member 'path'");
+        CHECK(patch_msg("{}", "[{\"op\":\"foo\",\"path\":\"\"}]") == "[json.exception.parse_error.105] parse error: operation value 'foo' is invalid");
+        CHECK(patch_msg("{\"a\":1}", "[{\"op\":\"remove\",\"path\":\"/b\"}]") == "[json.exception.out_of_range.403] key 'b' not found");
+        CHECK(patch_msg("[1]", "[{\"op\":\"add\",\"path\":\"/5\",\"value\":0}]") == "[json.exception.out_of_range.401] array index 5 is out of range");
+        CHECK(patch_msg("{\"a\":1}", "[{\"op\":\"add\",\"path\":\"/a/b\",\"value\":0}]") == "[json.exception.out_of_range.411] cannot add value: the JSON Patch 'add' target's parent is of type number, but must be an object or array");
+        CHECK(patch_msg("{\"a\":1}", "[{\"op\":\"remove\",\"path\":\"/a/b\"}]") == "[json.exception.out_of_range.413] cannot remove value: the JSON Patch 'remove' target's parent is of type number, but must be an object or array");
+        CHECK(patch_msg("{\"a\":{}}", "[{\"op\":\"move\",\"from\":\"/a\",\"path\":\"/a/b\"}]") == "[json.exception.out_of_range.414] cannot move value: 'from' path '/a' is a proper prefix of 'path' '/a/b'");
+        CHECK(patch_msg("{\"a\":1}", "[{\"op\":\"test\",\"path\":\"/a\",\"value\":2}]") == "[json.exception.other_error.501] unsuccessful: {\"op\":\"test\",\"path\":\"/a\",\"value\":2}");
+        CHECK(patch_msg("{\"a\":1}", "[{\"op\":\"move\",\"path\":\"/a\"}]") == "[json.exception.parse_error.105] parse error: operation 'move' must have member 'from'");
+    }
+}