mirror of https://github.com/nlohmann/json.git synced 2026-10-10 19:05:17 +00:00

Files

Niels Lohmann 23d3b373e1 Add JSON_DELETE_DEPRECATED_FUNCTIONS to delete the deprecated functions (#5755 )

* Add JSON_DELETE_DEPRECATED_FUNCTIONS to delete the deprecated functions

Defining JSON_DELETE_DEPRECATED_FUNCTIONS to 1 (or the CMake option
JSON_DeleteDeprecatedFunctions) declares every deprecated function as
deleted instead of deprecated, so that code that is not ready for 4.0.0
no longer compiles. A deleted function still takes part in overload
resolution, so from_*(ptr, len) cannot silently bind len to the strict
parameter of from_*(InputType&&, bool); the roadmap now plans to keep
these overloads deleted in 4.0.0 instead of removing them.

The legacy discarded-value comparison is left to its own macro.

Also update the 4.0 roadmap: add JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
and JSON_DELETE_DEPRECATED_FUNCTIONS to the macro table, add the
from_bjdata/from_bon8 (ptr, len) overloads to the deprecated functions,
document the macro in the migration guide, and fix the docs style check
findings (example titles, missing docset entry for JSON_STRICT_BINARY_UTF8).

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

* Declare each deprecated function once and guard only its body

Instead of repeating every deprecated declaration in an
#if JSON_DELETE_DEPRECATED_FUNCTIONS branch, keep one declaration
(with its deprecation attribute) and switch only between "= delete;"
and the function body. Suggested by @gregmarr in the review.

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

---------

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

2026-10-04 22:11:34 +02:00

3.8 KiB

Raw Blame History

JSON_DELETE_DEPRECATED_FUNCTIONS

#define JSON_DELETE_DEPRECATED_FUNCTIONS /* value */

When defined to 1, all deprecated functions of the library are declared as deleted (= delete) instead of only being marked as deprecated. Code that still calls one of them no longer compiles. This way, you can find all calls that need to be replaced before version 4.0.0 removes these functions; the migration guide describes how.

A deleted function, unlike a removed one, still takes part in overload resolution. A call that would select it therefore fails to compile instead of silently selecting another overload. This matters for the deprecated from_*(ptr, len) overloads of from_cbor, from_msgpack, from_ubjson, from_bjdata, from_bon8, and from_bson: without them, a call like from_cbor(ptr, len) would compile, read ptr as a NUL-terminated string, and convert len to the strict parameter.

The macro does not affect the deprecated legacy comparison of discarded values, which is controlled by JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON.

Default definition

The default value is 0 (disabled, the deprecated functions can still be called, and the compiler warns about it).

#define JSON_DELETE_DEPRECATED_FUNCTIONS 0

Notes

!!! info "CMake option"

The macro can also be set with the CMake option
[`JSON_DeleteDeprecatedFunctions`](../../integration/cmake.md#json_deletedeprecatedfunctions) (`OFF` by default).

!!! warning "Opt-in only"

This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
effect. Define it for the whole project to avoid different declarations of the same class in different
translation units.

!!! note "ABI compatibility"

The macro only turns calls that compile into calls that do not; it does not change the layout or the behavior of
any type. Its value is therefore not encoded in the [namespace](../../features/namespace.md).

Examples

??? example "Example: default behavior (macro not defined)"

Without the macro, the deprecated overload is called, and the compiler warns about it:

```cpp
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    const std::vector<std::uint8_t> v = {0x82, 0x01, 0x02};
    auto j = json::from_cbor(v.data(), v.size());
    // warning: 'from_cbor' is deprecated: Since 3.8.0; use from_cbor(ptr, ptr + len)
}
```

??? example "Example: deleted deprecated functions (macro defined to 1)"

With the macro, the call does not compile:

```cpp
#define JSON_DELETE_DEPRECATED_FUNCTIONS 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    const std::vector<std::uint8_t> v = {0x82, 0x01, 0x02};
    auto j = json::from_cbor(v.data(), v.size());
    // error: call to deleted function 'from_cbor'
}
```

Version history

Added in version 3.13.0.
Planned to be removed in version 4.0.0, which removes the deprecated functions. The deprecated from_*(ptr, len) overloads stay deleted in version 4.0.0.

3.8 KiB Raw Blame History