[nlohmann]

Adds an opt-in macro JSON_DELETE_DEPRECATED_FUNCTIONS, with the CMake option JSON_DeleteDeprecatedFunctions. When it is defined to 1, every deprecated function is declared = delete instead of JSON_HEDLEY_DEPRECATED_FOR. Code that is not ready for 4.0.0 then stops compiling, even if deprecation warnings are switched off. This follows the "try 4.0 today" approach from the roadmap (#5593).

This came out of @gregmarr's review of #5688 (comment). A deleted function, unlike a removed one, still takes part in overload resolution. So with the macro, from_cbor(ptr, len) is a hard error ("call to deleted function"). With the overload removed, the call would still compile: it would bind len to bool strict and read ptr as a NUL-terminated string. For the same reason, the roadmap now plans to keep the from_*(ptr, len) overloads deleted in 4.0.0 instead of removing them.

Changes

• Library: the 30 deprecated functions in json.hpp and json_pointer.hpp each get an #if JSON_DELETE_DEPRECATED_FUNCTIONS branch that declares them deleted. The parameter list and default arguments stay the same, so the deleted overload is still selected wherever the deprecated one would have been. This covers:

  • from_cbor, from_msgpack, from_ubjson, from_bjdata, from_bon8, from_bson with (ptr, len), and the first four plus from_bson with an initializer list
  • parse, accept, sax_parse with an initializer list
  • iterator_wrapper
  • j << is and j >> os
  • json_pointer::operator string_t
  • comparing a json_pointer with a string
  • value, contains, operator[], at taking a json_pointer<basic_json>

  The legacy discarded-value comparison keeps its own macro (JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON). The new macro gets no ABI tag: it changes no layout and no behavior, it only turns calls that compile into calls that don't (the same as JSON_USE_IMPLICIT_CONVERSIONS).

• Tests:

  • New unit-delete_deprecated_functions.cpp defines the macro itself. Using SFINAE traits, it checks that each of the 32 deprecated calls is ill-formed and that the replacements still compile. I checked that all 32 checks flip when the macro is 0, so they are not trivially false.
  • The tests that call deprecated functions capture the macro before including json.hpp, the same way as for JSON_STRICT_NUL_HANDLING, and skip those calls when it is set.
  • Two tests now use the replacement instead of the deprecated function: unit-regression2's [json.exception.type_error.317] cannot serialize binary data to text JSON #2067 test and the "preserve state after parsing" stream test.

• CI: new target ci_test_delete_deprecated_functions in ci_cmake_options. The CMake option is also added to the ci_cmake_flags checks.

• Docs:

  • New macro page, plus entries in the macro index, the macro overview, the CMake page, the nav, and the docset.
  • Roadmap ("Version 4.0"):
    • Adds JSON_DELETE_DEPRECATED_FUNCTIONS and the previously missing JSON_DISABLE_TUPLE_REFERENCE_CONVERSION (Add JSON_DISABLE_TUPLE_REFERENCE_CONVERSION to fix std::tuple conversions #5598) to the macro table and the #define block.
    • Explains why the (ptr, len) overloads stay deleted.
    • Adds the from_bjdata/from_bon8 (ptr, len) overloads from Add deprecated from_bon8/from_bjdata(ptr, len) overloads #5688 to the deprecated functions.
  • Migration guide ("Replace deprecated functions"): a tip pointing to the macro, and the from_bjdata/from_bon8 overloads.
  • JSON_DISABLE_TUPLE_REFERENCE_CONVERSION's version history now says it is planned to become the default in 4.0.0.
  • Fixes findings of check_structure.py on develop: example titles on the JSON_STRICT_BINARY_UTF8 and JSON_USE_IMPLICIT_CONVERSIONS pages, and the missing docset entry for JSON_STRICT_BINARY_UTF8.

Stacked on #5688, because it also deletes the new from_bjdata/from_bon8 overloads.

Testing

• Local full suite (Apple clang, Debug) with -DJSON_DeleteDeprecatedFunctions=ON: all tests pass except test-alt-string, which fails to build on develop itself (fixed in Fix CI on develop after merging the ready-to-merge PRs #5754).
• The changed test files also pass without the macro.
• unit-delete_deprecated_functions passes at C++11, 14, 17, and 20.
• mkdocs build --strict and check_structure.py pass.

Public API

No breaking changes. The macro defaults to 0, which keeps everything as it is. With 1, calls to deprecated functions fail to compile, which is the purpose of the opt-in.

---

This PR was written by Claude Code.

🤖 Generated with Claude Code

[github-actions]

🔴 Amalgamation check failed! 🔴

The source code has not been amalgamated and/or formatted correctly, or BUILD.bazel is out of date.

📎 A ready-to-apply patch is attached to the failed workflow run as the amalgamation-patch artifact. Download it, then apply it locally from the repository root with:

git apply amalgamation.patch

This does not require installing astyle yourself.

[gregmarr]

I wonder if this can avoid duplicating the declaration:

#if JSON_DELETE_DEPRECATED_FUNCTIONS
#define JSON_DELETE_DEPRECATED_FUNCTIONS_DEPRECATED(ver, func) 
#define JSON_DELETE_DEPRECATED_FUNCTIONS_DELETE = delete
#else
#define JSON_DELETE_DEPRECATED_FUNCTIONS_DEPRECATED(ver, func) JSON_HEDLEY_DEPRECATED_FOR(ver, func)
#define JSON_DELETE_DEPRECATED_FUNCTIONS_DELETE
#endif


    JSON_DELETE_DEPRECATED_FUNCTIONS_DEPRECATED(3.11.0, to_string())
    operator string_t() const
    JSON_DELETE_DEPRECATED_FUNCTIONS_DELETE()
    {
        return to_string();
    }

Still has the body, which would need guarding as well, but I have to run now.

[nlohmann]

Thanks, good point. I went with a slightly simpler variant in fe5bc3d: no new macros, and each declaration (with its deprecation attribute) appears only once. Only the end of the function is switched:

JSON_HEDLEY_DEPRECATED_FOR(3.11.0, to_string())
operator string_t() const
#if JSON_DELETE_DEPRECATED_FUNCTIONS
    = delete;
#else
{
    return to_string();
}
#endif

Passing the body as a macro argument would have broken bodies with // NOLINTNEXTLINE comments (e.g., sax_parse), and keeping the deprecation attribute on a deleted function is allowed. The unit-delete_deprecated_functions test passes with the macro set to 0 and 1 (clang, GCC 15).

(Written by Claude Code.)

[gregmarr]

I wasn't sure if you'd want to keep the JSON_HEDLEY_DEPRECATED_FOR around for things beyond 4.0.0. Otherwise I'm fine with this.

[nlohmann]

I thought about this as well, and kicked the can down the road. Let's see how much more will add up and decide then.