mirror of
https://github.com/nlohmann/json.git
synced 2026-10-06 14:40:32 +00:00
286 lines
10 KiB
Markdown
286 lines
10 KiB
Markdown
# Migration Guide
|
|
|
|
This page collects some guidelines on how to future-proof your code for future versions of this library. For how to
|
|
add the library to your project in the first place, see [Integration](index.md), [CMake](cmake.md), or
|
|
[Package Managers](package_managers.md). The [roadmap](../community/roadmap.md#version-40) lists what will change in
|
|
version 4.0, including the macros that let you try its behavior with a 3.x release; this page describes how to adjust
|
|
your code.
|
|
|
|
## Replace deprecated functions
|
|
|
|
The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0), see the
|
|
[roadmap](../community/roadmap.md#removal-of-deprecated-functions) for an overview. All
|
|
deprecations are annotated with
|
|
[`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which
|
|
function to use instead.
|
|
|
|
!!! tip "Find all calls of deprecated functions"
|
|
|
|
Define [`JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md) to `1` (or set the
|
|
CMake option [`JSON_DeleteDeprecatedFunctions`](cmake.md#json_deletedeprecatedfunctions)) to delete all deprecated
|
|
functions. Every remaining call then fails to compile, even if deprecation warnings are disabled, so your code is
|
|
ready for version 4.0.0 once it compiles with the macro.
|
|
|
|
### Parsing
|
|
|
|
- Function `friend std::istream& operator<<(basic_json&, std::istream&)` is deprecated since 3.0.0. Please use
|
|
[`friend std::istream& operator>>(std::istream&, basic_json&)`](../api/operator_gtgt.md) instead.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
nlohmann::json j;
|
|
std::stringstream ss("[1,2,3]");
|
|
j << ss;
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
nlohmann::json j;
|
|
std::stringstream ss("[1,2,3]");
|
|
ss >> j;
|
|
```
|
|
|
|
- Passing iterator pairs or pointer/length pairs to parsing functions ([`parse`](../api/basic_json/parse.md),
|
|
[`accept`](../api/basic_json/accept.md), [`sax_parse`](../api/basic_json/sax_parse.md),
|
|
[`from_cbor`](../api/basic_json/from_cbor.md), [`from_msgpack`](../api/basic_json/from_msgpack.md),
|
|
[`from_ubjson`](../api/basic_json/from_ubjson.md), and [`from_bson`](../api/basic_json/from_bson.md)) via initializer
|
|
lists is deprecated since 3.8.0. Instead, pass two iterators; for instance, call `from_cbor(ptr, ptr+len)` instead of
|
|
`from_cbor({ptr, len})`. Likewise, passing a pointer and a length as two separate arguments to `from_cbor`,
|
|
`from_msgpack`, `from_ubjson`, and `from_bson` is deprecated since 3.8.0, and to
|
|
[`from_bjdata`](../api/basic_json/from_bjdata.md) and [`from_bon8`](../api/basic_json/from_bon8.md) since 3.13.0; call
|
|
`from_cbor(ptr, ptr+len)` instead of `from_cbor(ptr, len)`. These overloads will not be removed in version 4.0.0, but
|
|
deleted, so a call like `from_cbor(ptr, len)` cannot compile and convert `len` to the `strict` parameter.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
const char* s = "[1,2,3]";
|
|
bool ok = nlohmann::json::accept({s, s + std::strlen(s)});
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
const char* s = "[1,2,3]";
|
|
bool ok = nlohmann::json::accept(s, s + std::strlen(s));
|
|
```
|
|
|
|
### JSON Pointers
|
|
|
|
- Comparing JSON Pointers with strings via [`operator==`](../api/json_pointer/operator_eq.md) and
|
|
[`operator!=`](../api/json_pointer/operator_ne.md) is deprecated since 3.11.2. To compare a
|
|
[`json_pointer`](../api/json_pointer/index.md) `p` with a string `s`, convert `s` to a `json_pointer` first and use
|
|
[`json_pointer::operator==`](../api/json_pointer/operator_eq.md) or
|
|
[`json_pointer::operator!=`](../api/json_pointer/operator_ne.md).
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
nlohmann::json::json_pointer lhs("/foo/bar/1");
|
|
assert(lhs == "/foo/bar/1");
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
nlohmann::json::json_pointer lhs("/foo/bar/1");
|
|
assert(lhs == nlohmann::json::json_pointer("/foo/bar/1"));
|
|
```
|
|
|
|
- The implicit conversion from JSON Pointers to string
|
|
([`json_pointer::operator string_t`](../api/json_pointer/operator_string_t.md)) is deprecated since 3.11.0. Use
|
|
[`json_pointer::to_string`](../api/json_pointer/to_string.md) instead.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
nlohmann::json::json_pointer ptr("/foo/bar/1");
|
|
std::string s = ptr;
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
nlohmann::json::json_pointer ptr("/foo/bar/1");
|
|
std::string s = ptr.to_string();
|
|
```
|
|
|
|
- Passing a `basic_json` specialization as template parameter `RefStringType` to
|
|
[`json_pointer`](../api/json_pointer/index.md) is deprecated since 3.11.0. The string type can now be directly
|
|
provided. This also applies to passing such a JSON pointer to [`at`](../api/basic_json/at.md),
|
|
[`contains`](../api/basic_json/contains.md), [`operator[]`](../api/basic_json/operator%5B%5D.md), and
|
|
[`value`](../api/basic_json/value.md).
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
using my_json = nlohmann::basic_json<std::map, std::vector, my_string_type>;
|
|
nlohmann::json_pointer<my_json> ptr("/foo/bar/1");
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
nlohmann::json_pointer<my_string_type> ptr("/foo/bar/1");
|
|
```
|
|
|
|
Thereby, `my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>`; in general,
|
|
`basic_json::json_pointer` is always an alias to the `json_pointer` with the appropriate string type for all
|
|
specializations of `basic_json`.
|
|
|
|
### Miscellaneous functions
|
|
|
|
- The function `iterator_wrapper` is deprecated since 3.1.0. Please use the member function
|
|
[`items`](../api/basic_json/items.md) instead.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
for (auto &x : nlohmann::json::iterator_wrapper(j))
|
|
{
|
|
std::cout << x.key() << ":" << x.value() << std::endl;
|
|
}
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
for (auto &x : j.items())
|
|
{
|
|
std::cout << x.key() << ":" << x.value() << std::endl;
|
|
}
|
|
```
|
|
|
|
- Function `friend std::ostream& operator>>(const basic_json&, std::ostream&)` is deprecated since 3.0.0. Please use
|
|
[`friend operator<<(std::ostream&, const basic_json&)`](../api/operator_ltlt.md) instead.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
j >> std::cout;
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
std::cout << j;
|
|
```
|
|
|
|
- The legacy comparison behavior for discarded values is deprecated since 3.11.0. It is already disabled by default and
|
|
can still be enabled by defining
|
|
[`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md) to `1`.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 1
|
|
#include <nlohmann/json.hpp>
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
#include <nlohmann/json.hpp>
|
|
```
|
|
|
|
## Replace implicit conversions
|
|
|
|
Implicit conversions via [`operator ValueType`](../api/basic_json/operator_ValueType.md) will be switched off by default
|
|
in the next major release of the library.
|
|
|
|
You can prepare existing code by already defining
|
|
[`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) to `0` and replace any implicit
|
|
conversions with calls to [`get`](../api/basic_json/get.md), [`get_to`](../api/basic_json/get_to.md),
|
|
[`get_ref`](../api/basic_json/get_ref.md), or [`get_ptr`](../api/basic_json/get_ptr.md).
|
|
|
|
!!! tip "Automatic migration"
|
|
|
|
The community-maintained clang-tidy check `modernize-nlohmann-json-explicit-conversions` rewrites most implicit
|
|
conversions into calls to [`get`](../api/basic_json/get.md). It is not part of clang-tidy itself; see
|
|
[discussion #4610](https://github.com/nlohmann/json/discussions/4610) for how to build and use it.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
nlohmann::json j = "Hello, world!";
|
|
std::string s = j;
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
nlohmann::json j = "Hello, world!";
|
|
auto s = j.get<std::string>();
|
|
```
|
|
|
|
=== "Future-proof (alternative)"
|
|
|
|
```cpp
|
|
nlohmann::json j = "Hello, world!";
|
|
std::string s;
|
|
j.get_to(s);
|
|
```
|
|
|
|
## Import namespace `literals` for UDLs
|
|
|
|
The user-defined string literals [`operator""_json`](../api/operator_literal_json.md) and
|
|
[`operator""_json_pointer`](../api/operator_literal_json_pointer.md) will be removed from the global namespace in the
|
|
next major release of the library.
|
|
|
|
=== "Deprecated"
|
|
|
|
```cpp
|
|
nlohmann::json j = "[1,2,3]"_json;
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
using namespace nlohmann::literals;
|
|
nlohmann::json j = "[1,2,3]"_json;
|
|
```
|
|
|
|
To prepare existing code, define [`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md) to `0` and bring the
|
|
string literals into scope where needed.
|
|
|
|
## Do not hard-code the complete library namespace
|
|
|
|
The [`nlohmann` namespace](../features/namespace.md) contains a sub-namespace to avoid problems when different
|
|
versions or configurations of the library are used in the same project. Always use `nlohmann` as namespace or, when the
|
|
exact version and configuration is relevant, use macro
|
|
[`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md) to denote the namespace.
|
|
|
|
=== "Dangerous"
|
|
|
|
```cpp
|
|
void to_json(nlohmann::json_abi_v3_11_2::json& j, const person& p)
|
|
{
|
|
j["age"] = p.age;
|
|
}
|
|
```
|
|
|
|
=== "Future-proof"
|
|
|
|
```cpp
|
|
void to_json(nlohmann::json& j, const person& p)
|
|
{
|
|
j["age"] = p.age;
|
|
}
|
|
```
|
|
|
|
=== "Future-proof (alternative)"
|
|
|
|
```cpp
|
|
void to_json(NLOHMANN_JSON_NAMESPACE::json& j, const person& p)
|
|
{
|
|
j["age"] = p.age;
|
|
}
|
|
```
|
|
|
|
## Do not use the `detail` namespace
|
|
|
|
The `nlohmann::detail` namespace is not part of the public API of the library and can change in any version without
|
|
an announcement. Do not rely on any function or type in the `detail` namespace.
|