< 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>
namespace ranges {

    inline namespace /*unspecified*/ {
        inline constexpr /*unspecified*/ iter_swap = /*unspecified*/;

(since C++20)
(customization point object)
Call signature
template< class I1, class I2 >
constexpr void iter_swap( I1&& i1, I2&& i2 ) noexcept(/* see below */);
(since C++20)

Swaps values denoted by two iterators.

ranges::iter_swap(i1, i2) is expression-equivalent to:

  1. (void)iter_swap(i1, i2), if std::remove_cvref_t<I1> or std::remove_cvref_t<I2> is a class or enumeration type and the expression is well-formed, where the overload resolution is performed within namespace std::ranges with the additional candidate:
    • void iter_swap(auto, auto) = delete;
    If the selected overload does not exchange the value denoted by i1 and i2, the program is ill-formed, no diagnostic required.
  2. Otherwise, ranges::swap(*i1, *i2) if both I1 and I2 model indirectly_readable and if std::iter_reference_t<I1> and std::iter_reference_t<I2> model swappable_with.
  3. Otherwise, (void)(*i1 = /*iter_exchange_move*/(i2, i1)), if std::indirectly_movable_storable<I1, I2> and std::indirectly_movable_storable<I2, I1>, where iter_exchange_move is an exposition-only function template described below (and i1 is only evaluated once).
  4. Otherwise, ranges::iter_swap(i1, i2) is ill-formed, which can result in substitution failure when ranges::iter_swap(e1, e2) appears in the immediate context of a template instantiation.

The exposition-only function template iter_exchange_move is defined the equivalent of:

template<class X, class Y>
constexpr std::iter_value_t<X> /*iter_exchange_move*/(X&& x, Y&& y)
    noexcept(noexcept(std::iter_value_t<X>(std::ranges::iter_move(x)) &&
             noexcept(*x = std::ranges::iter_move(y))))
    std::iter_value_t<X> old(std::ranges::iter_move(x));
    *x = std::ranges::iter_move(y);
    return old;

[edit] 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)).

[edit] Customization point objects

The name ranges::iter_swap 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_swap_fn.

All instances of __iter_swap_fn are equal. The effects of invoking different instances of type __iter_swap_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_swap 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_swap above, __iter_swap_fn models

Otherwise, no function call operator of __iter_swap_fn participates in overload resolution.

[edit] See also

swaps the objects pointed to by two adjusted underlying iterators
(function template) [edit]
swaps the objects pointed to by two underlying iterators
(function template) [edit]
swaps the elements pointed to by two iterators
(function template) [edit]