| United States |
|
|
|
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
|
