mirror of
https://github.com/nlohmann/json.git
synced 2026-10-03 06:15:44 +01:00
115 lines
3.7 KiB
Markdown
115 lines
3.7 KiB
Markdown
# JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
|
|
|
|
```cpp
|
|
#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION /* value */
|
|
```
|
|
|
|
When defined to `1`, a `basic_json` value can no longer be constructed from a one-element `std::tuple` whose element is
|
|
a reference to that `basic_json` type, such as `std::tuple<json&>`, `std::tuple<const json&>`, or `std::tuple<json&&>`.
|
|
These are the tuples created by `std::forward_as_tuple(j)`.
|
|
|
|
## Default definition
|
|
|
|
The default value is `0` (disabled — existing behavior is preserved).
|
|
|
|
```cpp
|
|
#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 0
|
|
```
|
|
|
|
## Notes
|
|
|
|
!!! note "Background"
|
|
|
|
By default, `basic_json` can be constructed from any `std::tuple` whose elements can be converted to JSON; the result
|
|
is an array. This includes `std::tuple<json&>`, which becomes a one-element array.
|
|
|
|
`std::tuple` only converts another tuple element by element if its element type cannot be constructed from the whole
|
|
source tuple. Because `json` *can* be constructed from `std::tuple<json&>`, `std::tuple` instead converts the whole
|
|
tuple into a single `json` value. This has two surprising effects:
|
|
|
|
```cpp
|
|
json j = true;
|
|
|
|
// rejected by some standard libraries (e.g., libc++); with others, the
|
|
// reference binds to a temporary that is destroyed right away
|
|
std::tuple<const json&> t1(std::forward_as_tuple(j));
|
|
|
|
// compiles, but std::get<0>(t2) is [true], not true
|
|
std::tuple<json> t2(std::forward_as_tuple(j));
|
|
```
|
|
|
|
Enabling this macro removes the conversion, so both tuples are converted element by element: `std::get<0>(t1)`
|
|
refers to `j`, and `std::get<0>(t2)` is a copy of `j` (see [#2226](https://github.com/nlohmann/json/issues/2226)).
|
|
|
|
!!! warning "Opt-in only"
|
|
|
|
This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
|
|
|
|
!!! note "Affected conversions"
|
|
|
|
Only one-element tuples holding a reference to the **same** `basic_json` type are affected. Constructing a JSON value
|
|
from them no longer compiles:
|
|
|
|
```cpp
|
|
json j = true;
|
|
json a = std::forward_as_tuple(j); // error with the macro enabled
|
|
json b = json::array({j}); // use this instead: [true]
|
|
```
|
|
|
|
Tuples holding a JSON value (`std::make_tuple(j)`), tuples with more than one element, and tuples holding references
|
|
to other types (including other `basic_json` specializations) are converted to arrays as before.
|
|
|
|
!!! hint "CMake option"
|
|
|
|
This behavior can also be controlled with the CMake option
|
|
[`JSON_DisableTupleReferenceConversion`](../../integration/cmake.md#json_disabletuplereferenceconversion)
|
|
(`OFF` by default) which defines `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION` accordingly.
|
|
|
|
## Examples
|
|
|
|
??? example "Default behavior (macro not defined)"
|
|
|
|
```cpp
|
|
#include <nlohmann/json.hpp>
|
|
|
|
using json = nlohmann::json;
|
|
|
|
int main()
|
|
{
|
|
json j = true;
|
|
|
|
std::tuple<json> t(std::forward_as_tuple(j));
|
|
// std::get<0>(t) is [true] -- the whole tuple was converted
|
|
}
|
|
```
|
|
|
|
??? example "Conversion disabled (macro defined to 1)"
|
|
|
|
```cpp
|
|
#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
|
|
#include <nlohmann/json.hpp>
|
|
|
|
using json = nlohmann::json;
|
|
|
|
int main()
|
|
{
|
|
json j = true;
|
|
|
|
std::tuple<json> t(std::forward_as_tuple(j));
|
|
// std::get<0>(t) is true -- a copy of j
|
|
|
|
std::tuple<const json&> r(std::forward_as_tuple(j));
|
|
// std::get<0>(r) refers to j
|
|
}
|
|
```
|
|
|
|
## See also
|
|
|
|
- [**basic_json(CompatibleType&&)**](../basic_json/basic_json.md) - the affected constructor
|
|
- [:simple-cmake: JSON_DisableTupleReferenceConversion](../../integration/cmake.md#json_disabletuplereferenceconversion) -
|
|
CMake option to control the macro
|
|
|
|
## Version history
|
|
|
|
- Added in version 3.13.0.
|