Namespaces
Variants
Views
Actions

Standard library header <iterator>

From cppreference.com
< cpp‎ | header
Revision as of 17:10, 5 June 2013 by P12 (Talk | contribs)

This header is part of the iterator library.

Contents

Classes

Primitives
provides uniform interface to the properties of an iterator
(class template) [edit]
empty class types used to indicate iterator categories
(class) [edit]
the basic iterator
(class template) [edit]
Adaptors
iterator adaptor for reverse-order traversal
(class template) [edit]
iterator adaptor which dereferences to an rvalue reference
(class template) [edit]
iterator adaptor for insertion at the end of a container
(class template) [edit]
iterator adaptor for insertion at the front of a container
(class template) [edit]
iterator adaptor for insertion into a container
(class template) [edit]
Stream Iterators
input iterator that reads from std::basic_istream
(class template) [edit]
output iterator that writes to std::basic_ostream
(class template) [edit]
input iterator that reads from std::basic_streambuf
(class template) [edit]
output iterator that writes to std::basic_streambuf
(class template) [edit]

Functions

Adaptors
creates a std::move_iterator of type inferred from the argument
(function template) [edit]
creates a std::front_insert_iterator of type inferred from the argument
(function template) [edit]
creates a std::back_insert_iterator of type inferred from the argument
(function template) [edit]
creates a std::insert_iterator of type inferred from the argument
(function template) [edit]
Operations
advances an iterator by given distance
(function) [edit]
returns the distance between two iterators
(function) [edit]
(C++11)
increment an iterator
(function) [edit]
(C++11)
decrement an iterator
(function) [edit]
Range
(C++11)(C++14)
returns an iterator to the beginning of a container or array
(function) [edit]
(C++11)(C++14)
returns an iterator to the end of a container or array
(function) [edit]
Non-member operators
compares the underlying iterators
(function template) [edit]
advances the iterator
(function template) [edit]
computes the distance between two iterator adaptors
(function template) [edit]
compares the underlying iterators
(function template) [edit]
advances the iterator
(function template) [edit]
computes the distance between two iterator adaptors
(function template) [edit]
compares two istream_iterators
(function template) [edit]
compares two istreambuf_iterators
(function template) [edit]

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 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(const 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
};