[libc++] [P1614] Implement std::compare_three_way.

[• Quuxplusone]

Summary

std::strong_order() etc. depend on this. Let's get this shipped!

[rarutyun]

libcxx/test/std/utilities/function.objects/comparisons/compare_three_way.pass.cpp

10

Some steps in CI failed. I believe adding // UNSUPPORTED: libcpp-no-concepts should help

34

Why do we check std::compare_three_way_result_t in this test?

47

I would suggest to also test for std::partial_ordering::unordered and also add some tests for weak_ordering

50

For heterogeneous case does it make sense to put int and double in reverse order?

[rarutyun]

Should we add test to check availability from <functional> header or it's already covered by this one libcxx/test/std/utilities/function.objects/comparisons/transparent.pass.cpp?

[Mordante]

libcxx/include/__compare/compare_three_way.h

30

Nit: s/_LIBCPP_INLINE_VISIBILITY/_LIBCPP_HIDE_FROM_ABI/

32

The Standard doesn't specify the noexcept, is this added intentionally?

libcxx/test/std/utilities/function.objects/comparisons/compare_three_way.pass.cpp

47

+1

libcxx/test/std/utilities/function.objects/comparisons/transparent.pass.cpp

60 ↗

(On Diff #375952)

Nit: the empty string isn't required in C++20.

[• Quuxplusone]

Address review comments; add test for <functional>.

libcxx/include/__compare/compare_three_way.h

32

Yes, for consistency with std::less<void> etc.
https://eel.is/c++draft/function.objects#comparisons doesn't put the conditional-noexcept on those either, but libc++ does. (That is, libc++ puts conditional-noexcept only on the transparent less<void>; not on less<T>.)

libcxx/test/std/utilities/function.objects/comparisons/compare_three_way.pass.cpp

34

Just sanity-checking. NotThreeWayComparable is an example of a type where it is legal to ask for its compare_three_way_result_t, but in fact if you try to call compare_three_way on it, it doesn't compile. (But the actual relevant test is down on line 64; I should move them closer together, but I have no good idea how to.)

libcxx/test/std/utilities/function.objects/comparisons/transparent.pass.cpp

60 ↗

(On Diff #375952)

Yeah, but consistency with the earlier lines (including the wonky spacing).

[Mordante]

LGTM!

[ldionne]

libcxx/include/functional

139

[ldionne]

LGTM but I have a nitpick fix (see comment) and please poke CI!

[• Quuxplusone]

Update comment and poke buildkite.

[• Quuxplusone]

Remove // -*- C++ -*- comment from generated file.

[• Quuxplusone]

libcxx/test/std/utilities/function.objects/comparisons/transparent.pass.cpp

61 ↗

(On Diff #378337)

Bother. @ldionne, is there anything clever we could do here, to avoid splitting this one line out into a separate test marked UNSUPPORTED: libcpp-no-concepts? I'll split it out if I need to, but I'm hoping that there's a clever approach I'm forgetting about.
std::compare_three_way does not exist unless !defined(_LIBCPP_HAS_NO_CONCEPTS).

[• Quuxplusone]

Split out the is_transparent test into its own file; mark it UNSUPPORTED: libcpp-no-concepts.
I'm expecting this to pass buildkite, and then land it tonight or tomorrow.

libcxx/docs/Status/SpaceshipProjects.csv

 Section,Description,Dependencies,Assignee,Complete
 | `[cmp.concept] <https://wg21.link/cmp.concept>`_,"| `three_way_comparable <https://reviews.llvm.org/D103478>`_
 | `three_way_comparable_with <https://reviews.llvm.org/D103478>`_",None,Ruslan Arutyunyan,|In Progress|
 | `[cmp.result] <https://wg21.link/cmp.result>`_,| `compare_three_way_result <https://reviews.llvm.org/D103581>`_,None,Arthur O'Dwyer,|Complete|
 | `[expos.only.func] <https://wg21.link/expos.only.func>`_,"| `synth-three-way <https://reviews.llvm.org/D107721>`_
 | `synth-three-way-result <https://reviews.llvm.org/D107721>`_",[cmp.concept],Kent Ross,|Complete|
-| `[comparisons.three.way] <https://wg21.link/comparisons.three.way>`_,| `compare_three_way <https://reviews.llvm.org/D80899>`_,[cmp.concept],Christopher Di Bella,|In Progress|
+| `[comparisons.three.way] <https://wg21.link/comparisons.three.way>`_,| `compare_three_way <https://reviews.llvm.org/D80899>`_,[cmp.concept],Arthur O'Dwyer,|Complete|
 | `[cmp.alg] <https://wg21.link/cmp.alg>`_,"| `strong_order <https://reviews.llvm.org/D107036>`_
 | `weak_order <https://reviews.llvm.org/D107036>`_
 | `partial_order <https://reviews.llvm.org/D107036>`_",None,Arthur O'Dwyer,|In Progress|
 | `[alg.three.way] <https://wg21.link/alg.three.way>`_,| `lexicographical_compare_three_way <https://reviews.llvm.org/D80902>`_,[comparisons.three.way],Christopher Di Bella,|In Progress|
 | `[coroutine.handle.compare] <https://wg21.link/coroutine.handle.compare>`_,| coroutine_handle,[comparisons.three.way],Unassigned,|Not Started|
 | `[pairs.spec] <https://wg21.link/pairs.spec>`_,| `pair <https://reviews.llvm.org/D107721>`_,[expos.only.func],Kent Ross,|Complete|
 | `[syserr.errcat.nonvirtuals] <https://wg21.link/syserr.errcat.nonvirtuals>`_,| error_category,[comparisons.three.way],Unassigned,|Not Started|
 | `[syserr.compare] <https://wg21.link/syserr.compare>`_,"| error_code

libcxx/include/CMakeLists.txt

set(files
   __bit/bit_cast.h
   __bits
   __bsd_locale_defaults.h
   __bsd_locale_fallbacks.h
   __charconv/chars_format.h
   __charconv/from_chars_result.h
   __charconv/to_chars_result.h
   __compare/common_comparison_category.h
+  __compare/compare_three_way.h
   __compare/compare_three_way_result.h
   __compare/is_eq.h
   __compare/ordering.h
   __compare/synth_three_way.h
   __compare/three_way_comparable.h
   __concepts/arithmetic.h
   __concepts/assignable.h
   __concepts/boolean_testable.h

libcxx/include/__compare/compare_three_way.h

+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBCPP___COMPARE_COMPARE_THREE_WAY_H
+#define _LIBCPP___COMPARE_COMPARE_THREE_WAY_H
+
+#include <__config>
+#include <__compare/three_way_comparable.h>
+#include <__utility/forward.h>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#pragma GCC system_header
+#endif
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+#if _LIBCPP_STD_VER > 17 && !defined(_LIBCPP_HAS_NO_SPACESHIP_OPERATOR) && !defined(_LIBCPP_HAS_NO_CONCEPTS)
+
+struct _LIBCPP_TEMPLATE_VIS compare_three_way
+{
+    template<class _T1, class _T2>
+        requires three_way_comparable_with<_T1, _T2>
+    constexpr _LIBCPP_HIDE_FROM_ABI
+    auto operator()(_T1&& __t, _T2&& __u) const
+        noexcept(noexcept(_VSTD::forward<_T1>(__t) <=> _VSTD::forward<_T2>(__u)))
+        { return          _VSTD::forward<_T1>(__t) <=> _VSTD::forward<_T2>(__u); }
+
+    using is_transparent = void;
+};
+
+#endif // _LIBCPP_STD_VER > 17 && !defined(_LIBCPP_HAS_NO_SPACESHIP_OPERATOR) && !defined(_LIBCPP_HAS_NO_CONCEPTS)
+
+_LIBCPP_END_NAMESPACE_STD
+
+#endif // _LIBCPP___COMPARE_COMPARE_THREE_WAY_H

libcxx/include/compare

template<class T, class U, class Cat = partial_ordering>
     concept three_way_comparable_with = see below;
 
   // [cmp.result], result of three-way comparison
   template<class T, class U = T> struct compare_three_way_result;
 
   template<class T, class U = T>
     using compare_three_way_result_t = typename compare_three_way_result<T, U>::type;
 
+  // [comparisons.three.way], class compare_three_way
+  struct compare_three_way; // C++20
+
   // [cmp.alg], comparison algorithms
   template<class T> constexpr strong_ordering strong_order(const T& a, const T& b);
   template<class T> constexpr weak_ordering weak_order(const T& a, const T& b);
   template<class T> constexpr partial_ordering partial_order(const T& a, const T& b);
 
   // [cmp.partialord], Class partial_ordering
   class partial_ordering {
   public:
public:
     friend constexpr bool operator>=(unspecified, strong_ordering v) noexcept;
     friend constexpr strong_ordering operator<=>(strong_ordering v, unspecified) noexcept;
     friend constexpr strong_ordering operator<=>(unspecified, strong_ordering v) noexcept;
   };
 }
 */
 
 #include <__compare/common_comparison_category.h>
+#include <__compare/compare_three_way.h>
 #include <__compare/compare_three_way_result.h>
 #include <__compare/is_eq.h>
 #include <__compare/ordering.h>
 #include <__compare/three_way_comparable.h>
 #include <__config>
 
 #ifndef _LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER
 #pragma GCC system_header

libcxx/include/functional

struct greater_equal {
     bool operator()(const T& x, const T& y) const;
 };
 
 template <class T> // <class T=void> in C++14
 struct less_equal {
     bool operator()(const T& x, const T& y) const;
 };
 
+// [comparisons.three.way], class compare_three_way
+struct compare_three_way;
+
 template <class T> // <class T=void> in C++14
 struct logical_and {
     bool operator()(const T& x, const T& y) const;
 };
 
 template <class T> // <class T=void> in C++14
 struct logical_or {
     bool operator()(const T& x, const T& y) const;

 
 POLICY:  For non-variadic implementations, the number of arguments is limited
          to 3.  It is hoped that the need for non-variadic implementations
          will be minimal.
 
 */
 
 #include <__algorithm/search.h>
+#include <__compare/compare_three_way.h>
 #include <__config>
 #include <__debug>
 #include <__functional/binary_function.h> // TODO: deprecate
 #include <__functional/binary_negate.h>
 #include <__functional/bind_back.h>
 #include <__functional/bind_front.h>
 #include <__functional/bind.h>
 #include <__functional/binder1st.h>

libcxx/include/module.modulemap

module codecvt {
     export *
   }
   module compare {
     header "compare"
     export *
 
     module __compare {
       module common_comparison_category { private header "__compare/common_comparison_category.h" }
+      module compare_three_way          { private header "__compare/compare_three_way.h"          }
       module compare_three_way_result   { private header "__compare/compare_three_way_result.h"   }
       module is_eq                      { private header "__compare/is_eq.h"                      }
       module ordering                   { private header "__compare/ordering.h"                   }
       module synth_three_way            { private header "__compare/synth_three_way.h"            }
       module three_way_comparable       { private header "__compare/three_way_comparable.h"       }
     }
   }
   module complex {

libcxx/test/libcxx/diagnostics/detail.headers/compare/compare_three_way.module.verify.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// REQUIRES: modules-build
+
+// WARNING: This test was generated by 'generate_private_header_tests.py'
+// and should not be edited manually.
+
+// expected-error@*:* {{use of private header from outside its module: '__compare/compare_three_way.h'}}
+#include <__compare/compare_three_way.h>

libcxx/test/std/utilities/function.objects/comparisons/compare_three_way.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17
+// UNSUPPORTED: libcpp-no-concepts
+
+// <compare>
+// <functional>
+
+// compare_three_way
+
+#include <compare>
+#include <cassert>
+#include <limits>
+#include <type_traits>
+
+#include "pointer_comparison_test_helper.h"
+
+template<class T, class U>
+constexpr auto test_sfinae(T t, U u)
+    -> decltype(std::compare_three_way()(t, u), std::true_type{})
+    { return std::true_type{}; }
+
+constexpr auto test_sfinae(...)
+    { return std::false_type{}; }
+
+struct NotThreeWayComparable {
+    std::strong_ordering operator<=>(const NotThreeWayComparable&) const;
+};
+ASSERT_SAME_TYPE(std::compare_three_way_result_t<NotThreeWayComparable>, std::strong_ordering);
+static_assert(!std::three_way_comparable<NotThreeWayComparable>);  // it lacks operator==
+
+struct WeaklyOrdered {
+    int i;
+    friend constexpr std::weak_ordering operator<=>(const WeaklyOrdered&, const WeaklyOrdered&) = default;
+};
+
+constexpr bool test()
+{
+    ASSERT_SAME_TYPE(decltype(std::compare_three_way()(1, 1)), std::strong_ordering);
+    assert(std::compare_three_way()(1, 2) == std::strong_ordering::less);
+    assert(std::compare_three_way()(1, 1) == std::strong_ordering::equal);
+    assert(std::compare_three_way()(2, 1) == std::strong_ordering::greater);
+
+    ASSERT_SAME_TYPE(decltype(std::compare_three_way()(WeaklyOrdered{1}, WeaklyOrdered{2})), std::weak_ordering);
+    assert(std::compare_three_way()(WeaklyOrdered{1}, WeaklyOrdered{2}) == std::weak_ordering::less);
+    assert(std::compare_three_way()(WeaklyOrdered{1}, WeaklyOrdered{1}) == std::weak_ordering::equivalent);
+    assert(std::compare_three_way()(WeaklyOrdered{2}, WeaklyOrdered{1}) == std::weak_ordering::greater);
+
+    ASSERT_SAME_TYPE(decltype(std::compare_three_way()(1.0, 1.0)), std::partial_ordering);
+    double nan = std::numeric_limits<double>::quiet_NaN();
+    assert(std::compare_three_way()(1.0, 2.0) == std::partial_ordering::less);
+    assert(std::compare_three_way()(1.0, 1.0) == std::partial_ordering::equivalent);
+    assert(std::compare_three_way()(2.0, 1.0) == std::partial_ordering::greater);
+    assert(std::compare_three_way()(nan, nan) == std::partial_ordering::unordered);
+
+    // Try heterogeneous comparison.
+    ASSERT_SAME_TYPE(decltype(std::compare_three_way()(42.0, 42)), std::partial_ordering);
+    assert(std::compare_three_way()(42.0, 42) == std::partial_ordering::equivalent);
+    ASSERT_SAME_TYPE(decltype(std::compare_three_way()(42, 42.0)), std::partial_ordering);
+    assert(std::compare_three_way()(42, 42.0) == std::partial_ordering::equivalent);
+
+    return true;
+}
+
+int main(int, char**)
+{
+    test();
+    static_assert(test());
+
+    do_pointer_comparison_test(std::compare_three_way());
+
+    static_assert(test_sfinae(1, 2));
+    static_assert(!test_sfinae(1, nullptr));
+    static_assert(!test_sfinae(NotThreeWayComparable(), NotThreeWayComparable()));
+
+    return 0;
+}

libcxx/test/std/utilities/function.objects/comparisons/compare_three_way_functional.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17
+// UNSUPPORTED: libcpp-no-concepts
+
+// <functional>
+
+// Test that std::compare_three_way is defined in <functional>,
+// not only in <compare>.
+
+#include <functional>
+#include <cassert>
+
+int main(int, char**)
+{
+    assert(std::compare_three_way()(1, 2) < 0);
+    assert(std::compare_three_way()(1, 1) == 0);
+    assert(std::compare_three_way()(2, 1) > 0);
+
+    return 0;
+}

libcxx/test/std/utilities/function.objects/comparisons/transparent_three_way.compile.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17
+// UNSUPPORTED: libcpp-no-concepts
+
+#include <functional>
+
+template<class T>
+concept Transparent = requires {
+    typename T::is_transparent;
+};
+
+static_assert(Transparent<std::compare_three_way>);