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

Restructure inline namespace and allow version component to be disabled (#3683)

Browse Source
This commit is contained in:
Florian Albrechtskirchinger
2022-08-10 20:24:16 +02:00
committed by GitHub
parent 93112fbf4d
commit 0e61ee8b07
21 changed files with 500 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/mkdocs/docs/api/macros/index.md
View File

@@ -32,7 +32,10 @@ header. See also the [macro overview page](../../features/macros.md).
## Library namespace
- [**NLOHMANN_JSON_NAMESPACE**](nlohmann_json_namespace.md) - full name of the `nlohmann` namespace
- [**NLOHMANN_JSON_NAMESPACE_BEGIN**<br>**NLOHMANN_JSON_NAMESPACE_END**](nlohmann_json_namespace_begin.md) - open and close the library namespace
- [**NLOHMANN_JSON_NAMESPACE_BEGIN**<br>**NLOHMANN_JSON_NAMESPACE_END**](nlohmann_json_namespace_begin.md) - open and
close the library namespace
- [**NLOHMANN_JSON_NAMESPACE_NO_VERSION**](nlohmann_json_namespace_no_version.md) - disable the version component of
the inline namespace
## Type conversions

16
docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md
View File

@@ -1,19 +1,18 @@
# NLOHMANN_JSON_NAMESPACE
```cpp
#define NLOHMANN_JSON_NAMESPACE
#define NLOHMANN_JSON_NAMESPACE /* value */
```
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.
## 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
[`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md)).
The default value consists of the root namespace (`nlohmann`) and an inline ABI namespace. See
[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
When the macro is not defined, the library will define it to its default value.
When the macro is not defined, the library will define it to its default value. Overriding this value has no effect on
the library.
## Examples
@@ -35,7 +34,8 @@ When the macro is not defined, the library will define it to its default value.
## See also
- [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)
- [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](nlohmann_json_namespace_no_version.md)
## Version history
- Added in version 3.11.0.
- Added in version 3.11.0. Changed inline namespace name in version 3.11.2.

43
docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md
View File

@@ -1,30 +1,35 @@
# NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END
```cpp
#define NLOHMANN_JSON_NAMESPACE_BEGIN // (1)
#define NLOHMANN_JSON_NAMESPACE_END // (2)
#define NLOHMANN_JSON_NAMESPACE_BEGIN /* value */ // (1)
#define NLOHMANN_JSON_NAMESPACE_END /* value */ // (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. See
[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
1. Opens the namespace.
```cpp
namespace nlohmann
{
inline namespace json_v3_11_0
{
```
2. Closes the namespace.
```cpp
} // namespace nlohmann
} // json_v3_11_0
```
## Default definition
The default definitions open and close the `nlohmann` as well as an inline namespace.
The default definitions open and close the `nlohmann` namespace. The precise definition of
[`NLOHMANN_JSON_NAMESPACE_BEGIN`] varies as described [here](../../features/namespace.md#structure).
1. Default definition of `NLOHMANN_JSON_NAMESPACE_BEGIN`:
```cpp
namespace nlohmann
{
inline namespace json_abi_v3_11_2
{
```
2. Default definition of `NLOHMANN_JSON_NAMESPACE_END`:
```cpp
} // namespace json_abi_v3_11_2
} // namespace nlohmann
```
When these macros are not defined, the library will define them to their default definitions.
@@ -32,7 +37,7 @@ When these macros are not defined, the library will define them to their default
??? example
The example shows an example how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the
The example shows 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
@@ -47,8 +52,10 @@ When these macros are not defined, the library will define them to their default
## See also
- [`nlohmann` Namespace](../../features/namespace.md)
- [NLOHMANN_JSON_NAMESPACE](nlohmann_json_namespace.md)
- [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](nlohmann_json_namespace_no_version.md)
## Version history
- Added in version 3.11.0.
- Added in version 3.11.0. Changed inline namespace name in version 3.11.2.

45
docs/mkdocs/docs/api/macros/nlohmann_json_namespace_no_version.md Normal file
View File

@@ -0,0 +1,45 @@
# NLOHMANN_JSON_NAMESPACE_NO_VERSION
```cpp
#define NLOHMANN_JSON_NAMESPACE_NO_VERSION /* value */
```
If defined to `1`, the version component is omitted from the inline namespace. See
[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
## Default definition
The default value is `0`.
```cpp
#define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
```
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_NO_VERSION` to disable the version component of the inline
namespace.
```cpp
--8<-- "examples/nlohmann_json_namespace_no_version.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_json_namespace_no_version.output"
```
## See also
- [`nlohmann` Namespace](../../features/namespace.md)
- [`NLOHMANN_JSON_NAMESPACE`](nlohmann_json_namespace.md)
- [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)
## Version history
- Added in version 3.11.2.

93
docs/mkdocs/docs/features/namespace.md Normal file
View File

@@ -0,0 +1,93 @@
# `nlohmann` Namespace
The 3.11.0 release introduced an
[inline namespace](https://en.cppreference.com/w/cpp/language/namespace#Inline_namespaces) to allow different parts of
a codebase to safely use different versions of the JSON library as long as they never exchange instances of library
types.
## Structure
The complete default namespace name is derived as follows:
- The root namespace is always `nlohmann`.
- The inline namespace starts with `json_abi` and is followed by serveral optional ABI tags according to the value of
these ABI-affecting macros, in order:
- [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) defined non-zero appends `_diag`.
- [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md)
defined non-zero appends `_ldvcmp`.
- The inline namespace ends with the suffix `_v` followed by the 3 components of the version number separated by
underscores. To omit the version component, see [Disabling the version component](#disabling-the-version-component)
below.
For example, the namespace name for version 3.11.2 with `JSON_DIAGNOSTICS` defined to `1` is:
```cpp
nlohmann::json_abi_diag_v3_11_2
```
## Purpose
Several incompatibilities have been observed. Amongst the most common ones is linking code compiled with different
definitions of [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This is illustrated in the diagram below.
```plantuml
[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=0] as [json]
[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=1] as [json_diag]
[**some_library**] as [library]
[**application**] as [app]
[library] ..|> [json]
[app] ..|> [json_diag]
[app] ..|>[library]
```
In releases prior to 3.11.0, mixing any version of the JSON library with different `JSON_DIAGNOSTICS` settings would
result in a crashing application. If `some_library` never passes instances of JSON library types to the application,
this scenario became safe in version 3.11.0 and above due to the inline namespace yielding distinct symbol names.
## Limitations
Neither the compiler nor the linker will issue as much as a warning when translation units – intended to be linked
together and that include different versions and/or configurations of the JSON library – exchange and use library
types.
There is an exception when forward declarations are used (i.e., when including `json_fwd.hpp`) in which case the linker
may complain about undefined references.
## Disabling the version component
Different versions are not necessarily ABI-incompatible, but the project does not actively track changes in the ABI and
recommends that all parts of a codebase exchanging library types be built with the same version. Users can, **at their
own risk**, disable the version component of the linline namespace, allowing different versions – but not
configurations – to be used in cases where the linker would otherwise output undefined reference errors.
To do so, define [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](../api/macros/nlohmann_json_namespace_no_version.md) to `1`.
This applies to version 3.11.2 and above only, versions 3.11.0 and 3.11.1 can apply the technique described in the next
section to emulate the effect of the `NLOHMANN_JSON_NAMESPACE_NO_VERSION` macro.
!!! danger "Use at your own risk"
Disabling the namespace version component and mixing ABI-incompatible versions will result in crashes or incorrect
behavior. You have been warned!
## Disabling the inline namespace completely
When interoperability with code using a pre-3.11.0 version of the library is required, users can, **at their own risk**
restore the old namespace layout by redefining
[`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](../api/macros/nlohmann_json_namespace_begin.md) as
follows:
```cpp
#define NLOHMANN_JSON_NAMESPACE_BEGIN namespace nlohmann {
#define NLOHMANN_JSON_NAMESPACE_END }
```
!!! danger "Use at your own risk"
Overriding the namespace and mixing ABI-incompatible versions will result in crashes or incorrect behavior. You
have been warned!
## Version history
- Introduced inline namespace (`json_v3_11_0[_abi-tag]*`) in version 3.11.0.
- Changed structure of inline namespace in version 3.11.2.