Serialize enum (#5151)

* Added NLOHNMANN_JSON_SERIALIZE_ENUM_STRICT - duplicate of NLOHMANN_JSON_SERIALIZE_ENUM Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * Added failing tests for NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * modified NLOHMANN_JSON_SERIALIZE_STRICT to throw Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * added documentation and changed readme to include NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * ran amalgamate Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * docs(macros): add page for JSON_SERIALIZE_ENUM_STRICT - added page to nav - added links to new page where appropriate Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * refactor(macros): make JSON_SERIALIZE_ENUM_STRICT use JSON_THROW - added templated wrapper function to fix scope error in calling JSON_THROW Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * refactor(macros): make NLOHMANN_SERIALIZE_ENUM_STRICT use error code 410 - added error code 410 to docs Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * tests(macros): add test for to_json with enum value not mentioned in mapping for NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * Apply suggestions from code review Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com> Signed-off-by: Caillin Nugent <nugentcaillin@gmail.com> * fix(macro): prevent compilation error with -Werror and -Wunused-parameter with NLOHMANN_JSON_SERIALIZE_ENUM_STRICT - casted exception to void to avoid warning Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * fix(docs): add link to NLOHMANN_SERIALIZE_ENUM_STRICT docs to exception page Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * docs(macros): add example of exception throwing for NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * refactor(macros): add more in-depth error message to NLOHMANN_JSON_SERIALIZE_ENUM_STRICT - changed error message to follow style of nlohmann/json#4989 - made description of throw wrapper more general - updated tests and example of exceptions Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> --------- Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> Signed-off-by: Caillin Nugent <nugentcaillin@gmail.com> Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com>
2026-06-18 18:34:17 +00:00 · 2026-05-19 04:37:07 +10:00
parent 47202c804a
commit 58cfecf7f7
16 changed files with 451 additions and 2 deletions
@@ -54,6 +54,7 @@ header. See also the [macro overview page](../../features/macros.md).
 ### Enums

 - [**NLOHMANN_JSON_SERIALIZE_ENUM**](nlohmann_json_serialize_enum.md) - serialize/deserialize an enum
+- [**NLOHMANN_JSON_SERIALIZE_ENUM_STRICT**](nlohmann_json_serialize_enum_strict.md) - serialize/deserialize an enum with exceptions

 ### Classes and structs

@@ -78,6 +78,7 @@ inline void from_json(const BasicJsonType& j, type& e);
 ## See also

 - [Specializing enum conversion](../../features/enum_conversion.md)
+- [`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT`](./nlohmann_json_serialize_enum_strict.md)
 - [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)

 ## Version history
@@ -0,0 +1,102 @@
+# NLOHMANN_JSON_SERIALIZE_ENUM_STRICT
+
+```cpp
+#define NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(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.
+
+`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT` allows to define a user-defined serialization for every enumerator that
+throws an exception on undefined input.
+
+## 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:
+
+```cpp
+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 throw an exception.
+    - 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.
+
+## Examples
+
+??? example "Example 1: Basic usage"
+
+    The example shows how `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT` 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_strict.cpp"
+    ```
+
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_serialize_enum_strict.output"
+    ```
+
+??? example "Example 2: 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_strict_2.cpp"
+    ```
+
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_serialize_enum_strict_2.output"
+    ```
+
+??? example "Example 3: exceptions on invalid serialization"
+    
+    The example shows how an invalid serialization causes an exception to be thrown. In the example,
+    Color::unknown is not defined in the mapping used to call `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT`
+    so causes an exception when used to serialize. Similarly, "what" does not refer to an enum
+    value so also causes an exception when deserialization is attempted.
+
+    ```cpp hl_lines="14 32 33 43 44 45"
+    --8<-- "examples/nlohmann_json_serialize_enum_strict_err.cpp"
+    ```
+
+    Output:
+    ```json
+    --8<-- "examples/nlohmann_json_serialize_enum_strict_err.output"
+    ```
+
+## See also
+
+- [Specializing enum conversion](../../features/enum_conversion.md)
+- [`NLOHMANN_JSON_SERIALIZE_ENUM`](./nlohmann_json_serialize_enum.md)
+- [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)
+
+## Version history
+
+Added in version 3.12.0.