From fb3d9d9b8ff92706bb562dd6319fa04257517317 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sun, 27 Sep 2026 16:51:39 +0200 Subject: [PATCH] List the deprecated functions removed in 4.0 in the roadmap The roadmap lists what will be removed; the migration guide keeps the examples for how to replace each item. Also mention the deprecated (ptr, len) overloads of the from_* functions in the migration guide. Signed-off-by: Niels Lohmann --- docs/mkdocs/docs/community/roadmap.md | 26 +++++++++++++++---- .../docs/integration/migration_guide.md | 12 +++++---- 2 files changed, 28 insertions(+), 10 deletions(-) diff --git a/docs/mkdocs/docs/community/roadmap.md b/docs/mkdocs/docs/community/roadmap.md index c622bbbb6..0a897620a 100644 --- a/docs/mkdocs/docs/community/roadmap.md +++ b/docs/mkdocs/docs/community/roadmap.md @@ -76,9 +76,25 @@ For example, the following makes a 3.x release behave like version 4.0 with resp ``` The macros must be defined before the library header is included; setting them once in the build system is the easiest -way to achieve this. In addition, -version 4.0 will remove all [deprecated functions](../integration/migration_guide.md#replace-deprecated-functions). -Compiling with deprecation warnings enabled shows which of them your code still uses. The -[migration guide](../integration/migration_guide.md) describes how to replace them. +way to achieve this. -New breaking changes will follow the same path: they are added to this table when they land in a 3.x release. +### Removal of deprecated functions + +Version 4.0 will remove all deprecated functions. Compiling with deprecation warnings enabled shows which of them your +code still uses. The [migration guide](../integration/migration_guide.md#replace-deprecated-functions) shows how to +replace each of them. + +| Deprecated | Since | Migration | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------------------------------------------------------------------------------| +| `#!cpp operator<<(basic_json&, std::istream&)` | 3.0.0 | [Parsing](../integration/migration_guide.md#parsing) | +| `#!cpp operator>>(const basic_json&, std::ostream&)` | 3.0.0 | [Miscellaneous functions](../integration/migration_guide.md#miscellaneous-functions) | +| `iterator_wrapper` | 3.1.0 | [Miscellaneous functions](../integration/migration_guide.md#miscellaneous-functions) | +| [`parse`](../api/basic_json/parse.md), [`accept`](../api/basic_json/accept.md), and [`sax_parse`](../api/basic_json/sax_parse.md) with an initializer list `{ptr, len}` or `{first, last}` | 3.8.0 | [Parsing](../integration/migration_guide.md#parsing) | +| [`from_bson`](../api/basic_json/from_bson.md), [`from_cbor`](../api/basic_json/from_cbor.md), [`from_msgpack`](../api/basic_json/from_msgpack.md), and [`from_ubjson`](../api/basic_json/from_ubjson.md) with `(ptr, len)` or an initializer list | 3.8.0 | [Parsing](../integration/migration_guide.md#parsing) | +| [`json_pointer::operator string_t`](../api/json_pointer/operator_string_t.md) | 3.11.0 | [JSON Pointers](../integration/migration_guide.md#json-pointers) | +| [`json_pointer`](../api/json_pointer/index.md) with a `basic_json` type as template argument, and the overloads of `value`, `contains`, `operator[]`, and `at` accepting such a pointer | 3.11.0 | [JSON Pointers](../integration/migration_guide.md#json-pointers) | +| Comparing a [`json_pointer`](../api/json_pointer/index.md) with a string via [`operator==`](../api/json_pointer/operator_eq.md) or [`operator!=`](../api/json_pointer/operator_ne.md) | 3.11.2 | [JSON Pointers](../integration/migration_guide.md#json-pointers) | + +The deprecated legacy comparison of discarded values is controlled by a macro and therefore listed in the table above. + +New breaking changes will follow the same path: they are added to these tables when they land in a 3.x release. diff --git a/docs/mkdocs/docs/integration/migration_guide.md b/docs/mkdocs/docs/integration/migration_guide.md index 22dacf70a..c38d7dea2 100644 --- a/docs/mkdocs/docs/integration/migration_guide.md +++ b/docs/mkdocs/docs/integration/migration_guide.md @@ -1,12 +1,13 @@ # Migration Guide This page collects some guidelines on how to future-proof your code for future versions of this library. -The [roadmap](../community/roadmap.md#trying-out-40-today) lists all macros that let you try the behavior of version -4.0 with a 3.x release. +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). All +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. @@ -36,8 +37,9 @@ function to use instead. [`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})`. + lists is deprecated since 3.8.0. The same holds for passing a pointer and a length as two arguments to the `from_*` + functions. Instead, pass two iterators; for instance, call `from_cbor(ptr, ptr+len)` instead of + `from_cbor({ptr, len})` or `from_cbor(ptr, len)`. === "Deprecated"