json/docs/mkdocs/docs/integration/migration_guide.md

# 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::json::with_string_t<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.

## See also

- [`JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md) - remove deprecated functions to check the migration
- [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) - control implicit conversions
- [`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md) - refer to the library namespace without hard-coding it
- [`nlohmann` Namespace](../features/namespace.md) - how the library namespace is structured
- [Converting values](../features/conversions.md) - explicit conversions with get
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions