deploy: 40a62947d3

features/enum_conversion.md

@@ -49,13 +49,75 @@ assert(jPi.get<TaskState>() == TS_INVALID );
 ??? example "Example: serializing/deserializing enums, including a second enum type"
 
     ```cpp
-    --8<-- "examples/nlohmann_json_serialize_enum.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(TaskState,
+    {
+        { TS_INVALID, nullptr },
+        { TS_STOPPED, "stopped" },
+        { TS_RUNNING, "running" },
+        { TS_COMPLETED, "completed" }
+    })
+    
+    enum class Color
+    {
+        red, green, blue, unknown
+    };
+    
+    NLOHMANN_JSON_SERIALIZE_ENUM(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;
+    
+        // deserializing undefined JSON value to enum
+        // (where the first map entry above is the default)
+        json j_pi = 3.14;
+        auto invalid = j_pi.get<ns::TaskState>();
+        auto unknown = j_pi.get<ns::Color>();
+        std::cout << j_pi << " -> " << invalid << ", "
+                  << j_pi << " -> " << static_cast<int>(unknown) << std::endl;
+    }
+    
     ```
 
     Output:
 
     ```json
-    --8<-- "examples/nlohmann_json_serialize_enum.output"
+    ns::TS_STOPPED -> "stopped", ns::Color::red -> "red"
+    "running" -> 1, "blue" -> 2
+    3.14 -> -1, 3.14 -> 3
+    
     ```
 
 ## Maps with enum keys
@@ -100,11 +162,66 @@ Other Important points:
 ??? example "Example: `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT` throwing on unrecognized values"
 
     ```cpp
-    --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"
+    
     ```