24 Iterators library [iterators]

24.5 Iterator adaptors [predef.iterators]

24.5.1 Reverse iterators [reverse.iterators]

1

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. The fundamental relation between a reverse iterator and its corresponding iterator i is established by the identity: &*(reverse_iterator(i)) == &*(i - 1).

24.5.1.1 Class template reverse_iterator [reverse.iterator]

namespace std {
  template <class Iterator>
  class reverse_iterator : public
        iterator<typename iterator_traits<Iterator>::iterator_category,
        typename iterator_traits<Iterator>::value_type,
        typename iterator_traits<Iterator>::difference_type,
        typename iterator_traits<Iterator>::pointer,
        typename iterator_traits<Iterator>::reference> {
  public:
    typedef Iterator                                            iterator_type;
    typedef typename iterator_traits<Iterator>::difference_type difference_type;
    typedef typename iterator_traits<Iterator>::reference       reference;
    typedef typename iterator_traits<Iterator>::pointer         pointer;

    reverse_iterator();
    explicit reverse_iterator(Iterator x);
    template <class U> reverse_iterator(const reverse_iterator<U>& u);
    template <class U> reverse_iterator& operator=(const reverse_iterator<U>& u);

    Iterator base() const;      // explicit
    reference operator*() const;
    pointer   operator->() const;

    reverse_iterator& operator++();
    reverse_iterator  operator++(int);
    reverse_iterator& operator--();
    reverse_iterator  operator--(int);

    reverse_iterator  operator+ (difference_type n) const;
    reverse_iterator& operator+=(difference_type n);
    reverse_iterator  operator- (difference_type n) const;
    reverse_iterator& operator-=(difference_type n);
    unspecified operator[](difference_type n) const;
  protected:
    Iterator current;
  private:
    Iterator deref_tmp;         // exposition only
  };

  template <class Iterator1, class Iterator2>
    bool operator==(
      const reverse_iterator<Iterator1>& x,
      const reverse_iterator<Iterator2>& y);
  template <class Iterator1, class Iterator2>
    bool operator<(
      const reverse_iterator<Iterator1>& x,
      const reverse_iterator<Iterator2>& y);
  template <class Iterator1, class Iterator2>
    bool operator!=(
      const reverse_iterator<Iterator1>& x,
      const reverse_iterator<Iterator2>& y);
  template <class Iterator1, class Iterator2>
    bool operator>(
      const reverse_iterator<Iterator1>& x,
      const reverse_iterator<Iterator2>& y);
  template <class Iterator1, class Iterator2>
    bool operator>=(
      const reverse_iterator<Iterator1>& x,
      const reverse_iterator<Iterator2>& y);
  template <class Iterator1, class Iterator2>
    bool operator<=(
      const reverse_iterator<Iterator1>& x,
      const reverse_iterator<Iterator2>& y);
  template <class Iterator1, class Iterator2>
    auto operator-(
      const reverse_iterator<Iterator1>& x,
      const reverse_iterator<Iterator2>& y) -> decltype(y.current - x.current);
  template <class Iterator>
    reverse_iterator<Iterator> operator+(
      typename reverse_iterator<Iterator>::difference_type n,
      const reverse_iterator<Iterator>& x);
}

24.5.1.2 reverse_iterator requirements [reverse.iter.requirements]

1

The template parameter Iterator shall meet all the requirements of a Bidirectional Iterator ([bidirectional.iterators]).

2

Additionally, Iterator shall meet the requirements of a Random Access Iterator ([random.access.iterators]) if any of the members operator+ ([reverse.iter.op+]), operator- ([reverse.iter.op-]), operator+= ([reverse.iter.op+=]), operator-= ([reverse.iter.op-=]), operator [] ([reverse.iter.opindex]), or the global operators operator< ([reverse.iter.op<]), operator> ([reverse.iter.op>]),
operator <= ([reverse.iter.op<=]), operator>= ([reverse.iter.op>=]), operator- ([reverse.iter.opdiff]) or operator+ ([reverse.iter.opsum]) are referenced in a way that requires instantiation ([temp.inst]).

24.5.1.3 reverse_iterator operations [reverse.iter.ops]

24.5.1.3.1 reverse_iterator constructor [reverse.iter.cons]

reverse_iterator();

1

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.

explicit reverse_iterator(Iterator x);

2

Effects: Initializes current with x.

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

3

Effects: Initializes current with u.current.

24.5.1.3.2 reverse_iterator::operator= [reverse.iter.op=]

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

1

Effects: Assigns u.base() to current.

2

Returns: *this.

24.5.1.3.3 Conversion [reverse.iter.conv]

Iterator base() const; // explicit

1

Returns: current.

24.5.1.3.4 operator* [reverse.iter.op.star]

reference operator*() const;

1

Effects: 

deref_tmp = current;
--deref_tmp;
return *deref_tmp;
2

[ Note: This operation must use an auxiliary member variable rather than a temporary variable to avoid returning a reference that persists beyond the lifetime of its associated iterator. (See [iterator.requirements].)  — end note ]

24.5.1.3.5 operator-> [reverse.iter.opref]

pointer operator->() const;

1

Returns: &(operator*()).

24.5.1.3.6 operator++ [reverse.iter.op++]

reverse_iterator& operator++();

1

Effects: -- current;

2

Returns: *this.

reverse_iterator operator++(int);

3

Effects: 

reverse_iterator tmp = *this;
--current;
return tmp;

24.5.1.3.7 operator-- [reverse.iter.op--]

reverse_iterator& operator--();

1

Effects: ++current

2

Returns: *this.

reverse_iterator operator--(int);

3

Effects: 

reverse_iterator tmp = *this;
++current;
return tmp;

24.5.1.3.8 operator+ [reverse.iter.op+]

reverse_iterator operator+(typename reverse_iterator<Iterator>::difference_type n) const;

1

Returns: reverse_iterator(current-n).

24.5.1.3.9 operator+= [reverse.iter.op+=]

reverse_iterator& operator+=(typename reverse_iterator<Iterator>::difference_type n);

1

Effects: current -= n;

2

Returns: *this.

24.5.1.3.10 operator- [reverse.iter.op-]

reverse_iterator operator-(typename reverse_iterator<Iterator>::difference_type n) const;

1

Returns: reverse_iterator(current+n).

24.5.1.3.11 operator-= [reverse.iter.op-=]

reverse_iterator& operator-=(typename reverse_iterator<Iterator>::difference_type n);

1

Effects: current += n;

2

Returns: *this.

24.5.1.3.12 operator[] [reverse.iter.opindex]

unspecified operator[]( typename reverse_iterator<Iterator>::difference_type n) const;

1

Returns: current[-n-1].

24.5.1.3.13 operator== [reverse.iter.op==]

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

1

Returns: x.current == y.current.

24.5.1.3.14 operator< [reverse.iter.op<]

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

1

Returns: x.current > y.current.

24.5.1.3.15 operator!= [reverse.iter.op!=]

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

1

Returns: x.current != y.current.

24.5.1.3.16 operator> [reverse.iter.op>]

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

1

Returns: x.current < y.current.

24.5.1.3.17 operator>= [reverse.iter.op>=]

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

1

Returns: x.current <= y.current.

24.5.1.3.18 operator<= [reverse.iter.op<=]

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

1

Returns: x.current >= y.current.

24.5.1.3.19 operator- [reverse.iter.opdiff]

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

1

Returns: y.current - x.current.

24.5.1.3.20 operator+ [reverse.iter.opsum]

template <class Iterator> reverse_iterator<Iterator> operator+( typename reverse_iterator<Iterator>::difference_type n, const reverse_iterator<Iterator>& x);

1

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