Use std::strong_order for total_less and total_greater when possible

Author: Morwenn

docs/Changelog.md

@@ -11,6 +11,11 @@ While **cpp-sort** theoretically requires a fully C++17-compliant compiler, a fe
 
 When compiled with C++20, **cpp-sort** might gain a few additional features depending on the level of C++20 support provided by the compiler. The availability of those features depends on the presence of corresponding [feature-testing macros][feature-test-macros] when possible, even though some checks are more granular. Don't hesitate to open an issue if your compiler and standard library supports one of those features but it doesn't seem to work in **cpp-sort**.
 
+**Correctness improvements:**
+* When possible, the total order predicates [`total_less` and `total_greater`][total-greater-less] use [`std::strong_order`][std-strong-order] to compare floating-point numbers, leading to a supposedly correct implementation of the IEEE *totalOrder* operator. In C++17 and earlier, those comparators don't actually implement a proper total order: they are unable to differentiate between quiet and signaling NaNs, and connot read NaN payloads.
+
+    The feature-test macro `__cpp_lib_three_way_comparison` can be used to check whether `std::strong_order` is available.
+
 **New features:**
 * When available, [`std::identity`][std-identity] benefits from dedicated support wherever [`utility::identity`][cpp-sort-function-objects] is supported, with equivalent semantics.
 
@@ -50,5 +55,7 @@ When compiled with C++20, **cpp-sort** might gain a few additional features depe
   [std-mem-fn]: https://en.cppreference.com/w/cpp/utility/functional/mem_fn
   [std-ranges-greater]: https://en.cppreference.com/w/cpp/utility/functional/ranges/greater
   [std-ranges-less]: https://en.cppreference.com/w/cpp/utility/functional/ranges/less
+  [std-strong-order]: https://en.cppreference.com/w/cpp/utility/compare/strong_order
   [std-swap]: https://en.cppreference.com/w/cpp/algorithm/swap
+  [total-greater-less]: Comparators.md#total-order-comparators
   [utility-iter-move]: Miscellaneous-utilities.md#iter_move-and-iter_swap

docs/Comparators.md

@@ -9,7 +9,7 @@ Every non-refined comparator described below is also a [transparent comparator][
 #include <cpp-sort/comparators/total_less.h>
 ```
 
-The comparators `total_less` and `total_order` are [customization points][custom-point] implementing a [total order][total-order], inspired by the similar functions described in [P0100][P0100]. The provided functions handle built-in integer out of the box (using the built-in relational operators) and implement IEEE 754's `totalOrder` for floating point numbers (from lesser to greater):
+The comparators `total_less` and `total_order` are [customization points][custom-point] implementing a [total order][total-order], inspired by the similar functions described in [P0100][P0100]. The provided functions handle built-in integer types out of the box (using the built-in relational operators) and attempt to implement IEEE 754's `totalOrder` for floating point numbers (from lesser to greater):
 * positive quiet NaNs
 * positive signaling NaNs
 * positive infinity
@@ -21,10 +21,14 @@ The comparators `total_less` and `total_order` are [customization points][custom
 * negative signaling NaNs
 * negative quiet NaNs
 
-That said, the comparators are currently unable to discriminate between quiet and signaling NaNs, so they are considered to be *equivalent*. When it doesn't handle a type natively and ADL doesn't find any suitable `total_less` function in a class namespace, `cppsort::total_less` does *not* fall back to `operator<`; see [P0100][P0100] for the rationale (it applies to the whole `total_*` family of customization points).
+That said, the comparators are unable to discriminate between quiet and signaling NaNs, and have no way to inspect the bit patterns of NaNs to compare them. All NaNs that share a same sign are therefore considered to be *equivalent* in C++17. In C++20 however, the comparators rely on [`std::strong_order`][std-strong-order] when available, which correctly implements `totalOrder` for IEEE 754 floating point numbers.
+
+When it doesn't handle a type natively and ADL doesn't find any suitable `total_less` function in a class namespace, `cppsort::total_less` does *not* fall back to `operator<`; see [P0100][P0100] for the rationale (it applies to the whole `total_*` family of customization points).
 
 Total order comparators are considered as [generating branchless code][branchless-traits] when comparing instances of a type that satisfies [`std::is_integral`][std-is-integral].
 
+*Changed in version 2.1.0:* `total_less` and `total_greater` now correctly implement IEEE 754 `totalOrder` in C++20 mode, when the featur-test macro `__cpp_lib_three_way_comparison` is defined.
+
 ### Weak order comparators
 
 ```cpp

include/cpp-sort/comparators/total_greater.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016-2025 Morwenn
+ * Copyright (c) 2016-2026 Morwenn
  * SPDX-License-Identifier: MIT
  */
 #ifndef CPPSORT_COMPARATORS_TOTAL_GREATER_H_
@@ -8,13 +8,18 @@
 ////////////////////////////////////////////////////////////
 // Headers
 ////////////////////////////////////////////////////////////
-#include <cmath>
 #include <type_traits>
 #include <utility>
 #include <cpp-sort/utility/branchless_traits.h>
-#include "../detail/floating_point_weight.h"
 #include "../detail/type_traits.h"
 
+#if defined(__cpp_lib_three_way_comparison)
+#   include <compare>
+#else
+#   include <cmath>
+#   include "../detail/floating_point_weight.h"
+#endif
+
 namespace cppsort
 {
     namespace detail
@@ -36,6 +41,11 @@ namespace cppsort
         auto total_greater(T lhs, T rhs)
             -> detail::enable_if_t<std::is_floating_point_v<T>, bool>
         {
+#if defined(__cpp_lib_three_way_comparison)
+            // Full implementation of totalOrder
+            return std::is_gt(std::strong_order(lhs, rhs));
+#else
+            // Approximation, unable to differentiate NaNs
             if (std::isfinite(lhs) && std::isfinite(rhs)) {
                 if (lhs == 0 && rhs == 0) {
                     return std::signbit(rhs) && not std::signbit(lhs);
@@ -46,6 +56,7 @@ namespace cppsort
             int lhs_weight = total_weight(lhs);
             int rhs_weight = total_weight(rhs);
             return lhs_weight > rhs_weight;
+#endif
         }
 
         ////////////////////////////////////////////////////////////

include/cpp-sort/comparators/total_less.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016-2025 Morwenn
+ * Copyright (c) 2016-2026 Morwenn
  * SPDX-License-Identifier: MIT
  */
 #ifndef CPPSORT_COMPARATORS_TOTAL_LESS_H_
@@ -11,10 +11,17 @@
 #include <cmath>
 #include <type_traits>
 #include <utility>
+#include <version>
 #include <cpp-sort/utility/branchless_traits.h>
-#include "../detail/floating_point_weight.h"
 #include "../detail/type_traits.h"
 
+#if defined(__cpp_lib_three_way_comparison)
+#   include <compare>
+#else
+#   include <cmath>
+#   include "../detail/floating_point_weight.h"
+#endif
+
 namespace cppsort
 {
     namespace detail
@@ -36,6 +43,11 @@ namespace cppsort
         auto total_less(T lhs, T rhs)
             -> detail::enable_if_t<std::is_floating_point_v<T>, bool>
         {
+#if defined(__cpp_lib_three_way_comparison)
+            // Full implementation of totalOrder
+            return std::is_lt(std::strong_order(lhs, rhs));
+#else
+            // Approximation, unable to differentiate NaNs
             if (std::isfinite(lhs) && std::isfinite(rhs)) {
                 if (lhs == 0 && rhs == 0) {
                     return std::signbit(lhs) && not std::signbit(rhs);
@@ -46,6 +58,7 @@ namespace cppsort
             int lhs_weight = total_weight(lhs);
             int rhs_weight = total_weight(rhs);
             return lhs_weight < rhs_weight;
+#endif
         }
 
         ////////////////////////////////////////////////////////////