< cpp‎ | iterator
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
Iterator adaptors
Stream iterators
Iterator customization points
Iterator operations
Range access
Defined in header <iterator>
inline namespace /*unspecified*/ {

    inline constexpr /*unspecified*/ iter_move = /*unspecified*/;

(since C++20)
(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:
  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.

[edit] Expression-equivalent

Expression e is expression-equivalent to expression f, if e and f have the same effects, either are both potentially-throwing or are both not potentially-throwing (i.e. noexcept(e) == noexcept(f)), and either are both constant subexpressions or are both not constant subexpressions.

[edit] 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 (denoted, for exposition purposes, as iter_move_ftor). All instances of iter_move_ftor are equal. 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_ftor will satisfy std::invocable<const iter_move_ftor&, Args...>. Otherwise, no function call operator of iter_move_ftor participates in overload resolution.

[edit] See also

casts the result of dereferencing the adjusted underlying iterator to its associated rvalue reference type
(function template) [edit]
casts the result of dereferencing the underlying iterator to its associated rvalue reference type
(function template) [edit]