From 10344907ffa10189c52a7ddc8e1dab13c886686a Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 9 Apr 2022 18:09:23 +0200 Subject: [PATCH] :memo: document which version introduced the macros #3429 (#3431) --- doc/mkdocs/docs/api/macros/index.md | 4 +++ doc/mkdocs/docs/features/macros.md | 46 +++++++++++++++++++++++++++-- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/doc/mkdocs/docs/api/macros/index.md b/doc/mkdocs/docs/api/macros/index.md index 9c390d55e..4c723c6a6 100644 --- a/doc/mkdocs/docs/api/macros/index.md +++ b/doc/mkdocs/docs/api/macros/index.md @@ -1,5 +1,9 @@ # Macros +!!! note + + This page is under construction. See the [macro overview page](../../features/macros.md) until then. + Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header. - [`JSON_ASSERT(x)`](json_assert.md) diff --git a/doc/mkdocs/docs/features/macros.md b/doc/mkdocs/docs/features/macros.md index dabb29917..576ec935d 100644 --- a/doc/mkdocs/docs/features/macros.md +++ b/doc/mkdocs/docs/features/macros.md @@ -14,6 +14,8 @@ This macro controls which code is executed for runtime assertions of the librari #define JSON_ASSERT(x) assert(x) ``` +The macro was introduced in version 3.9.0. + ## `JSON_CATCH_USER(exception)` This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library. @@ -39,6 +41,8 @@ See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an #define JSON_CATCH_USER(exception) if (false) ``` +The macro was introduced in version 3.1.0. + ## `JSON_DIAGNOSTICS` This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable @@ -63,6 +67,8 @@ The diagnostics messages can also be controlled with the CMake option `JSON_Diag #define JSON_DIAGNOSTICS 0 ``` +The macro was introduced in version 3.10.0. + ## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20` The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view` @@ -76,6 +82,8 @@ detected incorrectly. The default value is detected based on the preprocessor macros `#!cpp __cplusplus`, `#!cpp _HAS_CXX17`, or `#!cpp _MSVC_LANG`. +The macros were introduced in version 3.10.5. + ## `JSON_HAS_FILESYSTEM`, `JSON_HAS_EXPERIMENTAL_FILESYSTEM` When compiling with C++17, the library provides conversions from and to `std::filesystem::path`. As compiler support @@ -92,6 +100,8 @@ To override the built-in check, define `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERI Note that older compilers or older versions of libstd++ also require the library `stdc++fs` to be linked to for filesystem support. +The macros were introduced in version 3.10.5. + ## `JSON_NOEXCEPTION` Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try` @@ -111,6 +121,8 @@ The same effect is achieved by setting the compiler flag `-fno-exceptions`. Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824). +The macro was introduced in version 2.1.0. + ## `JSON_NO_IO` When defined, headers ``, ``, ``, ``, and `` are not included and parse functions @@ -125,6 +137,8 @@ security reasons (e.g., Intel Software Guard Extensions (SGX)). #undef JSON_NO_IO ``` +The macro was introduced in version 3.10.0. + ## `JSON_SKIP_LIBRARY_VERSION_CHECK` When defined, the library will not create a compiler warning when a different version of the library was already @@ -138,6 +152,8 @@ included. #undef JSON_SKIP_LIBRARY_VERSION_CHECK ``` +The macro was introduced in version 3.11.0. + ## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK` When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to @@ -151,6 +167,8 @@ use the library with compilers that do not fully support C++11 and may only work #undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK ``` +The macro was introduced in version 3.2.0. + ## `JSON_THROW_USER(exception)` This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that @@ -176,6 +194,8 @@ undefined behavior. See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. +The macro was introduced in version 3.1.0. + ## `JSON_TRY_USER` This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope. @@ -198,6 +218,8 @@ This macro overrides `#!cpp try` calls inside the library. It has no arguments a See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. +The macro was introduced in version 3.1.0. + ## `JSON_USE_IMPLICIT_CONVERSIONS` When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. @@ -228,6 +250,8 @@ sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. #define JSON_USE_IMPLICIT_CONVERSIONS 1 ``` +The macro was introduced in version 3.9.0. + ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)` This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as @@ -239,9 +263,16 @@ The first parameter is the name of the class/struct, and all remaining parameter See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. +The macro was introduced in version 3.9.0. + ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)` -This macro is similar to `NLOHMANN_DEFINE_TYPE_INTRUSIVE`. It will not throw an exception in `from_json()` due to a missing value in the JSON object, but can throw due to a mismatched type. In order to support that it requires that the type be default constructible. The `from_json()` function default constructs an object and uses its values as the defaults when calling the `value()` function. +This macro is similar to `NLOHMANN_DEFINE_TYPE_INTRUSIVE`. It will not throw an exception in `from_json()` due to a +missing value in the JSON object, but can throw due to a mismatched type. In order to support that it requires that the +type be default constructible. The `from_json()` function default constructs an object and uses its values as the +defaults when calling the `value()` function. + +The macro was introduced in version 3.11.0. ## `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)` @@ -254,16 +285,27 @@ first parameter is the name of the class/struct, and all remaining parameters na See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. +The macro was introduced in version 3.9.0. + ## `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)` -This macro is similar to `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`. It will not throw an exception in `from_json()` due to a missing value in the JSON object, but can throw due to a mismatched type. In order to support that it requires that the type be default constructible. The `from_json()` function default constructs an object and uses its values as the defaults when calling the `value()` function. +This macro is similar to `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`. It will not throw an exception in `from_json()` due to a +missing value in the JSON object, but can throw due to a mismatched type. In order to support that it requires that the +type be default constructible. The `from_json()` function default constructs an object and uses its values as the +defaults when calling the `value()` function. + +The macro was introduced in version 3.11.0. ## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)` This macro simplifies the serialization/deserialization of enum types. See [Specializing enum conversion](enum_conversion.md) for more information. +The macro was introduced in version 3.4.0. + ## `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH` These macros are defined by the library and contain the version numbers according to [Semantic Versioning 2.0.0](https://semver.org). + +The macros were introduced in version 3.1.0.