# Standard library header <iterator>

From cppreference.com
< cpp‎ | header

This header is part of the iterator library.

### Classes

##### Primitives

iterator_traits | provides uniform interface to the properties of an iterator (class template)
input_iterator_tag output_iterator_tag forward_iterator_tag bidirectional_iterator_tag random_access_iterator_tag | empty class types used to indicate iterator categories (class)
iterator (deprecated in C++17) | base class to ease the definition of required types for simple iterators (class template)

##### Adaptors

reverse_iterator | iterator adaptor for reverse-order traversal (class template)
move_iterator (C++11) | iterator adaptor which dereferences to an rvalue reference (class template)
back_insert_iterator | iterator adaptor for insertion at the end of a container (class template)
front_insert_iterator | iterator adaptor for insertion at the front of a container (class template)
insert_iterator | iterator adaptor for insertion into a container (class template)

##### Stream Iterators

istream_iterator | input iterator that reads from std::basic_istream (class template)
ostream_iterator | output iterator that writes to std::basic_ostream (class template)
istreambuf_iterator | input iterator that reads from std::basic_streambuf (class template)
ostreambuf_iterator | output iterator that writes to std::basic_streambuf (class template)

### Functions

##### Adaptors

make_reverse_iterator (C++14) | creates a std::reverse_iterator of type inferred from the argument (function template)
make_move_iterator (C++11) | creates a std::move_iterator of type inferred from the argument (function template)
front_inserter | creates a std::front_insert_iterator of type inferred from the argument (function template)
back_inserter | creates a std::back_insert_iterator of type inferred from the argument (function template)
inserter | creates a std::insert_iterator of type inferred from the argument (function template)

##### Operations

advance | advances an iterator by given distance (function)
distance | returns the distance between two iterators (function)
next (C++11) | increment an iterator (function)
prev (C++11) | decrement an iterator (function)

##### Range

begin cbegin (C++11)(C++14) | returns an iterator to the beginning of a container or array (function)
end cend (C++11)(C++14) | returns an iterator to the end of a container or array (function)
rbegin crbegin (C++14) | returns a reverse iterator to a container or array (function)
rend crend (C++14) | returns a reverse end iterator for a container or array (function)

##### Non-member operators

operator==operator!=operator<operator<=operator>operator>= | compares the underlying iterators (function template)
operator+ | advances the iterator (function template)
operator- | computes the distance between two iterator adaptors (function template)
operator==operator!=operator<operator<=operator>operator>= | compares the underlying iterators (function template)
operator+ | advances the iterator (function template)
operator- | computes the distance between two iterator adaptors (function template)
operator==operator!= | compares two `istream_iterator`s (function template)
operator==operator!= | compares two `istreambuf_iterator`s (function template)

### Synopsis

    namespace std {
        // primitives:
        template<class Iterator> struct iterator_traits;
        template<class T> struct iterator_traits<T*>;
        template<class Category, class T, class Distance = ptrdiff_t,
        class Pointer = T*, class Reference = T&> struct iterator;

        struct input_iterator_tag { };
        struct output_iterator_tag { };
        struct forward_iterator_tag: public input_iterator_tag { };
        struct bidirectional_iterator_tag: public forward_iterator_tag { };
        struct random_access_iterator_tag: public bidirectional_iterator_tag { };

        // iterator operations:
        template <class InputIterator, class Distance>
            void advance(InputIterator& i, Distance n);
        template <class InputIterator>
            typename iterator_traits<InputIterator>::difference_type
            distance(InputIterator first, InputIterator last);
        template <class ForwardIterator>
            ForwardIterator next(ForwardIterator x,
                typename std::iterator_traits<ForwardIterator>::difference_type n = 1);
        template <class BidirectionalIterator>
            BidirectionalIterator prev(BidirectionalIterator x,
                typename std::iterator_traits<BidirectionalIterator>::difference_type n = 1);

        // predefined iterators:
        template <class Iterator> class reverse_iterator;
        template <class Iterator1, class Iterator2>
            bool operator==(
                const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y);
        template <class Iterator1, class Iterator2>
            bool operator<(
                const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y);
        template <class Iterator1, class Iterator2>
            bool operator!=(
                const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y);
        template <class Iterator1, class Iterator2>
            bool operator>(
                const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y);
        template <class Iterator1, class Iterator2>
            bool operator>=(
                const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y);
        template <class Iterator1, class Iterator2>
            bool operator<=(
                const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y);

        template <class Iterator1, class Iterator2>
            auto operator-(
                const reverse_iterator<Iterator1>& x,
                const reverse_iterator<Iterator2>& y) ->decltype(y.base() - x.base());
        template <class Iterator>
            reverse_iterator<Iterator>
            operator+(
                typename reverse_iterator<Iterator>::difference_type n,
                const reverse_iterator<Iterator>& x);
        template <class Iterator>
            reverse_iterator<Iterator> make_reverse_iterator(Iterator i);

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

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

        template <class Container> class insert_iterator;
        template <class Container>
            insert_iterator<Container> inserter(Container& x, typename Container::iterator i);

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

        template <class Iterator1, class Iterator2>
            auto operator-(
                const move_iterator<Iterator1>& x,
                const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
        template <class Iterator>
            move_iterator<Iterator> operator+(
                typename move_iterator<Iterator>::difference_type n,
                const move_iterator<Iterator>& x);
        template <class Iterator>
            move_iterator<Iterator> make_move_iterator(Iterator i);

        // stream iterators:
        template <class T, class charT = char, class traits = char_traits<charT>,
                class Distance = ptrdiff_t>
            class istream_iterator;
        template <class T, class charT, class traits, class Distance>
            bool operator==(const istream_iterator<T,charT,traits,Distance>& x,
                const istream_iterator<T,charT,traits,Distance>& y);
        template <class T, class charT, class traits, class Distance>
            bool operator!=(const istream_iterator<T,charT,traits,Distance>& x,
                const istream_iterator<T,charT,traits,Distance>& y);

        template <class T, class charT = char, class traits = char_traits<charT> >
            class ostream_iterator;

        template<class charT, class traits = char_traits<charT> >
            class istreambuf_iterator;
        template <class charT, class traits>
            bool operator==(const istreambuf_iterator<charT,traits>& a,
                const istreambuf_iterator<charT,traits>& b);
        template <class charT, class traits>
            bool operator!=(const istreambuf_iterator<charT,traits>& a,
                const istreambuf_iterator<charT,traits>& b);

        template <class charT, class traits = char_traits<charT> >
            class ostreambuf_iterator;

        // range access:
        template <class C> auto begin(C& c) -> decltype(c.begin());
        template <class C> auto begin(const C& c) -> decltype(c.begin());
        template <class C> auto end(C& c) -> decltype(c.end());
        template <class C> auto end(const C& c) -> decltype(c.end());
        template <class T, size_t N> T* begin(T (&array)[N]);
        template <class T, size_t N> T* end(T (&array)[N]);
    }

#### Class std::iterator_traits

    template<class Iterator> struct iterator_traits {
        typedef typename Iterator::difference_type      difference_type;
        typedef typename Iterator::value_type           value_type;
        typedef typename Iterator::pointer              pointer;
        typedef typename Iterator::reference            reference;
        typedef typename Iterator::iterator_category    iterator_category;
    };

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

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

#### Class std::iterator

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

#### Iterator tags

    struct input_iterator_tag { };
    struct output_iterator_tag { };
    struct forward_iterator_tag: public input_iterator_tag { };
    struct bidirectional_iterator_tag: public forward_iterator_tag { };
    struct random_access_iterator_tag: public bidirectional_iterator_tag { };

#### Class std::reverse_iterator

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

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

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

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

        reverse_iterator  operator+ (difference_type n) const;
        reverse_iterator& operator+=(difference_type n);
        reverse_iterator  operator- (difference_type n) const;
        reverse_iterator& operator-=(difference_type n);

        /*unspecified*/ operator[](difference_type n) const;
    protected:
        Iterator current;
    private:
        Iterator deref_tmp; // exposition only
    };

#### Class std::back_insert_iterator

    template <class Container>
    class back_insert_iterator :
        public iterator<output_iterator_tag,void,void,void,void> {
    protected:
        Container* container;
    public:
        typedef Container container_type;

        explicit back_insert_iterator(Container& x);
        back_insert_iterator<Container>&
            operator=(const typename Container::value_type& value);
        back_insert_iterator<Container>&
            operator=(typename Container::value_type&& value);

        back_insert_iterator<Container>& operator*();
        back_insert_iterator<Container>& operator++();
        back_insert_iterator<Container>  operator++(int);
    };

#### Class std::front_insert_iterator

    template <class Container>
    class front_insert_iterator :
        public iterator<output_iterator_tag,void,void,void,void> {
    protected:
        Container* container;
    public:
        typedef Container container_type;

        explicit front_insert_iterator(Container& x);
        front_insert_iterator<Container>&
        operator=(const typename Container::value_type& value);
        front_insert_iterator<Container>&
        operator=(typename Container::value_type&& value);

        front_insert_iterator<Container>& operator*();
        front_insert_iterator<Container>& operator++();
        front_insert_iterator<Container>  operator++(int);
    };

#### Class std::insert_iterator

    template <class Container>
    class insert_iterator :
        public iterator<output_iterator_tag,void,void,void,void> {
    protected:
        Container*                   container;
        typename Container::iterator iter;
    public:
        typedef Container container_type;

        insert_iterator(Container& x, typename Container::iterator i);
        insert_iterator<Container>&
        operator=(const typename Container::value_type& value);
        insert_iterator<Container>&
        operator=(typename Container::value_type&& value);

        insert_iterator<Container>& operator*();
        insert_iterator<Container>& operator++();
        insert_iterator<Container>& operator++(int);
    };

#### Class std::move_iterator

    template <class Iterator>
    class move_iterator {
    public:
        typedef Iterator                                            iterator_type;
        typedef typename iterator_traits<Iterator>::difference_type difference_type;
        typedef Iterator                                            pointer;
        typedef typename iterator_traits<Iterator>::value_type      value_type;
        typedef typename iterator_traits<Iterator>::iterator_category
                                                                    iterator_category;
        typedef value_type&&                                        reference;

        move_iterator();
        explicit move_iterator(Iterator i);
        template <class U> move_iterator(const move_iterator<U>& u);
        template <class U> move_iterator& operator=(const move_iterator<U>& u);

        iterator_type base() const;
        reference operator*() const;
        pointer operator->() const;

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

        move_iterator   operator+(difference_type n) const;
        move_iterator&  operator+=(difference_type n);
        move_iterator   operator-(difference_type n) const;
        move_iterator&  operator-=(difference_type n);
        /*unspecified*/ operator[](difference_type n) const;

    private:
        Iterator current; // exposition only
    };

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/header/iterator&oldid=92150"