iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
iterator
- Base iterator class.
SYNOPSIS
#include <iterator>
template <class Category, class T, class Distance
RWSTD_SIMPLE_DEFAULT(ptrdiff_t)>
struct iterator
{
typedef T value_type;
typedef Distance distance_type;
typedef Category iterator_category;
};
DESCRIPTION
The iterator structure provides a base class from which all other
iterator types can be derived. This structure defines an
interface that consists of three public types: value_type,
distance_type, and iterator_category. These types are used
primarily by classes derived from iterator and by the
iterator_traits class.
See the iterators section in the Class Reference for a description
of iterators and the capabilities associated with various
types.
SEE ALSO
iterator_traits
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
iterator_category
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
iterator_category - Determines the category that an iterator
belongs to. This function is now obsolete. It is
retained in order to provide backward compatibility and support
compilers that do not provide partial specialization.
SYNOPSIS
#include <iterator>
template <class T, class Distance>
inline input_iterator_tag
iterator_category (const input_iterator<T, Distance>&)
inline output_iterator_tag iterator_category (const output_iterator&)
template <class T, class Distance>
inline forward_iterator_tag
iterator_category (const forward_iterator<T, Distance>&)
template <class T, class Distance>
inline bidirectional_iterator_tag
iterator_category (const bidirectional_iterator<T, Distance>&)
template <class T, class Distance>
inline random_access_iterator_tag
iterator_category (const random_access_iterator<T, Distance>&)
template <class T>
inline random_access_iterator_tag iterator_category (const T*)
DESCRIPTION
The iterator_category family of function templates allows you to
determine the category that any iterator belongs to. The
first five functions take an iterator of a specific type and return
the tag for that type. The last takes a T* and returns
random_access_iterator_tag.
TAG TYPES
input_iterator_tag
output_iterator_tag
forward_iterator_tag
bidirectional_iterator_tag
random_access_iterator_tag
The iterator_category function is particularly useful for improving
the efficiency of algorithms. An algorithm can use this
function to select the most efficient implementation an
iterator is capable of handling without sacrificing the ability to
work with a wide range of iterator types. For instance, both the
advance and distance primitives use iterator_category to maximize
their efficiency by using the tag returned from iterator_category to
select from one of several different auxiliary functions.
Because this is a compile time selection, use of this
primitive incurs no significant runtime overhead.
iterator_category is typically used like this:
template <class Iterator>
void foo(Iterator first, Iterator last)
{
__foo(begin,end,iterator_category(first));
}
template <class Iterator>
void __foo(Iterator first, Iterator last,
input_iterator_tag>
{
// Most general implementation
}
template <class Iterator>
void __foo(Iterator first, Iterator last,
bidirectional_iterator_tag>
{
// Implementation takes advantage of bi-diretional
// capability of the iterators
}
_etc.
See the iterator section in the Class Reference for a description of
iterators and the capabilities associated with each type of iterator
tag.
SEE ALSO
Other iterator primitives: value_type, distance_type,
distance,advance, iterator
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
iterator_traits
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
iterator_traits - Provides basic information about an iterator.
SYNOPSIS
template <class Iterator> struct iterator_traits
{
typedef Iterator::value_type value_type;
typedef Iterator::distance_type distance_type;
typedef Iterator::iterator::category iterator_category;
};
// Specialization
template <class T> struct iterator_traits<T*>
{
typedef T value_type;
typedef Distance ptrdiff_t;
typedef Category random_access_iterator_tag;
};
DESCRIPTION
The iterator_traits template and specialization provides a uniform
way for algorithms to access information about a particular
iterator. The template depends on an iterator providing a
basic interface consisting of the types value_type,
distance_type, and iterator_category, or on there being a spe-
cialization for the iterator. The library provides one
specialization (partial) to handle all pointer iterator types.
iterator_traits are used within algorithms to provide local
variables of the type pointed to by the iterator, or of the
iterator's distance type. The traits are is also used to improve the
efficiency of algorithms by making use of knowledge about basic
iterator categories provided by the iterator_category member. An
algorithm can use this "tag" to select the most efficient
implementation an iterator is capable of handling without
sacrificing the ability to work with a wide range of iterator types.
For instance, both the advance and distance primitives use
iterator_category to maximize their efficiency by using the tag to
select from one of several different auxiliary functions. The
iterator_category must therefore be one of the iterator tags
provided by the library.
TAG TYPES
input_iterator_tag
output_iterator_tag
forward_iterator_tag
bidirectional_iterator_tag
random_access_iterator_tag iterator_traits::iterator_category
is typically used like this:
template <class Iterator>
void foo(Iterator first, Iterator last)
{
__foo(begin,end,
iterator_traits<Iterator>::iterator_category);
}
template <class Iterator>
void __foo(Iterator first, Iterator last,
input_iterator_tag>
{
// Most general implementation
}
template <class Iterator>
void __foo(Iterator first, Iterator last,
bidirectional_iterator_tag>
{
// Implementation takes advantage of bi-diretional
// capability of the iterators
}
_etc.
See the iterator section in the Class Reference for a description of
iterators and the capabilities associated with each type of iterator
tag.
WARNING
If your compiler does not support partial specialization then this
template and specialization will not be available to you. Instead
you will need to use the distance_type, value_type, and
iterator_category families of function templates. The Rogue Wave
Standard C++ Library also provides alternate implementations of the
distance, advance, and count functions when partial
specialization is not supported by a particular compiler.
SEE ALSO
value_type, distance_type, iterator_category, distance,advance,
iterator
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
back_inserter
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
back_insert_iterator, back_inserter - An insert iterator used to
insert items at the end of a collection.
SYNOPSIS
#include <iterator>
template <class Container>
class back_insert_iterator : public output_iterator;
DESCRIPTION
Insert iterators let you insert new elements into a collection
rather than copy a new element's value over the value of an
existing element. The class back_insert_iterator is used to insert
items at the end of a collection. The function
back_inserter creates an instance of a back_insert_iterator for
a particular collection type. A back_insert_iterator can be used
with vectors, deques, and lists, but not with maps or sets.
INTERFACE
template <class Container>
class back_insert_iterator : public output_iterator {
protected:
Container& container;
public:
back_insert_iterator (Container&);
back_insert_iterator<Container>&
operator= (const Container::value_type&);
back_insert_iterator<Container>& operator* ();
back_insert_iterator<Container>& operator++ ();
back_insert_iterator<Container> operator++ (int);
};
template <class Container>
back_insert_iterator<Container> back_inserter (Container&);
CONSTRUCTOR
back_insert_iterator (Container& x); Constructor. Creates an
instance of a back_insert_iterator associated with container x.
OPERATORS
back_insert_iterator<Container>& operator= (const
Container::value_type& value); Inserts a copy of value on the
end of the container, and returns *this.
back_insert_iterator<Container>&
operator* ();
Returns *this.
back_insert_iterator<Container>&
operator++ ();
back_insert_iterator<Container>
operator++ (int);
Increments the input iterator and returns *this.
HELPER FUNCTION
template <class Container> back_insert_iterator<Container>
back_inserter (Container& x) Returns a back_insert_iterator that
will insert elements at the end of container x. This function
allows you to create insert iterators inline.
EXAMPLE
//
// ins_itr.cpp
//
#include <iterator>
#include <deque>
#include <iostream.h>
int main ()
{
//
// Initialize a deque using an array.
//
int arr[4] = { 3,4,7,8 };
deque<int> d(arr+0, arr+4);
//
// Output the original deque.
//
cout << "Start with a deque: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// Insert into the middle.
//
insert_iterator<deque<int> > ins(d, d.begin()+2);
*ins = 5; *ins = 6;
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use an insert_iterator: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// A deque of four 1s.
//
deque<int> d2(4, 1);
//
// Insert d2 at front of d.
//
copy(d2.begin(), d2.end(), front_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a front_inserter: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// Insert d2 at back of d.
//
copy(d2.begin(), d2.end(), back_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a back_inserter: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
cout << endl;
return 0;
}
Output :
Start with a deque:
3 4 7 8
Use an insert_iterator:
3 4 5 6 7 8
Use a front_inserter:
1 1 1 1 3 4 5 6 7 8
Use a back_inserter:
1 1 1 1 3 4 5 6 7 8 1 1 1 1
WARNING
If your compiler does not support default template parameters then
you need to always supply the Allocator template argument. For
instance you'll have to write:
vector<int,allocator<int> >
instead of:
vector<int>
SEE ALSO
insert iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
back_insert_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
back_insert_iterator, back_inserter - An insert iterator used to
insert items at the end of a collection.
SYNOPSIS
#include <iterator>
template <class Container>
class back_insert_iterator : public output_iterator;
DESCRIPTION
Insert iterators let you insert new elements into a collection
rather than copy a new element's value over the value of an
existing element. The class back_insert_iterator is used to insert
items at the end of a collection. The function
back_inserter creates an instance of a back_insert_iterator for
a particular collection type. A back_insert_iterator can be used
with vectors, deques, and lists, but not with maps or sets.
INTERFACE
template <class Container>
class back_insert_iterator : public output_iterator {
protected:
Container& container;
public:
back_insert_iterator (Container&);
back_insert_iterator<Container>&
operator= (const Container::value_type&);
back_insert_iterator<Container>& operator* ();
back_insert_iterator<Container>& operator++ ();
back_insert_iterator<Container> operator++ (int);
};
template <class Container>
back_insert_iterator<Container> back_inserter (Container&);
CONSTRUCTOR
back_insert_iterator (Container& x);
Constructor. Creates an instance of a back_insert_iterator
associated with container x.
OPERATORS
back_insert_iterator<Container>&
operator= (const Container::value_type& value);
Inserts a copy of value on the end of the container, and returns
*this.
back_insert_iterator<Container>&
operator* ();
Returns *this.
back_insert_iterator<Container>&
operator++ ();
back_insert_iterator<Container>
operator++ (int);
Increments the input iterator and returns *this.
HELPER FUNCTION
template <class Container>
back_insert_iterator<Container>
back_inserter (Container& x)
Returns a back_insert_iterator that will insert elements at the
end of container x. This function allows you to create insert
iterators inline.
EXAMPLE
//
// ins_itr.cpp
//
#include <iterator>
#include <deque>
#include <iostream.h>
int main ()
{
//
// Initialize a deque using an array.
//
int arr[4] = { 3,4,7,8 };
deque<int> d(arr+0, arr+4);
//
// Output the original deque.
//
cout << "Start with a deque: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// Insert into the middle.
//
insert_iterator<deque<int> > ins(d, d.begin()+2);
*ins = 5; *ins = 6;
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use an insert_iterator: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// A deque of four 1s.
//
deque<int> d2(4, 1);
//
// Insert d2 at front of d.
//
copy(d2.begin(), d2.end(), front_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a front_inserter: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// Insert d2 at back of d.
//
copy(d2.begin(), d2.end(), back_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a back_inserter: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
cout << endl;
return 0;
}
Output :
Start with a deque:
3 4 7 8
Use an insert_iterator:
3 4 5 6 7 8
Use a front_inserter:
1 1 1 1 3 4 5 6 7 8
Use a back_inserter:
1 1 1 1 3 4 5 6 7 8 1 1 1 1
WARNING
If your compiler does not support default template parameters then
you need to always supply the Allocator template argument. For
instance you'll have to write:
vector<int,allocator<int> >
instead of:
vector<int>
SEE ALSO
insert iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Bidirectional_Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Bidirectional_Iterators - An iterator that can both read and write
and can traverse a container in both directions
DESCRIPTION
For a complete discussion of iterators, see the Iterators section of
this reference.
Iterators are a generalization of pointers that allow a C++ program
to uniformly interact with different data structures. Bidirectional
iterators can move both forwards and backwards through a
container, and have the ability to both read and write data.
These iterators satisfy the requirements listed below.
KEY TO ITERATOR REQUIREMENTS
The following key pertains to the iterator descriptions listed below:
a and b values of type X
n value of distance type
u, Distance, tmp and m identifiers
r value of type X&
t value of type T
REQUIREMENTS FOR BIDIRECTIONAL ITERATORS
A bidirectional iterator must meet all the requirements listed
below. Note that most of these requirements are also the
requirements for forward iterators.
X u u might have a singular value
X() X() might be singular
X(a) copy constructor, a == X(a).
X u(a) copy constructor, u == a
X u = a assignment, u == a
a == b, a != b return value convertible to bool
a->m equivalent to (*a).m
*a return value convertible to T&
++r returns X&
r++ return value convertible to const X&
*r++ returns T&
--r returns X&
r-- return value convertible to const X&
*r-- returns T&
Like forward iterators, bidirectional iterators have the condition
that a == b implies *a== *b.
There are no restrictions on the number of passes an algorithm may
make through the structure.
SEE ALSO
Containers, Iterators, Forward Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Forward_Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Forward_Iterators - A forward-moving iterator that can both read
and write.
DESCRIPTION
For a complete discussion of iterators, see the Iterators section of
this reference.
Iterators are a generalization of pointers that allow a C++ program
to uniformly interact with different data structures. Forward
iterators are forward moving, and have the ability to both
read and write data. These iterators satisfy the requirements
listed below.
KEY TO ITERATOR REQUIREMENTS
The following key pertains to the iterator requirements listed below:
a and b values of type X
n value of distance type
u, Distance, tmp and m identifiers
r value of type X&
t value of type T
REQUIREMENTS FOR FORWARD ITERATORS
The following expressions must be valid for forward iterators:
X u u might have a singular value
X() X() might be singular
X(a) copy constructor, a == X(a).
X u(a) copy constructor, u == a
X u = a assignment, u == a
a == b, a != b return value convertible to bool
*a return value convertible to T&
a->m equivalent to (*a).m
++r returns X&
r++ return value convertible to const X&
*r++ returns T&
Forward iterators have the condition that a == b implies *a == *b.
There are no restrictions on the number of passes an algorithm may
make through the structure.
SEE ALSO
Iterators, Bidirectional Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
front_inserter
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
front_insert_iterator, front_inserter - An insert iterator used to
insert items at the beginning of a collection.
SYNOPSIS
#include <iterator>
template <class Container>
class front_insert_iterator : public output_iterator ;
DESCRIPTION
Insert iterators let you insert new elements into a collection
rather than copy a new element's value over the value of an
existing element. The class front_insert_iterator is used to
insert items at the beginning of a collection. The function
front_inserter creates an instance of a front_insert_iterator for a
particular collection type. A front_insert_iterator can be used
with deques and lists, but not with maps or sets.
Note that a front_insert_iterator makes each element that it inserts
the new front of the container. This has the effect of
reversing the order of the inserted elements. For example, if
you use a front_insert_iterator to insert "1" then "2" then "3" onto
the front of container exmpl, you will find, after the
three insertions, that the first three elements of exmpl are "3 2
1".
INTERFACE
template <class Container>
class front_insert_iterator : public output_iterator {
public:
explicit front_insert_iterator (Container&);
front_insert_iterator<Container>&
operator= (const typename Container::value_type&);
front_insert_iterator<Container>& operator* ();
front_insert_iterator<Container>& operator++ ();
front_insert_iterator<Container> operator++ (int);
};
template <class Container>
front_insert_iterator<Container> front_inserter (Container&);
CONSTRUCTOR
explicit
front_insert_iterator(Container& x);
Constructor. Creates an instance of a front_insert_iterator
associated with container x.
OPERATORS
front_insert_iterator<Container>&
operator=(const typename Container::value_type& value);
Assignment Operator. Inserts a copy of value on the front of the
container, and returns *this.
front_insert_iterator<Container>&
operator*();
Returns *this (the input iterator itself).
front_insert_iterator<Container>&
operator++();
front_insert_iterator<Container>
operator++(int);
Increments the insert iterator and returns *this.
NON-MEMBER FUNCTION
template <class Container>
front_insert_iterator<Container>
front_inserter(Container& x)
Returns a front_insert_iterator that will insert elements at the
beginning of container x. This function allows you to create
front insert iterators inline.
EXAMPLE
//
// ins_itr.cpp
//
#include <iterator>
#include <deque>
#include <iostream.h>
int main ()
{
//
// Initialize a deque using an array.
//
int arr[4] = { 3,4,7,8 };
deque<int> d(arr+0, arr+4);
//
// Output the original deque.
//
cout << "Start with a deque: " << endl << " ";
copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
//
// Insert into the middle.
//
insert_iterator<deque<int> > ins(d, d.begin()+2);
*ins = 5; *ins = 6;
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use an insert_iterator: " << endl << " ";
copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
//
// A deque of four 1s.
//
deque<int> d2(4, 1);
//
// Insert d2 at front of d.
//
copy(d2.begin(), d2.end(), front_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a front_inserter: " << endl << " ";
copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
//
// Insert d2 at back of d.
//
copy(d2.begin(), d2.end(), back_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a back_inserter: " << endl << " ";
copy(d.begin(), d.end(), ostream_iterator<int>(cout," "));
cout << endl;
return 0;
}
Output :
Start with a deque:
3 4 7 8
Use an insert_iterator:
3 4 5 6 7 8
Use a front_inserter:
1 1 1 1 3 4 5 6 7 8
Use a back_inserter:
1 1 1 1 3 4 5 6 7 8 1 1 1 1
WARNINGS
If your compiler does not support default template parameters then
you need to always supply the Allocator template argument. For
instance you'll have to write:
deque<int, allocator<int> >
instead of:
deque<int>
SEE ALSO
Insert Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Input_Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Input_Iterators - A read-only, forward moving iterator.
DESCRIPTION
For a complete discussion of iterators, see the Iterators section of
this reference.
Iterators are a generalization of pointers that allow a C++ program
to uniformly interact with different data structures. Input
iterators are read-only, forward moving iterators that satisfy
the requirements listed below.
KEY TO ITERATOR REQUIREMENTS
The following key pertains to the iterator requirement descriptions
listed below:
a and b values of type X
n value of distance type
u, Distance, tmp and m identifiers
r value of type X&
t value of type T
REQUIREMENTS FOR INPUT ITERATORS
The following expressions must be valid for input iterators:
X u(a) copy constructor, u == a
X u = a assignment, u == a
a == b, a != b return value convertible to bool
*a a == b implies *a == *b
++r returns X&
r++ return value convertible to const X&
*r++ returns type T
a -> m returns (*a).m
For input iterators, a == b does not imply that ++a == ++b.
Algorithms using input iterators should be single pass algorithms.
That is they should not pass through the same iterator twice.
The value of type T does not have to be an lvalue.
SEE ALSO
iterators, output iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
inserter
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
insert_iterator, inserter - An insert iterator used to insert items
into a collection rather than overwrite the collection.
SYNOPSIS
#include <iterator>
template <class Container>
class insert_iterator : public output_iterator;
DESCRIPTION
Insert iterators let you insert new elements into a collection
rather than copy a new element's value over the value of an
existing element. The class insert_iterator is used to insert
items into a specified location of a collection. The function
inserter creates an instance of an insert_iterator given a
particular collection type and iterator. An insert_iterator can be
used with vectors, deques, lists, maps and sets.
INTERFACE
template <class Container>
class insert_iterator : public output_iterator {
public:
insert_iterator (Container&, typename Container::iterator);
insert_iterator<Container>&
operator= (const typename Container::value_type&);
insert_iterator<Container>& operator* ();
insert_iterator<Container>& operator++ ();
insert_iterator<Container>& operator++ (int);
};
template <class Container, class Iterator>
insert_iterator<Container> inserter (Container&, Iterator)
CONSTRUCTOR
insert_iterator(Container& x, typename Container::iterator i);
Constructor. Creates an instance of an insert_iterator
associated with container x and iterator i.
OPERATORS
insert_iterator<Container>&
operator=(const typename Container::value_type& value);
Assignment operator. Inserts a copy of value into the container
at the location specified by the insert_iterator, increments the
iterator, and returns *this.
insert_iterator<Container>&
operator*();
Returns *this (the input iterator itself).
insert_iterator<Container>&
operator++();
insert_iterator<Container>&
operator++(int);
Increments the insert iterator and returns *this.
NON-MEMBER FUNCTION
template <class Container, class Iterator>
insert_iterator<Container>
inserter(Container& x, Iterator i);
Returns an insert_iterator that will insert elements into
container x at location i. This function allows you to create
insert iterators inline.
EXAMPLE
#include <iterator>
#include <vector>
#include <iostream.h>
int main()
{
//Initialize a vector using an array
int arr[4] = {3,4,7,8};
vector<int> v(arr,arr+4);
//Output the original vector
cout << "Start with a vector: " << endl << " ";
copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
//Insert into the middle
insert_iterator<vector<int> > ins(v, v.begin()+2);
*ins = 5;
*ins = 6;
//Output the new vector
cout << endl << endl;
cout << "Use an insert_iterator: " << endl << " ";
copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
return 0;
}
WARNINGS
If your compiler does not support default template parameters, then
you need to always supply the Allocator template argument. For
instance, you'll have to write:
vector<int, allocator<int> >
instead of:
vector<int>
SEE ALSO
back_insert_iterator, front_insert_iterator, Insert Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
insert_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
insert_iterator, inserter - An insert iterator used to insert items
into a collection rather than overwrite the collection.
SYNOPSIS
#include <iterator>
template <class Container>
class insert_iterator : public output_iterator;
DESCRIPTION
Insert iterators let you insert new elements into a collection
rather than copy a new element's value over the value of an
existing element. The class insert_iterator is used to insert
items into a specified location of a collection. The function
inserter creates an instance of an insert_iterator given a
particular collection type and iterator. An insert_iterator can be
used with vectors, deques, lists, maps and sets.
INTERFACE
template <class Container>
class insert_iterator : public output_iterator {
public:
insert_iterator (Container&, typename Container::iterator);
insert_iterator<Container>&
operator= (const typename Container::value_type&);
insert_iterator<Container>& operator* ();
insert_iterator<Container>& operator++ ();
insert_iterator<Container>& operator++ (int);
};
template <class Container, class Iterator>
insert_iterator<Container> inserter (Container&, Iterator)
CONSTRUCTOR
insert_iterator(Container& x, typename Container::iterator i);
Constructor. Creates an instance of an insert_iterator
associated with container x and iterator i.
OPERATORS
insert_iterator<Container>&
operator=(const typename Container::value_type& value);
Assignment operator. Inserts a copy of value into the container
at the location specified by the insert_iterator, increments the
iterator, and returns *this.
insert_iterator<Container>&
operator*();
Returns *this (the input iterator itself).
insert_iterator<Container>&
operator++();
insert_iterator<Container>&
operator++(int);
Increments the insert iterator and returns *this.
NON-MEMBER FUNCTION
template <class Container, class Iterator>
insert_iterator<Container>
inserter(Container& x, Iterator i);
Returns an insert_iterator that will insert elements into
container x at location i. This function allows you to create
insert iterators inline.
EXAMPLE
#include <iterator>
#include <vector>
#include <iostream.h>
int main()
{
//Initialize a vector using an array
int arr[4] = {3,4,7,8};
vector<int> v(arr,arr+4);
//Output the original vector
cout << "Start with a vector: " << endl << " ";
copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
//Insert into the middle
insert_iterator<vector<int> > ins(v, v.begin()+2);
*ins = 5;
*ins = 6;
//Output the new vector
cout << endl << endl;
cout << "Use an insert_iterator: " << endl << " ";
copy(v.begin(),v.end(),ostream_iterator<int,char>(cout," "));
return 0;
}
WARNINGS
If your compiler does not support default template parameters, then
you need to always supply the Allocator template argument. For
instance, you'll have to write:
vector<int, allocator<int> >
instead of:
vector<int>
SEE ALSO
back_insert_iterator, front_insert_iterator, Insert Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Insert_Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Insert_Iterators - Iterator adaptor that allows an iterator to
insert into a container rather than overwrite elements in the
container.
SYNOPSIS
#include <iterator>
template <class Container>
class insert_iterator : public output_iterator;
template <class Container>
class back_insert_iterator:public output_iterator;
template <class Container>
class front_insert_iterator : public output_iterator;
DESCRIPTION
Insert iterators are iterator adaptors that let an iterator insert
new elements into a collection rather than overwrite existing
elements when copying to a container. There are several types of
insert iterator classes.
+ The class back_insert_iterator is used to insert items
at the end of a collection. The function back_inserter
can be used with an iterator inline, to create an instance
of a back_insert_iterator for a particular collection type.
+ The class front_insert_iterator is used to insert items
at the start of a collection. The function front_inserter
creates an instance of a front_insert_iterator for a
particular collection type.
+ An insert_iterator inserts new items into a collection at
a location defined by an iterator supplied to the constructor.
Like the other insert iterators, insert_iterator has a helper
function called inserter, which takes a collection and an
iterator into that collection, and creates an instance of
the insert_iterator.
INTERFACE
template <class Container>
class insert_iterator : public output_iterator {
public:
insert_iterator (Container&, typename Container::iterator);
insert_iterator<Container>&
operator= (const typename Container::value_type&);
insert_iterator<Container>& operator* ();
insert_iterator<Container>& operator++ ();
insert_iterator<Container>& operator++ (int);
};
template <class Container>
class back_insert_iterator : public output_iterator {
public:
explicit back_insert_iterator (Container&);
back_insert_iterator<Container>&
operator= (const typename Container::value_type&);
back_insert_iterator<Container>& operator* ();
back_insert_iterator<Container>& operator++ ();
back_insert_iterator<Container> operator++ (int);
};
template <class Container>
class front_insert_iterator : public output_iterator {
public:
explicit front_insert_iterator (Container&);
front_insert_iterator<Container>&
operator= (const typename Container::value_type&);
front_insert_iterator<Container>& operator* ();
front_insert_iterator<Container>& operator++ ();
front_insert_iterator<Container> operator++ (int);
};
template <class Container, class Iterator>
insert_iterator<Container> inserter (Container&, Iterator);
template <class Container>
back_insert_iterator<Container> back_inserter (Container&);
template <class Container>
front_insert_iterator<Container> front_inserter (Container&);
SEE ALSO
back_insert_iterator, front_insert_iterator, insert_iterator
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
istream_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
istream_iterator - Stream iterator that provides iterator
capabilities for istreams. This iterator allows generic algorithms
to be used directly on streams.
SYNOPSIS
#include <iterator>
template <class T, class charT, class traits = ios_traits<charT>,
class Distance = ptrdiff_t>
class istream_iterator : public iterator<input_iterator_tag,
T,Distance>;
DESCRIPTION
Stream iterators provide the standard iterator interface for input
and output streams.
The class istream_iterator reads elements from an input stream
(using operator >>). A value of type T is retrieved and stored
when the iterator is constructed and each time operator++ is
called. The iterator will be equal to the end-of-stream
iterator value if the end-of-file is reached. Use the constructor
with no arguments to create an end-of-stream iterator. The only
valid use of this iterator is to compare to other iterators when
checking for end of file. Do not attempt to dereference the
end-of-stream iterator; it plays the same role as the
past-the-end iterator provided by the end() function of
containers. Since an istream_iterator is an input iterator, you
cannot assign to the value returned by dereferencing the iterator.
This also means that istream_iterators can only be used for sin-
gle pass algorithms.
Since a new value is read every time the operator++ is used on an
istream_iterator, that operation is not equality-preserving. This
means that i == j does not mean that ++i == ++j (although two
end-of-stream iterators are always equal).
INTERFACE
template <class T, class charT, class traits = ios_traits<charT>
class Distance = ptrdiff_t>
class istream_iterator : public iterator<input_iterator_tag,
T, Distance>
{
public:
typedef T value_type;
typedef charT char_type;
typedef traits traits_type;
typedef basic_istream<charT,traits> istream_type;
istream_iterator();
istream_iterator (istream_type&);
istream_iterator
(const stream_iterator<T,charT,traits,Distance>&);
~istream_itertor ();
const T& operator*() const;
const T* operator ->() const;
istream_iterator <T,charT,traits,Distance>& operator++();
istream_iterator <T,charT,traits,Distance> operator++ (int)
};
// Non-member Operators
template <class T, class charT, class traits, class Distance>
bool operator==(const istream_iterator<T,charT,traits,Distance>&,
const istream_iterator<T,charT,traits,Distance>&);
template <class T, class charT, class traits, class Distance>
bool operator!=(const istream_iterator<T,charT,traits,Distance>&,
const istream_iterator<T,charT,traits,Distance>&);
TYPES
value_type;
Type of value to stream in.
char_type;
Type of character the stream is built on.
traits_type;
Traits used to build the stream.
istream_type;
Type of stream this iterator is constructed on.
CONSTRUCTORS
istream_iterator(); Construct an end-of-stream iterator.
This iterator can be used to compare against an end-of-stream
condition. Use it to provide end iterators to algorithms
istream_iterator(istream& s);
Construct an istream_iterator on the given stream.
istream_iterator(const istream_iterator& x);
Copy constructor.
DESTRUCTORS
~istream_iterator();
Destructor.
OPERATORS
const T&
operator*() const;
Return the current value stored by the iterator.
const T*
operator->() const;
Return a pointer to the current value stored by the iterator.
istream_iterator& operator++()
istream_iterator operator++(int)
Retrieve the next element from the input stream.
NON-MEMBER OPERATORS
bool
operator==(const istream_iterator<T,charT,traits,Distance>& x,
const istream_iterator<T,charT,traits,Distance>& y)
Equality operator. Returns true if x is the same as y.
bool
operator!=(const istream_iterator<T,charT,traits,Distance>& x,
const istream_iterator<T,charT,traits,Distance>& y)
Inequality operator. Returns true if x is not the same
as y.
EXAMPLE
//
// io_iter.cpp
//
#include <iterator>
#include <vector>
#include <numeric>
#include <iostream.h>
int main ()
{
vector<int> d;
int total = 0;
//
// Collect values from cin until end of file
// Note use of default constructor to get ending iterator
//
cout << "Enter a sequence of integers (eof to quit): " ;
copy(istream_iterator<int,char>(cin),
istream_iterator<int,char>(),
inserter(d,d.begin()));
//
// stream the whole vector and the sum to cout
//
copy(d.begin(),d.end()-1,
ostream_iterator<int,char>(cout," + "));
if (d.size())
cout << *(d.end()-1) << " = " <<
accumulate(d.begin(),d.end(),total) << endl;
return 0;
}
WARNING
If your compiler does not support default template parameters, then
you will need to always supply the Allocator template argument. And
you'll have to provide all parameters to the istream_iterator
template. For instance, you'll have to write :
vector<int, allocator<int> >
instead of :
vector<int>
SEE ALSO
iterators, ostream_iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
istreambuf_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
istreambuf_iterator
SYNOPSIS
#include <streambuf>
template<class charT, class traits = char_traits<charT> >
class istreambuf_iterator
: public input_iterator
DESCRIPTION
The template class istreambuf_iterator reads successive characters
from the stream buffer for which it was constructed.
operator* provides access to the current input character, if
any, and operator++ advances to the next input character. If
the end of stream is reached, the iterator becomes equal to the
end of stream iterator value, which is constructed by the default
constructor, istreambuf_iterator(). An istreambuf_iterator object
can be used only for one-pass-algorithms.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class istreambuf_iterator
: public input_iterator {
public:
typedef charT char_type;
typedef typename traits::int_type int_type;
typedef traits traits_type;
typedef basic_streambuf<charT, traits> streambuf_type;
typedef basic_istream<charT, traits> istream_type;
class proxy;
istreambuf_iterator() throw();
istreambuf_iterator(istream_type& s) throw();
istreambuf_iterator(streambuf_type *s) throw();
istreambuf_iterator(const proxy& p) throw();
char_type operator*();
istreambuf_iterator<charT, traits>& operator++();
proxy operator++(int);
bool equal(istreambuf_iterator<charT, traits>& b);
};
template<class charT, class traits>
bool operator==(istreambuf_iterator<charT, traits>& a,
istreambuf_iterator<charT, traits>& b);
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
istream_type
The type istream_type is an instantiation of class basic_istream on
types charT and traits:
typedef basic_istream<charT, traits> istream_type;
streambuf_type
The type streambuf_type is an instantiation of class basic_streambuf
on types charT and traits:
typedef basic_streambuf<charT, traits> streambuf_type;
traits_type
The type traits_type is a synonym for the template parameter traits.
NESTED CLASS PROXY
Class istreambuf_iterator<charT,traits>::proxy provides a temporary
placeholder as the return value of the post-increment operator.
It keeps the character pointed to by the previous value of the
iterator for some possible future access.
CONSTRUCTORS
istreambuf_iterator()
throw();
Constructs the end of stream iterator.
istreambuf_iterator(istream_type& s)
throw();
Constructs an istreambuf_iterator that inputs characters using
the basic_streambuf object pointed to by s.rdbuf(). If
s.rdbuf() is a null pointer, the istreambuf_iterator is the
end-of-stream iterator.
istreambuf_iterator(streambuf_type *s)
throw();
Constructs an istreambuf_iterator that inputs characters using
the basic_streambuf object pointed at by s. If s is a null
pointer, the istreambuf_iterator is the end-of-stream iterator.
istreambuf_iterator(const proxy& p)
throw();
Constructs an istreambuf_iterator that uses the basic_streambuf
object embedded in the proxy object.
MEMBER OPERATORS
char_type
operator*();
Returns the character pointed at by the input sequence of the
attached stream buffer. If no character is available, the
iterator becomes equal to the end-of-stream iterator.
istreambuf_iterator<charT, traits>&
operator++();
Increments the input sequence of the attached stream buffer to
point to the next character. If the current character is
the last one, the iterator becomes equal to the end-of-stream
iterator.
proxy
operator++(int);
Increments the input sequence of the attached stream buffer to
point to the next character. If the current character is
the last one, the iterator becomes equal to the end-of-stream
iterator. The proxy object returned contains the character
pointed at before carrying out the post-increment
operator.
PUBLIC MEMBER FUNCTION
bool
equal(istreambuf_iterator<charT, traits>& b);
Returns true if and only if both iterators are at end of stream,
or neither is at end of stream, regardless of what stream
buffer object they are using.
NON MEMBER FUNCTIONS
template<class charT, class traits>
bool
operator==(istreambuf_iterator<charT, traits>& a,
istreambuf_iterator<charT, traits>& b);
Returns a.equal(b).
EXAMPLES
//
// stdlib/examples/manual/istreambuf_iterator.cpp
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// open the file is_iter.out for reading and writing
ofstream out("is_iter.out", ios_base::out | ios_base::in );
// output the example sentence into the file
out << "Ceci est un simple example pour demontrer le" << endl;
out << "fonctionement de istreambuf_iterator";
// seek to the beginning of the file
out.seekp(0);
// construct an istreambuf_iterator pointing to
// the ofstream object underlying stream buffer
istreambuf_iterator<char> iter(out.rdbuf());
// construct an end of stream iterator
istreambuf_iterator<char> end_of_stream_iterator;
cout << endl;
// output the content of the file
while( !iter.equal(end_of_stream_iterator) )
// use both operator++ and operator*
cout << *iter++;
cout << endl;
}
SEE ALSO
basic_streambuf, basic_istream,
ostreambuf_iterator
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 24.4.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ostream_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
ostream_iterator - Stream iterators provide iterator capabilities
for ostreams and istreams. They allow generic algorithms to be
used directly on streams.
SYNOPSIS
#include <ostream>
template <class T, class charT,
class traits = char_traits<charT> >
class ostream_iterator
: public iterator<output_iterator_tag,void,void>;
DESCRIPTION
Stream iterators provide the standard iterator interface for input
and output streams.
The class ostream_iterator writes elements to an output stream. If
you use the constructor that has a second, char * argument, then
that string will be written after every element . (The
string must be null-terminated.) Since an ostream iterator is an
output iterator, it is not possible to get an element out of
the iterator. You can only assign to it.
INTERFACE
template <class T, class charT,
class traits = char_traits<charT> >
class ostream_iterator
: public iterator<output_iterator_tag,void,void>
{
public:
typedef T value_type;
typedef charT char_type;
typedef traits traits_type;
typedef basic_ostream<charT,traits> ostream_type;
ostream_iterator(ostream&);
ostream_iterator (ostream&, const char*);
ostream_iterator (const
ostream_iterator<T,charT,char_traits<charT> >&);
~ostream_itertor ();
ostream_iterator<T,charT,char_traits<charT> >&
operator=(const T&);
ostream_iterator<T,charT,char_traits<charT> >&
operator* () const;
ostream_iterator<T,charT,char_traits<charT> >& operator++ ();
ostream_iterator<T,charT,char_traits<charT> > operator++ (int);
};
TYPES
value_type;
Type of value to stream in.
char_type;
Type of character the stream is built on.
traits_type;
Traits used to build the stream.
ostream_type;
Type of stream this iterator is constructed on.
CONSTRUCTORS
ostream_iterator (ostream& s);
Construct an ostream_iterator on the given stream.
ostream_iterator (ostream& s, const char* delimiter);
Construct an ostream_iterator on the given stream. The null
terminated string delimitor is written to the stream after
every element.
ostream_iterator (const ostream_iterator<T>& x);
Copy constructor.
DESTRUCTOR
~ostream_iterator ();
Destructor
OPERATORS
const T&
operator= (const T& value);
Shift the value T onto the output stream.
const T& ostream_iterator<T>&
operator* ();
ostream_iterator<T>&
operator++();
ostream_iterator<T>
operator++ (int);
These operators all do nothing. They simply allow the iterator
to be used in common constructs.
EXAMPLE
#include <iterator>
#include <numeric>
#include <deque>
#include <iostream.h>
int main ()
{
//
// Initialize a vector using an array.
//
int arr[4] = { 3,4,7,8 };
int total=0;
deque<int> d(arr+0, arr+4);
//
// stream the whole vector and a sum to cout
//
copy(d.begin(),d.end()-1,
ostream_iterator<int,char>(cout," + "));
cout << *(d.end()-1) << " = " <<
accumulate(d.begin(),d.end(),total) << endl;
return 0;
}
WARNING
If your compiler does not support default template parameters, then
you need to always supply the Allocator template argument. For
instance, you will need to write :
deque<int, allocator<int> >
instead of :
deque<int>
SEE ALSO
istream_iterator, iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ostreambuf_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
ostreambuf_iterator
SYNOPSIS
#include <streambuf>
template<class charT, class traits = char_traits<charT> >
class ostreambuf_iterator
: public output_iterator
DESCRIPTION
The template class ostreambuf_iterator writes successive characters
onto the stream buffer object from which it was constructed. The
operator= is used to write the characters and in case of
failure the member function failed() returns true.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class ostreambuf_iterator
: public output_iterator {
public:
typedef charT char_type;
typedef traits traits_type;
typedef basic_streambuf<charT, traits> streambuf_type;
typedef basic_ostream<charT, traits> ostream_type;
ostreambuf_iterator(ostream_type& s) throw();
ostreambuf_iterator(streambuf_type *s) throw();
ostreambuf_iterator& operator*();
ostreambuf_iterator& operator++();
ostreambuf_iterator operator++(int);
ostreambuf_iterator& operator=(charT c);
bool failed( ) const throw();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
ostream_type
The type ostream_type is an instantiation of class basic_ostream
on types charT and traits:
typedef basic_ostream<charT, traits> ostream_type;
streambuf_type
The type streambuf_type is an instantiation of class
basic_streambuf on types charT and traits:
typedef basic_streambuf<charT, traits> streambuf_type;
traits_type
The type traits_type is a synonym for the template parameter
traits.
CONSTRUCTORS
ostreambuf_iterator(ostream_type& s) throw();
Constructs an ostreambuf_iterator that uses the basic_streambuf
object pointed at by s.rdbuf()to output characters. If s.rdbuf()
is a null pointer, calls to the member function failed() return
true.
ostreambuf_iterator(streambuf_type *s) throw();
Constructs an ostreambuf_iterator that uses the basic_streambuf
object pointed at by s to output characters. If s is a null
pointer, calls to the member function failed() return true.
MEMBER OPERATORS
ostreambuf_iterator&
operator=(charT c);
Inserts the character c into the output sequence of the attached
stream buffer. If the operation fails, calls to the member
function failed() return true.
ostreambuf_iterator&
operator++();
Returns *this.
ostreambuf_iterator
operator++(int);
Returns *this.
ostreambuf_iterator
operator*();
Returns *this.
PUBLIC MEMBER FUNCTION
bool
failed() const
throw();
Returns true if the iterator failed inserting a characters or
false otherwise.
EXAMPLES
//
// stdlib/examples/manual/ostreambuf_iterator.cpp
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// create a filebuf object
filebuf buf;
// open the file iter_out and link it to the filebuf object
buf.open("iter_out", ios_base::in | ios_base::out );
// create an ostreambuf_iterator and link it to
// the filebuf object
ostreambuf_iterator<char> out_iter(&buf);
// output into the file using the ostreambuf_iterator
for(char i=64; i<128; i++ )
out_iter = i;
// seek to the beginning of the file
buf.pubseekpos(0);
// create an istreambuf_iterator and link it to
// the filebuf object
istreambuf_iterator<char> in_iter(&buf);
// construct an end of stream iterator
istreambuf_iterator<char> end_of_stream_iterator;
cout << endl;
// output the content of the file
while( !in_iter.equal(end_of_stream_iterator) )
// use both operator++ and operator*
cout << *in_iter++;
cout << endl;
}
SEE ALSO
basic_streambuf, basic_ostream,
istreambuf_iterator
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 24.4.4
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Output_Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Output_Iterators - A write-only, forward moving iterator.
DESCRIPTION
For a complete discussion of iterators, see the Iterators section of
this reference.
Iterators are a generalization of pointers that allow a C++ program
to uniformly interact with different data structures. Output
iterators are write-only, forward moving iterators that satisfy the
requirements listed below. Note that unlike other iterators used
with the standard library, output iterators cannot be constant.
KEY TO ITERATOR REQUIREMENTS
The following key pertains to the iterator requirements listed
below:
a and b values of type X
n value of distance type
u, Distance, tmp and m identifiers
r value of type X&
t value of type T
REQUIREMENTS FOR OUTPUT ITERATORS
The following expressions must be valid for output iterators:
X(a) copy constructor, a == X(a).
X u(a) copy constructor, u == a
X u = a assignment, u == a
*a = t result is not used
++r returns X&
r++ return value convertible to const X&
*r++ = t result is not used
The only valid use for the operator * is on the left hand side of
the assignment statement.
Algorithms using output iterators should be single pass algorithms.
That is, they should not pass through the same iterator twice.
SEE ALSO
Iterators, Input Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Random_Access_Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Random_Access_Iterators - An iterator that reads and writes, and
provides random access to a container.
DESCRIPTION
For a complete discussion of iterators, see the Iterators section of
this reference.
Iterators are a generalization of pointers that allow a C++ program
to uniformly interact with different data structures. Random
access iterators can read and write, and provide random access
to the containers they serve. These iterators satisfy the
requirements listed below.
KEY TO ITERATOR REQUIREMENTS
The following key pertains to the iterator requirements listed
below:
a and b values of type X
n value of distance type
u, Distance, tmp and m identifiers
r value of type X&
t value of type T
REQUIREMENTS FOR RANDOM ACCESS ITERATORS
The following expressions must be valid for random access iterators:
X u u might have a singular value
X() X() might be singular
X(a) copy constructor, a == X(a).
X u(a) copy constructor, u == a
X u = a assignment, u == a
a == b, a != b return value convertible to bool
*a return value convertible to T&
a->m equivalent to (*a).m
++r returns X&
r++ return value convertible to const X&
*r++ returns T&
--r returns X&
r-- return value convertible to const X&
*r-- returns T&
r += n Semantics of --r or ++r n times depending on the sign
of n
a + n, n + a returns type X
r -= n returns X&, behaves as r += -n
a - n returns type X
b - a returns Distance
a[n] *(a+n), return value convertible to T
a < b total ordering relation
a > b total ordering relation opposite to <
a <= b !(a < b)
a >= b !(a > b)
Like forward iterators, random access iterators have the condition
that a == b implies *a == *b.
There are no restrictions on the number of passes an algorithm may
make through the structure.
All relational operators return a value convertible to bool.
SEE ALSO
Iterators, Forward Iterators, Bidirectional Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
raw_storage_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
raw_storage_iterator - Enables iterator-based algorithms to store
results into uninitialized memory.
SYNOPSIS
#include <memory>
template <class OutputIterator, class T>
class raw_storage_iterator : public output_iterator {
public:
explicit raw_storage_iterator (OutputIterator);
raw_storage_iterator<OutputIterator, t>& operator*();
raw_storage_iterator<OutputIterator, T>&
operator= (const T&);
raw_storage_iterator<OutputIterator>& operator++();
raw_storage_iterator<OutputIterator> operator++ (int);
};
DESCRIPTION
Class raw_storage_iterator enables iterator-based algorithms to
store their results in uninitialized memory. The template
parameter, OutputIterator is required to have its operator* return
an object for which operator& is both defined and returns a
pointer to T.
CONSTRUCTOR
raw_storage_iterator (OutputIterator x);
Initializes the iterator to point to the same value that x
points to.
MEMBER OPERATORS
raw_storage_iterator <OutputIterator, T>&
operator =(const T& element);
Constructs an instance of T, initialized to the value element ,
at the location pointed to by the iterator.
raw_storage_iterator <OutputIterator, T>&
operator++();
Pre-increment: advances the iterator and returns a reference
to the updated iterator.
raw_storage_iterator<OutputIterator>
operator++ (int);
Post-increment: advances the iterator and returns the old
value of the iterator.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
reverse_bidirectional_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
reverse_bidirectional_iterator, reverse_iterator - An iterator that
traverses a collection backwards.
SYNOPSIS
#include <iterator>
template <class BidirectionalIterator,
class T,
class Reference = T&,
class Pointer = T*
class Distance = ptrdiff_t>
class reverse_bidirectional_iterator : public
iterator<bidirectional_iterator_tag,T, Distance> ;
template <class RandomAccessIterator,
class T,
class Reference = T&,
class Pointer = T*,
class Distance = ptrdiff_t>
class reverse_iterator : public
iterator<random_access_iterator_tag,T,Distance>;
DESCRIPTION
The iterators reverse_iterator and reverse_bidirectional_iterator
correspond to random_access_iterator and bidirectional_iterator,
except they traverse the collection they point to in the opposite
direction. The fundamental relationship between a reverse
iterator and its corresponding iterator i is established by the
identity:
&*(reverse_iterator(i)) == &*(i-1);
This mapping is dictated by the fact that, while there is always a
pointer past the end of a container, there might not be a valid
pointer before its beginning.
The following are true for reverse_bidirectional_iterators :
+ These iterators may be instantiated with the default
constructor or by a single argument constructor that
initializes the new reverse_bidirectional_iterator with a
bidirectional_iterator.
+ operator* returns a reference to the current value pointed to.
+ operator++ advances the iterator to the previous item
(--current) and returns a reference to *this.
+ operator++(int) advances the iterator to the previous
item (--current) and returns the old value of *this.
+ operator-- advances the iterator to the following item
(++current) and returns a reference to *this.
+ operator--(int) Advances the iterator to the following item
(++current) and returns the old value of *this.
+ operator== This non-member operator returns true if the
iterators x and y point to the same item.
The following are true for reverse_iterators :
+ These iterators may be instantiated with the default
constructor or by a single argument constructor which
initializes the new reverse_iterator with a
random_access_iterator.
+ operator* returns a reference to the current value pointed
to.
+ operator++ advances the iterator to the previous item
(--current) and returns a reference to *this.
+ operator++(int) advances the iterator to the previous item
(--current) and returns the old value of *this.
+ operator-- advances the iterator to the following item
(++current) and returns a reference to *this.
+ operator--(int) advances the iterator to the following item
(++current) and returns the old value of *this.
+ operator== is a non-member operator returns true if the
iterators x and y point to the same item.
+ operator!= is a non-member operator returns !(x==y).
+ operator< is a non-member operator returns true if the
iterator x precedes the iterator y.
+ operator> is a non-member operator returns y < x.
+ operator<= is a non-member operator returns !(y < x).
+ operator>= is a non-member operator returns !(x < y).
+ The remaining operators (<, +, - , +=, -=) are redefined
to behave exactly as they would in a random_access_iterator,
except with the sense of direction reversed.
COMPLEXITY
All iterator operations are required to take at most amortized
constant time.
INTERFACE
template <class BidirectionalIterator,
class T,
class Reference = T&,
class Pointer = T*,
class Distance = ptrdiff_t>
class reverse_bidirectional_iterator
: public iterator<bidirectional_iterator_tag,T, Distance> {
typedef reverse_bidirectional_iterator<BidirectionalIterator, T,
Reference,
Pointer, Distance> self;
friend bool operator== (const self&, const self&);
public:
reverse_bidirectional_iterator ();
explicit reverse_bidirectional_iterator
(BidirectionalIterator);
BidirectionalIterator base ();
Reference operator* ();
self& operator++ ();
self operator++ (int);
self& operator-- ();
self operator-- (int);
};
// Non-member Operators
template <class BidirectionalIterator,
class T, class Reference,
class Pointer, class Distance>
bool operator== (
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&,
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&);
template <class BidirectionalIterator,
class T, class Reference,
class Pointer, class Distance>
bool operator!= (
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&,
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&);
template <class RandomAccessIterator,
class T,
class Reference = T&,
class Pointer = T*,
class Distance = ptrdiff_t>
class reverse_iterator
: public iterator<random_access_iterator_tag,T,Distance> {
typedef reverse_iterator<RandomAccessIterator, T, Reference,
Pointer, Distance> self;
friend bool operator== (const self&, const self&);
friend bool operator< (const self&, const self&);
friend Distance operator- (const self&, const self&);
friend self operator+ (Distance, const self&);
public:
reverse_iterator ();
explicit reverse_iterator (RandomAccessIterator);
RandomAccessIterator base ();
Reference operator* ();
self& operator++ ();
self operator++ (int);
self& operator-- ();
self operator-- (int);
self operator+ (Distance) const;
self& operator+= (Distance);
self operator- (Distance) const;
self& operator-= (Distance);
Reference operator[] (Distance);
};
// Non-member Operators
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator== (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator!= (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator< (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator> (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator<= (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator>= (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> Distance operator- (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance>
reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance> operator+ (
Distance,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
EXAMPLE
//
// rev_itr.cpp
//
#include <iterator>
#include <vector>
#include <iostream.h>
int main()
{
//Initialize a vector using an array
int arr[4] = {3,4,7,8};
vector<int> v(arr,arr+4);
//Output the original vector
cout << "Traversing vector with iterator: " << endl << " ";
for(vector<int>::iterator i = v.begin(); i != v.end(); i++)
cout << *i << " ";
//Declare the reverse_iterator
vector<int>::reverse_iterator rev(v.end());
vector<int>::reverse_iterator rev_end(v.begin());
//Output the vector backwards
cout << endl << endl;
cout << "Same vector, same loop, reverse_itertor: " << endl
<< " ";
for(; rev != rev_end; rev++)
cout << *rev << " ";
return 0;
}
Output :
Traversing vector with iterator:
3 4 7 8
Same vector, same loop, reverse_itertor:
8 7 4 3
WARNING
If your compiler does not support default template parameters, then
you need to always supply the Allocator template argument. For
instance, you will need to write :
vector<int, allocator<int> >
instead of :
vector<int>
SEE ALSO
Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
reverse_iterator
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
reverse_bidirectional_iterator, reverse_iterator - An iterator that
traverses a collection backwards.
SYNOPSIS
#include <iterator>
template <class BidirectionalIterator,
class T,
class Reference = T&,
class Pointer = T*
class Distance = ptrdiff_t>
class reverse_bidirectional_iterator : public
iterator<bidirectional_iterator_tag,T, Distance> ;
template <class RandomAccessIterator,
class T,
class Reference = T&,
class Pointer = T*,
class Distance = ptrdiff_t>
class reverse_iterator : public
iterator<random_access_iterator_tag,T,Distance>;
DESCRIPTION
The iterators reverse_iterator and reverse_bidirectional_iterator
correspond to random_access_iterator and bidirectional_iterator,
except they traverse the collection they point to in the opposite
direction. The fundamental relationship between a reverse
iterator and its corresponding iterator i is established by the
identity:
&*(reverse_iterator(i)) == &*(i-1);
This mapping is dictated by the fact that, while there is always a
pointer past the end of a container, there might not be a valid
pointer before its beginning.
The following are true for reverse_bidirectional_iterators :
+ These iterators may be instantiated with the default
constructor or by a single argument constructor that
initializes the new reverse_bidirectional_iterator with a
bidirectional_iterator.
+ operator* returns a reference to the current value pointed
to.
+ operator++ advances the iterator to the previous item
(--current) and returns a reference to *this.
+ operator++(int) advances the iterator to the previous item
(--current) and returns the old value of *this.
+ operator-- advances the iterator to the following item
(++current) and returns a reference to *this.
+ operator--(int) Advances the iterator to the following item
(++current) and returns the old value of *this.
+ operator== This non-member operator returns true if the
iterators x and y point to the same item.
The following are true for reverse_iterators :
+ These iterators may be instantiated with the default
constructor or by a single argument constructor which
initializes the new reverse_iterator with a
random_access_iterator.
+ operator* returns a reference to the current value pointed
to.
+ operator++ advances the iterator to the previous item
(--current) and returns a reference to *this.
+ operator++(int) advances the iterator to the previous item
(--current) and returns the old value of *this.
+ operator-- advances the iterator to the following item
(++current) and returns a reference to *this.
+ operator--(int) advances the iterator to the following item
(++current) and returns the old value of *this.
+ operator== is a non-member operator returns true if the
iterators x and y point to the same item.
+ operator!= is a non-member operator returns !(x==y).
+ operator< is a non-member operator returns true if the
iterator x precedes the iterator y.
+ operator> is a non-member operator returns y < x.
+ operator<= is a non-member operator returns !(y < x).
+ operator>= is a non-member operator returns !(x < y).
+ The remaining operators (<, +, - , +=, -=) are redefined
to behave exactly as they would in a
random_access_iterator, except with the sense of direction
reversed.
COMPLEXITY
All iterator operations are required to take at most amortized
constant time.
INTERFACE
template <class BidirectionalIterator,
class T,
class Reference = T&,
class Pointer = T*,
class Distance = ptrdiff_t>
class reverse_bidirectional_iterator
: public iterator<bidirectional_iterator_tag,T, Distance> {
typedef reverse_bidirectional_iterator<BidirectionalIterator, T,
Reference,
Pointer, Distance> self;
friend bool operator== (const self&, const self&);
public:
reverse_bidirectional_iterator ();
explicit reverse_bidirectional_iterator
(BidirectionalIterator);
BidirectionalIterator base ();
Reference operator* ();
self& operator++ ();
self operator++ (int);
self& operator-- ();
self operator-- (int);
};
// Non-member Operators
template <class BidirectionalIterator,
class T, class Reference,
class Pointer, class Distance>
bool operator== (
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&,
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&);
template <class BidirectionalIterator,
class T, class Reference,
class Pointer, class Distance>
bool operator!= (
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&,
const reverse_bidirectional_iterator
<BidirectionalIterator,T,Reference,Pointer,Distance>&);
template <class RandomAccessIterator,
class T,
class Reference = T&,
class Pointer = T*,
class Distance = ptrdiff_t>
class reverse_iterator
: public iterator<random_access_iterator_tag,T,Distance> {
typedef reverse_iterator<RandomAccessIterator, T, Reference,
Pointer, Distance> self;
friend bool operator== (const self&, const self&);
friend bool operator< (const self&, const self&);
friend Distance operator- (const self&, const self&);
friend self operator+ (Distance, const self&);
public:
reverse_iterator ();
explicit reverse_iterator (RandomAccessIterator);
RandomAccessIterator base ();
Reference operator* ();
self& operator++ ();
self operator++ (int);
self& operator-- ();
self operator-- (int);
self operator+ (Distance) const;
self& operator+= (Distance);
self operator- (Distance) const;
self& operator-= (Distance);
Reference operator[] (Distance);
};
// Non-member Operators
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator== (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator!= (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator< (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator> (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator<= (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> bool operator>= (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance> Distance operator- (
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
template <class RandomAccessIterator, class T,
class Reference, class Pointer,
class Distance>
reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance> operator+ (
Distance,
const reverse_iterator<RandomAccessIterator, T,
Reference, Pointer,
Distance>&);
EXAMPLE
//
// rev_itr.cpp
//
#include <iterator>
#include <vector>
#include <iostream.h>
int main()
{
//Initialize a vector using an array
int arr[4] = {3,4,7,8};
vector<int> v(arr,arr+4);
//Output the original vector
cout << "Traversing vector with iterator: " << endl << " ";
for(vector<int>::iterator i = v.begin(); i != v.end(); i++)
cout << *i << " ";
//Declare the reverse_iterator
vector<int>::reverse_iterator rev(v.end());
vector<int>::reverse_iterator rev_end(v.begin());
//Output the vector backwards
cout << endl << endl;
cout << "Same vector, same loop, reverse_itertor: " << endl
<< " ";
for(; rev != rev_end; rev++)
cout << *rev << " ";
return 0;
}
Output :
Traversing vector with iterator:
3 4 7 8
Same vector, same loop, reverse_itertor:
8 7 4 3
WARNING
If your compiler does not support default template parameters, then
you need to always supply the Allocator template argument. For
instance, you will need to write :
vector<int, allocator<int> >
instead of :
vector<int>
SEE ALSO
Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Stream_Iterators
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
Stream_Iterators - Stream iterators provide iterator capabilities
for ostreams and istreams. They allow generic algorithms to be
used directly on streams.
See the sections istream_iterator and ostream_iterator for a
description of these iterators.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
value_type
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
value_type - Determine the type of value an iterator points to.
This function is now obsolete. It is retained in order to
provide backward compatibility and support compilers that do not
provide partial specialization.
SYNOPSIS
#include <iterator>
template <class T, class Distance>
inline T* value_type (const input_iterator<T, Distance>&)
template <class T, class Distance>
inline T* value_type (const forward_iterator<T, Distance>&)
template <class T, class Distance>
inline T* value_type (const bidirectional_iterator<T, Distance>&)
template <class T, class Distance>
inline T* value_type (const random_access_iterator<T, Distance>&)
template <class T>
inline T* value_type (const T*)
DESCRIPTION
The value_type function template returns a pointer to a default
value of the type pointed to by an iterator. Five overloaded
versions of this function template handle the four basic
iterator types and simple arrays. Each of the first four take
an iterator of a specific type, and return the value used to
instantiate the iterator. The fifth version takes and returns a T*
in order to handle the case when an iterator is a simple pointer.
This family of function templates can be used to extract a value
type from an iterator and subsequently use that type to create
a local variable. Typically the value_type functions are used
like this:
template <class Iterator>
void foo(Iterator first, Iterator last)
{
__foo(begin,end,value_type(first));
}
template <class Iterator, class T>
void __foo(Iterator first, Iterator last, T*>
{
T temp = *first;
_
}
The auxiliary function __foo extracts a usable value type from the
iterator and then puts the type to work.
SEE ALSO
Other iterator primitives: distance_type, iterator_category,
distance, advance
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
