24 Iterators library [iterators]

24.4 Iterator primitives [iterator.primitives]

24.4.4 Range iterator operations [range.iter.ops]

24.4.4.1 General [range.iter.ops.general]

The library includes the function templates ranges::advance, ranges::distance, ranges::next, and ranges::prev to manipulate iterators.

These operations adapt to the set of operators provided by each iterator category to provide the most efficient implementation possible for a concrete iterator type.

[Example 1:

ranges::advance uses the + operator to move a random_access_iterator forward n steps in constant time.

For an iterator type that does not model random_access_iterator, ranges::advance instead performs n individual increments with the ++ operator.

— end example]

The function templates defined in [range.iter.ops] are not found by argument-dependent name lookup ([basic.lookup.argdep]).

When found by unqualified ([basic.lookup.unqual]) name lookup for the postfix-expression in a function call ([expr.call]), they inhibit argument-dependent name lookup.

[Example 2: void foo() { using namespace std::ranges; std::vector<int> vec{1,2,3}; distance(begin(vec), end(vec)); // #1 }

The function call expression at #1 invokes std::ranges::distance, not std::distance, despite that (a) the iterator type returned from begin(vec) and end(vec) may be associated with namespace std and (b) std::distance is more specialized ([temp.func.order]) than std::ranges::distance since the former requires its first two parameters to have the same type.

— end example]

The number and order of deducible template parameters for the function templates defined in [range.iter.ops] is unspecified, except where explicitly stated otherwise.