<iterator>

Description
Synopsis
Classes
Template functions
Types
Operators

Description

Include the STL standard header <iterator> to define a number of classes, template classes, and template functions that aid in the declaration and manipulation of iterators.

Synopsis

namespace std {
struct input_iterator_tag;
struct output_iterator_tag;
struct forward_iterator_tag;
struct bidirectional_iterator_tag;
struct random_access_iterator_tag;

        // TEMPLATE CLASSES
template<class C, class T, class Dist,
    class Pt, class Rt>
    struct iterator;
template<class It>
    struct iterator_traits;
template<class T>
    struct iterator_traits<T *>
template<class RanIt>
    class reverse_iterator;
template<class Cont>
    class back_insert_iterator;
template<class Cont>
    class front_insert_iterator;
template<class Cont>
    class insert_iterator;
template<class U, class E, class T, class Dist>
    class istream_iterator;
template<class U, class E, class T>
    class ostream_iterator;
template<class E, class T>
    class istreambuf_iterator;
template<class E, class T>
    class ostreambuf_iterator;

        // TEMPLATE FUNCTIONS
template<class RanIt>
    bool operator==(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class U, class E, class T, class Dist>
    bool operator==(
        const istream_iterator<U, E, T, Dist>& lhs,
        const istream_iterator<U, E, T, Dist>& rhs);
template<class E, class T>
    bool operator==(
        const istreambuf_iterator<E, T>& lhs,
        const istreambuf_iterator<E, T>& rhs);
template<class RanIt>
    bool operator!=(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class U, class E, class T, class Dist>
    bool operator!=(
        const istream_iterator<U, E, T, Dist>& lhs,
        const istream_iterator<U, E, T, Dist>& rhs);
template<class E, class T>
    bool operator!=(
        const istreambuf_iterator<E, T>& lhs,
        const istreambuf_iterator<E, T>& rhs);
template<class RanIt>
    bool operator<(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class RanIt>
    bool operator>(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class RanIt>
    bool operator<=(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class RanIt>
    bool operator>=(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class RanIt>
    Dist operator-(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class RanIt>
    reverse_iterator<RanIt> operator+(
        Dist n,
        const reverse_iterator<RanIt>& rhs);
template<class Cont>
    back_insert_iterator<Cont> back_inserter(Cont& x);
template<class Cont>
    front_insert_iterator<Cont> front_inserter(Cont& x);
template<class Cont, class Iter>
    insert_iterator<Cont> inserter(Cont& x, Iter it);
template<class InIt, class Dist>
    void advance(InIt& it, Dist n);
template<class Init, class Dist>
    iterator_traits<InIt>::difference_type
        distance(InIt first, InIt last);
    }

Classes

back_insert_iterator
front_insert_iterator
insert_iterator
istream_iterator
istreambuf_iterator
iterator
iterator_traits
ostream_iterator
ostreambuf_iterator
reverse_iterator

back_insert_iterator

Description
Synopsis
Constructor
back_insert_iterator::back_insert_iterator
Types
back_insert_iterator::container_type
back_insert_iterator::reference
back_insert_iterator::value_type
Member functions
back_insert_iterator::operator*
back_insert_iterator::operator++
back_insert_iterator::operator=
Description

The template class describes an output iterator object. It inserts elements into a container of type Cont, which it accesses via the protected pointer object it stores called container. The container must define:

Synopsis
template<class Cont>
    class back_insert_iterator
        : public iterator<output_iterator_tag,
            void, void, void, void> {
public:
    typedef Cont container_type;
    typedef typename Cont::reference reference;
    typedef typename Cont::value_type value_type;
    explicit back_insert_iterator(Cont& x);
    back_insert_iterator&
        operator=(typename Cont::const_reference val);
    back_insert_iterator& operator*();
    back_insert_iterator& operator++();
    back_insert_iterator operator++(int);
protected:
    Cont *container;
    };
Constructor
back_insert_iterator::back_insert_iterator

explicit back_insert_iterator(Cont& x);

The constructor initializes container with &x.

Types
back_insert_iterator::container_type

typedef Cont container_type;

The type is a synonym for the template parameter Cont.

back_insert_iterator::reference

typedef typename Cont::reference reference;

The type describes a reference to an element of the sequence controlled by the associated container.

back_insert_iterator::value_type

typedef typename Cont::value_type value_type;

The type describes the elements of the sequence controlled by the associated container.

Member functions
back_insert_iterator::operator*

back_insert_iterator& operator*();

The member function returns *this.

back_insert_iterator::operator++

back_insert_iterator& operator++();
back_insert_iterator operator++(int);

The member functions both return *this.

back_insert_iterator::operator=

back_insert_iterator&
    operator=(typename Cont::const_reference val);

The member function evaluates container. push_back(val), then returns *this.

front_insert_iterator

Description
Synopsis
Constructor
front_insert_iterator::front_insert_iterator
Types
front_insert_iterator::container_type
front_insert_iterator::reference
front_insert_iterator::value_type
Member functions
front_insert_iterator::operator*
front_insert_iterator::operator++
front_insert_iterator::operator=
Description

The template class describes an output iterator object. It inserts elements into a container of type Cont, which it accesses via the protected pointer object it stores called container. The container must define:

Synopsis
template<class Cont>
    class front_insert_iterator
        : public iterator<output_iterator_tag,
            void, void, void, void> {
public:
    typedef Cont container_type;
    typedef typename Cont::reference reference;
    typedef typename Cont::value_type value_type;
    explicit front_insert_iterator(Cont& x);
    front_insert_iterator&
        operator=(typename Cont::const_reference val);
    front_insert_iterator& operator*();
    front_insert_iterator& operator++();
    front_insert_iterator operator++(int);
protected:
    Cont *container;
    };
Constructor
front_insert_iterator::front_insert_iterator

explicit front_insert_iterator(Cont& x);

The constructor initializes container with &x.

Types
front_insert_iterator::container_type

typedef Cont container_type;

The type is a synonym for the template parameter Cont.

front_insert_iterator::reference

typedef typename Cont::reference reference;

The type describes a reference to an element of the sequence controlled by the associated container.

front_insert_iterator::value_type

typedef typename Cont::value_type value_type;

The type describes the elements of the sequence controlled by the associated container.

Member functions
front_insert_iterator::operator*

front_insert_iterator& operator*();

The member function returns *this.

front_insert_iterator::operator++

front_insert_iterator& operator++();
front_insert_iterator operator++(int);

The member functions both return *this.

front_insert_iterator::operator=

front_insert_iterator&
    operator=(typename Cont::const_reference val);

The member function evaluates container. push_front(val), then returns *this.

insert_iterator

Description
Synopsis
Constructor
insert_iterator::insert_iterator
Types
insert_iterator::container_type
insert_iterator::reference
insert_iterator::value_type
Member functions
insert_iterator::operator*
insert_iterator::operator++
insert_iterator::operator=
Description

The template class describes an output iterator object. It inserts elements into a container of type Cont, which it accesses via the protected pointer object it stores called container. It also stores the protected iterator object, of class Cont::iterator, called iter. The container must define:

Synopsis
template<class Cont>
    class insert_iterator
        : public iterator<output_iterator_tag,
            void, void, void, void> {
public:
    typedef Cont container_type;
    typedef typename Cont::reference reference;
    typedef typename Cont::value_type value_type;
    insert_iterator(Cont& x,
        typename Cont::iterator it);
    insert_iterator&
        operator=(typename Cont::const_reference val);
    insert_iterator& operator*();
    insert_iterator& operator++();
    insert_iterator& operator++(int);
protected:
    Cont *container;
    typename Cont::iterator iter;
    };
Constructor
insert_iterator::insert_iterator

insert_iterator(Cont& x,
    typename Cont::iterator it);

The constructor initializes container with &x, and iter with it.

Types
insert_iterator::container_type

typedef Cont container_type;

The type is a synonym for the template parameter Cont.

insert_iterator::reference

typedef typename Cont::reference reference;

The type describes a reference to an element of the sequence controlled by the associated container.

insert_iterator::value_type

typedef typename Cont::value_type value_type;

The type describes the elements of the sequence controlled by the associated container.

Member functions
insert_iterator::operator*

insert_iterator& operator*();

The member function returns *this.

insert_iterator::operator++

insert_iterator& operator++();
insert_iterator& operator++(int);

The member functions both return *this.

insert_iterator::operator=

insert_iterator&
    operator=(typename Cont::const_reference val);

The member function evaluates iter = container. insert(iter, val), then returns *this.

istream_iterator

Description
Synopsis
Constructor
istream_iterator::istream_iterator
Types
istream_iterator::char_type
istream_iterator::istream_type
istream_iterator::traits_type
Operators
istream_iterator::operator*
istream_iterator::operator->
istream_iterator::operator++
Description

The template class describes an input iterator object. It extracts objects of class U from an input stream, which it accesses via an object it stores, of type pointer to basic_istream<E, T>. After constructing or incrementing an object of class istream_iterator with a non-null stored pointer, the object attempts to extract and store an object of type U from the associated input stream. If the extraction fails, the object effectively replaces the stored pointer with a null pointer (thus making an end-of-sequence indicator).

Synopsis
template<class U, class E = char,
    class T = char_traits>
    class Dist = ptrdiff_t>
    class istream_iterator
        : public iterator<input_iterator_tag,
            U, Dist, U *, U&> {
public:
    typedef E char_type;
    typedef T traits_type;
    typedef basic_istream<E, T> istream_type;
    istream_iterator();
    istream_iterator(istream_type& is);
    const U& operator*() const;
    const U *operator->() const;
    istream_iterator<U, E, T, Dist>& operator++();
    istream_iterator<U, E, T, Dist> operator++(int);
    };
Constructor
istream_iterator::istream_iterator

istream_iterator();
istream_iterator(istream_type& is);

The first constructor initializes the input stream pointer with a null pointer. The second constructor initializes the input stream pointer with &is, then attempts to extract and store an object of type U.

Types
istream_iterator::char_type

typedef E char_type;

The type is a synonym for the template parameter E.

istream_iterator::istream_type

typedef basic_istream<E, T> istream_type;

The type is a synonym for basic_istream<E, T>.

istream_iterator::traits_type

typedef T traits_type;

The type is a synonym for the template parameter T.

Operators
istream_iterator::operator*

const U& operator*() const;

The operator returns the stored object of type U.

istream_iterator::operator->

const U *operator->() const;

The operator returns &**this.

istream_iterator::operator++

istream_iterator<U, E, T, Dist>& operator++();
istream_iterator<U, E, T, Dist> operator++(int);

The first operator attempts to extract and store an object of type U from the associated input stream. The second operator makes a copy of the object, increments the object, then returns the copy.

istreambuf_iterator

Description
Synopsis
Constructor
istreambuf_iterator::istreambuf_iterator
Types
istreambuf_iterator::char_type
istreambuf_iterator::int_type
istreambuf_iterator::istream_type
istreambuf_iterator::streambuf_type
istreambuf_iterator::traits_type
Member functions
istreambuf_iterator::equal
Operators
istreambuf_iterator::operator*
istreambuf_iterator::operator++
istreambuf_iterator::operator->
Description

The template class describes an input iterator object. It extracts elements of class E from an input stream buffer, which it accesses via an object it stores, of type pointer to basic_streambuf<E, T>. After constructing or incrementing an object of class istreambuf_iterator with a non-null stored pointer, the object effectively attempts to extract and store an object of type E from the associated itput stream. (The extraction may be delayed, however, until the object is actually dereferenced or copied.) If the extraction fails, the object effectively replaces the stored pointer with a null pointer (thus making an end-of-sequence indicator).

Synopsis
template<class E, class T = char_traits<E> >
    class istreambuf_iterator
        : public iterator<input_iterator_tag,
            E, typename T::off_type, E *, E&> {
public:
    typedef E char_type;
    typedef T traits_type;
    typedef typename T::int_type int_type;
    typedef basic_streambuf<E, T> streambuf_type;
    typedef basic_istream<E, T> istream_type;
    istreambuf_iterator(streambuf_type *sb = 0) throw();
    istreambuf_iterator(istream_type& is) throw();
    const E& operator*() const;
    const E *operator->();
    istreambuf_iterator& operator++();
    istreambuf_iterator operator++(int);
    bool equal(const istreambuf_iterator& rhs) const;
    };
Constructor
istreambuf_iterator::istreambuf_iterator

istreambuf_iterator(streambuf_type *sb = 0) throw();
istreambuf_iterator(istream_type& is) throw();

The first constructor initializes the input stream-buffer pointer with sb. The second constructor initializes the input stream-buffer pointer with is.rdbuf(), then (eventually) attempts to extract and store an object of type E.

Types
istreambuf_iterator::char_type

typedef E char_type;

The type is a synonym for the template parameter E.

istreambuf_iterator::int_type

typedef typename T::int_type int_type;

The type is a synonym for T::int_type.

istreambuf_iterator::istream_type

typedef basic_istream<E, T> istream_type;

The type is a synonym for basic_istream<E, T>.

istreambuf_iterator::streambuf_type

typedef basic_streambuf<E, T> streambuf_type;

The type is a synonym for basic_streambuf<E, T>.

istreambuf_iterator::traits_type

typedef T traits_type;

The type is a synonym for the template parameter T.

Member functions
istreambuf_iterator::equal

bool equal(const istreambuf_iterator& rhs) const;

The member function returns true only if the stored stream buffer pointers for the object and rhs are both null pointers or are both non-null pointers.

Operators
istreambuf_iterator::operator*

const E& operator*() const;

The operator returns the stored object of type E.

istreambuf_iterator::operator++

istreambuf_iterator& operator++();
istreambuf_iterator operator++(int);

The first operator (eventually) attempts to extract and store an object of type E from the associated input stream. The second operator makes a copy of the object, increments the object, then returns the copy.

istreambuf_iterator::operator->

const E *operator->() const;

The operator returns &**this.

iterator

template<class C, class T, class Dist = ptrdiff_t
    class Pt = T *, class Rt = T&>
    struct iterator {
    typedef C iterator_category;
    typedef T value_type;
    typedef Dist difference_type;
    typedef Pt pointer;
    typedef Rt reference;
    };

The template class serves as a base type for all iterators. It defines the member types iterator_category, (a synonym for the template parameter C), value_type (a synonym for the template parameter T), difference_type (a synonym for the template parameter Dist), pointer (a synonym for the template parameter Pt), and reference (a synonym for the template parameter T).

Note that value_type should not be a constant type even if pointer points at an object of const type and reference designates an object of const type.

iterator_traits

template<class It>
    struct iterator_traits {
    typedef typename It::iterator_category iterator_category;
    typedef typename It::value_type value_type;
    typedef typename It::difference_type difference_type;
    typedef typename It::pointer pointer;
    typedef typename It::reference reference;
    };
template<class T>
    struct iterator_traits<T *> {
    typedef random_access_iterator_tag iterator_category;
    typedef T value_type;
    typedef ptrdiff_t difference_type;
    typedef T *pointer;
    typedef T& reference;
    };
template<class T>
    struct iterator_traits<const T *> {
    typedef random_access_iterator_tag iterator_category;
    typedef T value_type;
    typedef ptrdiff_t difference_type;
    typedef const T *pointer;
    typedef const T& reference;
    };

The template class determines several critical types associated with the iterator type It. It defines the member types iterator_category (a synonym for It::iterator_category), value_type (a synonym for It::value_type), difference_type (a synonym for It::difference_type), pointer (a synonym for It::pointer), and reference (a synonym for It::reference).

The partial specializations determine the critical types associated with an object pointer type T *. In this implementation, you can also use several template functions that do not make use of partial specialization:

template<class C, class T, class Dist>
    C _Iter_cat(const iterator<C, T, Dist>&);
template<class T>
    random_access_iterator_tag _Iter_cat(const T *);

template<class C, class T, class Dist>
    T *_Val_type(const iterator<C, T, Dist>&);
template<class T>
    T *_Val_type(const T *);

template<class C, class T, class Dist>
    Dist *_Dist_type(const iterator<C, T, Dist>&);
template<class T>
    ptrdiff_t *_Dist_type(const T *);

which determine several of the same types a bit more indirectly. You use these functions as arguments on a function call. Their sole purpose is to supply a useful template class parameter to the called function.

ostream_iterator

Description
Synopsis
Constructor
ostream_iterator::ostream_iterator
Types
ostream_iterator::char_type
ostream_iterator::ostream_type
ostream_iterator::traits_type
ostream_iterator::value_type
Operators
ostream_iterator::operator*
ostream_iterator::operator++
ostream_iterator::operator=
Description

The template class describes an output iterator object. It inserts objects of class U into an output stream, which it accesses via an object it stores, of type pointer to basic_ostream<E, T>. It also stores a pointer to a delimiter string, a null-terminated string of elements of type E, which is appended after each insertion. (Note that the string itself is not copied by the constructor.

Synopsis
template<class U, class E = char,
    class T = char_traits<E>  >
    class ostream_iterator
        : public iterator<output_iterator_tag,
            void, void, void, void> {
public:
    typedef U value_type;
    typedef E char_type;
    typedef T traits_type;
    typedef basic_ostream<E, T> ostream_type;
    ostream_iterator(ostream_type& os);
    ostream_iterator(ostream_type& os, const E *delim);
    ostream_iterator<U, E, T>& operator=(const U& val);
    ostream_iterator<U, E, T>& operator*();
    ostream_iterator<U, E, T>& operator++();
    ostream_iterator<U, E, T> operator++(int);
    };
Constructor
ostream_iterator::ostream_iterator

ostream_iterator(ostream_type& os);
ostream_iterator(ostream_type& os, const E *delim);

The first constructor initializes the output stream pointer with &os. The delimiter string pointer designates an empty string. The second constructor initializes the output stream pointer with &os and the delimiter string pointer with delim.

Types
ostream_iterator::char_type

typedef E char_type;

The type is a synonym for the template parameter E.

ostream_iterator::ostream_type

typedef basic_ostream<E, T> ostream_type;

The type is a synonym for basic_ostream<E, T>.

ostream_iterator::traits_type

typedef T traits_type;

The type is a synonym for the template parameter T.

ostream_iterator::value_type

typedef U value_type;

The type is a synonym for the template parameter U.

Operators
ostream_iterator::operator*

ostream_iterator<U, E, T>& operator*();

The operator returns *this.

ostream_iterator::operator++

ostream_iterator<U, E, T>& operator++();
ostream_iterator<U, E, T> operator++(int);

The operators both return *this.

ostream_iterator::operator=

ostream_iterator<U, E, T>& operator=(const U& val);

The operator inserts val into the output stream associated with the object, then returns *this.

ostreambuf_iterator

Description
Synopsis
Constructor
ostreambuf_iterator::ostreambuf_iterator
Types
ostreambuf_iterator::char_type
ostreambuf_iterator::ostream_type
ostreambuf_iterator::streambuf_type
ostreambuf_iterator::traits_type
Member functions
ostreambuf_iterator::failed
Operators
ostreambuf_iterator::operator*
ostreambuf_iterator::operator++
ostreambuf_iterator::operator=
Description

The template class describes an output iterator object. It inserts elements of class E into an output stream buffer, which it accesses via an object it stores, of type pointer to basic_streambuf<E, T>.

Synopsis
template<class E, class T = char_traits<E> >
    class ostreambuf_iterator
        : public iterator<output_iterator_tag,
            void, void, void, void> {
public:
    typedef E char_type;
    typedef T traits_type;
    typedef basic_streambuf<E, T> streambuf_type;
    typedef basic_ostream<E, T> ostream_type;
    ostreambuf_iterator(streambuf_type *sb) throw();
    ostreambuf_iterator(ostream_type& os) throw();
    ostreambuf_iterator& operator=(E x);
    ostreambuf_iterator& operator*();
    ostreambuf_iterator& operator++();
    T1 operator++(int);
    bool failed() const throw();
    };
Constructor
ostreambuf_iterator::ostreambuf_iterator

ostreambuf_iterator(streambuf_type *sb) throw();
ostreambuf_iterator(ostream_type& os) throw();

The first constructor initializes the output stream-buffer pointer with sb. The second constructor initializes the output stream-buffer pointer with os.rdbuf(). (The stored pointer must not be a null pointer.)

Types
ostreambuf_iterator::char_type

typedef E char_type;

The type is a synonym for the template parameter E.

ostreambuf_iterator::ostream_type

typedef basic_ostream<E, T> ostream_type;

The type is a synonym for basic_ostream<E, T>.

ostreambuf_iterator::streambuf_type

typedef basic_streambuf<E, T> streambuf_type;

The type is a synonym for basic_streambuf<E, T>.

ostreambuf_iterator::traits_type

typedef T traits_type;

The type is a synonym for the template parameter T.

Member functions
ostreambuf_iterator::failed

bool failed() const throw();

The member function returns true only if no insertion into the output stream buffer has earlier failed.

Operators
ostreambuf_iterator::operator*

ostreambuf_iterator& operator*();

The operator returns *this.

ostreambuf_iterator::operator++

ostreambuf_iterator& operator++();
T1 operator++(int);

The first operator returns *this. The second operator returns an object of some type T1 that can be converted to ostreambuf_iterator<E, T>.

ostreambuf_iterator::operator=

ostreambuf_iterator& operator=(E x);

The operator inserts x into the associated stream buffer, then returns *this.

reverse_iterator

Description
Synopsis
Constructor
reverse_iterator::reverse_iterator
Types
reverse_iterator::iterator_type
reverse_iterator::pointer
reverse_iterator::reference
Member functions
reverse_iterator::base
Operators
reverse_iterator::operator*
reverse_iterator::operator+
reverse_iterator::operator++
reverse_iterator::operator+=
reverse_iterator::operator-
reverse_iterator::operator—
reverse_iterator::operator-=
reverse_iterator::operator->
reverse_iterator::operator[]
Description

The template class describes an object that behaves like a random-access iterator, only in reverse. It stores a random-access iterator of type RanIt in the protected object current. Incrementing the object x of type reverse_iterator decrements x.current, and decrementing x increments x.current. Moreover, the expression *x evaluates to *(current - 1), of type Ref. Typically, Ref is type T&.

Thus, you can use an object of class reverse_iterator to access in reverse order a sequence that is traversed in order by a random-access iterator.

Several STL containers specialize reverse_iterator for RanIt a bidirectional iterator. In these cases, you must not call any of the member functions operator+=, operator+, operator-=, operator-, or operator[].

Synopsis
template<class RanIt>
    class reverse_iterator : public iterator<
        typename iterator_traits<RanIt>::iterator_category,
        typename iterator_traits<RanIt>::value_type,
        typename iterator_traits<RanIt>::difference_type,
        typename iterator_traits<RanIt>::pointer,
        typename iterator_traits<RanIt>::reference> {
    typedef typename iterator_traits<RanIt>::difference_type
        Dist;
    typedef typename iterator_traits<RanIt>::pointer
        Ptr;
    typedef typename iterator_traits<RanIt>::reference
        Ref;
public:
    typedef RanIt iterator_type;
    reverse_iterator();
    explicit reverse_iterator(RanIt x);
    template<class U>
        reverse_iterator(const reverse_iterator<U>& x);
    RanIt base() const;
    Ref operator*() const;
    Ptr operator->() const;
    reverse_iterator& operator++();
    reverse_iterator operator++(int);
    reverse_iterator& operator--();
    reverse_iterator operator--();
    reverse_iterator& operator+=(Dist n);
    reverse_iterator operator+(Dist n) const;
    reverse_iterator& operator-=(Dist n);
    reverse_iterator operator-(Dist n) const;
    Ref operator[](Dist n) const;
protected:
    RanIt current;
    };
Constructor
reverse_iterator::reverse_iterator

reverse_iterator();
explicit reverse_iterator(RanIt x);
template<class U>
    reverse_iterator(const reverse_iterator<U>& x);

The first constructor initializes current with its default constructor. The second constructor initializes current with x.current.

The template constructor initializes current with x.base ().

Types
reverse_iterator::iterator_type

typedef RanIt iterator_type;

The type is a synonym for the template parameter RanIt.

reverse_iterator::pointer

typedef Ptr pointer;

The type is a synonym for the template parameter Ref.

reverse_iterator::reference

typedef Ref reference;

The type is a synonym for the template parameter Ref.

Member functions
reverse_iterator::base

RanIt base() const;

The member function returns current.

Operators
reverse_iterator::operator*

Ref operator*() const;

The operator returns *(current - 1).

reverse_iterator::operator+

reverse_iterator operator+(Dist n) const;

The operator returns reverse_iterator(*this) += n.

reverse_iterator::operator++

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

The first (preincrement) operator evaluates —current. then returns *this.

The second (postincrement) operator makes a copy of *this, evaluates —current, then returns the copy.

reverse_iterator::operator+=

reverse_iterator& operator+=(Dist n);

The operator evaluates current - n. then returns *this.

reverse_iterator::operator-

reverse_iterator operator-(Dist n) const;

The operator returns reverse_iterator(*this) -= n.

reverse_iterator::operator—

reverse_iterator& operator--();
reverse_iterator operator--();

The first (predecrement) operator evaluates ++current. then returns *this.

The second (postdecrement) operator makes a copy of *this, evaluates ++current, then returns the copy.

reverse_iterator::operator-=

reverse_iterator& operator-=(Dist n);

The operator evaluates current + n. then returns *this.

reverse_iterator::operator->

Ptr operator->() const;

The operator returns &**this.

reverse_iterator::operator[]

Ref operator[](Dist n) const;

The operator returns *(*this + n).

Template functions

advance
back_inserter
distance
front_inserter
inserter

advance

template<class InIt, class Dist>
    void advance(InIt& it, Dist n);

The template function effectively advances it by incrementing it n times. If InIt is a random-access iterator type, the function evaluates the expression it += n. Otherwise, it performs each increment by evaluating ++it. If InIt is an input or forward iterator type, n must not be negative.

back_inserter

template<class Cont>
    back_insert_iterator<Cont> back_inserter(Cont& x);

The template function returns back_insert_iterator<Cont>(x).

distance

template<class Init, class Dist>
    typename iterator_traits<InIt>::difference_type
        distance(InIt first, InIt last);

The template function sets a count n to zero. It then effectively advances first and increments n until first == last. If InIt is a random-access iterator type, the function evaluates the expression n += last - first. Otherwise, it performs each iterator increment by evaluating ++first.

front_inserter

template<class Cont>
    front_insert_iterator<Cont> front_inserter(Cont& x);

The template function returns front_insert_iterator<Cont>(x).

inserter

template<class Cont, class Iter>
    insert_iterator<Cont> inserter(Cont& x, Iter it);

The template function returns insert_iterator<Cont>(x, it).

Types

bidirectional_iterator_tag
forward_iterator_tag
input_iterator_tag
output_iterator_tag
random_access_iterator_tag

bidirectional_iterator_tag

struct bidirectional_iterator_tag
    : public forward_iterator_tag {
    };

The type is the same as iterator<It>::iterator_category when It describes an object that can serve as a bidirectional iterator.

forward_iterator_tag

struct forward_iterator_tag
    : public input_iterator_tag {
    };

The type is the same as iterator<It>::iterator_category when It describes an object that can serve as a forward iterator.

input_iterator_tag

struct input_iterator_tag {
    };

The type is the same as iterator<It>::iterator_category when It describes an object that can serve as an input iterator.

output_iterator_tag

struct output_iterator_tag {
    };

The type is the same as iterator<It>::iterator_category when It describes an object that can serve as a output iterator.

random_access_iterator_tag

struct random_access_iterator_tag
    : public bidirectional_iterator_tag {
    };

The type is the same as iterator<It>::iterator_category when It describes an object that can serve as a random-access iterator.

Operators

operator!=
operator==
operator<
operator<=
operator>
operator>=
operator+
operator-

operator!=

template<class RanIt>
    bool operator!=(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class U, class E, class T, class Dist>
    bool operator!=(
        const istream_iterator<U, E, T, Dist>& lhs,
        const istream_iterator<U, E, T, Dist>& rhs);
template<class E, class T>
    bool operator!=(
        const istreambuf_iterator<E, T>& lhs,
        const istreambuf_iterator<E, T>& rhs);

The template operator returns !(lhs == rhs).

operator==

template<class RanIt>
    bool operator==(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);
template<class U, class E, class T, class Dist>
    bool operator==(
        const istream_iterator<U, E, T, Dist>& lhs,
        const istream_iterator<U, E, T, Dist>& rhs);
template<class E, class T>
    bool operator==(
        const istreambuf_iterator<E, T>& lhs,
        const istreambuf_iterator<E, T>& rhs);

The first template operator returns true only if lhs.current == rhs.current. The second template operator returns true only if both lhs and rhs store the same stream pointer. The third template operator returns lhs.equal(rhs).

operator<

template<class RanIt>
    bool operator<(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);

The template operator returns rhs.current < lhs.current [sic].

operator<=

template<class RanIt>
    bool operator<=(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);

The template operator returns !(rhs < lhs).

operator>

template<class RanIt>
    bool operator>(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);

The template operator returns rhs < lhs.

operator>=

template<class RanIt>
    bool operator>=(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);

The template operator returns !(lhs < rhs).

operator+

template<class RanIt>
    reverse_iterator<RanIt> operator+(Dist n,
        const reverse_iterator<RanIt>& rhs);

The template operator returns rhs + n.

operator-

template<class RanIt>
    Dist operator-(
        const reverse_iterator<RanIt>& lhs,
        const reverse_iterator<RanIt>& rhs);

The template operator returns rhs.current - lhs.current [sic].

Copyright note

Certain materials included or referred to in this document are copyright P.J. Plauger and/or Dinkumware, Ltd. or are based on materials that are copyright P.J. Plauger and/or Dinkumware, Ltd.

Notwithstanding the meta-data for this document, copyright information for this document is as follows:

Copyright © IBM Corp. 1999, 2010. & Copyright © P.J. Plauger and/or Dinkumware, Ltd. 1992-2006.