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