• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Migration Guide
2
3This page collects some guidelines on how to future-proof your code for future versions of this library.
4
5## Replace deprecated functions
6
7The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0). All
8deprecations are annotated with
9[`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which
10function to use instead.
11
12#### Parsing
13
14- Function `friend std::istream& operator<<(basic_json&, std::istream&)` is deprecated since 3.0.0. Please use
15  [`friend std::istream&  operator>>(std::istream&, basic_json&)`](../api/operator_gtgt.md) instead.
16
17    === "Deprecated"
18
19        ```cpp
20        nlohmann::json j;
21        std::stringstream ss("[1,2,3]");
22        j << ss;
23        ```
24
25    === "Future-proof"
26
27        ```cpp
28        nlohmann::json j;
29        std::stringstream ss("[1,2,3]");
30        ss >> j;
31        ```
32
33- Passing iterator pairs or pointer/length pairs to parsing functions ([`parse`](../api/basic_json/parse.md),
34  [`accept`](../api/basic_json/accept.md), [`sax_parse`](../api/basic_json/sax_parse.md),
35  [`from_cbor`](../api/basic_json/from_cbor.md), [`from_msgpack`](../api/basic_json/from_msgpack.md),
36  [`from_ubjson`](../api/basic_json/from_ubjson.md), and [`from_bson`](../api/basic_json/from_bson.md) via initializer
37  lists is deprecated since 3.8.0. Instead, pass two iterators; for instance, call `from_cbor(ptr, ptr+len)` instead of
38  `from_cbor({ptr, len})`.
39
40    === "Deprecated"
41
42          ```cpp
43          const char* s = "[1,2,3]";
44          bool ok = nlohmann::json::accept({s, s + std::strlen(s)});
45          ```
46
47    === "Future-proof"
48
49          ```cpp
50          const char* s = "[1,2,3]";
51          bool ok = nlohmann::json::accept(s, s + std::strlen(s));
52          ```
53
54#### JSON Pointers
55
56- Comparing JSON Pointers with strings via [`operator==`](../api/json_pointer/operator_eq.md) and
57  [`operator!=`](../api/json_pointer/operator_ne.md) is deprecated since 3.11.2. To compare a
58  [`json_pointer`](../api/json_pointer/index.md) `p` with a string `s`, convert `s` to a `json_pointer` first and use
59  [`json_pointer::operator==`](../api/json_pointer/operator_eq.md) or
60  [`json_pointer::operator!=`](../api/json_pointer/operator_ne.md).
61
62    === "Deprecated"
63
64        ```cpp
65        nlohmann::json::json_pointer lhs("/foo/bar/1");
66        assert(lhs == "/foo/bar/1");
67        ```
68
69    === "Future-proof"
70
71        ```cpp
72        nlohmann::json::json_pointer lhs("/foo/bar/1");
73        assert(lhs == nlohmann::json::json_pointer("/foo/bar/1"));
74        ```
75
76- The implicit conversion from JSON Pointers to string
77  ([`json_pointer::operator string_t`](../api/json_pointer/operator_string_t.md)) is deprecated since 3.11.0. Use
78  [`json_pointer::to_string`](../api/json_pointer/to_string.md) instead.
79
80    === "Deprecated"
81
82          ```cpp
83          nlohmann::json::json_pointer ptr("/foo/bar/1");
84          std::string s = ptr;
85          ```
86
87    === "Future-proof"
88
89          ```cpp
90          nlohmann::json::json_pointer ptr("/foo/bar/1");
91          std::string s = ptr.to_string();
92          ```
93
94- Passing a `basic_json` specialization as template parameter `RefStringType` to
95  [`json_pointer`](../api/json_pointer/index.md) is deprecated since 3.11.0. The string type can now be directly
96  provided.
97
98    === "Deprecated"
99
100          ```cpp
101          using my_json = nlohmann::basic_json<std::map, std::vector, my_string_type>;
102          nlohmann::json_pointer<my_json> ptr("/foo/bar/1");
103          ```
104
105    === "Future-proof"
106
107          ```cpp
108          nlohmann::json_pointer<my_string_type> ptr("/foo/bar/1");
109          ```
110
111    Thereby, `nlohmann::my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>` and is always an
112    alias to the `json_pointer` with the appropriate string type for all specializations of `basic_json`.
113
114#### Miscellaneous functions
115
116- The function `iterator_wrapper` is deprecated since 3.1.0. Please use the member function
117  [`items`](../api/basic_json/items.md) instead.
118
119    === "Deprecated"
120
121          ```cpp
122          for (auto &x : nlohmann::json::iterator_wrapper(j))
123          {
124              std::cout << x.key() << ":" << x.value() << std::endl;
125          }
126          ```
127
128    === "Future-proof"
129
130          ```cpp
131          for (auto &x : j.items())
132          {
133              std::cout << x.key() << ":" << x.value() << std::endl;
134          }
135          ```
136
137- Function `friend std::ostream& operator>>(const basic_json&, std::ostream&)` is deprecated since 3.0.0. Please use
138  [`friend operator<<(std::ostream&, const basic_json&)`](../api/operator_ltlt.md) instead.
139
140    === "Deprecated"
141
142          ```cpp
143          j >> std::cout;
144          ```
145
146    === "Future-proof"
147
148          ```cpp
149          std::cout << j;
150          ```
151
152- The legacy comparison behavior for discarded values is deprecated since 3.11.0. It is already disabled by default and
153  can still be enabled by defining
154  [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md) to `1`.
155
156    === "Deprecated"
157
158          ```cpp
159          #define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 1
160          #include <nlohmann/json.hpp>
161          ```
162
163    === "Future-proof"
164
165          ```cpp
166          #include <nlohmann/json.hpp>
167          ```
168
169## Replace implicit conversions
170
171Implicit conversions via [`operator ValueType`](../api/basic_json/operator_ValueType.md) will be switched off by default
172in the next major release of the library.
173
174You can prepare existing code by already defining
175[`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) to `0` and replace any implicit
176conversions with calls to [`get`](../api/basic_json/get.md), [`get_to`](../api/basic_json/get_to.md),
177[`get_ref`](../api/basic_json/get_ref.md), or [`get_ptr`](../api/basic_json/get_ptr.md).
178
179=== "Deprecated"
180
181      ```cpp
182      nlohmann::json j = "Hello, world!";
183      std::string s = j;
184      ```
185
186=== "Future-proof"
187
188      ```cpp
189      nlohmann::json j = "Hello, world!";
190      auto s = j.template get<std::string>();
191      ```
192
193=== "Future-proof (alternative)"
194
195      ```cpp
196      nlohmann::json j = "Hello, world!";
197      std::string s;
198      j.get_to(s);
199      ```
200
201You can prepare existing code by already defining
202[`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) to `0` and replace any implicit
203conversions with calls to [`get`](../api/basic_json/get.md).
204
205## Import namespace `literals` for UDLs
206
207The user-defined string literals [`operator""_json`](../api/operator_literal_json.md) and
208[`operator""_json_pointer`](../api/operator_literal_json_pointer.md) will be removed from the global namespace in the
209next major release of the library.
210
211=== "Deprecated"
212
213      ```cpp
214      nlohmann::json j = "[1,2,3]"_json;
215      ```
216
217=== "Future-proof"
218
219      ```cpp
220      using namespace nlohmann::literals;
221      nlohmann::json j = "[1,2,3]"_json;
222      ```
223
224To prepare existing code, define [`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md) to `0` and bring the
225string literals into scope where needed.
226
227## Do not hard-code the complete library namespace
228
229The [`nlohmann` namespace](../features/namespace.md) contains a sub-namespace to avoid problems when different
230versions or configurations of the library are used in the same project. Always use `nlohmann` as namespace or, when the
231exact version and configuration is relevant, use macro
232[`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md) to denote the namespace.
233
234=== "Dangerous"
235
236      ```cpp
237      void to_json(nlohmann::json_abi_v3_11_2::json& j, const person& p)
238      {
239          j["age"] = p.age;
240      }
241      ```
242
243=== "Future-proof"
244
245      ```cpp
246      void to_json(nlohmann::json& j, const person& p)
247      {
248          j["age"] = p.age;
249      }
250      ```
251
252=== "Future-proof (alternative)"
253
254      ```cpp
255      void to_json(NLOHMANN_JSON_NAMESPACE::json& j, const person& p)
256      {
257          j["age"] = p.age;
258      }
259      ```
260
261## Do not use the `details` namespace
262
263The `details` namespace is not part of the public API of the library and can change in any version without announcement.
264Do not rely on any function or type in the `details` namespace.
265