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>

docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict.cpp

@@ -0,0 +1,52 @@
+#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;
+
+}

docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict.output

@@ -0,0 +1,2 @@
+ns::TS_STOPPED -> "stopped", ns::Color::red -> "red"
+"running" -> 1, "blue" -> 2

docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_2.cpp

@@ -0,0 +1,33 @@
+#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;
+}

docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_2.output

@@ -0,0 +1,3 @@
+0 -> "red"
+"rot" -> 0
+"red" -> 0

docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_err.cpp

@@ -0,0 +1,53 @@
+#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;
+}

docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_err.output

@@ -0,0 +1,2 @@
+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"