mirror of
https://github.com/nlohmann/json.git
synced 2025-05-11 21:53:56 +00:00
29cd970b94
* 🔥 consolidate documentation * ♻️ overwork std specializations * 🚚 move images files to mkdocs * ♻️ fix URLs * 🔧 tweak MkDocs configuration * 🔧 add namespaces * 📝 document deprecations * 📝 document documentation generation * 🚸 improve search * 🚸 add examples * 🚧 start adding documentation for macros * 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139 * 📝 overwork example handling * 📝 fix Markdown tables
60 lines
2.0 KiB
Markdown
60 lines
2.0 KiB
Markdown
# Specializing enum 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 de-serialized JSON data may be
|
|
undefined or a different enum value than was originally intended.
|
|
|
|
It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:
|
|
|
|
```cpp
|
|
// example enum type declaration
|
|
enum TaskState {
|
|
TS_STOPPED,
|
|
TS_RUNNING,
|
|
TS_COMPLETED,
|
|
TS_INVALID=-1,
|
|
};
|
|
|
|
// map TaskState values to JSON as strings
|
|
NLOHMANN_JSON_SERIALIZE_ENUM( TaskState, {
|
|
{TS_INVALID, nullptr},
|
|
{TS_STOPPED, "stopped"},
|
|
{TS_RUNNING, "running"},
|
|
{TS_COMPLETED, "completed"},
|
|
})
|
|
```
|
|
|
|
The `NLOHMANN_JSON_SERIALIZE_ENUM()` macro declares a set of `to_json()` / `from_json()` functions for type `TaskState`
|
|
while avoiding repetition and boilerplate serialization code.
|
|
|
|
## Usage
|
|
|
|
```cpp
|
|
// enum to JSON as string
|
|
json j = TS_STOPPED;
|
|
assert(j == "stopped");
|
|
|
|
// json string to enum
|
|
json j3 = "running";
|
|
assert(j3.get<TaskState>() == TS_RUNNING);
|
|
|
|
// undefined json value to enum (where the first map entry above is the default)
|
|
json jPi = 3.14;
|
|
assert(jPi.get<TaskState>() == TS_INVALID );
|
|
```
|
|
|
|
## Notes
|
|
|
|
Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
|
|
|
|
- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace),
|
|
or the library will not be able to locate it, and it will default to integer serialization.
|
|
- It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.
|
|
|
|
Other Important points:
|
|
|
|
- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this
|
|
default pair carefully.
|
|
- If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the
|
|
map will be returned when converting to or from JSON.
|