std::ranges::iter_move(3)

NAME
std::ranges::iter_move - std::ranges::iter_move

Synopsis
   Defined in header <iterator>
   inline namespace /*unspecified*/ {
   inline constexpr /*unspecified*/ iter_move = (since C++20)
   /*unspecified*/; (customization point object)
   }
   Call signature
   template< class T >
   requires /* see below */
   constexpr decltype(auto) iter_move( T&& t )
   noexcept(/* see below */);
   Obtains an rvalue reference or a prvalue temporary from a given iterator.
   A call to ranges::iter_move is expression-equivalent to:
    1. iter_move(std::forward<T>(t)), if std::remove_cvref_t<T> is a class or
       enumeration type and the expression is well-formed in unevaluated context, where
       the overload resolution is performed with the following candidates:
          * void iter_move();
          * any declarations of iter_move found by argument-dependent lookup.
    2. Otherwise, std::move(*std::forward<T>(t)) if *std::forward<T>(t) is well-formed
       and is an lvalue.
    3. Otherwise, *std::forward<T>(t) if *std::forward<T>(t) is well-formed and is an

rvalue.
   In all other cases, a call to ranges::iter_move is ill-formed, which can result in
   substitution failure when ranges::iter_move(e) appears in the immediate context of a
   template instantiation.
   If ranges::iter_move(e) is not equal to *e, the program is ill-formed, no diagnostic
   required.
  Expression-equivalent
   Expression e is expression-equivalent to expression f, if
     * e and f have the same effects, and
     * either both are constant subexpressions or else neither is a constant
       subexpression, and
     * either both are potentially-throwing or else neither is potentially-throwing
       (i.e. noexcept(e) == noexcept(f)).
  Customization point objects
   The name ranges::iter_move denotes a customization point object, which is a const
   function object of a literal semiregular class type. For exposition purposes, the
   cv-unqualified version of its type is denoted as __iter_move_fn.
   All instances of __iter_move_fn are equal. The effects of invoking different
   instances of type __iter_move_fn on the same arguments are equivalent, regardless of
   whether the expression denoting the instance is an lvalue or rvalue, and is
   const-qualified or not (however, a volatile-qualified instance is not required to be
   invocable). Thus, ranges::iter_move can be copied freely and its copies can be used
   interchangeably.
   Given a set of types Args..., if std::declval<Args>()... meet the requirements for
   arguments to ranges::iter_move above, __iter_move_fn models
     * std::invocable<__iter_move_fn, Args...>,
     * std::invocable<const __iter_move_fn, Args...>,
     * std::invocable<__iter_move_fn&, Args...>, and
     * std::invocable<const __iter_move_fn&, Args...>.
   Otherwise, no function call operator of __iter_move_fn participates in overload
   resolution.

See also
   iter_move casts the result of dereferencing the adjusted underlying iterator to its
   (C++20) associated rvalue reference type
             (function)
   iter_move casts the result of dereferencing the underlying iterator to its
   (C++20) associated rvalue reference type
             (function)