Fix C++20/gcc-12 issues (Part 2) (#3446)

* Add C++20 3-way comparison operator and fix broken comparisons

Fixes #3207.
Fixes #3409.

* Fix iterators to meet (more) std::ranges requirements

Fixes #3130.
Related discussion: #3408

* Add note about CMake standard version selection to unit tests

Document how CMake chooses which C++ standard version to use when
building tests.

* Update documentation

* CI: add legacy discarded value comparison

* Fix internal linkage errors when building a module

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

@@ -17,6 +17,8 @@ header. See also the [macro overview page](../../features/macros.md).
 
 - [**JSON_HAS_CPP_11**<br>**JSON_HAS_CPP_14**<br>**JSON_HAS_CPP_17**<br>**JSON_HAS_CPP_20**](json_has_cpp_11.md) - set supported C++ standard
 - [**JSON_HAS_FILESYSTEM**<br>**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support
+- [**JSON_HAS_RANGES**](json_has_ranges.md) - control `std::ranges` support
+- [**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
 
@@ -29,6 +31,12 @@ header. See also the [macro overview page](../../features/macros.md).
 
 - [**JSON_USE_IMPLICIT_CONVERSIONS**](json_use_implicit_conversions.md) - control implicit conversions
 
+<!-- comment-->
+## Comparison behavior
+
+- [**JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON**](json_use_legacy_discarded_value_comparison.md) -
+  control comparison of discarded values
+
 ## Serialization/deserialization macros
 
 - [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_intrusive.md) - serialization/deserialization of types _with_ access to private variables

docs/mkdocs/docs/api/macros/json_has_ranges.md

@@ -0,0 +1,18 @@
+# JSON_HAS_RANGES
+
+```cpp
+#define JSON_HAS_RANGES /* value */
+```
+
+This macro indicates whether the standard library has any support for ranges. Implies support for concepts.
+Possible values are `1` when supported or `0` when unsupported.
+
+## Default definition
+
+The default value is detected based on the preprocessor macro `#!cpp __cpp_lib_ranges`.
+
+When the macro is not defined, the library will define it to its default value.
+
+## Version history
+
+- Added in version 3.11.0.

docs/mkdocs/docs/api/macros/json_has_three_way_comparison.md

@@ -0,0 +1,19 @@
+# JSON_HAS_THREE_WAY_COMPARISON
+
+```cpp
+#define JSON_HAS_THREE_WAY_COMPARISON /* value */
+```
+
+This macro indicates whether the compiler and standard library support 3-way comparison.
+Possible values are `1` when supported or `0` when unsupported.
+
+## Default definition
+
+The default value is detected based on the preprocessor macros `#!cpp __cpp_impl_three_way_comparison`
+and `#!cpp __cpp_lib_three_way_comparison`.
+
+When the macro is not defined, the library will define it to its default value.
+
+## Version history
+
+- Added in version 3.11.0.

docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md

@@ -0,0 +1,61 @@
+# JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON
+
+```cpp
+#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */
+```
+
+This macro enables the (incorrect) legacy comparison behavior of discarded JSON values.
+Possible values are `1` to enable or `0` to disable (default).
+
+When enabled, comparisons involving at least one discarded JSON value yield results as follows:
+
+| **Operator** | **Result**    |
+|--------------|---------------|
+| `==`         | `#!cpp false` |
+| `!=`         | `#!cpp true`  |
+| `<`          | `#!cpp false` |
+| `<=`         | `#!cpp true`  |
+| `>=`         | `#!cpp true`  |
+| `>`          | `#!cpp false` |
+
+Otherwise, comparisons involving at least one discarded JSON value always yield `#!cpp false`.
+
+## Default definition
+
+The default value is `0`.
+
+```cpp
+#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 0
+```
+
+When the macro is not defined, the library will define it to its default value.
+
+## Notes
+
+!!! warning "Inconsistent behavior in C++20 and beyond"
+
+    When targeting C++20 or above, enabling the legacy comparison behavior is _strongly_
+    discouraged.
+
+      - The 3-way comparison operator (`<=>`) will always give the correct result
+        (`#!cpp std::partial_ordering::unordered`) regardless of the value of
+        `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`.
+      - Overloads for the equality and relational operators emulate the legacy behavior.
+
+    Code outside your control may use either 3-way comparison or the equality and
+    relational operators, resulting in inconsistent and unpredictable behavior.
+
+    See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way
+    comparison.
+
+!!! warning "Deprecation"
+
+    The legacy comparison behavior is deprecated and may be removed in a future major
+    version release.
+
+    New code should not depend on it and existing code should try to remove or rewrite
+    expressions relying on it.
+
+## Version history
+
+- Added in version 3.11.0.