std::ranges::iter_move(3) | C++ Standard Libary | 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)*

2022.07.31 | http://cppreference.com |