This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

<iterator>

advance · back_insert_iterator · back_inserter · bidirectional_iterator_tag · distance · forward_iterator_tag · front_insert_iterator · front_inserter · input_iterator_tag · insert_iterator · inserter · istream_iterator · istreambuf_iterator · iterator · iterator_traits · operator!= · operator== · operator< · operator<= · operator> · operator>= · operator+ · operator- · ostream_iterator · ostreambuf_iterator · output_iterator_tag · random_access_iterator_tag · reverse_iterator

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.

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 Category, class Ty, class Diff,
    class Pointer, class Reference>
    struct iterator;
template<class Iter>
    struct iterator_traits;
template<class Ty>
    struct iterator_traits<Ty *>;
template<class Ty>
    struct iterator_traits<const Ty *>;
template<class RanIt>
    class reverse_iterator;
template<class Container>
    class back_insert_iterator;
template<class Container>
    class front_insert_iterator;
template<class Container>
    class insert_iterator;
template<class Ty, class Elem, class Tr, class Diff>
    class istream_iterator;
template<class Ty, class Elem, class Tr>
    class ostream_iterator;
template<class Elem, class Tr>
    class istreambuf_iterator;
template<class Elem, class Tr>
    class ostreambuf_iterator;

        // TEMPLATE FUNCTIONS
template<class RanIt>
    bool operator==(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
    bool operator==(
        const istream_iterator<Ty, Elem, Tr, Diff>& left,
        const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
    bool operator==(
        const istreambuf_iterator<Elem, Tr>& left,
        const istreambuf_iterator<Elem, Tr>& right);
template<class RanIt>
    bool operator!=(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
    bool operator!=(
        const istream_iterator<Ty, Elem, Tr, Diff>& left,
        const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
    bool operator!=(
        const istreambuf_iterator<Elem, Tr>& left,
        const istreambuf_iterator<Elem, Tr>& right);
template<class RanIt>
    bool operator<(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class RanIt>
    bool operator>(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class RanIt>
    bool operator<=(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class RanIt>
    bool operator>=(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class RanIt>
    Diff operator-(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class RanIt>
    reverse_iterator<RanIt> operator+(
        Diff off,
        const reverse_iterator<RanIt>& right);
template<class Container>
    back_insert_iterator<Container> back_inserter(Container& cont);
template<class Container>
    front_insert_iterator<Container> front_inserter(Container& cont);
template<class Container, class Iter>
    insert_iterator<Container> inserter(Container& cont, Iter it);
template<class InIt, class Diff>
    void advance(InIt& it, Diff off);
template<class Init>
    iterator_traits<InIt>::difference_type
        distance(InIt first, InIt last);
    };

advance

template<class InIt, class Diff>
    void advance(InIt& it, Diff off);

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

back_insert_iterator

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

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

• the member type const_reference, which is the type of a constant reference to an element of the sequence controlled by the container
• the member type reference, which is the type of a reference to an element of the sequence controlled by the container
• the member type value_type, which is the type of an element of the sequence controlled by the container
• the member function push_back(value_type val), which appends a new element with value val to the end of the sequence

back_insert_iterator::back_insert_iterator

explicit back_insert_iterator(Container& cont);

The constructor initializes container with &cont.

back_insert_iterator::container_type

typedef Container container_type;

The type is a synonym for the template parameter Container.

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 Container::const_reference val);

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

back_insert_iterator::reference

typedef typename Container::reference reference;

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

back_inserter

template<class Container>
    back_insert_iterator<Container> back_inserter(Container& cont);

The template function returns back_insert_iterator<Container>(cont).

bidirectional_iterator_tag

struct bidirectional_iterator_tag
    : public forward_iterator_tag {
    };

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

distance

template<class Init>
    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. The function returns N.

forward_iterator_tag

struct forward_iterator_tag
    : public input_iterator_tag {
    };

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

front_insert_iterator

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

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

• the member type const_reference, which is the type of a constant reference to an element of the sequence controlled by the container
• the member type reference, which is the type of a reference to an element of the sequence controlled by the container
• the member type value_type, which is the type of an element of the sequence controlled by the container
• the member function push_front(value_type val), which prepends a new element with value val to the beginning of the sequence

front_insert_iterator::container_type

typedef Container container_type;

The type is a synonym for the template parameter Container.

front_insert_iterator::front_insert_iterator

explicit front_insert_iterator(Container& cont);

The constructor initializes container with &cont.

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 Container::const_reference val);

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

front_insert_iterator::reference

typedef typename Container::reference reference;

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

front_inserter

template<class Container>
    front_insert_iterator<Container> front_inserter(Container& cont);

The template function returns front_insert_iterator<Container>(cont).

input_iterator_tag

struct input_iterator_tag {
    };

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

insert_iterator

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

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

• the member type const_reference, which is the type of a constant reference to an element of the sequence controlled by the container
• the member type iterator, which is the type of an iterator for the container
• the member type reference, which is the type of a reference to an element of the sequence controlled by the container
• the member type value_type, which is the type of an element of the sequence controlled by the container
• the member function insert(iterator it, value_type val), which inserts a new element with value val immediately before the element designated by it in the controlled sequence, then returns an iterator that designates the inserted element

insert_iterator::container_type

typedef Container container_type;

The type is a synonym for the template parameter Container.

insert_iterator::insert_iterator

insert_iterator(Container& cont,
    typename Container::iterator it);

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

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 Container::const_reference val);

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

insert_iterator::reference

typedef typename Container::reference reference;

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

inserter

template<class Container, class Iter>
    insert_iterator<Container> inserter(Container& cont, Iter it);

The template function returns insert_iterator<Container>(cont, it).

istream_iterator

template<class Ty, class Elem = char,
    class Tr = char_traits>
    class Diff = ptrdiff_t>
    class istream_iterator
        : public iterator<input_iterator_tag,
            Ty, Diff, const Ty *, const Ty&> {
public:
    typedef Elem char_type;
    typedef Tr traits_type;
    typedef basic_istream<Elem, Tr> istream_type;
    istream_iterator();
    istream_iterator(istream_type& istr);
    const Ty& operator*() const;
    const Ty *operator->() const;
    istream_iterator<Ty, Elem, Tr, Diff>& operator++();
    istream_iterator<Ty, Elem, Tr, Diff> operator++(int);
    };

The template class describes an input iterator object. It extracts objects of class Ty from an input stream, which it accesses via an object it stores, of type pointer to basic_istream<Elem, Tr>. 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 Ty 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).

istream_iterator::char_type

typedef Elem char_type;

The type is a synonym for the template parameter Elem.

istream_iterator::istream_iterator

istream_iterator();
istream_iterator(istream_type& istr);

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

istream_iterator::istream_type

typedef basic_istream<Elem, Tr> istream_type;

The type is a synonym for basic_istream<Elem, Tr>.

istream_iterator::operator*

const Ty& operator*() const;

The operator returns the stored object of type Ty.

istream_iterator::operator->

const Ty *operator->() const;

The operator returns &**this.

istream_iterator::operator++

istream_iterator<Ty, Elem, Tr, Diff>& operator++();
istream_iterator<Ty, Elem, Tr, Diff> operator++(int);

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

istream_iterator::traits_type

typedef Tr traits_type;

The type is a synonym for the template parameter Tr.

istreambuf_iterator

template<class Elem, class Tr = char_traits<Elem> >
    class istreambuf_iterator
        : public iterator<input_iterator_tag,
            Elem, typename Ty::off_type, Elem *, Elem&> {
public:
    typedef Elem char_type;
    typedef Tr traits_type;
    typedef typename Tr::int_type int_type;
    typedef basic_streambuf<Elem, Tr> streambuf_type;
    typedef basic_istream<Elem, Tr> istream_type;
    istreambuf_iterator(streambuf_type *strbuf = 0) throw();
    istreambuf_iterator(istream_type& istr) throw();
    Elem operator*() const;
    istreambuf_iterator& operator++();
    istreambuf_iterator operator++(int);
    bool equal(const istreambuf_iterator& right) const;
    };

The template class describes an input iterator object. It extracts elements of class Elem from an input stream buffer, which it accesses via an object it stores, of type pointer to basic_streambuf<Elem, Tr>. 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 Elem from the associated input 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).

istreambuf_iterator::char_type

typedef Elem char_type;

The type is a synonym for the template parameter Elem.

istreambuf_iterator::equal

bool equal(const istreambuf_iterator& right) const;

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

istreambuf_iterator::int_type

typedef typename Tr::int_type int_type;

The type is a synonym for Ty::int_type.

istreambuf_iterator::istream_type

typedef basic_istream<Elem, Tr> istream_type;

The type is a synonym for basic_istream<Elem, Tr>.

istreambuf_iterator::istreambuf_iterator

istreambuf_iterator(streambuf_type *strbuf = 0) throw();
istreambuf_iterator(istream_type& istr) throw();

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

istreambuf_iterator::operator*

Elem operator*() const;

The operator returns the stored object of type Elem.

istreambuf_iterator::operator++

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

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

istreambuf_iterator::streambuf_type

typedef basic_streambuf<Elem, Tr> streambuf_type;

The type is a synonym for basic_streambuf<Elem, Tr>.

istreambuf_iterator::traits_type

typedef Tr traits_type;

The type is a synonym for the template parameter Tr.

iterator

template<class Category, class Ty, class Diff = ptrdiff_t
    class Pointer = Ty *, class Reference = Ty&>
    struct iterator {
    typedef Category iterator_category;
    typedef Ty value_type;
    typedef Diff difference_type;
    typedef Pointer pointer;
    typedef Reference reference;
    };

The template class can serve as a convenient base class for an iterator class that you define. It defines the member types iterator_category (a synonym for the template parameter Category), value_type (a synonym for the template parameter Ty), difference_type (a synonym for the template parameter Diff), pointer (a synonym for the template parameter Pointer), and reference (a synonym for the template parameter Reference).

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 Iter>
    struct iterator_traits {
    typedef typename Iter::iterator_category iterator_category;
    typedef typename Iter::value_type value_type;
    typedef typename Iter::difference_type difference_type;
    typedef typename Iter::pointer pointer;
    typedef typename Iter::reference reference;
    };
template<class Ty>
    struct iterator_traits<Ty *> {
    typedef random_access_iterator_tag iterator_category;
    typedef Ty value_type;
    typedef ptrdiff_t difference_type;
    typedef Ty *pointer;
    typedef Ty& reference;
    };
template<class Ty>
    struct iterator_traits<const Ty *> {
    typedef random_access_iterator_tag iterator_category;
    typedef Ty value_type;
    typedef ptrdiff_t difference_type;
    typedef const Ty *pointer;
    typedef const Tr& reference;
    };

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

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

template<class Category, class Ty, class Diff>
    C _Iter_cat(const iterator<Category, Ty, Diff>&);
template<class Ty>
    random_access_iterator_tag _Iter_cat(const Ty *);

template<class Category, class Ty, class Diff>
    Ty *_Val_type(const iterator<Category, Ty, Diff>&);
template<class Ty>
    Ty *_Val_type(const Ty *);

template<class Category, class Ty, class Diff>
    Diff *_Dist_type(const iterator<Category, Ty, Diff>&);
template<class Ty>
    ptrdiff_t *_Dist_type(const Ty *);

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.

operator!=

template<class RanIt>
    bool operator!=(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
    bool operator!=(
        const istream_iterator<Ty, Elem, Tr, Diff>& left,
        const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
    bool operator!=(
        const istreambuf_iterator<Elem, Tr>& left,
        const istreambuf_iterator<Elem, Tr>& right);

The template operator returns !(left == right).

operator==

template<class RanIt>
    bool operator==(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);
template<class Ty, class Elem, class Tr, class Diff>
    bool operator==(
        const istream_iterator<Ty, Elem, Tr, Diff>& left,
        const istream_iterator<Ty, Elem, Tr, Diff>& right);
template<class Elem, class Tr>
    bool operator==(
        const istreambuf_iterator<Elem, Tr>& left,
        const istreambuf_iterator<Elem, Tr>& right);

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

operator<

template<class RanIt>
    bool operator<(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);

The template operator returns right.current < left.current [sic].

operator<=

template<class RanIt>
    bool operator<=(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);

The template operator returns !(right < left).

operator>

template<class RanIt>
    bool operator>(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);

The template operator returns right < left.

operator>=

template<class RanIt>
    bool operator>=(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);

The template operator returns !(left < right).

operator+

template<class RanIt>
    reverse_iterator<RanIt> operator+(Diff off,
        const reverse_iterator<RanIt>& right);

The template operator returns right + off.

operator-

template<class RanIt>
    Diff operator-(
        const reverse_iterator<RanIt>& left,
        const reverse_iterator<RanIt>& right);

The template operator returns right.current - left.current [sic].

ostream_iterator

template<class Ty, class Elem = char,
    class Tr = char_traits<Elem>  >
    class ostream_iterator
        : public iterator<output_iterator_tag,
            void, void, void, void> {
public:
    typedef Elem char_type;
    typedef Tr traits_type;
    typedef basic_ostream<Elem, Tr> ostream_type;
    ostream_iterator(ostream_type& ostr);
    ostream_iterator(ostream_type& ostr, const Elem *delim);
    ostream_iterator<Ty, Elem, Tr>& operator=(const Ty& val);
    ostream_iterator<Ty, Elem, Tr>& operator*();
    ostream_iterator<Ty, Elem, Tr>& operator++();
    ostream_iterator<Ty, Elem, Tr> operator++(int);
    };

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

ostream_iterator::char_type

typedef Elem char_type;

The type is a synonym for the template parameter Elem.

ostream_iterator::operator*

ostream_iterator<Ty, Elem, Tr>& operator*();

The operator returns *this.

ostream_iterator::operator++

ostream_iterator<Ty, Elem, Tr>& operator++();
ostream_iterator<Ty, Elem, Tr> operator++(int);

The operators both return *this.

ostream_iterator::operator=

ostream_iterator<Ty, Elem, Tr>& operator=(const Ty& val);

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

ostream_iterator::ostream_iterator

ostream_iterator(ostream_type& ostr);
ostream_iterator(ostream_type& ostr, const Elem *delim);

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

ostream_iterator::ostream_type

typedef basic_ostream<Elem, Tr> ostream_type;

The type is a synonym for basic_ostream<Elem, Tr>.

ostream_iterator::traits_type

typedef Tr traits_type;

The type is a synonym for the template parameter Tr.

ostreambuf_iterator

template<class Elem, class Tr = char_traits<Elem> >
    class ostreambuf_iterator
        : public iterator<output_iterator_tag,
            void, void, void, void> {
public:
    typedef Elem char_type;
    typedef Tr traits_type;
    typedef basic_streambuf<Elem, Tr> streambuf_type;
    typedef basic_ostream<Elem, Tr> ostream_type;
    ostreambuf_iterator(streambuf_type *stebuf) throw();
    ostreambuf_iterator(ostream_type& ostr) throw();
    ostreambuf_iterator& operator=(Elem ch);
    ostreambuf_iterator& operator*();
    ostreambuf_iterator& operator++();
    T1 operator++(int);
    bool failed() const throw();
    };

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

ostreambuf_iterator::char_type

typedef Elem char_type;

The type is a synonym for the template parameter Elem.

ostreambuf_iterator::failed

bool failed() const throw();

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

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<Elem, Tr>.

ostreambuf_iterator::operator=

ostreambuf_iterator& operator=(Elem ch);

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

ostreambuf_iterator::ostream_type

typedef basic_ostream<Elem, Tr> ostream_type;

The type is a synonym for basic_ostream<Elem, Tr>.

ostreambuf_iterator::ostreambuf_iterator

ostreambuf_iterator(streambuf_type *strbuf) throw();
ostreambuf_iterator(ostream_type& ostr) throw();

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

ostreambuf_iterator::streambuf_type

typedef basic_streambuf<Elem, Tr> streambuf_type;

The type is a synonym for basic_streambuf<Elem, Tr>.

ostreambuf_iterator::traits_type

typedef Tr traits_type;

The type is a synonym for the template parameter Tr.

output_iterator_tag

struct output_iterator_tag {
    };

The type is the same as iterator<Iter>::iterator_category when Iter 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<Iter>::iterator_category when Iter describes an object that can serve as a random-access iterator.

reverse_iterator

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
        difference_type;
    typedef typename iterator_traits<RanIt>::pointer
        pointer;
    typedef typename iterator_traits<RanIt>::reference
        reference;
public:
    typedef RanIt iterator_type;
    reverse_iterator();
    explicit reverse_iterator(RanIt right);
    template<class Ty>
        reverse_iterator(const reverse_iterator<Ty>& right);
    RanIt base() const;
    reference operator*() const;
    pointer operator->() const;
    reverse_iterator& operator++();
    reverse_iterator operator++(int);
    reverse_iterator& operator--();
    reverse_iterator operator--();
    reverse_iterator& operator+=(difference_type off);
    reverse_iterator operator+(difference_type off) const;
    reverse_iterator& operator-=(difference_type off);
    reverse_iterator operator-(difference_type off) const;
    reference operator[](difference_type off) const;
protected:
    RanIt current;
    };

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 reference. Typically, reference is type Tr&.

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[].

reverse_iterator::base

RanIt base() const;

The member function returns current.

reverse_iterator::difference_type

typedef typename iterator_traits<RanIt>::difference_type
    difference_type;

The type is a synonym for the iterator trait typename iterator_traits<RanIt>::pointer.

reverse_iterator::iterator_type

typedef RanIt iterator_type;

The type is a synonym for the template parameter RanIt.

reverse_iterator::operator*

reference operator*() const;

The operator returns *(current - 1).

reverse_iterator::operator+

reverse_iterator operator+(difference_type off) const;

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

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+=(difference_type off);

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

reverse_iterator::operator-

reverse_iterator operator-(difference_type off) const;

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

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-=(difference_type off);

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

reverse_iterator::operator->

pointer operator->() const;

The operator returns &**this.

reverse_iterator::operator[]

reference operator[](difference_type off) const;

The operator returns *(*this + off).

reverse_iterator::pointer

typedef typename iterator_traits<RanIt>::pointer
    pointer;

The type is a synonym for the iterator trait typename iterator_traits<RanIt>::pointer.

reverse_iterator::reference

typedef typename iterator_traits<RanIt>::reference
    reference;

The type is a synonym for the iterator trait typename iterator_traits<RanIt>::reference.

reverse_iterator::reverse_iterator

reverse_iterator();
explicit reverse_iterator(RanIt right);
template<class Ty>
    reverse_iterator(const reverse_iterator<Ty>& right);

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

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

See also the Table of Contents and the Index.

Copyright © 1994-2002 by P.J. Plauger. Portions derived from work copyright © 1994 by Hewlett-Packard Company. All rights reserved.