integration/migration_guide.md - third_party/json - Git at Google

 # Migration Guide

 This page collects some guidelines on how to future-proof your code for future versions of this library.

 ## Replace deprecated functions

 The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0). 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.

 #### 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})`.

     === "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.

     === "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, `nlohmann::my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>` and 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).

 === "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 `details` namespace

 The `details` 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 `details` namespace.
	# Migration Guide

	This page collects some guidelines on how to future-proof your code for future versions of this library.

	## Replace deprecated functions

	The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0). 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.

	#### 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})`.

	=== "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.

	=== "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, `nlohmann::my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>` and 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).

	=== "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 `details` namespace

	The `details` 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 `details` namespace.