std::random_access_iterator

The concept random_access_iterator refines bidirectional_iterator by adding support for constant time advancement with the +=, +, -=, and - operators, constant time computation of distance with -, and array notation with subscripting []

Iterator concept determination

Definition of this concept is specified via an exposition-only alias template /*ITER_CONCEPT*/.

In order to determine /*ITER_CONCEPT*/<I>, let ITER_TRAITS<I> denote I if the specialization std::iterator_traits<I> is generated from the primary template, or std::iterator_traits<I>

• If ITER_TRAITS<I>::iterator_concept is valid and names a type, /*ITER_CONCEPT*/<I>
• Otherwise, if ITER_TRAITS<I>::iterator_category is valid and names a type, /*ITER_CONCEPT*/<I>
• Otherwise, if std::iterator_traits<I> is generated from the primary template, /*ITER_CONCEPT*/<I> denotes std::random_access_iterator_tag
• Otherwise, /*ITER_CONCEPT*/<I>

Semantic requirements

Let a and b be valid iterators of type I such that b is reachable from a, and let n be a value of type std::iter_difference_t<I> equal to b - a. std::random_access_iterator<I>

• (a += n) is equal to b
• std::addressof (a + = n) is equal to std::addressof(a). ^[1]
• (a + n) is equal to (a += n)
• (a + n) is equal to (n + a)
• For any two positive integers x and y, if a + (x + y) is valid, then a + (x + y) is equal to (a + x) + y
• a + 0 is equal to a.
• If (a + (n - 1)) is valid, then --b is equal to (a + (n - 1))
• (b += -n) and (b -= n) are both equal to a
• std::addressof (b - = n) is equal to std::addressof(b). ^[1]
• (b - n) is equal to (b -= n)
• If b is dereferenceable, then a[n] is valid and is equal to *b
• bool(a <= b) is true
• Every required operation has constant time complexity.

Note that std::addressof returns the address of the iterator object, not the address of the object the iterator points to. I.e. operator+= and operator-= must return a reference to *this

Equality preservation

Expressions declared in requires expressions of the standard library concepts are required to be equality-preserving

Implicit expression variations

A requires expression that uses an expression that is non-modifying for some constant lvalue operand also requires implicit expression variations

Notes

Unlike the LegacyRandomAccessIterator requirements, the random_access_iterator

Example

#include <iterator>
 
namespace cxx20
{
    template<std::input_or_output_iterator Iter>
    constexpr std::iter_difference_t<Iter> distance(Iter first, Iter last)
    {
        if constexpr(std::random_access_iterator<Iter>)
            return last - first;
        else
        {
            std::iter_difference_t<Iter> result{};
            for (; first != last; ++first)
                ++result;
            return result;
        }
    }
}
 
int main()
{
    static constexpr auto il = {3, 1, 4};
 
    static_assert(std::random_access_iterator<decltype(il.begin())> &&
                  cxx20::distance(il.begin(), il.end()) == 3 &&
                  cxx20::distance(il.end(), il.begin()) == -3);
}

See also