# <iterator>

<head><title>&lt;iterator&gt;</title></head>

# `<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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#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);
    }  // namespace stdCopy to clipboard

## `advance`

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

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;
        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;
        };Copy to clipboard

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);Copy to clipboard

The constructor initializes
`container`
with `&cont`.

### `back_insert_iterator::container_type`

    typedef Container container_type;Copy to clipboard

The type is a synonym for the template parameter `Container`.

### `back_insert_iterator::operator*`

    back_insert_iterator& operator*();Copy to clipboard

The member function returns `*this`.

### `back_insert_iterator::operator++`

    back_insert_iterator& operator++();
    back_insert_iterator operator++(int);Copy to clipboard

The member functions both return `*this`.

### `back_insert_iterator::operator=`

    back_insert_iterator&
        operator=(typename Container::const_reference val);Copy to clipboard

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

## `back_inserter`

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

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

## `bidirectional_iterator_tag`

    struct bidirectional_iterator_tag
        : public forward_iterator_tag {
        };Copy to clipboard

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);Copy to clipboard

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 {
        };Copy to clipboard

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;
        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;
        };Copy to clipboard

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;Copy to clipboard

The type is a synonym for the template parameter `Container`.

### `front_insert_iterator::front_insert_iterator`

    explicit front_insert_iterator(Container& cont);Copy to clipboard

The constructor initializes
`container`
with `&cont`.

### `front_insert_iterator::operator*`

    front_insert_iterator& operator*();Copy to clipboard

The member function returns `*this`.

### `front_insert_iterator::operator++`

    front_insert_iterator& operator++();
    front_insert_iterator operator++(int);Copy to clipboard

The member functions both return `*this`.

### `front_insert_iterator::operator=`

    front_insert_iterator&
        operator=(typename Container::const_reference val);Copy to clipboard

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

## `front_inserter`

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

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

## `input_iterator_tag`

    struct input_iterator_tag {
        };Copy to clipboard

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;
        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;
        };Copy to clipboard

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;Copy to clipboard

The type is a synonym for the template parameter `Container`.

### `insert_iterator::insert_iterator`

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

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

### `insert_iterator::operator*`

    insert_iterator& operator*();Copy to clipboard

The member function returns `*this`.

### `insert_iterator::operator++`

    insert_iterator& operator++();
    insert_iterator& operator++(int);Copy to clipboard

The member functions both return `*this`.

### `insert_iterator::operator=`

    insert_iterator&
        operator=(typename Container::const_reference val);Copy to clipboard

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

## `inserter`

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

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);
        };Copy to clipboard

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;Copy to clipboard

The type is a synonym for the template parameter `Elem`.

### `istream_iterator::istream_iterator`

    istream_iterator();
    istream_iterator(istream_type& istr);Copy to clipboard

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;Copy to clipboard

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

### `istream_iterator::operator*`

    const Ty& operator*() const;Copy to clipboard

The operator returns the stored object of type `Ty`.

### `istream_iterator::operator->`

    const Ty *operator->() const;Copy to clipboard

The operator returns `&**this`.

### `istream_iterator::operator++`

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

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;Copy to clipboard

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;
        };Copy to clipboard

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;Copy to clipboard

The type is a synonym for the template parameter `Elem`.

### `istreambuf_iterator::equal`

    bool equal(const istreambuf_iterator& right) const;Copy to clipboard

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;Copy to clipboard

The type is a synonym for
`Ty::int_type`.

### `istreambuf_iterator::istream_type`

    typedef basic_istream<Elem, Tr> istream_type;Copy to clipboard

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();Copy to clipboard

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;Copy to clipboard

The operator returns the stored object of type `Elem`.

### `istreambuf_iterator::operator++`

    istreambuf_iterator& operator++();
    istreambuf_iterator operator++(int);Copy to clipboard

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;Copy to clipboard

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

### `istreambuf_iterator::traits_type`

    typedef Tr traits_type;Copy to clipboard

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;
        };Copy to clipboard

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;
        };Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#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 *);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

The template operator returns `!(right < left)`.

## `operator>`

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

The template operator returns `right < left`.

## `operator>=`

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

The template operator returns `!(left < right)`.

## `operator+`

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

The template operator returns `right + off`.

## `operator-`

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

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);
        };Copy to clipboard

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;Copy to clipboard

The type is a synonym for the template parameter `Elem`.

### `ostream_iterator::operator*`

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

The operator returns `*this`.

### `ostream_iterator::operator++`

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

The operators both return `*this`.

### `ostream_iterator::operator=`

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

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);Copy to clipboard

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;Copy to clipboard

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

### `ostream_iterator::traits_type`

    typedef Tr traits_type;Copy to clipboard

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();
        };Copy to clipboard

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;Copy to clipboard

The type is a synonym for the template parameter `Elem`.

### `ostreambuf_iterator::failed`

    bool failed() const throw();Copy to clipboard

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

### `ostreambuf_iterator::operator*`

    ostreambuf_iterator& operator*();Copy to clipboard

The operator returns `*this`.

### `ostreambuf_iterator::operator++`

    ostreambuf_iterator& operator++();
    T1 operator++(int);Copy to clipboard

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);Copy to clipboard

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

### `ostreambuf_iterator::ostream_type`

    typedef basic_ostream<Elem, Tr> ostream_type;Copy to clipboard

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();Copy to clipboard

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;Copy to clipboard

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

### `ostreambuf_iterator::traits_type`

    typedef Tr traits_type;Copy to clipboard

The type is a synonym for the template parameter `Tr`.

## `output_iterator_tag`

    struct output_iterator_tag {
        };Copy to clipboard

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 {
        };Copy to clipboard

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;
        };Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cont.html#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;Copy to clipboard

The member function returns
`current`.

### `reverse_iterator::difference_type`

    typedef typename iterator_traits<RanIt>::difference_type
        difference_type;Copy to clipboard

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

### `reverse_iterator::iterator_type`

    typedef RanIt iterator_type;Copy to clipboard

The type is a synonym for the template parameter `RanIt`.

### `reverse_iterator::operator*`

    reference operator*() const;Copy to clipboard

The operator returns
`*(current - 1)`.

### `reverse_iterator::operator+`

    reverse_iterator operator+(difference_type off) const;Copy to clipboard

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

### `reverse_iterator::operator++`

    reverse_iterator& operator++();
    reverse_iterator operator++(int);Copy to clipboard

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);Copy to clipboard

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

### `reverse_iterator::operator-`

    reverse_iterator operator-(difference_type off) const;Copy to clipboard

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

### `reverse_iterator::operator--`

    reverse_iterator& operator--();
    reverse_iterator operator--();Copy to clipboard

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);Copy to clipboard

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

### `reverse_iterator::operator->`

    pointer operator->() const;Copy to clipboard

The operator returns `&**this`.

### `reverse_iterator::operator[]`

    reference operator[](difference_type off) const;Copy to clipboard

The operator returns `*(*this + off)`.

### `reverse_iterator::pointer`

    typedef typename iterator_traits<RanIt>::pointer
        pointer;Copy to clipboard

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

### `reverse_iterator::reference`

    typedef typename iterator_traits<RanIt>::reference
        reference;Copy to clipboard

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);Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. Portions derived from work[copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_hp.html) © 1994by Hewlett-Packard Company. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<istream></istream> Next Topic

<limits.h></limits.h>