diff --git a/doc/mkdocs/docs/api/basic_json/meta.md b/doc/mkdocs/docs/api/basic_json/meta.md index e2b312e0c..87767e4d5 100644 --- a/doc/mkdocs/docs/api/basic_json/meta.md +++ b/doc/mkdocs/docs/api/basic_json/meta.md @@ -45,6 +45,10 @@ Constant. --8<-- "examples/meta.output" ``` +## See also + +- [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md) - library version information + ## Version history - Added in version 2.1.0. diff --git a/doc/mkdocs/docs/api/macros/index.md b/doc/mkdocs/docs/api/macros/index.md index c2f91da18..585a88164 100644 --- a/doc/mkdocs/docs/api/macros/index.md +++ b/doc/mkdocs/docs/api/macros/index.md @@ -21,19 +21,22 @@ header. ## Language support -- `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20` -- [**JSON_HAS_FILESYSTEM**/**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support -- `JSON_NO_IO` +- [**JSON_HAS_CPP_11**
**JSON_HAS_CPP_14**
**JSON_HAS_CPP_17**
**JSON_HAS_CPP_20**](json_has_cpp_11.md) - set supported C++ standard +- [**JSON_HAS_FILESYSTEM**
**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support +- [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers -- `JSON_SKIP_LIBRARY_VERSION_CHECK` + +## Library version + +- [**JSON_SKIP_LIBRARY_VERSION_CHECK**](json_skip_library_version_check.md) - skip library version check +- [**NLOHMANN_JSON_VERSION_MAJOR**
**NLOHMANN_JSON_VERSION_MINOR**
**NLOHMANN_JSON_VERSION_PATCH**](nlohmann_json_version_major.md) - library version information ## Type conversions -- `JSON_USE_IMPLICIT_CONVERSIONS` +- [**JSON_USE_IMPLICIT_CONVERSIONS**](json_use_implicit_conversions.md) - control implicit conversions ## Serialization/deserialization macros - `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)` - `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)` - `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)` -- `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH` diff --git a/doc/mkdocs/docs/api/macros/json_assert.md b/doc/mkdocs/docs/api/macros/json_assert.md index abb890d63..45c99bc3f 100644 --- a/doc/mkdocs/docs/api/macros/json_assert.md +++ b/doc/mkdocs/docs/api/macros/json_assert.md @@ -4,7 +4,8 @@ #define JSON_ASSERT(x) /* value */ ``` -This macro controls which code is executed for [runtime assertions](../../features/assertions.md) of the libraries. +This macro controls which code is executed for [runtime assertions](../../features/assertions.md) of the libraries. It +is set by the library, but can be overridden by defining it before including the library. ## Parameters diff --git a/doc/mkdocs/docs/api/macros/json_has_cpp_11.md b/doc/mkdocs/docs/api/macros/json_has_cpp_11.md new file mode 100644 index 000000000..ddb813132 --- /dev/null +++ b/doc/mkdocs/docs/api/macros/json_has_cpp_11.md @@ -0,0 +1,28 @@ +# JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20 + +```cpp +#define JSON_HAS_CPP_11 +#define JSON_HAS_CPP_14 +#define JSON_HAS_CPP_17 +#define JSON_HAS_CPP_20 +``` + +The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view` +support for C++17). For these new features, the library implements some preprocessor checks to determine the C++ +standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is +unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be +detected incorrectly. + +## Default definition + +The default value is detected based on the preprocessor macros `#!cpp __cplusplus`, `#!cpp _HAS_CXX17`, or +`#!cpp _MSVC_LANG`. + +## Notes + +- `#!cpp JSON_HAS_CPP_11` is always defined. +- All macros are undefined outside the library. + +## Version history + +- Added in version 3.10.5. diff --git a/doc/mkdocs/docs/api/macros/json_no_io.md b/doc/mkdocs/docs/api/macros/json_no_io.md new file mode 100644 index 000000000..52baefc66 --- /dev/null +++ b/doc/mkdocs/docs/api/macros/json_no_io.md @@ -0,0 +1,21 @@ +# JSON_NO_IO + +```cpp +#define JSON_NO_IO +``` + +When defined, headers ``, ``, ``, ``, and `` are not included and parse functions +relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for +security reasons (e.g., Intel Software Guard Extensions (SGX)). + +## Default definition + +By default, `#!cpp JSON_NO_IO` is not defined. + +```cpp +#undef JSON_NO_IO +``` + +## Version history + +- Added in version 3.10.0. diff --git a/doc/mkdocs/docs/api/macros/json_skip_library_version_check.md b/doc/mkdocs/docs/api/macros/json_skip_library_version_check.md new file mode 100644 index 000000000..e2b3a0097 --- /dev/null +++ b/doc/mkdocs/docs/api/macros/json_skip_library_version_check.md @@ -0,0 +1,20 @@ +# JSON_SKIP_LIBRARY_VERSION_CHECK + +```cpp +#define JSON_SKIP_LIBRARY_VERSION_CHECK +``` + +When defined, the library will not create a compiler warning when a different version of the library was already +included. + +## Default definition + +By default, the macro is not defined. + +```cpp +#undef JSON_SKIP_LIBRARY_VERSION_CHECK +``` + +## Version history + +Added in version 3.11.0. diff --git a/doc/mkdocs/docs/api/macros/json_skip_unsupported_compiler_check.md b/doc/mkdocs/docs/api/macros/json_skip_unsupported_compiler_check.md index 604e0913b..c58d0ea85 100644 --- a/doc/mkdocs/docs/api/macros/json_skip_unsupported_compiler_check.md +++ b/doc/mkdocs/docs/api/macros/json_skip_unsupported_compiler_check.md @@ -1,7 +1,7 @@ # JSON_SKIP_UNSUPPORTED_COMPILER_CHECK ```cpp -#undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK +#define 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 diff --git a/doc/mkdocs/docs/api/macros/json_use_implicit_conversions.md b/doc/mkdocs/docs/api/macros/json_use_implicit_conversions.md new file mode 100644 index 000000000..833ad424c --- /dev/null +++ b/doc/mkdocs/docs/api/macros/json_use_implicit_conversions.md @@ -0,0 +1,41 @@ +# JSON_USE_IMPLICIT_CONVERSIONS + +```cpp +#define JSON_USE_IMPLICIT_CONVERSIONS /* value */ +``` + +When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. + +Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which +sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. + +## Default definition + +By default, implicit conversions are enabled + +```cpp +#define JSON_USE_IMPLICIT_CONVERSIONS 1 +``` + +## Examples + +??? example + + This is an example for an implicit conversion: + + ```cpp + json j = "Hello, world!"; + std::string s = j; + ``` + + When `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`, the code above does no longer compile. Instead, it must be + written like this: + + ```cpp + json j = "Hello, world!"; + auto s = j.get(); + ``` + +## Version history + +- Added in version 3.9.0. diff --git a/doc/mkdocs/docs/api/macros/nlohmann_json_version_major.md b/doc/mkdocs/docs/api/macros/nlohmann_json_version_major.md new file mode 100644 index 000000000..826785292 --- /dev/null +++ b/doc/mkdocs/docs/api/macros/nlohmann_json_version_major.md @@ -0,0 +1,23 @@ +# NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH + +```cpp +#define NLOHMANN_JSON_VERSION_MAJOR /* value */ +#define NLOHMANN_JSON_VERSION_MINOR /* value */ +#define NLOHMANN_JSON_VERSION_PATCH /* value */ +``` + +These macros are defined by the library and contain the version numbers according to +[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). + +## Default definition + +The macros are defined according to the current library version. + +## See also + +- [meta](../basic_json/meta.md) - returns version information on the library +- [JSON_SKIP_LIBRARY_VERSION_CHECK](json_skip_library_version_check.md) - skip library version check + +## Version history + +- Added in version 3.1.0. diff --git a/doc/mkdocs/docs/features/macros.md b/doc/mkdocs/docs/features/macros.md index aefa54664..0fcae96d9 100644 --- a/doc/mkdocs/docs/features/macros.md +++ b/doc/mkdocs/docs/features/macros.md @@ -57,12 +57,7 @@ standard. By defining any of these symbols, the internal check is overridden and unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be detected incorrectly. -!!! info "Default behavior" - - 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. +See [full documentation of `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, and `JSON_HAS_CPP_20`](../api/macros/json_has_cpp_11.md). ## `JSON_HAS_FILESYSTEM`, `JSON_HAS_EXPERIMENTAL_FILESYSTEM` @@ -100,30 +95,14 @@ When defined, headers ``, ``, ``, ``, and `(); - ``` - -Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which -sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. - -!!! info "Default behavior" - - ```cpp - #define JSON_USE_IMPLICIT_CONVERSIONS 1 - ``` - -The macro was introduced in version 3.9.0. +See [full documentation of `JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md). ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)` @@ -269,6 +222,6 @@ 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). +[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). -The macros were introduced in version 3.1.0. +See [full documentation of `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, and `NLOHMANN_JSON_VERSION_PATCH`](../api/macros/nlohmann_json_version_major.md). diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index c500aa8ae..cc8dd5e85 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -236,8 +236,18 @@ nav: - 'JSON_ASSERT(x)': api/macros/json_assert.md - 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md + - 'JSON_HAS_CPP_11': api/macros/json_has_cpp_11.md + - 'JSON_HAS_CPP_14': api/macros/json_has_cpp_11.md + - 'JSON_HAS_CPP_17': api/macros/json_has_cpp_11.md + - 'JSON_HAS_CPP_20': api/macros/json_has_cpp_11.md - 'JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md + - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md + - 'JSON_NO_IO': api/macros/json_no_io.md + - 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md - 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md + - 'NLOHMANN_JSON_VERSION_MAJOR': api/macros/nlohmann_json_version_major.md + - 'NLOHMANN_JSON_VERSION_MINOR': api/macros/nlohmann_json_version_major.md + - 'NLOHMANN_JSON_VERSION_PATCH': api/macros/nlohmann_json_version_major.md # Extras extra: