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

Documentation change (#3672)

Browse Source 
Co-authored-by: Florian Albrechtskirchinger <falbrechtskirchinger@gmail.com>
This commit is contained in:
Niels Lohmann
2022-08-05 19:51:39 +02:00
committed by GitHub
co-authored by Florian Albrechtskirchinger
parent 9e1a7c85e3
commit 7b6cf5918b
65 changed files with 582 additions and 302 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mkdocs/docs/api/macros/json_use_global_udls.md
+3 -4
View File
@@ -21,8 +21,7 @@ When the macro is not defined, the library will define it to its default value.
!!! info "Future behavior change"
The user-defined string literals will be removed from the global namespace in the next major release of the
library.
The user-defined string literals will be removed from the global namespace in the next major release of the library.
To prepare existing code, define `JSON_USE_GLOBAL_UDLS` to `0` and bring the string literals into scope where
needed. Refer to any of the [string literals](#see-also) for details.
@@ -30,8 +29,8 @@ When the macro is not defined, the library will define it to its default value.
!!! hint "CMake option"
The placement of user-defined string literals can also be controlled with the CMake option
[`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default)
which defines `JSON_USE_GLOBAL_UDLS` accordingly.
[`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`ON` by default) which defines
`JSON_USE_GLOBAL_UDLS` accordingly.
## Examples
docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md
+7 -10
View File
@@ -4,8 +4,8 @@
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */
```
This macro enables the (incorrect) legacy comparison behavior of discarded JSON values.
Possible values are `1` to enable or `0` to disable (default).
This macro enables the (incorrect) legacy comparison behavior of discarded JSON values. Possible values are `1` to
enable or `0` to disable (default).
When enabled, comparisons involving at least one discarded JSON value yield results as follows:
@@ -42,19 +42,16 @@ When the macro is not defined, the library will define it to its default value.
`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`.
- Overloads for the equality and relational operators emulate the legacy behavior.
Code outside your control may use either 3-way comparison or the equality and
relational operators, resulting in inconsistent and unpredictable behavior.
Code outside your control may use either 3-way comparison or the equality and relational operators, resulting in
inconsistent and unpredictable behavior.
See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way
comparison.
See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way comparison.
!!! warning "Deprecation"
The legacy comparison behavior is deprecated and may be removed in a future major
version release.
The legacy comparison behavior is deprecated and may be removed in a future major version release.
New code should not depend on it and existing code should try to remove or rewrite
expressions relying on it.
New code should not depend on it and existing code should try to remove or rewrite expressions relying on it.
!!! hint "CMake option"
docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md
+5 -5
View File
@@ -7,9 +7,9 @@
These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as
serialization and want to use the member variable names as object keys in that object. The macro is to be defined
**inside** the class/struct to create code for.
Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members.
The first parameter is the name of the class/struct, and all remaining parameters name the members.
**inside** the class/struct to create code for. Unlike
[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members. The first
parameter is the name of the class/struct, and all remaining parameters name the members.
1. Will use [`at`](../basic_json/at.md) during deserialization and will throw
[`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object.
@@ -40,8 +40,8 @@ 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?][GetNonDefNonCopy]
for how to overcome this limitation.
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
docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md
+5 -4
View File
@@ -7,9 +7,9 @@
These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as
serialization and want to use the member variable names as object keys in that object. The macro is to be defined
**outside** the class/struct to create code for, but **inside** its namespace.
Unlike [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members.
The first parameter is the name of the class/struct, and all remaining parameters name the members.
**outside** the class/struct to create code for, but **inside** its namespace. Unlike
[`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members. The first
parameter is the name of the class/struct, and all remaining parameters name the members.
1. Will use [`at`](../basic_json/at.md) during deserialization and will throw
[`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object.
@@ -103,7 +103,8 @@ See examples below for the concrete generated code.
- `ns::person` is default-constructible. This is a requirement for using the macro.
- `ns::person` has only public member variables. This makes `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT`
applicable.
- The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its namespace `ns`.
- The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its
namespace `ns`.
- A missing key "age" in the deserialization does not yield an exception. Instead, the default value `-1` is used.
The macro is equivalent to:
docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md
+21 -6
View File
@@ -4,19 +4,34 @@
#define NLOHMANN_JSON_NAMESPACE
```
This macro evaluates to the full name of the `nlohmann` namespace, including
the name of a versioned and ABI-tagged inline namespace. Use this macro to
unambiguously refer to the `nlohmann` namespace.
This macro evaluates to the full name of the `nlohmann` namespace, including the name of a versioned and ABI-tagged
inline namespace. Use this macro to unambiguously refer to the `nlohmann` namespace.
## Default definition
The default value consists of a prefix, a version string, and optional ABI tags
depending on whether ABI-affecting macros are defined (e.g.,
[`JSON_DIAGNOSTICS`](json_diagnostics.md), and
The default value consists of a prefix, a version string, and optional ABI tags depending on whether ABI-affecting
macros are defined (e.g., [`JSON_DIAGNOSTICS`](json_diagnostics.md), and
[`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md)).
When the macro is not defined, the library will define it to its default value.
## Examples
??? example
The example shows how to use `NLOHMANN_JSON_NAMESPACE` instead of just `nlohmann`, as well as how to output the value
of `NLOHMANN_JSON_NAMESPACE`.
```cpp
--8<-- "examples/nlohmann_json_namespace.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_json_namespace.output"
```
## See also
- [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)
docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md
+21 -7
View File
@@ -5,9 +5,8 @@
#define NLOHMANN_JSON_NAMESPACE_END // (2)
```
These macros can be used to open and close the `nlohmann` namespace. They
include an inline namespace used to differentiate symbols when linking multiple
versions (including different ABI-affecting macros) of this library.
These macros can be used to open and close the `nlohmann` namespace. They include an inline namespace used to
differentiate symbols when linking multiple versions (including different ABI-affecting macros) of this library.
1. Opens the namespace.
```cpp
@@ -25,11 +24,26 @@ versions (including different ABI-affecting macros) of this library.
## Default definition
The default definitions open and close the `nlohmann` as well as an inline
namespace.
The default definitions open and close the `nlohmann` as well as an inline namespace.
When these macros are not defined, the library will define them to their
default definitions.
When these macros are not defined, the library will define them to their default definitions.
## Examples
??? example
The example shows an example how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the
[How do I convert third-party types?](../../features/arbitrary_types.md#how-do-i-convert-third-party-types) page.
```cpp
--8<-- "examples/nlohmann_json_namespace_begin.c++17.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_json_namespace_begin.c++17.output"
```
## See also