amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-09-04 07:25:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

More documentation updates for 3.11.0 (#3553)

Browse Source 
* mkdocs: add string_view examples

* mkdocs: reference underlying operators

* mkdocs: add operator<=> examples

* mkdocs: fix style check issues

* mkdocs: tweak BJData page

* mkdocs: add CMake option hints to macros

* mkdocs: fix JSON_DISABLE_ENUM_SERIALIZATION definition

* mkdocs: fix link to unit-udt.cpp

* mkdocs: fix "Arbitrary Type Conversions" title

* mkdocs: link to api/macros/*.md instead of features/macros.md

* mkdocs: document JSON_DisableEnumSerialization CMake option

* mkdocs: encode required C++ standard in example files

* docset: detect gsed/sed

* docset: update index

* docset: fix CSS patching

* docset: add list_missing_pages make target

* docset: add list_removed_paths make target

* docset: replace page titles with name from index

* docset: add install target for Zeal docset browser

* Use GCC_TOOL in ci_test_documentation target
This commit is contained in:
Florian Albrechtskirchinger
2022-07-31 14:05:58 +02:00
committed by GitHub
parent 11ba5c1120
commit d3e347bd2d
84 changed files with 1024 additions and 259 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mkdocs/docs/api/macros/index.md
+10 -5
View File
@@ -25,7 +25,8 @@ header. See also the [macro overview page](../../features/macros.md).
## Library version
- [**JSON_SKIP_LIBRARY_VERSION_CHECK**](json_skip_library_version_check.md) - skip library version check
- [**NLOHMANN_JSON_VERSION_MAJOR**<br>**NLOHMANN_JSON_VERSION_MINOR**<br>**NLOHMANN_JSON_VERSION_PATCH**](nlohmann_json_version_major.md) - library version information
- [**NLOHMANN_JSON_VERSION_MAJOR**<br>**NLOHMANN_JSON_VERSION_MINOR**<br>**NLOHMANN_JSON_VERSION_PATCH**](nlohmann_json_version_major.md)
\- library version information
## Library namespace
@@ -45,7 +46,11 @@ header. See also the [macro overview page](../../features/macros.md).
## Serialization/deserialization macros
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_intrusive.md) - serialization/deserialization of types _with_ access to private variables
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_non_intrusive.md) - serialization/deserialization of types _without_ access to private variables
- [**NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)**](nlohmann_json_serialize_enum.md) - serialization/deserialization of enum
types
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**][DefInt]
\- serialization/deserialization of types _with_ access to private variables
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)**][DefNonInt]
\- serialization/deserialization of types _without_ access to private variables
- [**NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)**](nlohmann_json_serialize_enum.md) - serialization/deserialization of enum types
[DefInt]: nlohmann_define_type_intrusive.md
[DefNonInt]: nlohmann_define_type_non_intrusive.md
docs/mkdocs/docs/api/macros/json_diagnostics.md
+6 -3
View File
@@ -11,9 +11,6 @@ When enabled, exception messages contain a [JSON Pointer](../json_pointer/json_p
triggered the exception. Note that enabling this macro increases the size of every JSON value by one pointer and adds
some runtime overhead.
The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
`JSON_DIAGNOSTICS` accordingly.
## Default definition
The default value is `0` (extended diagnostics are switched off).
@@ -37,6 +34,12 @@ When the macro is not defined, the library will define it to its default value.
Where possible, it is still recommended that all code define this the same way for maximum interoperability.
!!! hint "CMake option"
Diagnostic messages can also be controlled with the CMake option
[`JSON_Diagnostics`](../../integration/cmake.md#json_diagnostics) (`OFF` by default)
which defines `JSON_DIAGNOSTICS` accordingly.
## Examples
??? example "Example 1: default behavior"
docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md
+20 -7
View File
@@ -1,10 +1,12 @@
# JSON_DISABLE_ENUM_SERIALIZATION
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION
#define JSON_DISABLE_ENUM_SERIALIZATION /* value */
```
When defined, default serialization and deserialization functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see [arbitrary type conversions](../../features/arbitrary_types.md) for more details).
When defined to `1`, default serialization and deserialization functions for enums are excluded and have to be provided
by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see
[arbitrary type conversions](../../features/arbitrary_types.md) for more details).
Parsing or serializing an enum will result in a compiler error.
@@ -12,17 +14,26 @@ This works for both unscoped and scoped enums.
## Default definition
By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
The default value is `0`.
```cpp
#undef JSON_DISABLE_ENUM_SERIALIZATION
#define JSON_DISABLE_ENUM_SERIALIZATION 0
```
## Notes
!!! hint "CMake option"
Enum serialization can also be controlled with the CMake option
[`JSON_DisableEnumSerialization`](../../integration/cmake.md#json_disableenumserialization)
(`OFF` by default) which defines `JSON_DISABLE_ENUM_SERIALIZATION` accordingly.
## Examples
??? example "Example 1: Disabled behavior"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below **does not** compile.
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below
**does not** compile.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
@@ -48,7 +59,8 @@ By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
??? example "Example 2: Serialize enum macro"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses
[`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
@@ -80,7 +92,8 @@ By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
??? example "Example 3: User-defined serialization/deserialization functions"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined functions to parse and serialize the enum.
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined
functions to parse and serialize the enum.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
docs/mkdocs/docs/api/macros/json_has_ranges.md
+13
View File
@@ -13,6 +13,19 @@ The default value is detected based on the preprocessor macro `#!cpp __cpp_lib_r
When the macro is not defined, the library will define it to its default value.
## Examples
??? example
The code below forces the library to enable support for ranges:
```cpp
#define JSON_HAS_RANGES 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.11.0.
docs/mkdocs/docs/api/macros/json_has_three_way_comparison.md
+13
View File
@@ -14,6 +14,19 @@ and `#!cpp __cpp_lib_three_way_comparison`.
When the macro is not defined, the library will define it to its default value.
## Examples
??? example
The code below forces the library to use 3-way comparison:
```cpp
#define JSON_HAS_THREE_WAY_COMPARISON 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.11.0.
docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md
+6 -3
View File
@@ -7,9 +7,6 @@
When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The
value directly affects [`operator ValueType`](../basic_json/operator_ValueType.md).
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.
@@ -27,6 +24,12 @@ By default, implicit conversions are enabled.
You can prepare existing code by already defining `JSON_USE_IMPLICIT_CONVERSIONS` to `0` and replace any implicit
conversions with calls to [`get`](../basic_json/get.md).
!!! hint "CMake option"
Implicit conversions can also be controlled with the CMake option
[`JSON_ImplicitConversions`](../../integration/cmake.md#json_legacydiscardedvaluecomparison)
(`ON` by default) which defines `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
## Examples
??? example
docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md
+19
View File
@@ -56,6 +56,25 @@ When the macro is not defined, the library will define it to its default value.
New code should not depend on it and existing code should try to remove or rewrite
expressions relying on it.
!!! hint "CMake option"
Legacy comparison can also be controlled with the CMake option
[`JSON_LegacyDiscardedValueComparison`](../../integration/cmake.md#json_legacydiscardedvaluecomparison)
(`OFF` by default) which defines `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON` accordingly.
## Examples
??? example
The code below switches on the legacy discarded value comparison behavior in the library.
```cpp
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.11.0.
docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md
+4 -2
View File
@@ -40,10 +40,12 @@ See examples below for the concrete generated code.
!!! info "Prerequisites"
1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?](../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types)
1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy]
for how to overcome this limitation.
2. The macro must be used inside the type (class/struct).
[GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types
!!! warning "Implementation limits"
- The current implementation is limited to at most 64 member variables. If you want to serialize/deserialize types
@@ -116,7 +118,7 @@ See examples below for the concrete generated code.
- [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE / NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_non_intrusive.md)
for a similar macro that can be defined _outside_ the type.
- [Arbitrary Types Conversions](../../features/arbitrary_types.md) for an overview.
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
## Version history
docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md
+4 -2
View File
@@ -40,11 +40,13 @@ See examples below for the concrete generated code.
!!! info "Prerequisites"
1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?](../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types)
1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy]
for how to overcome this limitation.
2. The macro must be used outside the type (class/struct).
3. The passed members must be public.
[GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types
!!! warning "Implementation limits"
- The current implementation is limited to at most 64 member variables. If you want to serialize/deserialize types
@@ -116,7 +118,7 @@ See examples below for the concrete generated code.
- [NLOHMANN_DEFINE_TYPE_INTRUSIVE / NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_intrusive.md)
for a similar macro that can be defined _inside_ the type.
- [Arbitrary Types Conversions](../../features/arbitrary_types.md) for an overview.
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
## Version history