mirror of https://github.com/nlohmann/json.git synced 2026-10-28 19:45:22 +00:00

Files

T

Niels Lohmann e5fe4ebdd2 json_view: from_json() of the macros reads views directly (#5922 )

get<T>() and get_to() of a view call T's from_json() with the view itself
when that from_json() accepts views but not an unrelated probe type, and
fall back to materialize() otherwise. The from_json() functions of the
NLOHMANN_DEFINE_TYPE_*, NLOHMANN_DEFINE_DERIVED_TYPE_* and
NLOHMANN_JSON_SERIALIZE_ENUM(_STRICT) macros accept basic_json values and
views; a derived type whose base reads only json reads the base part
through materialize(). The library's own from_json() overloads are not
called with views: from_json() of a view (and of the probe) only looks up
functions by ADL.

New public trait nlohmann::is_json_view<T>, and the member type
basic_json_type of basic_json_view. With duplicate keys, the members of
such a T are those the view's lookups find (the first ones).

bench_decode.cpp measures decoding into structs (4-6x faster than
materialize().get<T>() on twitter, citm_catalog, and synthetic records).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-10-26 20:13:31 +01:00

3.4 KiB

Raw Blame History

NLOHMANN_JSON_SERIALIZE_ENUM

#define NLOHMANN_JSON_SERIALIZE_ENUM(type, conversion...)

By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later deserialized JSON data may be undefined or a different enum value than was originally intended.

The NLOHMANN_JSON_SERIALIZE_ENUM allows to define a user-defined serialization for every enumerator.

Parameters

type (in): name of the enum to serialize/deserialize
conversion (in): a pair of an enumerator and a JSON serialization; arbitrary pairs can be given as a comma-separated list

Default definition

The macro adds two functions to the namespace which take care of the serialization and deserialization:

template<typename BasicJsonType>
inline void to_json(BasicJsonType& j, const type& e);
template<typename BasicJsonType>
inline void from_json(const BasicJsonType& j, type& e);

Notes

!!! info "Prerequisites"

The macro must be used inside the namespace of the enum.

!!! important "Important notes"

- When using [`get<ENUM_TYPE>()`](../basic_json/get.md), undefined JSON values will default to the first specified
  conversion. Select this default pair carefully. See example 1 below.
- If an enum or JSON value is specified in multiple conversions, the first matching conversion from the top of the
  list will be returned when converting to or from JSON. See example 2 below.
- Maps with enum keys (e.g., `std::map<ENUM_TYPE, T>`) are stored as arrays of `[key, value]` pairs by default.
  Define [`JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](json_use_objects_for_enum_keyed_maps.md) to store them as objects
  with the converted keys. Such maps can be read from both forms.

!!! info "Views"

The generated `from_json()` also reads the views of [`json_document`](../json_document.md)s
(`<nlohmann/json_view.hpp>`), comparing the view with the entries of the mapping, without building a `json` value
first.

Examples

??? example "Example: Basic usage"

The example shows how `NLOHMANN_JSON_SERIALIZE_ENUM` can be used to serialize/deserialize both classical enums and
C++11 enum classes:

```cpp hl_lines="16 17 18 19 20 21 22 29 30 31 32 33"
--8<-- "examples/nlohmann_json_serialize_enum.cpp"
```

Output:

```json
--8<-- "examples/nlohmann_json_serialize_enum.output"
```

??? example "Example: Multiple conversions for one enumerator"

The example shows how to use multiple conversions for a single enumerator. In the example, `Color::red` will always
be *serialized* to `"red"`, because the first occurring conversion. The second conversion, however, offers an
alternative *deserialization* from `"rot"` to `Color::red`.

```cpp hl_lines="17"
--8<-- "examples/nlohmann_json_serialize_enum_2.cpp"
```

Output:

```json
--8<-- "examples/nlohmann_json_serialize_enum_2.output"
```

Version history

Added in version 3.4.0.

The generated from_json() reads the views of json_documents since version 3.13.0.

3.4 KiB Raw Blame History