[libc++] Add std::ranges::iter_move and std::iter_rvalue_reference_t

Original patch by @cjdb, modified by @ldionne.

Differential Revision: https://reviews.llvm.org/D99873

Author: ldionne

libcxx/include/CMakeLists.txt

@@ -12,8 +12,9 @@ set(files
   __functional_base_03
   __hash_table
   __iterator/concepts.h
-  __iterator/iterator_traits.h
   __iterator/incrementable_traits.h
+  __iterator/iter_move.h
+  __iterator/iterator_traits.h
   __iterator/readable_traits.h
   __libcpp_version
   __locale

libcxx/include/__iterator/iter_move.h

@@ -0,0 +1,90 @@
+// -*- 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___ITERATOR_ITER_MOVE_H
+#define _LIBCPP___ITERATOR_ITER_MOVE_H
+
+#include <__config>
+#include <__iterator/concepts.h>
+#include <concepts> // __class_or_enum
+#include <type_traits>
+#include <utility>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#pragma GCC system_header
+#endif
+
+_LIBCPP_PUSH_MACROS
+#include <__undef_macros>
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+#if !defined(_LIBCPP_HAS_NO_RANGES)
+
+namespace ranges::__iter_move {
+void iter_move();
+
+template<class _Ip>
+concept __unqualified_iter_move = requires(_Ip&& __i) {
+    iter_move(_VSTD::forward<_Ip>(__i));
+};
+
+// [iterator.cust.move]/1
+// The name ranges::iter_move denotes a customization point object.
+// The expression ranges::iter_move(E) for a subexpression E is
+// expression-equivalent to:
+struct __fn {
+  // [iterator.cust.move]/1.1
+  // iter_move(E), if E has class or enumeration type and iter_move(E) is a
+  // well-formed expression when treated as an unevaluated operand, [...]
+  template<class _Ip>
+    requires __class_or_enum<remove_cvref_t<_Ip>> && __unqualified_iter_move<_Ip>
+  [[nodiscard]] constexpr decltype(auto) operator()(_Ip&& __i) const
+    noexcept(noexcept(iter_move(_VSTD::forward<_Ip>(__i))))
+  {
+    return iter_move(_VSTD::forward<_Ip>(__i));
+  }
+
+  // [iterator.cust.move]/1.2
+  // Otherwise, if the expression *E is well-formed:
+  //  1.2.1 if *E is an lvalue, std::move(*E);
+  //  1.2.2 otherwise, *E.
+  template<class _Ip>
+    requires (!(__class_or_enum<remove_cvref_t<_Ip>> && __unqualified_iter_move<_Ip>)) &&
+    requires(_Ip&& __i) { *_VSTD::forward<_Ip>(__i); }
+  [[nodiscard]] constexpr decltype(auto) operator()(_Ip&& __i) const
+    noexcept(noexcept(*_VSTD::forward<_Ip>(__i)))
+  {
+    if constexpr (is_lvalue_reference_v<decltype(*_VSTD::forward<_Ip>(__i))>) {
+      return _VSTD::move(*_VSTD::forward<_Ip>(__i));
+    } else {
+      return *_VSTD::forward<_Ip>(__i);
+    }
+  }
+
+  // [iterator.cust.move]/1.3
+  // Otherwise, ranges::iter_move(E) is ill-formed.
+};
+} // namespace ranges::__iter_move
+
+namespace ranges::inline __cpo {
+  inline constexpr auto iter_move = __iter_move::__fn{};
+}
+
+template<__dereferenceable _Tp>
+requires requires(_Tp& __t) { { ranges::iter_move(__t) } -> __referenceable; }
+using iter_rvalue_reference_t = decltype(ranges::iter_move(declval<_Tp&>()));
+
+#endif // !_LIBCPP_HAS_NO_RANGES
+
+_LIBCPP_END_NAMESPACE_STD
+
+_LIBCPP_POP_MACROS
+
+#endif // _LIBCPP___ITERATOR_ITER_MOVE_H

libcxx/include/concepts

@@ -246,14 +246,16 @@ concept copy_constructible =
   constructible_from<_Tp, const _Tp&> && convertible_to<const _Tp&, _Tp> &&
   constructible_from<_Tp, const _Tp> && convertible_to<const _Tp, _Tp>;
 
+// Whether a type is a class type or enumeration type according to the Core wording.
+template<class _Tp>
+concept __class_or_enum = is_class_v<_Tp> || is_union_v<_Tp> || is_enum_v<_Tp>;
+
 // [concept.swappable]
 namespace ranges::__swap {
   // Deleted to inhibit ADL
   template<class _Tp>
   void swap(_Tp&, _Tp&) = delete;
 
-  template<class _Tp>
-  concept __class_or_enum = is_class_v<_Tp> || is_union_v<_Tp> || is_enum_v<_Tp>;
 
   // [1]
   template<class _Tp, class _Up>
@@ -440,7 +442,7 @@ concept equivalence_relation = relation<_Rp, _Tp, _Up>;
 template<class _Rp, class _Tp, class _Up>
 concept strict_weak_order = relation<_Rp, _Tp, _Up>;
 
-#endif //_LIBCPP_STD_VER > 17 && !defined(_LIBCPP_HAS_NO_CONCEPTS)
+#endif // _LIBCPP_STD_VER > 17 && !defined(_LIBCPP_HAS_NO_CONCEPTS)
 
 _LIBCPP_END_NAMESPACE_STD
 

libcxx/include/iterator

@@ -35,6 +35,14 @@ struct iterator_traits<T*>;
 template<dereferenceable T>
   using iter_reference_t = decltype(*declval<T&>());
 
+namespace ranges::inline unspecified {
+    inline constexpr unspecified iter_move = unspecified; // since C++20, nodiscard as an extension
+}}
+
+template<dereferenceable T>
+  requires ...
+using iter_rvalue_reference_t = decltype(ranges::iter_move(declval<T&>())); // since C++20
+
 template<class Category, class T, class Distance = ptrdiff_t,
          class Pointer = T*, class Reference = T&>
 struct iterator
@@ -422,6 +430,7 @@ template <class E> constexpr const E* data(initializer_list<E> il) noexcept;
 #include <cstddef>
 #include <initializer_list>
 #include <__iterator/incrementable_traits.h>
+#include <__iterator/iter_move.h>
 #include <__iterator/iterator_traits.h>
 #include <__iterator/readable_traits.h>
 #include <__memory/addressof.h>

libcxx/test/std/iterators/iterator.requirements/iterator.cust/iterator.cust.move/iter_move.nodiscard.verify.cpp

@@ -0,0 +1,38 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+// UNSUPPORTED: gcc-10
+
+// Test the [[nodiscard]] extension in libc++.
+// REQUIRES: libc++
+
+// template<class I>
+// unspecified iter_move;
+
+#include <iterator>
+
+struct WithADL {
+  WithADL() = default;
+  constexpr decltype(auto) operator*() const noexcept;
+  constexpr WithADL& operator++() noexcept;
+  constexpr void operator++(int) noexcept;
+  constexpr bool operator==(WithADL const&) const noexcept;
+  friend constexpr auto iter_move(WithADL&) { return 0; }
+};
+
+int main(int, char**) {
+  int* noADL = nullptr;
+  std::ranges::iter_move(noADL); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+
+  WithADL adl;
+  std::ranges::iter_move(adl); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+
+  return 0;
+}