[reverse.iterators] (original) (raw)

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_category denotes

random_access_iterator_tag if the typeiterator_traits<Iterator>::iterator_category modelsderived_from<random_access_iterator_tag>, and
iterator_traits<Iterator>::iterator_category otherwise.

24.5.1.3 Requirements [reverse.iter.requirements]

Additionally,Iteratorshall either meet the requirements of a_Cpp17RandomAccessIterator_ ([random.access.iterators]) or modelrandom_access_iterator ([iterator.concept.random.access]) if the definitions of any of the members

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

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

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

are instantiated ([temp.inst]).

24.5.1.4 Construction and assignment [reverse.iter.cons]

constexpr reverse_iterator();

Effects: Value-initializescurrent.

constexpr explicit reverse_iterator(Iterator x);

Effects: Initializescurrentwith x.

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

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

Effects: Initializescurrentwithu.current.

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

Effects: Assigns u.current to 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:

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

constexpr _unspecified_ operator[](difference_type n) const;

Returns: current[-n - 1].

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;

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.

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;

constexpr reverse_iterator& operator-=(difference_type n);

Effects: As if by: current += n;

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](cmp.concept#concept:three%5Fway%5Fcomparable%5Fwith "17.12.4 Concept three_way_comparable [cmp.concept]")<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](alg.req.ind.swap#concept:indirectly%5Fswappable "24.3.7.4 Concept indirectly_swappable [alg.req.ind.swap]")<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).