Allow disabling default enum conversions (#3536)

docs/docset/docSet.sql

@@ -140,6 +140,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('SAX Interface', 'Guide', 'fea
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_ASSERT', 'Macro', 'features/macros/index.html#json_assertx');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_CATCH_USER', 'Macro', 'features/macros/index.html#json_catch_userexception');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTICS', 'Macro', 'features/macros/index.html#json_diagnostics');
+INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_ENUM_SERIALIZATION', 'Macro', 'features/macros/index.html#json_disable_enum_serialization');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_11', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_14', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_17', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');

docs/mkdocs/docs/api/macros/index.md

@@ -29,6 +29,7 @@ header. See also the [macro overview page](../../features/macros.md).
 
 ## Type conversions
 
+- [**JSON_DISABLE_ENUM_SERIALIZATION**](json_disable_enum_serialization.md) - switch off default serialization/deserialization functions for enums
 - [**JSON_USE_IMPLICIT_CONVERSIONS**](json_use_implicit_conversions.md) - control implicit conversions
 
 <!-- comment-->

docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md

@@ -0,0 +1,135 @@
+# JSON_DISABLE_ENUM_SERIALIZATION
+
+```cpp
+#define JSON_DISABLE_ENUM_SERIALIZATION
+```
+
+When defined, default serialization and deserialization functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see [arbitrary type conversions](../../features/arbitrary_types.md) for more details).
+
+Parsing or serializing an enum will result in a compiler error.
+
+This works for both unscoped and scoped enums.
+
+## Default definition
+
+By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
+
+```cpp
+#undef JSON_DISABLE_ENUM_SERIALIZATION
+```
+
+## Examples
+
+??? example "Example 1: Disabled behavior"
+
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below **does not** compile.
+
+    ```cpp
+    #define JSON_DISABLE_ENUM_SERIALIZATION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    enum class Choice
+    {
+        first,
+        second,
+    };
+    
+    int main()
+    {
+        // normally invokes to_json serialization function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
+        const json j = Choice::first; 
+
+        // normally invokes from_json parse function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
+        Choice ch = j.get<Choice>();
+    }
+    ```
+
+??? example "Example 2: Serialize enum macro"
+
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
+
+    ```cpp
+    #define JSON_DISABLE_ENUM_SERIALIZATION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    enum class Choice
+    {
+        first,
+        second,
+    };
+
+    NLOHMANN_JSON_SERIALIZE_ENUM(Choice,
+    {
+        { Choice::first, "first" },
+        { Choice::second, "second" },
+    })
+    
+    int main()
+    {
+        // uses user-defined to_json function defined by macro
+        const json j = Choice::first; 
+
+        // uses user-defined from_json function defined by macro
+        Choice ch = j.get<Choice>();
+    }
+    ```
+
+??? example "Example 3: User-defined serialization/deserialization functions"
+
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined functions to parse and serialize the enum.
+
+    ```cpp
+    #define JSON_DISABLE_ENUM_SERIALIZATION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    enum class Choice
+    {
+        first,
+        second,
+    };
+
+    void from_json(const json& j, Choice& ch)
+    {
+        auto value = j.get<std::string>();
+        if (value == "first")
+        {
+            ch = Choice::first;
+        }
+        else if (value == "second")
+        {
+            ch = Choice::second;
+        }
+    }
+
+    void to_json(json& j, const Choice& ch)
+    {
+        auto value = j.get<std::string>();
+        if (value == "first")
+        {
+            ch = Choice::first;
+        }
+        else if (value == "second")
+        {
+            ch = Choice::second;
+        }
+    }
+    
+    int main()
+    {
+        // uses user-defined to_json function
+        const json j = Choice::first; 
+
+        // uses user-defined from_json function
+        Choice ch = j.get<Choice>();
+    }
+    ```
+
+## See also
+
+- [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md)

docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum.md

@@ -78,6 +78,7 @@ inline void from_json(const BasicJsonType& j, type& e);
 ## See also
 
 - [Specializing enum conversion](../../features/enum_conversion.md)
+- [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)
 
 ## Version history
 

docs/mkdocs/docs/features/enum_conversion.md

@@ -58,3 +58,4 @@ Other Important points:
   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.
+- To disable the default serialization of enumerators as integers and force a compiler error instead, see [`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md).

docs/mkdocs/docs/features/macros.md

@@ -54,6 +54,12 @@ Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`.
 
 See [full documentation of `JSON_NOEXCEPTION`](../api/macros/json_noexception.md).
 
+## `JSON_DISABLE_ENUM_SERIALIZATION`
+
+When defined, default parse and serialize functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](../api/macros/nlohmann_json_serialize_enum.md).
+
+See [full documentation of `JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md).
+
 ## `JSON_NO_IO`
 
 When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions

docs/mkdocs/mkdocs.yml

@@ -241,6 +241,7 @@ nav:
         - 'JSON_ASSERT': api/macros/json_assert.md
         - 'JSON_CATCH_USER': api/macros/json_throw_user.md
         - 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md
+        - 'JSON_DISABLE_ENUM_SERIALIZATION': api/macros/json_disable_enum_serialization.md
         - 'JSON_HAS_CPP_11': api/macros/json_has_cpp_11.md
         - 'JSON_HAS_CPP_14': api/macros/json_has_cpp_11.md
         - 'JSON_HAS_CPP_17': api/macros/json_has_cpp_11.md