std::reverse_iterator

From cppreference.com
< cpplrm; | iterator
Defined in header <iterator>
template< class Iter >

class reverse_iterator : public std::iterator<
typename std::iterator_traits<Iter>::iterator_category,
typename std::iterator_traits<Iter>::value_type,
typename std::iterator_traits<Iter>::difference_type,
typename std::iterator_traits<Iter>::pointer,

typename std::iterator_traits<Iter>::reference >
(until C++17)
template< class Iter >
class reverse_iterator;
(since C++17)

std::reverse_iterator is an iterator adaptor that reverses the direction of a given iterator. In other words, when provided with a bidirectional iterator, std::reverse_iterator produces a new iterator that moves from the end to the beginning of the sequence defined by the underlying bidirectional iterator.

For a reverse iterator r constructed from an iterator i, the relationship &*r == &*(i-1) is always true (as long as r is dereferenceable); thus a reverse iterator constructed from a one-past-the-end iterator dereferences to the last element in a sequence.

This is the iterator returned by member functions rbegin() and rend() of the standard library containers.

range-rbegin-rend.svg

Member types

Member type Definition
value_type std::iterator_traits<Iter>::value_type
difference_type std::iterator_traits<Iter>::difference_type
pointer std::iterator_traits<Iter>::pointer
reference std::iterator_traits<Iter>::reference
iterator_category std::iterator_traits<Iter>::iterator_category

These member types are required to be obtained by inheriting from std::iterator< std::iterator_traits<Iter>::iterator_category
, std::iterator_traits<Iter>::value_type
, std::iterator_traits<Iter>::difference_type
, std::iterator_traits<Iter>::pointer
, std::iterator_traits<Iter>::reference
>
.

(until C++17)
Member type Definition
iterator_type Iter

Member functions

constructs a new iterator adaptor
(public member function)
assigns another iterator
(public member function)
accesses the underlying iterator
(public member function)
accesses the pointed-to element
(public member function)
accesses an element by index
(public member function)
advances or decrements the iterator
(public member function)

Member objects

Member name Definition
current (protected) a copy of the base() iterator

Non-member functions

creates a std::reverse_iterator of type inferred from the argument
(function template)
compares the underlying iterators
(function template)
advances the iterator
(function template)
computes the distance between two iterator adaptors
(function template)

Notes

std::reverse_iterator does not work with iterators that return a reference to a member object (so-called "stashing iterators"). An example of stashing iterator is std::filesystem::path::iterator.

Example

#include <iostream>
#include <string>
#include <iterator>

int main()
{
    std::string s = "Hello, world";
    std::reverse_iterator<std::string::iterator> r = s.rbegin();
    r[7] = 'O'; // replaces 'o' with 'O' 
    r += 7; // iterator now points at 'O'
    std::string rev(r, s.rend());
    std::cout << rev << '\n';
}

Output:

OlleH

See also

(deprecated in C++17)
base class to ease the definition of required types for simple iterators
(class template)