24 Iterators library [iterators]

24.5 Iterator adaptors [predef.iterators]

24.5.1 Reverse iterators [reverse.iterators]

24.5.1.1 General [reverse.iterators.general]

Class template reverse_iterator is an iterator adaptor that iterates from the end of the sequence defined by its underlying iterator to the beginning of that sequence.

24.5.1.2 Class template reverse_iterator [reverse.iterator]

🔗

namespace std { template<class Iterator> class reverse_iterator { public: using iterator_type = Iterator; using iterator_concept = see below; using iterator_category = see below; using value_type = iter_value_t<Iterator>; using difference_type = iter_difference_t<Iterator>; using pointer = typename iterator_traits<Iterator>::pointer; using reference = iter_reference_t<Iterator>; constexpr reverse_iterator(); constexpr explicit reverse_iterator(Iterator x); template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u); template<class U> constexpr reverse_iterator& operator=(const reverse_iterator<U>& u); constexpr Iterator base() const; constexpr reference operator*() const; constexpr pointer operator->() const requires see below; constexpr reverse_iterator& operator++(); constexpr reverse_iterator operator++(int); constexpr reverse_iterator& operator--(); constexpr reverse_iterator operator--(int); constexpr reverse_iterator operator+ (difference_type n) const; constexpr reverse_iterator& operator+=(difference_type n); constexpr reverse_iterator operator- (difference_type n) const; constexpr reverse_iterator& operator-=(difference_type n); constexpr unspecified operator[](difference_type n) const; friend constexpr iter_rvalue_reference_t<Iterator> iter_move(const reverse_iterator& i) noexcept(see below); template<indirectly_swappable<Iterator> Iterator2> friend constexpr void iter_swap(const reverse_iterator& x, const reverse_iterator<Iterator2>& y) noexcept(see below); protected: Iterator current; }; }

The member typedef-name iterator_concept denotes

(1.1)
random_access_iterator_tag if Iterator models random_access_iterator, and
(1.2)
bidirectional_iterator_tag otherwise.

The member typedef-name iterator_category denotes

(2.1)
random_access_iterator_tag if the type iterator_traits<Iterator>::iterator_category models derived_from<random_access_iterator_tag>, and
(2.2)
iterator_traits<Iterator>::iterator_category otherwise.

24.5.1.3 Requirements [reverse.iter.requirements]

The template parameter Iterator shall either meet the requirements of a Cpp17BidirectionalIterator ([bidirectional.iterators]) or model bidirectional_iterator ([iterator.concept.bidir]).

Additionally, Iterator shall either meet the requirements of a Cpp17RandomAccessIterator ([random.access.iterators]) or model random_access_iterator ([iterator.concept.random.access]) if the definitions of any of the members

(2.1)
operator+, operator-, operator+=, operator-= ([reverse.iter.nav]), or
(2.2)
operator[] ([reverse.iter.elem]),

or the non-member operators ([reverse.iter.cmp])

(2.3)
operator<, operator>, operator<=, operator>=, operator-, or operator+ ([reverse.iter.nonmember])

are instantiated ([temp.inst]).

24.5.1.4 Construction and assignment [reverse.iter.cons]

🔗

constexpr reverse_iterator();

Effects: Value-initializes current.

Iterator operations applied to the resulting iterator have defined behavior if and only if the corresponding operations are defined on a value-initialized iterator of type Iterator.

🔗

constexpr explicit reverse_iterator(Iterator x);

Effects: Initializes current with x.

🔗

template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u);

Constraints: is_same_v<U, Iterator> is false and const U& models convertible_to<Iterator>.

Effects: Initializes current with u.current.

🔗

template<class U>
  constexpr reverse_iterator&
    operator=(const reverse_iterator<U>& u);

Constraints: is_same_v<U, Iterator> is false, const U& models convertible_to<Iterator>, and assignable_from<Iterator&, const U&> is modeled.

Effects: Assigns u.current to current.

Returns: *this.

24.5.1.5 Conversion [reverse.iter.conv]

🔗

constexpr Iterator base() const;

Returns: current.

24.5.1.6 Element access [reverse.iter.elem]

🔗

constexpr reference operator*() const;

Effects: As if by: Iterator tmp = current; return *--tmp;

🔗

constexpr pointer operator->() const
  requires (is_pointer_v<Iterator> ||
            requires(const Iterator i) { i.operator->(); });

Effects:

(2.1)
If Iterator is a pointer type, equivalent to: return prev(current);
(2.2)
Otherwise, equivalent to: return prev(current).operator->();

🔗

constexpr unspecified operator[](difference_type n) const;

Returns: current[-n-1].

24.5.1.7 Navigation [reverse.iter.nav]

🔗

constexpr reverse_iterator operator+(difference_type n) const;

Returns: reverse_iterator(current-n).

🔗

constexpr reverse_iterator operator-(difference_type n) const;

Returns: reverse_iterator(current+n).

🔗

constexpr reverse_iterator& operator++();

Effects: As if by: --current;

Returns: *this.

🔗

constexpr reverse_iterator operator++(int);

Effects: As if by: reverse_iterator tmp = *this; --current; return tmp;

🔗

constexpr reverse_iterator& operator--();

Effects: As if by ++current.

Returns: *this.

🔗

constexpr reverse_iterator operator--(int);

Effects: As if by: reverse_iterator tmp = *this; ++current; return tmp;

🔗

constexpr reverse_iterator& operator+=(difference_type n);

Effects: As if by: current -= n;

Returns: *this.

🔗

constexpr reverse_iterator& operator-=(difference_type n);

Effects: As if by: current += n;

Returns: *this.

24.5.1.8 Comparisons [reverse.iter.cmp]

🔗

template<class Iterator1, class Iterator2>
  constexpr bool operator==(
    const reverse_iterator<Iterator1>& x,
    const reverse_iterator<Iterator2>& y);

Constraints: x.base() == y.base() is well-formed and convertible to bool.

Returns: x.base() == y.base().

🔗

template<class Iterator1, class Iterator2>
  constexpr bool operator!=(
    const reverse_iterator<Iterator1>& x,
    const reverse_iterator<Iterator2>& y);

Constraints: x.base() != y.base() is well-formed and convertible to bool.

Returns: x.base() != y.base().

🔗

template<class Iterator1, class Iterator2>
  constexpr bool operator<(
    const reverse_iterator<Iterator1>& x,
    const reverse_iterator<Iterator2>& y);

Constraints: x.base() > y.base() is well-formed and convertible to bool.

Returns: x.base() > y.base().

🔗

template<class Iterator1, class Iterator2>
  constexpr bool operator>(
    const reverse_iterator<Iterator1>& x,
    const reverse_iterator<Iterator2>& y);

Constraints: x.base() < y.base() is well-formed and convertible to bool.

Returns: x.base() < y.base().

🔗

template<class Iterator1, class Iterator2>
  constexpr bool operator<=(
    const reverse_iterator<Iterator1>& x,
    const reverse_iterator<Iterator2>& y);

Constraints: x.base() >= y.base() is well-formed and convertible to bool.

Returns: x.base() >= y.base().

🔗

template<class Iterator1, class Iterator2>
  constexpr bool operator>=(
    const reverse_iterator<Iterator1>& x,
    const reverse_iterator<Iterator2>& y);

Constraints: x.base() <= y.base() is well-formed and convertible to bool.

Returns: x.base() <= y.base().

🔗

template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
  constexpr compare_three_way_result_t<Iterator1, Iterator2>
    operator<=>(const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y);

Returns: y.base() <=> x.base().

[Note 1:

The argument order in the Returns: element is reversed because this is a reverse iterator.

— end note]

24.5.1.9 Non-member functions [reverse.iter.nonmember]

🔗

template<class Iterator1, class Iterator2>
  constexpr auto operator-(
    const reverse_iterator<Iterator1>& x,
    const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());

Returns: y.base() - x.base().

🔗

template<class Iterator>
  constexpr reverse_iterator<Iterator> operator+(
    iter_difference_t<Iterator> n,
    const reverse_iterator<Iterator>& x);

Returns: reverse_iterator<Iterator>(x.base() - n).

🔗

friend constexpr iter_rvalue_reference_t<Iterator>
  iter_move(const reverse_iterator& i) noexcept(see below);

Effects: Equivalent to: auto tmp = i.base(); return ranges::iter_move(--tmp);

Remarks: The exception specification is equivalent to: is_nothrow_copy_constructible_v<Iterator> && noexcept(ranges::iter_move(--declval<Iterator&>()))

🔗

template<indirectly_swappable<Iterator> Iterator2>
  friend constexpr void
    iter_swap(const reverse_iterator& x,
              const reverse_iterator<Iterator2>& y) noexcept(see below);

Effects: Equivalent to: auto xtmp = x.base(); auto ytmp = y.base(); ranges::iter_swap(--xtmp, --ytmp);

Remarks: The exception specification is equivalent to: is_nothrow_copy_constructible_v<Iterator> && is_nothrow_copy_constructible_v<Iterator2> && noexcept(ranges::iter_swap(--declval<Iterator&>(), --declval<Iterator2&>()))

🔗

template<class Iterator>
  constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);

Returns: reverse_iterator<Iterator>(i).