.\" ident @(#)istream_iterator.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH istream_iterator 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2istream_iterator\fP \ - A stream iterator that has iterator capabilities for istreams. This iterator allows generic algorithms to be used directly on streams. .SH SYNOPSIS .br #include .br template , .RE .RS 9 class Distance = ptrdiff_t> .RE .RS 0 class istream_iterator : public iterator; .SH DESCRIPTION Stream iterators are the standard iterator interface for input and output streams. The class_istream_iterator reads elements from an input stream using operator \f2>>\fP. A value of type \f2T\fP is retrieved and stored when the iterator is constructed and each time \f2operator++\fP is called. The iterator is equal to the end-of-stream iterator value if the end-of-file is reached. You can 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 of the \f2end()\fP 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 single pass algorithms. Since a new value is read every time the\f2 operator++\fP is used on an istream_iterator, that operation is not equality-preserving. This means that \f2i == j \fPdoes not mean that \f2++i == ++j\fP (although two end-of-stream iterators are always equal). .SH INTERFACE .RE .RS 0 template .RE .RS 9 class Distance = ptrdiff_t> .RE .RS 0 class istream_iterator : .RE .RS 9 public iterator .RE .RS 1 { .RE .RS 0 .br public: .RE .RS 3 typedef T value_type; .br typedef charT char_type; .br typedef traits traits_type; .br typedef basic_istream istream_type; .RE .RS 0 .RE .RS 3 istream_iterator(); .br istream_iterator (istream_type&); .br istream_iterator .RE .RS 10 (const stream_iterator&); .RE .RS 4 ~istream_itertor (); .RE .RS 0 .RE .RS 3 const T& operator*() const; .br const T* operator ->() const; .br istream_iterator & operator++(); .RE .RS 3 istream_iterator .RE .RS 21 operator++ (int) .RE .RS 1 }; .RE .RS 0 .br // Non-member Operators .br .br template .br bool operator==(const istream_iterator&, .RE .RS 9 const istream_iterator&); .RE .RS 0 .br template .br bool operator!=(const istream_iterator&, .RE .RS 9 const istream_iterator&); .SH TYPES .RE .RS 0 value_type; .RE .RS 3 Type of value to stream in. .RE .br char_type; .RE .RS 3 Type of character the stream is built on. .RE .br traits_type; .RE .RS 3 Traits used to build the stream. .RE .br istream_type; .RE .RS 3 Type of stream this iterator is constructed on. .RE .SH CONSTRUCTORS .br istream_iterator(); .RE .RS 3 Constructs 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. .RE .br istream_iterator(istream& s); .RE .RS 3 Constructs an istream_iterator on the given stream. .RE .br istream_iterator(const istream_iterator& x); .RE .RS 3 Copy constructor. .RE .SH DESTRUCTORS .br ~istream_iterator(); .SH OPERATORS .br const T& .br operator*() const; .RE .RS 3 Returns the current value stored by the iterator. .RE .br const T* .br operator->() const; .RE .RS 3 Returns a pointer to the current value stored by the iterator. .RE .br istream_iterator& operator++() .br istream_iterator operator++(int) .RE .RS 3 Retrieves the next element from the input stream. .RE .SH NON-MEMBER OPERATORS .br bool .br operator==(const istream_iterator& x, .br const .br istream_iterator& y) .RE .RS 3 Returns \f2true\fP if \f2x\fP is the same as \f2y\fP. .RE .RE .RS 0 bool .br operator!=(const istream_iterator& x, .br const .br istream_iterator& y) .RE .RS 3 Returns \f2true\fP if \f2x\fP is not the same as \f2y\fP. .RE .SH EXAMPLE .RE .RS 0 // .br // io_iter.cpp .br // .RE .RS 1 #include .br #include .br #include .br #include .RE .RS 0 using namespace std; .br .br int main () .RE .RS 1 { .RE .RS 2 vector d; .br int total = 0; .RE .RS 3 // .br // Collect values from cin until end of file .br // Note use of default constructor to get ending iterator .br // .RE .RS 2 cout << "Enter a sequence of integers (eof to quit): " ; .br copy(istream_iterator(cin), .RE .RS 8 istream_iterator(), .RE .RS 7 inserter(d,d.begin())); .RE .RS 3 // .br // stream the whole vector and the sum to cout .br // .RE .RS 2 copy(d.begin(),d.end()-1, .RE .RS 7 ostream_iterator(cout," + ")); .RE .RS 2 if (d.size()) .RE .RS 4 cout << *(d.end()-1) << " = " << .RE .RS 9 accumulate(d.begin(),d.end(),total) << endl; .RE .RS 2 return 0; .RE .RS 1 } .SH WARNINGS If your compiler does not support default template parameters, then you always need to supply the \f2Allocator\fP template argument. You also have to include all parameters to the istream_iterator template. For instance, you have to write: \f2vector >\fP instead of: \f2vector\fP If your compiler does not support namespaces, then you do not need the using declaration for \f2std\fP. .SH SEE ALSO Iterators, ostream_iterator