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