Move UDLs out of the global namespace (#3605)

* Move UDLs into nlohmann::literals::json_literals namespace

* Add 'using namespace' to unit tests

* Add 'using namespace' to examples

* Add 'using namespace' to README

* Move UDL mkdocs pages out of basic_json/

* Update documentation

* Update docset index

* Add JSON_GlobalUDLs CMake option

* Add unit test

* Build examples without global UDLs

* Add CI target

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

@@ -21,6 +21,7 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
+- [**JSON_USE_GLOBAL_UDLS**](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace
 
 ## Library version
 

docs/mkdocs/docs/api/macros/json_use_global_udls.md

@@ -0,0 +1,99 @@
+# JSON_USE_GLOBAL_UDLS
+
+```cpp
+#define JSON_USE_GLOBAL_UDLS /* value */
+```
+
+When defined to `1`, the user-defined string literals (UDLs) are placed into the global namespace instead of
+`nlohmann::literals::json_literals`.
+
+## Default definition
+
+The default value is `1`.
+
+```cpp
+#define JSON_USE_GLOBAL_UDLS 1
+```
+
+When the macro is not defined, the library will define it to its default value.
+
+## Notes
+
+!!! info "Future behavior change"
+
+    The user-defined string literals will be removed from the global namespace in the next major release of the
+    library.
+
+    To prepare existing code, define `JSON_USE_GLOBAL_UDLS` to `0` and bring the string literals into scope where
+    needed. Refer to any of the [string literals](#see-also) for details.
+
+!!! hint "CMake option"
+
+    The placement of user-defined string literals can also be controlled with the CMake option
+    [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default)
+    which defines `JSON_USE_GLOBAL_UDLS` accordingly.
+
+## Examples
+
+??? example "Example 1: Default behavior"
+
+    The code below shows the default behavior using the `_json` UDL.
+    
+    ```cpp
+    #include <nlohmann/json.hpp>
+    
+    #include <iostream>
+    
+    int main()
+    {
+        auto j = "42"_json;
+    
+        std::cout << j << std::endl;
+    }
+    ```
+    
+    Output:
+    
+    ```json
+    42
+    ```
+
+??? example "Example 2: Namespaced UDLs"
+
+    The code below shows how UDLs need to be brought into scope before using `_json` when `JSON_USE_GLOBAL_UDLS` is
+    defined to `0`.
+    
+    ```cpp
+    #define JSON_USE_GLOBAL_UDLS 0
+    #include <nlohmann/json.hpp>
+
+    #include <iostream>
+    
+    int main()
+    {
+        // auto j = "42"_json; // This line would fail to compile,
+                               // because the UDLs are not in the global namespace
+    
+        // Bring the UDLs into scope
+        using namespace nlohmann::json_literals;
+    
+        auto j = "42"_json;
+    
+        std::cout << j << std::endl;
+    }
+    ```
+    
+    Output:
+    
+    ```json
+    42
+    ```
+
+## See also
+
+- [`operator""_json`](../operator_literal_json.md)
+- [`operator""_json_pointer`](../operator_literal_json_pointer.md)
+
+## Version history
+
+- Added in version 3.11.0.