deploy: 40a62947d3

api/macros/nlohmann_json_serialize_enum_strict.md

@@ -56,13 +56,67 @@ inline void from_json(const BasicJsonType& j, type& e);
     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"
+    #include <iostream>
+    #include <nlohmann/json.hpp>
+    
+    using json = nlohmann::json;
+    
+    namespace ns
+    {
+    enum TaskState
+    {
+        TS_STOPPED,
+        TS_RUNNING,
+        TS_COMPLETED,
+        TS_INVALID = -1
+    };
+    
+    NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(TaskState,
+    {
+        { TS_INVALID, nullptr },
+        { TS_STOPPED, "stopped" },
+        { TS_RUNNING, "running" },
+        { TS_COMPLETED, "completed" }
+    })
+    
+    enum class Color
+    {
+        red, green, blue, unknown
+    };
+    
+    NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(Color,
+    {
+        { Color::unknown, "unknown" }, { Color::red, "red" },
+        { Color::green, "green" }, { Color::blue, "blue" }
+    })
+    } // namespace ns
+    
+    int main()
+    {
+        // serialization
+        json j_stopped = ns::TS_STOPPED;
+        json j_red = ns::Color::red;
+        std::cout << "ns::TS_STOPPED -> " << j_stopped
+                  << ", ns::Color::red -> " << j_red << std::endl;
+    
+        // deserialization
+        json j_running = "running";
+        json j_blue = "blue";
+        auto running = j_running.get<ns::TaskState>();
+        auto blue = j_blue.get<ns::Color>();
+        std::cout << j_running << " -> " << running
+                  << ", " << j_blue << " -> " << static_cast<int>(blue) << std::endl;
+    
+    }
+    
     ```
 
     Output:
     
     ```json
-    --8<-- "examples/nlohmann_json_serialize_enum_strict.output"
+    ns::TS_STOPPED -> "stopped", ns::Color::red -> "red"
+    "running" -> 1, "blue" -> 2
+    
     ```
 
 ??? example "Example: Multiple conversions for one enumerator"
@@ -72,13 +126,49 @@ inline void from_json(const BasicJsonType& j, type& e);
     alternative *deserialization* from `"rot"` to `Color::red`.
 
     ```cpp hl_lines="17"
-    --8<-- "examples/nlohmann_json_serialize_enum_strict_2.cpp"
+    #include <iostream>
+    #include <nlohmann/json.hpp>
+    
+    using json = nlohmann::json;
+    
+    namespace ns
+    {
+    enum class Color
+    {
+        red, green, blue, unknown
+    };
+    
+    NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(Color,
+    {
+        { Color::unknown, "unknown" }, { Color::red, "red" },
+        { Color::green, "green" }, { Color::blue, "blue" },
+        { Color::red, "rot" } // a second conversion for Color::red
+    })
+    }
+    
+    int main()
+    {
+        // serialization
+        json j_red = ns::Color::red;
+        std::cout << static_cast<int>(ns::Color::red) << " -> " << j_red << std::endl;
+    
+        // deserialization
+        json j_rot = "rot";
+        auto rot = j_rot.get<ns::Color>();
+        auto red = j_red.get<ns::Color>();
+        std::cout << j_rot << " -> " << static_cast<int>(rot) << std::endl;
+        std::cout << j_red << " -> " << static_cast<int>(red) << std::endl;
+    }
+    
     ```
 
     Output:
     
     ```json
-    --8<-- "examples/nlohmann_json_serialize_enum_strict_2.output"
+    0 -> "red"
+    "rot" -> 0
+    "red" -> 0
+    
     ```
 
 ??? example "Example: exceptions on invalid serialization"
@@ -89,12 +179,67 @@ inline void from_json(const BasicJsonType& j, type& e);
     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"
+    #include <iostream>
+    #include <nlohmann/json.hpp>
+    
+    using json = nlohmann::json;
+    
+    namespace ns
+    {
+    
+    enum class Color
+    {
+        red,
+        green,
+        blue,
+        unknown // not mapped in JSON_SERIALIZE_ENUM_STRICT
+    };
+    
+    NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(Color,
+    {
+        {Color::red, "red"},
+        {Color::green, "green"},
+        {Color::blue, "blue"}
+    })
+    
+    } // namespace ns
+    
+    
+    int main()
+    {
+        // invalid serialization
+        try
+        {
+            // ns::color::unknown was not mapped in macro
+            json invalid_serialization = ns::Color::unknown;
+        }
+        catch (const json::exception e)
+        {
+            std::cout << "deserialization failed: " << e.what() << std::endl;
+        }
+    
+        // invalid deserialization
+        try
+        {
+            // what does not map to an enum
+            json invalid_deserialization("what");
+            ns::Color color = invalid_deserialization.get<ns::Color>();
+        }
+        catch (const json::exception e)
+        {
+            std::cout << "deserialization failed: " << e.what() << std::endl;
+        }
+    
+        return 0;
+    }
+    
     ```
 
     Output:
     ```json
-    --8<-- "examples/nlohmann_json_serialize_enum_strict_err.output"
+    deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color
+    deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color: "what"
+    
     ```
 
 ## See also