Compaq C++ User Documentation

| United States

cxxlstd$help.HLP

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

    iostream_intro
    Name
      iostream_intro - Introduction	to the Compaq C++ Standard	Library	iostream
      Package

      This page is an introduction to the ANSI I/O stream classes. If you
      would like information on the pre-ANSI I/O stream package, use the
      command:

           help cxxl

    Description

    Compatibility

      The ANSI Standard Library provides two macros that enable or
      disable use of the ANSI iostream package at compile
      time.  The ANSI  iostream package may cause compile time and/or
      run time behavior incompatibilities that require source
      code changes to resolve.   These macros allow users to choose the
      iostream package they want.

      Check	the C++ documentation for a description of the default
      settings of these macros in different compiler modes.

      The -D Compaq C++ compiler switch can be	used on	the compile
      command line without requiring source code	changes	while the
      #define line should be added	to the source code prior to any	#include
      statement.

      All source modules within the	same application must be compiled in
      the same mode.

      ________________________________________________________________
    		       __USE_STD_IOSTREAM
    	      Usage		  Description
      ________________________________________________________________
      cxx -D__USE_STD_IOSTREAM	  Use ANSI iostream package
      #define __USE_STD_IOSTREAM	  Use ANSI iostream package
      ________________________________________________________________
    		      __NO_USE_STD_IOSTREAM
    	      Usage		  Description
      ________________________________________________________________
      cxx -D__NO_USE_STD_IOSTREAM	  Use pre-ANSI iostream	package
      #define __NO_USE_STD_IOSTREAM	  Use pre-ANSI iostream	package
      ________________________________________________________________

    See Also
      basic_iostream

    basic_filebuf
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_filebuf,filebuf

      This page describes the ANSI basic_filebuf class.  If	you would like
      information on the	pre-ANSI filebuf class,	use the	command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_filebuf
      : public basic_streambuf<charT, traits>

    DESCRIPTION

      The template class basic_filebuf is derived from basic_streambuf.  It
      associates the input or output sequence with a file. Each	object
      of type basic_filebuf<charT, traits> controls	two character sequences:

      +	  a character input sequence

      +	  a character output sequence

      The restrictions on reading  and writing a sequence controlled by an
      object of class basic_filebuf<charT,traits> are the same as for
      reading  and writing with the Standard	C library files.

      If the file is not  open for reading the input	sequence
      cannot	be read.  If the file is not open for writing the
      output sequence cannot be  written.  A joint	file position is
      maintained for	both the input  and output sequences.

      A file provides byte sequences. So the basic_filebuf	class treats a
      file as the external source (or sink) byte	sequence. In order to
      provide the contents of a	file as	wide character sequences, a
      wide-oriented file buffer called wfilebuf converts wide
      character sequences to multibytes character sequences (and vice
      versa) according to the current locale being used	in  the stream
      buffer.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_filebuf
      : public basic_streambuf<charT, traits> {

      public:

       typedef traits			traits_type;
       typedef charT			char_type;
       typedef typename traits::int_type	int_type;
       typedef typename traits::pos_type	pos_type;
       typedef typename traits::off_type	off_type;

       basic_filebuf();
       basic_filebuf(int fd);

       virtual ~basic_filebuf();

       bool	is_open() const;

       basic_filebuf<charT,	traits>* open(const char *s,
    				      ios_base::openmode,
    				      long protection =	0666);

       basic_filebuf<charT,	traits>* open(int fd);

       basic_filebuf<charT,	traits>* close();

      protected:

       virtual int	    showmanyc();

       virtual int_type overflow(int_type c	= traits::eof());

       virtual int_type pbackfail(int_type c = traits::eof());

       virtual int_type underflow();

       virtual basic_streambuf<charT,traits>*
         setbuf(char_type *s,streamsize n);

       virtual pos_type seekoff(off_type off,
    			    ios_base::seekdir way,
    			    ios_base::openmode which =
    			    ios_base::in | ios_base::out);

       virtual pos_type seekpos(pos_type sp,
    			    ios_base::openmode which =
    			    ios_base::in | ios_base::out);

       virtual int sync();

       virtual streamsize xsputn(const char_type* s, streamsize n);

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      filebuf
         The type filebuf is an instantiation of class basic_filebuf on type
         char:

           typedef basic_filebuf<char> filebuf;

      int_type
         The type int_type is a synonym of type traits::in_type.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wfilebuf
         The type wfilebuf is an instantiation of class basic_filebuf on type
         wchar_t:

           typedef basic_filebuf<wchar_t> wfilebuf;

    CONSTRUCTORS

      basic_filebuf();
         Constructs	an object of class basic_filebuf<charT,traits>,
         initializing the base class with basic_streambuf<charT,traits>().

      basic_filebuf(int fd);
         Constructs	an object of class basic_filebuf<charT,traits>,
         initializing the base class with basic_streambuf<charT,traits>(),
         then calls open(fd). This function is	not described in the
         C++ standard, and is provided as an extension in order to
         manipulate pipes, sockets  or other UNIX devices, that
         can be accessed	through	file  descriptors.

    DESTRUCTOR

      virtual ~basic_filebuf();
         Calls close() and destroys	the object.

    MEMBER FUNCTIONS

      basic_filebuf<charT,traits>*
      close();
         If	is_open() == false, returns a null pointer. Otherwise,
         closes the
         file, and returns *this.

      bool
      is_open() const;
         Returns true if the associated file is open.

      basic_filebuf<charT,traits>*
      open(const char* s, ios_base::openmode mode,
           long protection = 0666);
         If	is_open() == true, returns a null pointer.  Otherwise opens
         the	file, whose name	is stored in the
         null-terminated byte-string s.	 The file open modes	are
         given by their C-equivalent	description (see the C
         function fopen):

         in			     "w"
         in|binary		     "rb"
         out		     "w"
         out|app		     "a"
         out|binary		     "wb"
         out|binary|app	     "ab"
         out|in		     "r+"
         out|in|app		     "a+"
         out|in|binary	     "r+b"
         out|in|binary|app	     "a+b"
         trunc|out		     "w"
         trunc|out|binary	     "wb"
         trunc|out|in	     "w+"
         trunc|out|in|binary     "w+b"

         The third argument, protection, is	used as	the file permission.
         It	does not appear	in the Standard	C++ description	of the
         function	open and is provided as an extension. It determines
         the file  read/write/execute permissions under UNIX.  It is more
         limited  under DOS	since files are always readable and do not
         have  special execute permission. If the	open function fails,
         it	returns	a null pointer.

      basic_filebuf<charT,traits>*
      open(int fd);
         Attaches the file previously opened and identified	by its file
         descriptor fd, to	the basic_filebuf object. This function	is
         not described in the C++ standard, and is provided as an extension
         in order	to manipulate pipes, sockets or other UNIX devices,
         that	can be accessed	through	file descriptors.

      int_type
      overflow(int_type c =	traits::eof() );
         If	the output sequence has	a put position available, and c	is not
         traits::eof(), then write c into it. If there is no position
         available, the function output the content of	the buffer to
         the associated file and then write	c at the new current put
         position.  If the operation fails, the function returns
         traits::eof(). Otherwise  it returns traits::not_eof(c). In wide
         characters file buffer,  overflow converts the internal wide
         characters to their external  multibytes representation by	using
         the locale::codecvt  facet	located	in the locale object imbued in
         the stream buffer.

      int_type
      pbackfail(int_type c = traits::eof() );
         Puts back the character designated	by c into the input sequence. If
         traits::eq_int_type(c,traits::eof()) returns true,	move the input
         sequence one position backward. If	the operation fails, the function
         returns traits::eof(). Otherwise it returns traits::not_eof(c).

      pos_type
      seekoff(off_type off,	ios_base::seekdir way,	  ios_base::openmode
           which = ios_base::in | ios_base::out);
         If	the open mode is in | out, alters the stream position of both
         the input and the output sequence. If the open	mode is	in,
         alters the stream position of only the input	sequence, and
         if it is out, alters the stream position of only the output
         sequence. The new position is calculated by combining the two
         parameters off (displacement) and way (reference point). If
         the current position of	the sequence is	invalid	before repo-
         sitioning,	the operation fails and	the return value is
         pos_type(off_type(-1)). Otherwise the function returns the
         current	new position. File buffers using locale::codecvt facet
         performing state dependent conversion, only	support
         seeking	to the beginning of the	file, to	the current
         position, or to a position previously obtained by a	call
         to	one of the iostreams seeking functions.

      pos_type
      seekpos(pos_type sp,ios_base::openmode      which = ios_base::in |
      ios_base::out);
         If	the open mode is in | out, alters the stream position of both
         the input and the output sequence. If the open	mode is	in,
         alters the stream position of only the input	sequence, and
         if it is out, alters the stream position of only the output
         sequence. If the current position of the sequence is invalid
         before repositioning, the operation fails and the return
         value is pos_type(off_type(-1)). Otherwise the function returns
         the current new position. File buffers using locale::codecvt
         facet performing state dependent conversion, only support
         seeking to the beginning of the file, to the current position,
         or to a position previously obtained by a call to one of the
         iostreams	seeking	functions.

      basic_filebuf<charT,traits>*
      setbuf(char_type*s, streamsize n);
         If	s is not a null	pointer, output	the content of the current
         buffer to the associated file, then delete the current buffer and
         replace it	by s. Otherwise resize the current buffer to size n
         after outputting its content to the associated file if
         necessary.

      int
      sync();
         Synchronizes the content of the external file, with its image
         maintained in	memory by the file buffer. If the function
         fails, it returns -1, otherwise it returns 0.

      int_type
      underflow();
         If	the input sequence has a read position available, returns the
         content of	this position. Otherwise fills up the buffer by
         reading	characters from the associated file and if it
         succeeds, returns the content of the new current position. The
         function	returns	traits::eof() to indicate failure. In wide
         characters file buffer, underflow	converts the external
         mutltibytes characters to their wide character representation by
         using the locale::codecvt facet located in the locale object
         imbued in the stream buffer.

      streamsize
      xsputn(const char_type* s, streamsize	n);
         Writes up to n characters to the output sequence. The characters
         written are obtained from successive elements of the array	whose
         first element is	designated by s. The function returns the
         number of characters written.

    EXAMPLES

      //
      // stdlib/examples/manual/filebuf.cpp
      //
      #include<iostream>
      #include<fstream>
      void main ( )
      {
       using namespace std;
        // create a	read/write file-stream object on tiny char
        // and attach it to	the file "filebuf.out"
       ofstream out("filebuf.out",ios_base::in |	       ios_base::out);
        // tie the istream object to the ofstream object
       istream in(out.rdbuf());
        // output to out
       out << "Il errait comme un ame en peine";
        // seek to the beginning of	the file
       in.seekg(0);
        // output in to the	standard output
       cout	<< in.rdbuf() << endl;
        // close the file "filebuf.out"
       out.close();
        // open the	existing file "filebuf.out"
        // and truncate it
       out.open("filebuf.out",ios_base::in |       ios_base::out |
       ios_base::trunc);
        // set the buffer size
       out.rdbuf()->pubsetbuf(0,4096);
        // open the	source code file
       ifstream ins("filebuf.cpp");
        //output it	to filebuf.out
       out << ins.rdbuf();
        // seek to the beginning of	the file
       out.seekp(0);
        // output the all file to the standard output
       cout	<< out.rdbuf();
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_ifstream, basic_ofstream,
      basic_fstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.8.1.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_fstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_fstream,fstream,ofstream

      This page describes the ANSI basic_fstream class.  If	you would like
      information on the	pre-ANSI fstream class,	use the	command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_fstream
      : public basic_iostream<charT, traits>

    DESCRIPTION

      The template class basic_fstream<charT,traits> supports reading and
      writing to named files or other devices associated with a file
      descriptor. It	uses a basic_filebuf object to control the
      associated sequences. It inherits from basic_iostream and can
      therefore	use all	the formatted and unformatted input	and
      output functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_fstream
      : public basic_iostream<charT, traits> {

      public:

       typedef basic_ios<charT, traits>   ios_type;

       typedef charT		       char_type;
       typedef traits		       traits_type;
       typedef typename traits::int_type  int_type;
       typedef typename traits::pos_type  pos_type;
       typedef typename traits::off_type  off_type;

       basic_fstream();

       explicit basic_fstream(const	char *s, ios_base::openmode
    			  mode = ios_base::in |	ios_base::out,
    			  long protection = 0666);

       explicit basic_fstream(int fd);

       basic_fstream(int fd, char_type *buf, int len);

       virtual ~basic_fstream();

       basic_filebuf<charT,	traits>	*rdbuf() const;

       bool	is_open();

       void	open(const char	*s, ios_base::openmode mode =
    	     ios_base::in | ios_base::out,
    	     long protection = 0666);

       void	close();

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      fstream
         The type fstream is an instantiation of class basic_fstream on type
         char:

           typedef basic_fstream<char> fstream;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wfstream
         The type wfstream is an instantiation of class basic_fstream  on type
         wchar_t:

           typedef basic_fstream<wchar_t> wfstream;

    CONSTRUCTORS

      basic_fstream();
         Constructs	an object of class basic_fstream<charT,traits>,
         initializing the base class basic_iostream with	the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). After construction,
         a file can be attached to the basic_ftream object by using the
         open() member function.

      basic_fstream(const char* s,
    	       ios_base::openmode mode=
    	       ios_base::in | iosw_base::out,
    	       long protection=	0666);
         Constructs an	object of class	basic_fstream<charT,traits>,
         initializing the base	class basic_iostream with  the
         associated file buffer, which is initialized  by calling the
         basic_filebuf	constructor  basic_filebuf<charT,traits>().
         The constructor then  calls the open function
         open(s,mode,protection) in  order to attach the file, whose name
         is pointed at by	s,  to the basic_ftream object. The third
         argument,  protection, is used as the file permission. It does
         not appear in	the Standard C++ description and is provided
         as an extension. It determines the  file read/write/execute
         permissions under UNIX.   It is more limited under DOS since
         files are always	readable and do not have special execute
         permission.

      explicit basic_fstream(int fd);
         Constructs	an object of class basic_fstream<charT,traits>,
         initializing the base class basic_iostream with	the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_ftream object. This
         constructor	is not described in the C++ standard, and
         is provided as an extension in order to	manipulate pipes,
         sockets or other UNIX	devices, that can be accessed through
         file descriptors. If the function fails, it sets
         ios_base::failbit.

      basic_fstream(int fd,	char_type* buf,int len);
         Constructs	an object of class basic_fstream<charT,traits>,
         initializing the base class basic_iostream with	the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_ftream object. The
         underlying buffer is	then replaced by calling the
         basic_filebuf member function, setbuf(), with parameters	buf
         and	len. This constructor is not described in the C++
         standard, and is provided as an extension in order	to manipulate
         pipes, sockets, or other UNIX devices that can be	accessed
         through file descriptors. It also maintains compatibility with
         the old iostreams library. If the function fails, it	sets
         ios_base::failbit.

    DESTRUCTOR

      virtual ~basic_fstream();
         Destroys an object	of class basic_fstream.

    MEMBER FUNCTIONS

      void
      close();
         Calls the associated basic_filebuf	function close() and if	this
         function fails, it calls the basic_ios member function
         setstate(failbit).

      bool
      is_open();
         Calls the associated basic_filebuf	function is_open() and return
         its result.

      void
      open(const char* s,ios_base::openmode	=
          ios_base::out | ios_base::in,
          long protection =	0666);
         Calls the associated basic_filebuf function
         open(s,mode,protection) and, if this function fails at
         opening	the file, calls	the basic_ios member	function
         setstate(failbit). The	third argument  protection is used as
         the file permissions. It does not  appear in the Standard C++
         description and is provided as	an extension. It determines
         the	file read/write/execute  permissions	under UNIX. It
         is more limited under DOS since files are always readable and do
         not	have special  execute permission.

      basic_filebuf<charT,traits>*
      rdbuf() const;
         Returns a pointer to the basic_filebuf associated with the	stream.

    EXAMPLES

      //
      // stdlib/examples/manual/fstream.cpp
      //
      #include<iostream>
      #include<bidirec>
      void main ( )
      {
         using namespace std;

          // create	a bi-directional fstream object
         fstream inout("fstream.out");

          // output	characters
         inout << "Das ist die rede	von einem man" << endl;
         inout << "C'est l'histoire	d'un home" << endl;
         inout << "This is the story of a man" << endl;

         char p[100];

          // seek back to the beginning of the file
         inout.seekg(0);

          // extract the first line
         inout.getline(p,100);

          // output	the first line to stdout
         cout << endl << "Deutch :"	<< endl;
         cout << p;

         fstream::pos_type pos = inout.tellg();

          // extract the seconf line
         inout.getline(p,100);

          // output	the second line	to stdout
         cout << endl << "Francais :" << endl;
         cout << p;

          // extract the third line
         inout.getline(p,100);

          // output	the third line to stdout
         cout << endl << "English :" << endl;
         cout << p;

          // move the put sequence before the second line
         inout.seekp(pos);

          // replace the second line
         inout << "This is the story of a man" << endl;

          // replace the third line
         inout << "C'est l'histoire	d'un home";

          // seek to the beginning of the file
         inout.seekg(0);

          // output	the all	content	of the fstream object to stdout
         cout << endl << endl << inout.rdbuf();
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_filebuf, basic_ifstream, basic_ofstream

      Working Paper	for Draft Proposed International Standard for Information
      Systems--Programming Language	C++, Section 27.8.1.11

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_ifstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ifstream,fstream

      This page describes the ANSI basic_ifstream class.  If you would like
      information on the pre-ANSI ifstream class, use the command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ifstream
      : public basic_istream<charT,	traits>

    DESCRIPTION

      The template class basic_ifstream<charT,traits> supports reading
      from	named files	or other devices associated with a file
      descriptor. It uses a basic_filebuf	object to control the
      associated sequences.  It	inherits from basic_istream	and
      can	therefore use all the formatted	and unformatted	input
      functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ifstream
      : public basic_istream<charT,	traits>	{

      public:

       typedef basic_ios<charT, traits>    ios_type;

       typedef traits		       traits_type;
       typedef charT		       char_type;
       typedef typename traits::int_type   int_type;
       typedef typename traits::pos_type   pos_type;
       typedef typename traits::off_type   off_type;

       basic_ifstream();

       explicit basic_ifstream(const char *s,
    			   ios_base::openmode mode =
    			   ios_base::in,
    			   long	protection = 0666);

       explicit basic_ifstream(int fd);

       basic_ifstream(int fd, char_type* buf, int len);

       virtual ~basic_ifstream();

       basic_filebuf<charT,	traits>	*rdbuf() const;

       bool	is_open();

       void	open(const char	*s, ios_base::openmode mode =
    	     ios_base::in, long	protection = 0666);

       void	close();

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      ifstream
         The type ifstream is an instantiation of class basic_ifstream on type
         char:

           typedef basic_ifstream<char> ifstream;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wifstream
         The type wifstream	is an instantiation of class basic_ifstream on
         type wchar_t:

           typedef basic_ifstream<wchar_t> wifstream;

    CONSTRUCTORS

      basic_ifstream();
         Constructs	an object of class basic_ifstream<charT,traits>,
         initializing the base class basic_istream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). After construction,
         a file can be attached to the basic_iftream object by using the
         open member function.

      basic_ifstream(const char* s,
    		ios_base::openmode mode= ios_base::in,
    		long protection= 0666);
         Constructs an object	of class basic_ifstream<charT,traits>,
         initializing the base class basic_istream with the associated
         file buffer, which	is initialized by calling the basic_filebuf
         constructor basic_filebuf<charT,traits>(). The constructor then
         calls the open function open(s,mode,protection) in	order to
         attach the file whose name is pointed at by s, to the
         basic_iftream object. The third argument protection provides file
         permissions. It does not appear in the Standard C++ description
         and is provided as an extension. It determines the file
         read/write/execute permissions under UNIX. It is more limited
         under DOS	since files are	always readable	and do not have
         special	execute	permission.

      explicit basic_ifstream(int fd)
         Constructs	an object of class basic_ifstream<charT,traits>,
         initializing the base class basic_istream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_iftream	object.	This
         constructor is not described in the C++ standard, and	is
         provided as an extension in order to	manipulate pipes,
         sockets or other UNIX	devices, that can be accessed through
         file descriptors. If the function fails, it sets
         ios_base::failbit.

      basic_ifstream(int fd, char_type* buf,int len);
         Constructs	an object of class basic_ifstream<charT,traits>,
         initializing the base class basic_istream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_iftream	object.	The
         underlying buffer is then replaced by calling the basic_filebuf
         member function setbuf with parameters buf and len.	This
         constructor is not	described in the C++ standard, and is
         provided as an extension in order to manipulate pipes, sockets or
         other UNIX devices, that can be	accessed through file
         descriptors. It also maintains compatibility with the old
         iostreams library. If the function fails, it	sets
         ios_base::failbit.

    DESTRUCTOR

      virtual ~basic_ifstream();
         Destroys an object	of class basic_ifstream.

    MEMBER FUNCTIONS

      void
      close();
         Calls the associated basic_filebuf	function close() and if	this function
         fails, it calls the basic_ios member function setstate(failbit).

      bool
      is_open();
         Calls the associated basic_filebuf	function is_open() and return its
         result.

      void
      open(const char* s,ios_base::openmode	=
          ios_base::in, long protection = 0666);
         Calls the associated basic_filebuf function
         open(s,mode,protection). If this function fails	opening	the
         file, it calls the basic_ios member	function
         setstate(failbit). The	third argument protection provides
         file	permissions. It	does not appear	in the Standard	C++
         description and is provided as	an extension. It determines
         the	file read/write/execute permissions	under UNIX. It
         is more limited under DOS since files are always readable and do
         not	have special execute permission.

      basic_filebuf<charT,traits>*
      rdbuf() const;
         Returns a pointer to the basic_filebuf associated with the	stream.

    EXAMPLES

      //
      // stdlib/examples/manual/ifstream.cpp
      //
      #include<iostream>
      #include<fstream>
      #include<iomanip>

      void main ( )
      {
       using namespace std;

       long	  l= 20;
       char	  *ntbs="Le minot passait la piece a frotter";
       char	  c;
       char	  buf[50];

      try {

        // create a	read/write file-stream object on char
        // and attach it to	an ifstream object
       ifstream in("ifstream.out",ios_base::in |
    	       ios_base::out | ios_base::trunc);

        // tie the ostream object to the ifstream object
       ostream out(in.rdbuf());

        // output ntbs in out
       out << ntbs << endl;

        // seek to the beginning of	the file
       in.seekg(0);

        // output each word	on a separate line
       while ( in.get(c) )
         {
          if ( char_traits<char>::eq(c,' ')	)
           cout << endl;
          else
           cout << c;
         }
       cout	<< endl	<< endl;

        // move back to the	beginning of the file
       in.seekg(0);

        // clear the state flags
       in.clear();

        // does the	same thing as the previous code
        // output each word	on a separate line
       while ( in >> buf )
        cout << buf	<< endl;

       cout	<< endl	<< endl;

        // output the base info before each	integer
       out << showbase;

       ostream::pos_type pos= out.tellp();

        // output l	in hex with a field with of 20
       out << hex << setw(20) << l << endl;

        // output l	in oct with a field with of 20
       out << oct << setw(20) << l << endl;

        // output l	in dec with a field with of 20
       out << dec << setw(20) << l << endl;

        // move back to the	beginning of the file
       in.seekg(0);

        // output the all file
       cout	<< in.rdbuf();

        // clear the flags
       in.clear();

        // seek the	input sequence to pos
       in.seekg(pos);

       int a,b,d;

        // read the	previous outputted integer
       in >> a >> b	>> d;

        // output 3	times 20
       cout	<< a <<	endl <<	b << endl << d << endl;

      }
       catch( ios_base::failure& var )
         {
           cout << var.what();
         }

      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_filebuf, basic_ofstream, basic_fstream

      Working Paper	for Draft Proposed International Standard for Information
      Systems--Programming Language	C++, Section 27.8.1.5

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_ios
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ios,ios

      This page describes the ANSI ios class.  If you would	like
      information on the pre-ANSI ios class, use the command:

           help cxxl

    SYNOPSIS

      #include <ios>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ios : public ios_base

    DESCRIPTION

      The class basic_ios is a base	class that provides the	common
      functionality required by all streams. It maintains	state
      information that reflects	the integrity of the stream and stream
      buffer. It	also maintains the link between the stream classes and
      the stream buffers classes via	the rdbuf member functions.
      Classes derived from basic_ios specialize operations for input, and
      output.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ios : public ios_base {

        public:

         typedef basic_ios<charT, traits>		ios_type;
         typedef basic_streambuf<charT, traits>	streambuf_type;
         typedef basic_ostream<charT, traits>	ostream_type;

         typedef typename traits::char_type		char_type;
         typedef traits				traits_type;

         typedef typename traits::int_type		int_type;
         typedef typename traits::off_type		off_type;
         typedef typename traits::pos_type		pos_type;

         explicit basic_ios(basic_streambuf<charT, traits> *sb_arg);
         virtual ~basic_ios();

         char_type fill() const;
         char_type fill(char_type ch);

         void exceptions(iostate except);
         iostate exceptions() const;

         void clear(iostate	state =	goodbit);

         void setstate(iostate state);
         iostate rdstate() const;

         operator void*() const;
         bool operator!() const;

         bool good() const;
         bool eof()	const;
         bool fail() const;
         bool bad()	const;

         ios_type& copyfmt(const ios_type& rhs);

         ostream_type *tie() const;
         ostream_type *tie(ostream_type *tie_arg);

         streambuf_type *rdbuf() const;
         streambuf_type *rdbuf( streambuf_type *sb);

         locale imbue(const	locale&	loc);

         char narrow(charT,	char) const;
         charT widen(char) const;

        protected:

         basic_ios();

         void init(basic_streambuf<charT, traits> *sb);
      };

    TYPES

      char_type
         The type char_type	is a synonym of	type traits::char_type.

      ios
         The type ios is an	instantiation of basic_ios on char:

           typedef basic_ios<char> ios;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is a synonym for	basic_ios<charT, traits> .

      off_type
         The type off_type is a synonym of type traits::off_type.

      ostream_type
         The type ostream_type is a	synonym	for basic_ostream<charT, traits> .

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      streambuf_type
         The type streambuf_type is	a synonym for basic_streambuf<charT, traits>
         .

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wios
         The type wios is an instantiation of basic_ios on wchar_t:

           typedef basic_ios<wchar_t> wios;

    PUBLIC CONSTRUCTORS

      explicit basic_ios(basic_streambuf<charT, traits>* sb);
         Constructs	an object of class basic_ios, assigning	initial	values
         to its member objects by calling init(sb). If sb is a null
         pointer, the stream is	positioned in error state, by
         triggering its badbit.

      basic_ios();
         Constructs	an object of class basic_ios leaving its member
         objects	uninitialized.	The object must	be initialized
         by calling the init member function before using it.

    PUBLIC DESTRUCTOR

      virtual ~basic_ios();
         Destroys an object	of class basic_ios.

    PUBLIC MEMBER FUNCTIONS

      bool
      bad()	const;
         Returns true if badbit is set in rdstate().

      void
      clear(iostate	state =	goodbit);
         If	(state & exception()) == 0, returns.  Otherwise, the function
         throws an	object of class	ios_base::failure. After the call
         returns state	== rdstate().

      basic_ios&
      copyfmt(const	basic_ios& rhs);
         Assigns to	the member objects of *this the	corresponding member
         objects of	rhs, with the following	exceptions:

         +	     rdstate() and rdbuf() are left unchanged

         +	     calls ios_base::copyfmt

         +	     exceptions() is altered last by calling
    	  exceptions(rhs.exceptions())

      bool
      eof()	const;
         Returns true if eofbit is set in rdstate().

      iostate
      exceptions() const;
         Returns a mask that determines what elements set in rdstate()
         cause exceptions	to be thrown.

      void
      exceptions(iostate except);
         Set the exception mask to except then calls clear(rdstate()).

      bool
      fail() const;
         Returns true if failbit or	badbit is set in rdstate().

      char_type
      fill() const;
         Returns the character used	to pad (fill) an output	conversion to
         the specified field width.

      char_type
      fill(char_type fillch);
         Saves the field width value then replaces it by fillch and
         returns	the previously	saved value.

      bool
      good() const;
         Returns rdstate() == 0.

      locale
      imbue(const locale& loc);
         Saves the value returned by getloc() then assigns loc to a
         private	variable and if rdbuf() != 0 calls
         rdbuf()->pubimbue(loc) and returns the previously	saved value.

      void
      init(basic_streambuf<charT,traits>* sb);
         Performs the following initialization:

         rdbuf()	  sb
         tie()	  0
         rdstate()	  goodbit if sb	is not null otherwise badbit
         exceptions() goodbit
         flags()	  skipws | dec
         width()	  0
         precision()  6
         fill()	  the space character
         getloc()	  locale::locale()

      char
      narrow(charT c, char dfault) const;
         Uses the stream's locale to convert the wide character c to a
         tiny	character, and	then returns it. If no
         conversion exists, it returns the character dfault.

      bool
      operator!() const;
         Returns fail() ? 1	: 0;

      streambuf_type*
      rdbuf() const;
         Returns a pointer to the stream buffer associated with the	stream.

      streambuf_type*
      rdbuf(streambuf_type*	sb);
         Associates	a stream buffer	with the stream. All the input and
         output will be directed to this stream buffer. If	sb is a	null
         pointer, the stream is positioned in error state, by triggering
         its badbit.

      iostate
      rdstate() const;
         Returns the control state of the stream.

      void
      setstate(iostate state);
         Calls clear(rdstate() | state).

      ostream_type*
      tie()	const;
         Returns an	output sequence	that is	tied to	(synchronized with) the
         sequence controlled by the	stream buffer.

      ostream_type*
      tie(ostream_type* tiestr);
         Saves the tie() value then	replaces it by tiestr and returns the
         value previously	saved.

      operator
      void*() const;
         Returns fail() ? 0	: 1;

      charT
      widen(char c)	const;
         Uses the stream's locale to convert the tiny character c to a
         wide	character, then returns it.

    SEE ALSO

      ios_base, basic_istream, basic_ostream,
      basic_streambuf, char_traits

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++.

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_iostream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_iostream,iostream

      This page describes the ANSI basic_iostream class.  If you would
      like information on the pre-ANSI iostream class, use the command:

           help cxxl

    SYNOPSIS

      #include <istream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_iostream
      : public basic_istream<charT,	traits>,
      public basic_ostream<charT, traits>

    DESCRIPTION

      The class basic_iostream inherits a number of	functions from classes
      basic_ostream<charT, traits> and basic_istream<charT,	traits>. They
      assist in formatting	and interpreting sequences of characters
      controlled by a stream buffer. Two groups of functions share common
      properties, the formatted functions	and the	unformatted functions.

    INTERFACE

      template<class charT,	class traits>
      class	basic_iostream
      : public basic_istream<charT,	traits>,
       public basic_ostream<charT, traits>

      {

      public:

       explicit basic_iostream(basic_streambuf<charT, traits> *sb);
       virtual ~basic_iostream();

      protected:

       explicit basic_iostream();

      };

    PUBLIC CONSTRUCTORS

      explicit basic_iostream(basic_streambuf<charT, traits>* sb);
         Constructs	an object of class basic_iostream, assigning initial
         values to	the base class by calling
         basic_istream<charT, traits>(sb) and
         basic_ostream<charT, traits>(sb).

      explicit basic_iostream();
         Constructs	an object of class basic_iostream, assigning
         initial values to	the base class by calling
         basic_istream<charT, traits>() and basic_ostream<charT, traits>().
         After construction	the object has its badbit set.

    DESTRUCTOR

      virtual ~basic_iostream();
         Destroys an object	of class basic_iostream.

    EXAMPLES

      See basic_istream and	basic_ostream examples.

    COMPATIBILITY

      [Digital]  The ANSI Standard Library provides	two macros which
      enable	or disable use of the ANSI iostream package at compile
      time.

      ______________________________________________________________
      Macro			  Description
      ______________________________________________________________
      __USE_STD_IOSTREAM	  Use the ANSI Standard	iostream package
      __NO_USE_STD_IOSTREAM	  Use the pre-ANSI iostream package
      ______________________________________________________________

      See ios_intro(help cxxl) or iostream_intro(help cxxlstd) for more
      details.

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_istream, basic_ostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section
      27.6.1.4.1

    STANDARDS CONFORMANCE

      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_istream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_istream,istream

      This page describes the ANSI basic_istream class.  If	you would like
      information on the	pre-ANSI istream class,	use the	command:

           help cxxl

    SYNOPSIS

      #include <istream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_istream
      : virtual public basic_ios<charT, traits>

    DESCRIPTION

      The class basic_istream defines a number of member function
      signatures that assist in reading and	interpreting input from
      sequences controlled by	a stream buffer.

      Two groups of	member function	signatures share common	properties:
      the formatted input functions (or extractors) and the unformatted
      input functions. Both groups of input functions obtain	(or
      extract) input characters by calling basic_streambuf member
      functions. They both begin by constructing an object of class
      basic_istream::sentry	and, if	this object is in good state after
      construction, the function endeavors to	obtain the requested
      input. The sentry object performs exception safe initialization,
      such as controlling the status of the stream	or locking it
      in multithread environment.

      Some formatted input functions parse characters extracted from the
      input sequence, converting the result to a value of	some scalar
      data type, and storing the converted	value in an object of that
      scalar type.	The conversion behavior	is locale dependent,
      and directly depend on the	locale object imbued in the
      stream.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_istream
      : virtual public basic_ios<charT, traits> {

      public:

      typedef basic_istream<charT, traits>	  istream_type;
      typedef basic_ios<charT, traits>	  ios_type;
      typedef basic_streambuf<charT, traits>  streambuf_type;

      typedef traits		      traits_type;
      typedef charT			      char_type;
      typedef typename traits::int_type   int_type;
      typedef typename traits::pos_type   pos_type;
      typedef typename traits::off_type   off_type;

      explicit basic_istream(basic_streambuf<charT,	traits>	*sb);
      virtual ~basic_istream();

      class	sentry
        {
          public:

           inline explicit sentry(basic_istream<charT,traits>&,
    			      bool noskipws = 0);
    	 ~sentry();
    	operator bool ();
        };

      istream_type&	operator>>(istream_type& (*pf)(istream_type&));
      istream_type&	operator>>(ios_base& (*pf)(ios_base&));
      istream_type&	operator>>(ios_type& (*pf)(ios_type&));

      istream_type&	operator>>(bool& n);
      istream_type&	operator>>(short& n);
      istream_type&	operator>>(unsigned short& n);
      istream_type&	operator>>(int&	n);
      istream_type&	operator>>(unsigned int& n);
      istream_type&	operator>>(long& n);
      istream_type&	operator>>(unsigned long& n);
      istream_type&	operator>>(float& f);
      istream_type&	operator>>(double& f);
      istream_type&	operator>>(long	double&	f);

      istream_type&	operator>>(void*& p);

      istream_type&	operator>>(streambuf_type& sb);
      istream_type&	operator>>(streambuf_type *sb);

      int_type get();

      istream_type&	get(char_type *s, streamsize n,	char_type delim);
      istream_type&	get(char_type *s, streamsize n);

      istream_type&	get(char_type& c);

      istream_type&	get(streambuf_type& sb,char_type delim);
      istream_type&	get(streambuf_type& sb);

      istream_type&	getline(char_type *s, streamsize n,char_type delim);
      istream_type&	getline(char_type *s, streamsize n);

      istream_type&	ignore(streamsize n = 1,
    		       int_type	delim =	traits::eof());

      istream_type&	read(char_type *s, streamsize n);

      streamsize readsome(char_type	*s, streamsize n);

      int peek();

      pos_type tellg();

      istream_type&	seekg(pos_type&);
      istream_type&	seekg(off_type&, ios_base::seekdir);

      istream_type&	putback(char_type c);
      istream_type&	unget();

      streamsize gcount() const;

      int sync();

      protected:

      explicit basic_istream( );

      };

      //global function

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      ws(basic_istream<charT, traits>&);
      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>> (basic_istream<charT, traits>&, charT&);
      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>> (basic_istream<charT, traits>&, charT*);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, unsigned char&);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, signed char&);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, unsigned char*);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, signed char*);

    TYPES

      char_type
         The type char_type	is a synonym for them template parameter charT.

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is a synonym for	basic_ios<charT, traits> .

      istream
         The type istream is an instantiation of class basic_istream on type
         char:

           typedef basic_istream<char> istream;

      istream_type
         The type istream_type is a	synonym	for basic_istream<charT, traits>.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      streambuf_type
         The type streambuf_type is	a synonym for
         basic_streambuf<charT, traits>.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wistream
         The type wistream is an instantiation of class basic_istream on type
         wchar_t:

         typedef basic_istream<wchar_t> wistream;

    PUBLIC CONSTRUCTOR

      explicit basic_istream(basic_streambuf<charT,	traits>* sb);
         Constructs	an object of class basic_istream, assigning initial
         values to the base class by calling basic_ios::init(sb).

    PUBLIC DESTRUCTOR

      virtual ~basic_istream();
         Destroys an object	of class basic_istream.

    SENTRY CLASS

      explicit sentry(basic_istream<charT,traits>&,	bool noskipws=0);
         Prepares for formatted or unformatted input. First	if the
         basic_ios member function tie() is not a null pointer, the
         function synchronizes the output	sequence with any associated
         stream. If	noskipws is zero and the ios_base member function
         flags() & skipws is nonzero, the function extracts and discards
         each	character as long as the next available	input
         character is a white space	character. If after any	preparation is
         completed the	basic_ios member function good() is true, the
         sentry conversion function operator bool() will	return true.
         Otherwise it will return false. In multithread environment the
         sentry object constructor is responsible for locking the stream
         and the	stream buffer associated with the stream.

      ~sentry();
         Destroys an object	of class sentry. In multithread	environment,
         the sentry object	destructor is responsible for
         unlocking	the stream and the stream buffer associated with the
         stream.

      operator bool();
         If	after any preparation is completed the basic_ios member
         function good() is true, the sentry	conversion function
         operator bool() will return true else it will return false.

    EXTRACTORS

      istream_type&
      operator>>(istream_type&
    	    (*pf) (istream_type&));
    	       Calls pf(*this),	then return *this. See,	for example, the
    	       function	signature ws(basic_istream&).

      istream_type&
      operator>>(ios_type& (*pf) (ios_type&));
         Calls pf(*this), then return *this.

      istream_type&
      operator>>(ios_base& (*pf) (ios_base&));

         Calls pf(*this), then return *this. See, for example, the
         function	signature dec(ios_base&).

      istream_type&
      operator>>(bool& n);
          Converts a	Boolean	value, if one is available, and	stores it in
         n.	If the ios_base member function flag() & ios_base::boolalpha
         is false	it tries to read an integer value, which if found must
         be 0 or 1. If the boolalpha flag is true, it	reads
         characters until it determines whether the characters read are
         correct according to the locale function numpunct<>::truename()
         or numpunct<>::falsename().	If no match is found, it
         calls the basic_ios member function setstate(failbit), which may
         throw ios_base::failure.

      istream_type&
      operator>>(short& n);
         Converts a	signed short integer, if one is	available, and stores
         it in n,	then returns *this.

      istream_type&
      operator>>(unsigned short& n);
         Converts an unsigned short	integer, if one	is available, and
         stores it in	n, then	return *this.

      istream_type&
      operator>>(int& n);
         Converts a	signed integer,	if one is available, and stores	it in
         n, then return *this.

      istream_type&
      operator>>(unsigned int& n);
         Converts an unsigned integer, if one is available,	and stores it
         in n, then return *this.

      istream_type&
      operator>>(long& n);
         Converts a	signed long integer, if	one is available, and stores
         it	in n, then returns *this.

      istream_type&
      operator>>(unsigned long& n);
         Converts an unsigned long integer,	if one is available, and
         stores	it in n,	then returns *this.

      istream_type&
      operator>>(float& f);
         Converts a	float, if one is available, and	stores it in f,	then
         returns *this.

      istream_type&
      operator>>(double& f);
         Converts a	double,	if one is available, and stores	it in f, then
         returns *this.

      istream_type&
      operator>>(long double& f);
         Converts a	long double, if	one is available, and stores it	in f,
         then returns *this.

      istream_type&
      operator>>(void*& p);
         Extracts a	void pointer, if one is	available, and stores it in p,
         then return *this.

      istream_type&
      operator>>(streambuf_type* sb);
         If	sb is null, calls the basic_ios	member function
         setstate(badbit), which may throw ios_base::failure.
         Otherwise extracts characters from *this and inserts them in the
         output sequence controlled by sb. Characters are extracted
         and inserted until any of the following	occurs:

         +	     end-of-file occurs	on the input sequence

         +	     inserting in the output sequence fails

         +	     an	exception occurs

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. If failure was due to	catching an exception
         thrown while extracting characters from sb and failbit is on in
         exception(), then the caught exception is	rethrown.

         istream_type& operator>>(streambuf_type& sb);
           Extracts characters from *this and inserts them in the
           output sequence controlled by sb. Characters are extracted
           and inserted until and of the following occurs:

         +	     end-of-file occurs	on the input sequence

         +	     inserting in the output sequence fails

         +	     an	exception occurs

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. If failure was due to	catching an exception
         thrown while extracting characters from sb and failbit is on in
         exception(), then the caught exception is	rethrown.

    UNFORMATTED FUNCTIONS

      streamsize
      gcount() const;
         Returns the number	of characters extracted	by the last
         unformatted	input member function called.

      int_type
      get();
         Extracts a	character, if one is available.	Otherwise, the
         function	calls the basic_ios member function setstate(failbit),
         which may	throw ios_base::failure.	Returns	the character
         extracted	or traits::eof() if none is available.

      istream_type&
      get(char_type& c);
         Extracts a	character, if one is available,	and assigns it to c.
         Otherwise, the function	calls the basic_ios member function
         setstate(failbit),	which may throw	ios_base::failure.

      istream_type&
      get(char_type* s, streamsize n,char_type delim);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. Characters
         are extracted and stored	until any of the following occurs:

         +	     n-1 characters are	stored

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	== delim.

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. In any case, it stores a null character into
         the next successive location	of the array.

      istream_type&
      get(char_type* s, streamsize n);
         Calls get(s,n,widen('0)).

      istream_type&
      get(streambuf_type& sb,char_type delim);
         Extracts characters and inserts them in the output	sequence
         controlled by	sb. Characters are extracted and inserted
         until	any of the following occurs:

         +	     end-of-file occurs	on the input sequence

         +	     inserting in the output sequence fails

         +	     the next available	input character	== delim.

         +	     an	exception occurs

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. If failure was due to	catching an exception
         thrown while extracting characters from sb and failbit is on in
         exception(), then the caught exception is	rethrown.

      istream_type&
      get(streambuf_type& sb);
         Calls get(sb,widen('0)).

      istream_type&
      getline(char_type* s,	streamsize n, char_type	delim);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. Characters
         are extracted and stored	until any of the following occurs:

         +	     n-1 characters are	stored

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	== delim.

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. In any case, it stores a null character into
         the next successive location	of the array.

      istream_type&
      getline(char_type* s,	streamsize n);
         Calls getline(s,n,widen('0)).

      istream_type&
      ignore(streamsize n=1, int_type delim=traits::eof());
         Extracts characters and discards them. Characters are extracted
         until any of the	following occurs:

         +	     n characters are extracted

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	== delim.

      int_type
      peek();
         Returns traits::eof() if the basic_ios member function good()
         returns false. Otherwise, returns the next	available character.
         Does not increment the current get pointer.

      istream_type&
      putback(char_type c);
         Insert c in the putback sequence.

      istream_type&
      read(char_type* s, streamsize	n);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. Characters
         are extracted and stored	until any of the following occurs:

         +	     n characters are stored

         +	     end-of-file occurs	on the input sequence

         If	the function does not store n characters, it calls the
         basic_ios member function setstate(failbit),	which may
         throw	ios_base::failure.

      streamsize
      readsome(char_type* s, streamsize n);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. If
         rdbuf()->in_avail() == -1, calls the basic_ios member function
         setstate(eofbit).

         +	     If	rdbuf()->in_avail() == 0, extracts no characters

         +	     If	rdbuf()->in_avail() > 0, extracts min( rdbuf()->in_avail(),
           	      n)

         In	any case the function returns the number of characters
         extracted.

      istream_type&
      seekg(pos_type& pos);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(pos), which will position the current pointer
         of the input sequence at the position designated by pos.

      istream_type&
      seekg(off_type& off, ios_base::seekdir dir);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(off,dir), which will position the current
         pointer of the input sequence	at the position	designated by
         off and dir.

      int
      sync();
         If	rdbuf()	is a null pointer, return -1. Otherwise, calls
         rdbuf()- >pubsync()	and if that function returns -1	calls
         the basic_ios member function setstate(badbit).	The purpose of
         this function is	to synchronize the internal input buffer,
         with the external sequence of characters.

      pos_type
      tellg();
         If	the basic_ios member function fail() returns true, tellg()
         returns pos_type(off_type(-1)) to indicate	failure. Otherwise it
         returns the current position of the input sequence by calling
         rdbuf()- >pubseekoff(0,cur,in).

      istream_type&
      unget();
         If	rdbuf()	is not null, calls rdbuf()->sungetc(). If rdbuf() is
         null or if	sungetc() returns traits::eof(), calls the basic_ios
         member function setstate(badbit).

    NON MEMBER FUNCTIONS

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& is, charT& c);
         Extracts a	character if one is available, and stores it in	c.
         Otherwise the function calls	the basic_ios member function
         setstate(failbit), which may throw ios_base::failure.

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& is, charT* s);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. If the
         ios_base member function is.width() is greater than zero, then
         is.width() is the maximum number of characters stored. Characters
         are extracted and stored until any of the	following occurs:

         +	     if	is.witdh()>0, is.witdh()-1 characters are extracted

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	is a white space.

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. In any case, it then stores a null character
         into	the next successive location of	the array and calls
         width(0).

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, unsigned char& c);
         Returns is	>> (char&)c.

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, signed char& c);
         Returns is	>> (char&)c.

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, unsigned char* c);
         Returns is	>> (char*)c.

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, signed char* c);
         Returns is	>> (char*)c.

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      ws(basic_istream<charT, traits>& is);
         Skips any white space in the input	sequence and returns is.

    EXAMPLES

      //
      // stdlib/examples/manual/istream1.cpp
      //
      #include<iostream>
      #include<istream>
      #include<fstream>

      void main ( )
      {
       using namespace std;

       float f= 3.14159;
       int	 i= 3;
       char	 s[200];

        // open a file for read and	write operations
       ofstream out("example", ios_base::in	| ios_base::out
    		 | ios_base::trunc);

        // tie the istream object to the ofstream filebuf
       istream  in (out.rdbuf());

        // output to the file
       out << "Annie is the	Queen of porting" << endl;
       out << f << endl;
       out << i << endl;

        // seek to the beginning of	the file
       in.seekg(0);

       f = i = 0;

        // read from the file using	formatted functions
       in >> s >> f	>> i;

        // seek to the beginning of	the file
       in.seekg(0,ios_base::beg);

        // output the all file to the standard output
       cout	<< in.rdbuf();

        // seek to the beginning of	the file
       in.seekg(0);

        // read the	first line in the file
        // "Annie is the Queen of porting"
       in.getline(s,100);

       cout	<< s <<	endl;

        // read the	second line in the file
        // 3.14159
       in.getline(s,100);

       cout	<< s <<	endl;

        // seek to the beginning of	the file
       in.seekg(0);

        // read the	first line in the file
        // "Annie is the Queen of porting"
       in.get(s,100);

        // remove the newline character
       in.ignore();

       cout	<< s <<	endl;

        // read the	second line in the file
        // 3.14159
       in.get(s,100);

       cout	<< s <<	endl;

        // remove the newline character
       in.ignore();

        // store the current file position
       istream::pos_type position =	in.tellg();

       out << "replace the int" << endl;

        // move back to the	previous saved position
       in.seekg(position);

        // output the remain of the	file
        // "replace	the int"
        // this is equivalent to
        // cout << in.rdbuf();
       while( !char_traits<char>::eq_int_type(in.peek(),
       char_traits<char>::eof()) )
        cout << char_traits<char>::to_char_type(in.get());

       cout	<< "0 << flush;
      }

      //
      // istream example two
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       char	p[50];

        // remove all the white spaces
       cin >> ws;

        // read characters from stdin until	a newline
        // or 49 characters	have been read
       cin.getline(p,50);

        // output the result to stdout
       cout	<< p;
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_iostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.6.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_istringstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_istringstream

    SYNOPSIS

      #include <sstream>
      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_istringstream
      : public basic_istream<charT,	traits>

    DESCRIPTION

      The template class basic_istringstream<charT,traits,Allocator>
      provides functionality	to read	from an	array in memory. It
      supports reading objects of class
      basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
      object to control the	associated storage. It inherits	from
      basic_istream and therefore	can use	all the	formatted and
      unformatted input	functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_istringstream
      : public basic_istream<charT,	traits>	{

      public:

       typedef basic_stringbuf<charT, traits, Allocator>  sb_type;
       typedef basic_ios<charT, traits>		      ios_type;

       typedef basic_string<charT, traits, Allocator>     string_type;

       typedef traits			    traits_type;
       typedef charT			    char_type;
       typedef typename traits::int_type	    int_type;
       typedef typename traits::pos_type	    pos_type;
       typedef typename traits::off_type	    off_type;

       explicit basic_istringstream(ios_base::openmode which =
    				ios_base::in);

       explicit basic_istringstream(const string_type& str,
    				ios_base::openmode which =
    				ios_base::in);

       virtual ~basic_istringstream();

       basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
       string_type str() const;

       void	str(const string_type& str);

      };

    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.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      istringstream
         The type istringstream is an instantiation	of class
         basic_istringstream on	type char:

           typedef basic_istringstream<char> istringstream;

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      sb_type
         The type sb_type is an instantiation of class basic_stringbuf on
         type charT.

      string_type
         The type string_type is an	instantiation of class basic_string on
         type charT.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wistringstream
         The type wistringstream is	an instantiation of class
         basic_istringstream on	type wchar_t:

           typedef basic_istringstream<wchar_t> wistringstream;

    CONSTRUCTORS

      explicit basic_istringstream(ios_base::openmode which	=
    		     ios_base::in);
    	Constructs an object of	class basic_istringstream,
    	initializing the base class basic_istream with the
    	associated string buffer. The string buffer is ini-
    	tialized by calling the	basic_stringbuf	constructor
    	basic_stringbuf<charT,traits,Allocator>(which).

      explicit basic_istringstream(const string_type& str,
    		     ios_base::openmode	which =
    		     ios_base::in);
    	Constructs an object of	class basic_istringstream,
    	initializing the base class basic_istream with the
    	associated string buffer. The string buffer is ini-
    	tialized by calling the	basic_stringbuf	constructor
    	basic_stringbuf<charT,traits,Allocator>(str,which).

    DESTRUCTOR

      virtual ~basic_istringstream();
         Destroys an object	of class basic_istringstream.

    MEMBER FUNCTIONS

      basic_stringbuf<charT,traits,Allocator>*
      rdbuf() const;
         Returns a pointer to the basic_stringbuf associated with the
         stream.

      string_type
      str()	const;
         Returns a string object of	type string_type, which	contains a
         copy	of the underlying buffer contents.

      void
      str(const string_type& str);
         Clears the	string buffer and copies the string object str into
         it.	If the opening mode is in, initialize	the input
         sequence to point at the first character of	the buffer. If
         the opening mode	is out,	initialize the output	sequence to
         point at the first character of the	buffer.	If the opening
         mode is out | app, initialize the output sequence to point at
         the last character of the buffer.

    EXAMPLES

      //
      // stdlib/examples/manual/istringstream.cpp
      //
      #include<iostream>
      #include<sstream>
      #include<string>
      #include<iomanip>

      void main ( )
      {
       using namespace std;

       long	  l= 20;
       wchar_t *ntbs=L"Il avait l'air heureux";
       wchar_t c;
       wchar_t buf[50];

        // create a	read/write string-stream object	on wide	char
        // and attach it to	an wistringstream object
       wistringstream in(ios_base::in | ios_base::out);

        // tie the ostream object to the wistringstream object
       wostream out(in.rdbuf());

        // output ntbs in out
       out << ntbs;

        // output each word	on a separate line
       while ( in.get(c) )
         {
          if ( c ==	L' ' )
           wcout <<	endl;
          else
           wcout <<	c;
         }
       wcout << endl << endl;

        // move back the input sequence to the beginning
       in.seekg(0);

        // clear the state flags
       in.clear();

        // does the	same thing as the previous code
        // output each word	on a separate line
       while ( in >> buf )
        wcout << buf << endl;

       wcout << endl << endl;

        // create a	tiny string object
       string test_string("Il dormait pour l'eternite");

        // create a	read/write string-stream object	on char
        // and attach it to	an istringstream object
       istringstream in_bis(ios_base:: in |	ios_base::out |
    			ios_base::app );

        // create an ostream object
       ostream out_bis(in_bis.rdbuf());

        // initialize the string buffer with test_string
       in_bis.str(test_string);

       out_bis << endl;

        // output the base info before each	integer
       out_bis << showbase;

       ostream::pos_type pos= out_bis.tellp();

        // output l	in hex with a field with of 20
       out_bis << hex << setw(20) << l << endl;

        // output l	in oct with a field with of 20
       out_bis << oct << setw(20) << l << endl;

        // output l	in dec with a field with of 20
       out_bis << dec << setw(20) << l << endl;

        // output the all buffer
       cout	<< in_bis.rdbuf();

        // seek the	input sequence to pos
       in_bis.seekg(pos);

       int a,b,d;

        // read the	previous outputted integer
       in_bis >> a >> b >> d;

        // output 3	times 20
       cout	<< a <<	endl <<	b << endl << d << endl;

      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_stringbuf, basic_string,
      basic_ostringstream,	basic_stringstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.7.2

    STANDARDS CONFORMANC

      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_ofstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ofstream,ofstream

      This page describes the ANSI	basic_ofstream class.  If you would
      like information on the pre-ANSI ofstream class, use the command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ofstream
      : public basic_ostream<charT,	traits>

    DESCRIPTION

      The template class basic_ofstream<charT,traits> supports writing
      into	named files	or other devices associated with a file
      descriptor. It uses a basic_filebuf	object to control the
      associated sequences. It inherits	from basic_ostream	and
      can	therefore use all the formatted	and unformatted	output
      functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ofstream
      : public basic_ostream<charT,	traits>	{

      public:

       typedef basic_ios<charT, traits>    ios_type;

       typedef charT		       char_type;
       typedef traits		       traits_type;
       typedef typename traits::int_type   int_type;
       typedef typename traits::pos_type   pos_type;
       typedef typename traits::off_type   off_type;

       basic_ofstream();

       explicit basic_ofstream(const char *s,
    			   ios_base::openmode mode =
    			   ios_base::out,
    			   long	protection = 0666);

       explicit basic_ofstream(int fd);

       basic_ofstream(int fd, char_type* buf, int len);

       virtual ~basic_ofstream();

       basic_filebuf<charT,	traits>	*rdbuf() const;

       bool	is_open();

       void	open(const char	*s, ios_base::openmode mode =
    	     ios_type::out, long protection = 0666);

       void	close();

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      ofstream
         The type ofstream is an instantiation of  class basic_ofstream on
         type char:

           typedef basic_ofstream<char> ofstream;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wofstream
         The type wofstream	is an instantiation of class basic_ofstream on
         type wchar_t:

           typedef basic_ofstream<wchar_t> wofstream;

    CONSTRUCTORS

      basic_ofstream();
         Constructs	an object of class basic_ofstream<charT,traits>,
         initializing the base class basic_ostream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). After construction a
         file can be attached to	the basic_oftream object using the
         open	member function.

      basic_ofstream(const char* s,
    		ios_base::openmode mode= ios_base::in,
    		long protection= 0666);
    	Constructs an object	of class
    	basic_ofstream<charT,traits>,  initializing the base	class
    	basic_ostream with the associated file buffer, which	is
    	initialized by calling the basic_filebuf constructor
    	basic_filebuf<charT,traits>(). The constructor then calls
    	the open function open(s,mode,protection) in	order to
    	attach the file whose name is pointed at by s, to the
    	basic_oftream object. The third argument, protection, is
    	used	as the file permissions. It does not appear in the
    	Standard C++	description and	is provided as an extension.
    	It determines the file read/write/execute permissions
    	under UNIX.	It is more limited under DOS since files are
    	always readable and do not have special execute permission.

       explicit basic_ofstream(int fd);
         Constructs	an object of class basic_ofstream<charT,traits>,
         initializing the base class	basic_ostream with the
         associated file buffer, which is	initialized by calling the
         basic_filebuf constructor basic_filebuf<charT,traits>(). The
         constructor then calls the basic_filebuf open	function
         open(fd) in order to attach the file descriptor	fd to the
         basic_oftream	 object. This constructor is not described in
         the C++ standard, and	is provided as an extension in order
         to	manipulate pipes, sockets or other UNIX	devices, that can be
         accessed through file descriptors. If the function fails, it sets
         ios_base::failbit.

      basic_ofstream(int fd, char_type* buf,int len);
         Constructs	an object of class basic_ofstream<charT,traits>,
         initializing the base class	basic_ostream with the
         associated file buffer, which is	initialized by calling the
         basic_filebuf constructor basic_filebuf<charT,traits>(). The
         constructor then calls the basic_filebuf open	function
         open(fd) in order to attach the file descriptor	fd to the
         basic_oftream	 object. The underlying	buffer is then
         replaced by calling the basic_filebuf	member function	setbuf
         with parameters	buf and	len. This constructor is not described
         in the C++ standard, and is provided as an extension in order
         to manipulate pipes, sockets or	other UNIX devices, that can
         be	accessed through file descriptors. It also maintains
         compatibility with the old iostreams library. If the function
         fails, it	sets ios_base::failbit.

    DESTRUCTOR

      virtual ~basic_ofstream();
         Destroys an object	of class basic_ofstream.

    MEMBER FUNCTIONS

      void
      close();
         Calls the associated basic_filebuf	function close() and if	this
         function fails, it calls the basic_ios member function
         setstate(failbit).

      bool
      is_open();
         Calls the associated basic_filebuf	function is_open() and return
         its result.

      void
      open(const char* s,ios_base::openmode	=
     	   ios_base::out, long protection = 0666);
          Calls the	associated basic_filebuf function
          open(s,mode,protection) and, if this function fails opening the
          file, calls the basic_ios	member function	setstate(failbit).
          The third	argument, protection, is used as the file permis-
          sions. It	does not appear	in the Standard	C++ description	and
          is provided as an	extension. It determines the file
          read/write/execute permissions under UNIX, and is	more limited
          under DOS	since files are	always readable	and do not have	special
          execute permission.

      basic_filebuf<charT,traits>*
      rdbuf() const;
         Returns a pointer to the basic_filebuf associated with the	stream.

    EXAMPLES

      See basic_fstream, basic_ifstream and	basic_filebuf examples.

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_filebuf, basic_ifstream, basic_fstream

      Working Paper	for Draft Proposed International Standard for Information
      Systems--Programming Language	C++, Section 27.8.1.8

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_ostream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ostream

    SYNOPSIS

      #include <ostream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ostream
      : virtual public basic_ios<charT, traits>

    DESCRIPTION

      The class basic_ostream defines a number of member function
      signatures that assist in formatting and writing output to sequences
      controlled by a stream buffer.

      Two groups of	member function	signatures share common	properties:
      the formatted output	functions (or insertors) and the
      unformatted output functions. Both groups of	functions
      insert characters by calling basic_streambuf member functions. They
      both begin by constructing an object of class basic_ostream::sentry
      and, if this object is	in good	state after construction,
      the function tries to perform the requested output. The sentry
      object performs exception-safe initialization, such as
      controlling the status of the	stream or locking it in	multithread
      environment.

      Some formatted output	functions generate the requested output	by
      converting a value from some scalar to text form	and inserting
      the converted text in the output sequence. The conversion behavior
      is locale dependent, and directly depend on the locale	object
      imbued in the stream.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ostream
      :virtual public basic_ios<charT, traits> {

      public:

       typedef basic_ostream<charT,	traits>	  ostream_type;
       typedef basic_ios<charT, traits>	  ios_type;

       typedef traits			  traits_type;
       typedef charT			  char_type;

       typedef typename traits::int_type	  int_type;
       typedef typename traits::pos_type	  pos_type;
       typedef typename traits::off_type	  off_type;

       explicit basic_ostream(basic_streambuf<charT, traits> *sb);
       virtual ~basic_ostream();

      class	sentry {

       public:

          explicit sentry(basic_ostream<charT,traits>&);
           ~sentry();
          operator bool ();

        };

       ostream_type& operator<<(ostream_type& (*pf)(ostream_type&));
       ostream_type& operator<<(ios_base& (*pf)(ios_base&));
       ostream_type& operator<<(ios_type& (*pf)(ios_type&));

       ostream_type& operator<<(bool n);
       ostream_type& operator<<(short n);
       ostream_type& operator<<(unsigned short n);
       ostream_type& operator<<(int	n);
       ostream_type& operator<<(unsigned int n);
       ostream_type& operator<<(long n);
       ostream_type& operator<<(unsigned long n);
       ostream_type& operator<<(float f);
       ostream_type& operator<<(double f);
       ostream_type& operator<<(long double	f);

       ostream_type& operator<<(void *p);

       ostream_type& operator<<(basic_streambuf<char_type, traits>&	sb);
       ostream_type& operator<<(basic_streambuf<char_type, traits> *sb);

       ostream_type& put(char_type c);

       ostream_type& write(const char_type *s, streamsize n);

       ostream_type& flush();

       ostream_type& seekp(pos_type	);
       ostream_type& seekp(off_type	, ios_base::seekdir );
       pos_type tellp();

      protected:

       basic_ostream();

      };

      //global functions

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, charT);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, char);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, char);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, const charT*);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, const char*);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, const	char*);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, unsigned char);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, signed char);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, const	unsigned char*);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, const	signed char*);

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      endl(basic_ostream<charT, traits>& os);

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      ends(basic_ostream<charT, traits>& os);

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      flush(basic_ostream<charT, traits>& os);

    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.

      ios_type
         The type ios_type is a synonym for	basic_ios<charT, traits>.

      off_type
         The type off_type is a synonym of type traits::off_type.

      ostream
         The type ostream is an instantiation of class basic_ostream on type
         char:

           typedef basic_ostream<char> ostream;

      ostream_type
         The type ostream_type is a	synonym	for basic_ostream<charT, traits>.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wostream
         The type wostream is an instantiation of class basic_ostream on type
         wchar_t:

           typedef basic_ostream<wchar_t> wostream;

    CONSTRUCTOR

      explicit basic_ostream(basic_streambuf<charT,	traits>* sb);
         Constructs	an object of class basic_ostream, assigning initial
         values to the base class by calling
         basic_ios<charT,traits>::init(sb).

    DESTRUCTOR

      virtual ~basic_ostream();
         Destroys an object	of class basic_ostream.

    SENTRY CLASS

      explicit sentry(basic_ostream<charT,traits>&);
         Prepares for formatted or unformatted output. First if the
         basic_ios member function tie() is not a null pointer, the
         function synchronizes the output	sequence with any associated
         stream. If	after any preparation is	completed the
         basic_ios	member function	good() is true,	the sentry conversion
         function operator bool () will return true. Otherwise it will
         return false. In multithread environment the sentry object
         constructor is	responsible for	locking	the stream and the
         stream buffer associated with the stream.

      ~sentry();
         Destroys an object	of class sentry. If the	ios_base member
         function flags() & unitbuf == true,	then flush the buffer.
         In multithread environment the sentry object destructor is
         responsible for unlocking the stream	and the	stream buffer
         associated with the stream.

      operator bool();
         If	after any preparation is completed the ios_base	member
         function good() is true, the sentry	conversion function
         operator bool() will return true else it will return false.

    INSERTORS

      ostream_type&
      operator<<(ostream_type& (*pf) (ostream_type&));
         Calls pf(*this), then return *this. See, for example, the
         function	signature endl(basic_ostream&).

      ostream_type&
      operator<<(ios_type& (*pf) (ios_type&));
         Calls pf(*this), then return *this.

      ostream_type&
      operator<<(ios_base& (*pf) (ios_base&));
         Calls pf(*this), then return *this. See, for example, the
         function	signature dec(ios_base&).

      ostream_type&
      operator<<(bool n);
         Converts the boolean value	n, and outputs it into the
         basic_ostream object's buffer. If the ios_base member function
         flag() & ios_base::boolalpha is false it tries to write an
         integer value, which must be 0 or 1. If	the boolalpha flag is
         true, it writes characters according to the locale function
         numpunct<>::truename() or numpunct<>::falsename().

      ostream_type&
      operator<<(short n);
         Converts the signed short integer n, and output it	into the stream
         buffer, then return *this.

      ostream_type&
      operator<<(unsigned short n);
         Converts the unsigned short integer n, and	output it into the
         stream buffer, then return *this.

      ostream_type&
      operator<<(int n);
         Converts the signed integer n, and	output it into the stream
         buffer, then return *this.

      ostream_type&
      operator<<(unsigned int n);
         Converts the unsigned integer n, and output it into the stream
         buffer, then return *this.

      ostream_type&
      operator<<(long n);
         Converts the signed long integer n, and output it into the	stream
         buffer, then return *this.

      ostream_type&
      operator<<(unsigned long n);
         Converts the unsigned long	integer	n, and output it into the
         stream buffer, then return *this.

      ostream_type&
      operator<<(float f);
         Converts the float	f and output it	into the stream	buffer,	then
         return *this.

      ostream_type&
      operator<<(double f);
         Converts the double f and output it into the stream buffer, then
         return *this.

      ostream_type&
      operator<<(long double f);
         Converts the long double f	and output it into the stream buffer,
         then return *this.

      ostream_type&
      operator<<(void *p);
         Converts the pointer p, and output	it into	the stream buffer,
         then return *this.

      ostream_type&
      operator<<(basic_streambuf<charT,traits> *sb);
         If	sb is null calls the basic_ios member function
         setstate(badbit). Otherwise gets characters from sb and
         inserts	them into the stream buffer until any of the
         following occurs:

         +	     end-of-file occurs	on the input sequence.

         +	     inserting in the output sequence fails

         +	     an	exception occurs while getting a character from	sb

         If	the function inserts no	characters or if it stopped because an
         exception was thrown while extracting a	character, it calls
         the	basic_ios member function setstate(failbit).	If an
         exception	was thrown while extracting	a character it is
         rethrown.

      ostream_type&
      operator<<(basic_streambuf<charT,traits>& sb);
         Gets characters from sb and inserts them into the stream buffer
         until any of the	following occurs:

         +	     end-of-file occurs	on the input sequence.

         +	     inserting in the output sequence fails

         +	     an	exception occurs while getting a character from	sb

         If	the function inserts no	characters or if it stopped because an
         exception was thrown while extracting a	character, it calls
         the	basic_ios member function setstate(failbit).	If an
         exception was thrown while extracting	a character it is
         rethrown.

    UNFORMATTED FUNCTIONS

      ostream_type&
      flush();
         If	rdbuf()	is not a null pointer, calls rdbuf()->pubsync()	and
         returns *this. If that function returns -1	calls
         setstate(badbit).

      ostream_type&
      put(char_type	c);
         Inserts the character c. If the operation fails, calls the
         basic_ios member function setstate(badbit).

      ostream_type&
      seekp(pos_type pos);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(pos), which will position the current pointer
         of the output sequence at	the position designated	by pos.

      ostream_type&
      seekp(off_type off, ios_base::seekdir	dir);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(off,dir), which will position the current
         pointer of the output	sequence at the	position designated by
         off and dir.

      pos_type
      tellp();
         If	the basic_ios member function fail() returns true, tellp()
         returns pos_type(off_type(-1)) to indicate	failure. Otherwise it
         returns the current position of the output sequence by
         calling	rdbuf()-> pubseekoff(0,cur, out).

      ostream_type&
      write(const char_type* s, streamsize n);
         Obtains characters	to insert from successive locations of an
         array	whose first element is designated by s. Characters are
         inserted until either of	the following occurs:

         +	     n characters are inserted

         +	     inserting in the output sequence fails

         In	the second case	the function calls the basic_ios member	function
         setstate(badbit). The function returns *this.

    NON MEMBER FUNCTIONS

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      endl(basic_ostream<charT, traits>& os);
         Outputs a newline character and flush the buffer, then returns os.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      ends(basic_ostream<charT, traits>& os);
         Inserts a null character into the output sequence,	then returns os.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      flush(basic_ostream<charT, traits>& os);
         Flushes the buffer, then returns os.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, charT c);
         Outputs the character c of	type charT into	the basic_ostream
         object's buffer. Both the stream and the stream buffer are
         instantiated on type charT. Padding is not ignored.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, char c);
         Outputs the character c of	type char into the basic_ostream
         object's buffer. Both the stream and the stream buffer are
         instantiated on type charT. Conversion from characters of type
         char to characters of type charT is performed	by the
         basic_ios member	function widen.	padding	is not ignored.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, char c);
         Outputs the character c of	type char into the basic_ostream
         object's buffer. Both the stream and the stream buffer are
         instantiated on type char. Padding is not ignored.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, const charT* s);
         Outputs the null-terminated-byte-string s of type charT* into the
         basic_ostream object's buffer. Both the stream and	the stream
         buffer are instantiated on type charT.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, const char* s);
         Outputs the null-terminated-byte-string s of type char* into the
         basic_ostream object's buffer. Both the stream and	the stream
         buffer are instantiated on type charT. Conversion from characters
         of type char to characters	of type	charT is performed by the
         basic_ios member function widen.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, const char* s);
         Outputs the null-terminated-byte-string s of type char* into the
         basic_ostream object's buffer. Both the stream and	the stream
         buffer are instantiated on type char.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, unsigned char c);
         Returns os	<< (char)c.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, signed char c);
         Returns os	<< (char)c.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, unsigned char* c);
         Returns os	<< (char*)c.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, signed char* c);
         Returns os	<< (char*)c.

    FORMATTING

      The formatting is done through member	functions or manipulators.

      Manipulators		      Member Functions

      showpos		      setf(ios_base::showpos)
      noshowpos		      unsetf(ios_base::showpos)
      showbase		      setf(ios_base::showbase)
      noshowbase		      unsetf(ios_base::showbase)
      uppercase		      setf(ios_base::uppercase)
      nouppercase		      unsetf(ios_base::uppercase)
      showpoint		      setf(ios_base::showpoint)
      noshowpoint		      unsetf(ios_base::showpoint)
      boolalpha		      setf(ios_base::boolalpha)
      noboolalpha		      unsetf(ios_base::boolalpha)
      unitbuf		      setf(ios_base::unitbuf)
      nounitbuf		      unsetf(ios_base::unitbuf)
      internal		      setf(ios_base::internal,
    				 ios_base::adjustfield)
      left			      setf(ios_base::left,
    				 ios_base::adjustfield)
      right			      setf(ios_base::right,
    				 ios_base::adjustfield)
      dec			      setf(ios_base::dec,
    				 ios_base::basefield)
      hex			      setf(ios_base::hex,
    				 ios_base::basefield)
      oct			      setf(ios_base::oct,
    				 ios_base::basefield)
      fixed			      setf(ios_base::fixed,
    				 ios_base::floatfield)
      scientific		      setf(ios_base::scientific,
    				 ios_base::floatfield)
      resetiosflags
       (ios_base::fmtflags flag)  setf(0,flag)
      setiosflags
       (ios_base::fmtflags flag)  setf(flag)
      setbase(int base)	      See above
      setfill(char_type c)	      fill(c)
      setprecision(int n)	      precision(n)
      setw(int n)		      width(n)

    DESCRIPTION

      showpos   Generates a	+ sign in non-negative generated numeric output

      showbase   Generates a prefix	indicating the numeric base of generated
    	     integer output

      uppercase   Replaces certain lowercase letters with their uppercase
    	      equivalents in generated output

      showpoint   Generates	a decimal-point	character unconditionally in gen-
    	      erated floating-point output

      boolalpha   Insert and extract bool type in alphabetic format

      unitbuf   Flushes output after each output operation

      internal   Adds fill characters at a designated internal point in certain
    	     generated output, or identical to right if	no such	point is
    	     designated

      left	 Adds fill characters on the right (final positions) of	certain
             generated	output

      right	  Adds fill characters on the left (initial positions) of certain
    	  generated output

      dec	Converts integer input or generates integer output in decimal base

      hex	Converts integer input or generates integer output in hexadecimal
    	base

      oct	Converts integer input or generates integer output in octal base

      fixed	  Generates floating-point output in fixed-point notation

      scientific   Generates floating-point	output in scientific notation

      resetiosflagss

      (ios_base::fmtflags flag)   Resets the fmtflags field	flag

      setiosflags

      (ios_base::fmtflags flag)   Set up the flag flag

      setbase(int base)   Converts integer input or	generates integer output
                          in base base. The parameter base can	be 8, 10
                          or 16.

      setfill(char_type c)	 Set the character used	to pad (fill) an output
    			 conversion to the specified field width

      setprecision(int n)	Set the	precision (number of digits after the
                            decimal point) to generate on certain output
                            conversions

      setw(int n)	Set the	field with (number of characters) to generate
                    on certain output conversions

    EXAMPLES

      //
      // stdlib/examples/manual/ostream1.cpp
      //
      #include<iostream>
      #include<ostream>
      #include<sstream>
      #include<iomanip>

      void main ( )
      {
        using namespace std;

        float f= 3.14159;
        int	  i= 22;
        char* s= "Randy is the king	of stdlib";

         //	create a read/write stringbuf object on	tiny char
         //	and attach it to an istringstream object
        istringstream in( ios_base::in | ios_base::out );

         //	tie the	ostream	object to the istringstream object
        ostream out(in.rdbuf());

        out	<< "test beginning !" << endl;

         //	output i in hexadecimal
        out	<< hex << i <<endl;

         //	set the	field width to 10
         //	set the	padding	character to '@'
         //	and output i in	octal
        out	<< setw(10) << oct << setfill('@') << i	<< endl;

         //	set the	precision to 2 digits after the	separator
         //	output f
        out	<< setprecision(3) << f	<< endl;

         //	output the 17 first characters of s
        out.write(s,17);

         //	output a newline character
        out.put('0);

         //	output s
        out	<< s <<	endl;

         //	output the all buffer to standard output
        cout << in.rdbuf();
      }

      //
      // stdlib/examples/manual/ostream2.cpp
      //
      #include<iostream>
      #include<ostream>
      #include<sstream>

      void main ( )
      {
        using namespace std;

        float f= 3.14159;
        wchar_t* s=	L"Kenavo !";

         //	create a read/write stringbuf object on	wide char
         //	and attach it to an wistringstream object
        wistringstream in( ios_base::in | ios_base::out );

         //	tie the	wostream object	to the wistringstream object
        wostream out(in.rdbuf());

        out	<< L"test beginning !" << endl;

         //	output f in scientific format
        out	<< scientific << f <<endl;

         //	store the current put-pointer position
        wostream::pos_type pos = out.tellp();

         //	output s
        out	<< s <<	endl;

         //	output the all buffer to standard output
        wcout << in.rdbuf()	<< endl;

         //	position the get-pointer
        in.seekg(pos);

         //	output s
        wcout << in.rdbuf()	<< endl;
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_iostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.6.2.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_ostringstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ostringstream

    SYNOPSIS

      #include <sstream>
      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_ostringstream
      : public basic_ostream<charT,	traits>

    DESCRIPTION

      The template class basic_ostringstream<charT,traits,Allocator>
      provides functionality	to write to an array in	memory.	It
      supports writing objects of class
      basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
      object to control the	associated storage. It inherits	from
      basic_ostream and therefore	can use	all the	formatted and
      unformatted output functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_ostringstream
      : public basic_ostream<charT,	traits>	{

      public:

       typedef basic_stringbuf<charT, traits, Allocator> sb_type;
       typedef basic_ios<charT, traits>		     ios_type;

       typedef basic_string<charT, traits, Allocator>    string_type;

       typedef traits			    traits_type;
       typedef charT			    char_type;
       typedef typename traits::int_type	    int_type;
       typedef typename traits::pos_type	    pos_type;
       typedef typename traits::off_type	    off_type;

       explicit basic_ostringstream(ios_base::openmode which =
    				ios_base::out);

       explicit basic_ostringstream(const string_type& str,
    				ios_base::openmode which =
    				ios_base::out);

       virtual ~basic_ostringstream();

       basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
       string_type str() const;

       void	str(const string_type& str);

      };

    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.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      ostringstream
         The type ostringstream is an instantiation	of class
         basic_ostringstream on	type char:

           typedef basic_ostringstream<char> ostringstream;

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      sb_type
         The type sb_type is an instantiation of class basic_stringbuf
         on type charT.

      string_type
         The type string_type is an	instantiation of class basic_string
         on type charT.

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

      wostringstream
         The type wostringstream is	an instantiation of class
         basic_ostringstream on	type wchar_t:

           typedef basic_ostringstream<wchar_t> wostringstream;

    CONSTRUCTORS

      explicit basic_ostringstream(ios_base::openmode which	=
    			      ios_base::out);
    		Constructs an object of class
    		basic_ostringstream, initializing the base
    		class basic_ostream with the associated
    		string	buffer.	The string buffer is initial-
    		ized by calling the basic_stringbuf con-
    		structor
    		basic_stringbuf<charT,traits,Allocator>(which).

      explicit basic_ostringstream(const string_type& str,
    			      ios_base::openmode which =
    			      ios_base::out);
    		Constructs an object of class
    		basic_ostringstream, initializing the base
    		class basic_ostream with the associated
    		string	buffer.	The string buffer is initial-
    		ized by calling the basic_stringbuf con-
    		structor
    		basic_stringbuf<charT,traits,Allocator>(str,which).

    DESTRUCTOR

      virtual ~basic_ostringstream();
         Destroys an object	of class basic_ostringstream.

    MEMBER FUNCTIONS

      basic_stringbuf<charT,traits,Allocator>*
      rdbuf() const;
         Returns a pointer to the basic_stringbuf associated with the
         stream.

      string_type
      str()	const;
         Returns a string object of	type string_type whose contents	is a
         copy of the underlying buffer contents.

      void
      str(const string_type& str);
         Clears the	underlying string buffer and copies the	string object
         str into it. If the opening mode is in, initialize the	input
         sequence to point at the first	character of the buffer. If
         the	opening	mode is	out, initialize	the output sequence to
         point at	the first character of the buffer. If	the opening
         mode is out	| app, initialize the output sequence to
         point at the last character of the buffer.

    EXAMPLES

      See basic_stringstream, basic_istringstream and basic_stringbuf
      examples.

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_stringbuf, basic_string,
      basic_istringstream,	basic_stringstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.7.2.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_streambuf
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_streambuf,streambuf

      This page describes the ANSI streambuf class.	 If you	would like
      information on the pre-ANSI streambuf class,	use the
      command:

           help cxxl

    SYNOPSIS

      #include <streambuf>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_streambuf;

    DESCRIPTION

      The class template basic_streambuf<charT,traits> serves as an
      abstract base class	for deriving various stream buffers whose
      objects each control two character sequences:

      +	  A character input sequence;

      +	  A character output sequence.

      Each sequence	is characterized by three pointers which, if non-null,
      all point	into the same charT array object. The array object
      represents, at any moment, a subsequence	of characters from the
      sequence. Operations performed on a sequence	alter the values
      stored	in these pointers, perform reads and writes directly
      to or	from associated	sequences, and alter "the stream position" and
      conversion state as needed to maintain this subsequence	rela-
      tionship. The	three pointers are:

      +	  The beginning	pointer, or lowest element address in the array;

      +	  The next pointer, or next element address that is a current
           candidate for	reading	or writing;

      +	  The end pointer, or first element address beyond the end of
           the array.

      Stream buffers can impose various constraints	on the sequences they
      control,	including:

      +	  The controlled input sequence	may be unreadable;

      +	  The controlled output	sequence may be	unwritable;

      +	  The controlled sequences can be associated with the
           contents of other representations for character sequences, such
           as external files;

      +	  The controlled sequences can impose limitations on how the
           program can read	characters from	a sequence, write characters
           to	a sequence, put characters back into	an input sequence,
           or alter the	stream position.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_streambuf	{

      public:

      typedef charT			      char_type;
      typedef traits		      traits_type;

      typedef typename traits::int_type    int_type;
      typedef typename traits::pos_type    pos_type;
      typedef typename traits::off_type    off_type;

      virtual ~basic_streambuf();

      locale pubimbue( const locale& loc);
      locale getloc() const;

      basic_streambuf<char_type, traits> *
        pubsetbuf(char_type	*s, streamsize n);

      pos_type pubseekoff(off_type off, ios_base::seekdir way,
    		      ios_base::openmode which =
    		      ios_base::in | ios_base::out);

      pos_type pubseekpos(pos_type sp, ios_base::openmode which =
    		      ios_base::in | ios_base::out);

      int pubsync();

      ios_base::openmode which_open_mode();

      streamsize   in_avail();

      int_type snextc();

      int_type sbumpc();

      int_type sgetc();

      streamsize sgetn(char_type *s, streamsize n);

      int_type sputbackc(char_type c);

      int sungetc();

      int_type sputc(char_type c);

      streamsize sputn(const char_type *s, streamsize n);

      protected:

      basic_streambuf();

      char_type *eback() const;
      char_type *gptr() const;
      char_type *egptr() const;

      void gbump(int n);

      void setg(char_type *gbeg_arg,char_type *gnext_arg,
    	    char_type *gend_arg);

      char_type *pbase() const;
      char_type *pptr() const;
      char_type *epptr() const;

      void pbump(int n);

      void setp(char_type *pbeg_arg,char_type *pend_arg);

      virtual void imbue( const locale& loc);

      virtual int_type overflow(int_type c = traits::eof());

      virtual int_type pbackfail(int_type c	= traits::eof());

      virtual int showmanyc();

      virtual int_type underflow();

      virtual int_type uflow();

      virtual streamsize xsgetn(char_type *s, streamsize n);

      virtual streamsize xsputn(const char_type *s,	streamsize n);

      virtual pos_type seekoff(off_type off,ios_base::seekdir way,
    			   ios_base::openmode which =
    			   ios_base::in	| ios_base::out);

      virtual pos_type seekpos(pos_type sp,ios_base::openmode which	=
    			   ios_base::in	| ios_base::out);

      virtual basic_streambuf<charT, traits>*
        setbuf(char_type *s, streamsize n);

      virtual int sync();

      };

    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.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      streambuf
         The type streambuf	is an instantiation of class
         basic_streambuf  on	type  char:

           typedef basic_streambuf<char> streambuf;

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wstreambuf
         The type wstreambuf is an instantiation of	 class basic_streambuf on
         type wchar_t:

           typedef basic_streambuf<wchar_t>	wstreambuf;

    PUBLIC CONSTRUCTOR

      basic_streambuf();
         Constructs	an object of class basic_streambuf and initializes all
         its pointer member objects to null pointers and the getloc()
         member function to	return the value of locale::locale().

    PUBLIC DESTRUCTOR

      virtual ~basic_streambuf();
         Destroys an object	of class basic_streambuf.

    PUBLIC MEMBER FUNCTIONS

      locale
      getloc() const;
         If	pubimbue() has ever been called, returns the last value	of loc
         supplied, otherwise, the default locale locale::locale() in
         effect at	the time of construction.

      streamsize
      in_avail();
         If	a read position	is available, returns the number of available
         character in the	input sequence.	Otherwise calls	the protected
         function showmanyc().

      locale
      pubimbue(const locale& loc);
         Calls the protected function imbue(loc).

      pos_type
      pubseekoff(off_type off, ios_base::seekdir way,
    	    ios_base::openmode which =
    	    ios_base::in | ios_base::out );
    	       Calls the protected function seekoff(off,way,which).

      pos_type
      pubseekpos(pos_type sp, ios_base::openmode which=
    	    ios_base::in | ios_base::out );
    	       Calls the protected function seekpos(sp,which).

      basic_streambuf<char_type,traits>*
      pubsetbuf(char_type* s,streamsize n);
         Calls the protected function setbuf(s,n) .

      int
      pubsync();
         Calls the protected function sync().

      int_type
      sbumpc();
         If	the input sequence read	position is not	available, calls the
         function uflow(), otherwise	returns	*gptr()	and increments
         the next	pointer	for the input sequence.

      int_type
      sgetc();
         If	the input sequence read	position is not	available, calls the
         protected function underflow(), otherwise returns *gptr() .

      streamsize
      sgetn(char_type* s, streamsize n);
         Calls the protected function xsgetn(s,n).

      int_type
      snextc();
         Calls the function	sbumpc() and if	it returns traits::eof(),
         returns traits::eof(); otherwise calls the	function sgetc() .

      int_type
      sputbackc(char_type c);
         If	the input sequence putback position is not available, or if
         traits::eq(c,gptr() [-1]) returns false, calls the	protected
         function pbackfail(c), otherwise decrements	the next
         pointer for the input sequence and returns *gptr().

      int_type
      sputc(char_type c);
         If	the output sequence write position is not available, calls the
         protected function overflow(traits::to_int_type( c )).
         Otherwise, stores c at	the next pointer for the output
         sequence, increments the pointer, and returns *pptr() .

      streamsize
      sputn(const char_type* s, streamsize n);
         Calls the protected function xsputn(s,n).

      int_type
      sungetc();
         If	the input sequence putback position is not available, calls
         the	protected function pbackfail(). Otherwise decrements
         the next	pointer	for the input sequence	and returns *gptr().

      ios_base::openmode
      which_open_mode();
         Returns the mode in which the stream buffer is opened. This
         function is not described in the C++ standard.

    PROTECTED MEMBER FUNCTIONS

      char_type*
      eback() const;
         Returns the beginning pointer for the input sequence.

      char_type*
      egptr() const;
         Returns the end pointer for the input sequence.

      char_type*
      epptr() const;
         Returns the end pointer for the output sequence.

      void
      gbump(int n);
         Advances the next pointer for the input sequence by n.

      char_type*
      gptr() const;
         Returns the next pointer for the input sequence.

      void
      imbue(const locale&);
         Changes any translations based on locale. The default behavior is
         to do nothing, this function has	to be overloaded in the
         classes	derived	from basic_streambuf. The purpose of this
         function is to allow the derived class to be informed of changes
         in	locale at the time they	occur. The new imbued	locale object
         is only used by the stream buffer, it does not affect the	stream
         itself.

      int_type
      overflow(int_type c =	traits::eof() );
         The member	functions sputc() and sputn() call this	function in
         case that not enough	room can be found in the put buffer to
         accommodate the argument character sequence. The function
         returns traits::eof() if it fails to	make more room
         available, or to	empty the buffer by writing the characters
         to their output	device.

      int_type
      pbackfail(int_type c = traits::eof() );
         If	c is equal to traits::eof(), gptr() is moved back one position
         otherwise c is prepended. The function returns traits::eof() to
         indicate failure.

      char_type*
      pbase() const;
         Returns the beginning pointer for the output sequence.

      void
      pbump(int n);
         Advances the next pointer for the output sequence by n.

      char_type*
      pptr() const;
         Returns the next pointer for the output sequence.

      pos_type
      seekoff(off_type off,	ios_base::seekdir way,
    	 ios_base::openmode which =
    	 ios_base::in |	ios_base::out );
        Alters the stream positions within one or more of the controlled
        sequences in a way that is defined separately for each class
        derived from basic_streambuf. The default behavior is to return
        an object of type pos_type that stores an invalid stream posi-
        tion.

      pos_type
      seekpos(pos_type sp, ios_base::openmode which=
    	 ios_base::in |	ios_base::out );
        Alters the stream positions	within one or more of the controlled
        sequences in a way that is defined separately for each class
        derived from basic_streambuf. The default behavior is to return
        an object of class pos_type	that stores an invalid stream posi-
        tion.

      basic_streambuf*
      setbuf(char_type* s, streamsize n);
        Performs an operation that	is defined separately for each class
         derived from basic_streambuf. The purpose of this function	is to
         allow the	user to	provide	his own	buffer,	or to resize the
         current buffer.

      void
      setg(char_type* gbeg,	char_type* gnext, char_type* gend);
         Sets up private member for	the following to be true:

         eback() ==	gbeg, gptr() ==	gnext and egptr() == gend

      void
      setp(char_type* pbeg,	char_type* pend);
         Sets up private member for	the following to be true:

         pbase() ==	pbeg, pptr() ==	pbeg and epptr() == pend

      int
      showmanyc();
         Returns the number	of characters available	in the internal
         buffer,	or -1.

      int
      sync();
         Synchronizes the controlled sequences with	the internal buffer,
         in	a way that is defined separately	for each class derived
         from basic_streambuf. The default behavior is to	do nothing. On
         failure the return value	is -1.

      int_type
      underflow();
         The public	members	of basic_streambuf call	this function only if
         gptr() is	null or	gptr() >= egptr(). This	function returns the
         character pointed at	by gptr() if gptr() is not null	and if
         gptr() <	egptr(). Otherwise the	function try to	read
         character into the	buffer,	and if it fails return traits::eof().

      int_type
      uflow();
         Calls underflow() and if underflow() returns traits::eof(),
         returns traits::eof(). Otherwise, does gbump(1) and returns the
         value of *gptr().

      streamsize
      xsgetn(char_type* s, streamsize n);
         Assigns up	to n characters	to successive elements of the array
         whose first element is designated by s. The characters are read
         from the	input sequence. Assigning stops when either n
         characters	have been assigned or a call to sbumpc()	would
         return traits::eof(). The	function returns the number of
         characters read.

      streamsize
      xsputn(const char_type* s, streamsize	n);
         Writes up to n characters to the output sequence. The characters
         written are obtained from successive elements of the array	whose
         first element is	designated by s. Writing stops when either n
         characters	have been written or	a call to sputc() would	return
         traits::eof(). The function returns the number	of characters
         written.

    SEE ALSO

      char_traits,	basic_filebuf,	basic_stringbuf,
      strstreambuf

      Working Paper	for Draft Proposed International Standard for Information
      Systems--Programming Language	C++, Section 27.5

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    basic_stringstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_stringstream

    SYNOPSIS

      #include <sstream>
      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_stringstream
      : public basic_iostream<charT, traits>

    DESCRIPTION

      The template class basic_stringstream<charT,traits,Allocator>
      provides functionality	to read	and write to an	array in
      memory. It supports writing and reading objects of class
      basic_string<charT,traits,Alocator>. It uses a basic_stringbuf
      object to control the	associated storage. It inherits	from
      basic_iostream and therefore can use all the formatted and
      unformatted output and input	functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_stringstream
      : public basic_iostream<charT, traits> {

      public:

       typedef basic_stringbuf<charT, traits, Allocator>  sb_type;
       typedef basic_ios<charT, traits>		      ios_type;

       typedef basic_string<charT, traits, Allocator>     string_type;

       typedef traits			     traits_type;
       typedef charT			     char_type;
       typedef typename traits::int_type	     int_type;
       typedef typename traits::pos_type	     pos_type;
       typedef typename traits::off_type	     off_type;

       explicit basic_stringstream(ios_base::openmode which	=
    			       ios_base::out | ios_base::in);

       explicit basic_stringstream(const string_type& str,
    			       ios_base::openmode which	=
    			       ios_base::out | ios_base::in);

       virtual ~basic_stringstream();

       basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
       string_type str() const;

       void	str(const string_type& str);

      };

    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.

      ios_type
         The type ios_type is an instantiation of class
         basic_ios on type charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      sb_type
         The type sb_type is an instantiation of class basic_stringbuf on
         type charT.

      string_type
         The type string_type is an	instantiation of class basic_string on
         type charT.

      stringstream
         The type stringstream is an instantiation of class
         basic_stringstream on type char:

           typedef basic_stringstream<char>	stringstream;

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

      wstringstream
         The type wstringstream is an instantiation	of class
         basic_stringstream on	type wchar_t:

           typedef basic_stringstream<wchar_t> wstringstream;

    CONSTRUCTORS

      explicit basic_stringstream(ios_base::openmode which =
    		    ios_base::in | ios_base::out);
    	Constructs an object of class basic_stringstream, ini-
    	tializing the base class	basic_iostream with the	asso-
    	ciated string buffer. The string	buffer is initialized
            by calling the basic_stringbuf constructor
    	basic_stringbuf<charT,traits,Allocator>(which).

      explicit basic_stringstream(const string_type& str,
    		    ios_base::openmode which =
    		    ios_base::in | ios_base::out);
    	Constructs an object of class basic_stringstream, ini-
    	tializing the base class	basic_iostream with the	asso-
    	ciated string buffer. The string	buffer is initialized
            by calling the basic_stringbuf constructor
    	basic_stringbuf<charT,traits,Allocator>(str,which).

    DESTRUCTOR

      virtual ~basic_stringstream();
         Destroys an object	of class basic_stringstream.

    MEMBER FUNCTIONS

      basic_stringbuf<charT,traits,Allocator>*
      rdbuf() const;
         Returns a pointer to the basic_stringbuf associated with the
         stream.

      string_type
      str()	const;
         Returns a string object of	type string_type whose contents	is a
         copy of the underlying buffer contents.

      void
      str(const string_type& str);
         Clears the	string buffer and copies the string object str into
         it.	If the opening mode is in, initializes the input
         sequence to point at	the first character of	the buffer. If
         the opening mode	is out,	initializes the output	sequence to
         point at the first	character of the buffer. If the opening mode
         is out | app, initializes	the output sequence to point at	the
         last character of the buffer.

    EXAMPLES

      //
      // stdlib/examples/manual/stringstream.cpp
      //
      #include<iostream>
      #include<sstream>

      void main ( )
      {
       using namespace std;

        // create a	bi-directional wstringstream object
       wstringstream inout;

        // output characters
       inout << L"Das ist die rede von einem man" << endl;
       inout << L"C'est l'histoire d'un home" << endl;
       inout << L"This is the story	of a man" << endl;

       wchar_t p[100];

        // extract the first line
       inout.getline(p,100);

        // output the first	line to	stdout
       wcout << endl << L"Deutch :"	<< endl;
       wcout << p;

        // extract the seconf line
       inout.getline(p,100);

        // output the second line to stdout
       wcout << endl << L"Francais :" << endl;
       wcout << p;

        // extract the third line
       inout.getline(p,100);

        // output the third	line to	stdout
       wcout << endl << L"English :" << endl;
       wcout << p;

        // output the all content of the
        //wstringstream object to stdout
       wcout << endl << endl << inout.str();
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_stringbuf, basic_string,
      basic_istringstream,	basic_ostringstream(3c++)

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.7.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    cerr
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      cerr

    SYNOPSIS

      #include <iostream>
      extern ostream cerr;

      DESCRIPTION
      ostream cerr;

      The object	cerr controls output to	an unbuffered stream buffer
      associated with the object stderr declared in
      <cstdio>. By default, the standard C and	C++ streams are
      synchronized, but you may improve performance by	using the
      ios_base member function synch_with_stdio to desynchronize them.

    FORMATTING

      The formatting is done through member	functions or manipulators. See
      cout or basic_ostream for details.

    EXAMPLES

      //
      // cerr example
      //
      #include<iostream>
      #include<fstream>

      void main ( )
      {
       using namespace std;

        // open the	file "file_name.txt"
        // for reading
       ifstream in("file_name.txt");

        // output the all file to stdout
       if (	in )
         cout << in.rdbuf();
       else
          // if the	ifstream object	is in a	bad state
          // output	an error message to stderr
         cerr << "Error while opening the file" << endl;
      }

    SEE ALSO

      basic_ostream, iostream, basic_filebuf,
      cout, cin, clog, wcin, wcout,
      wcerr, wclog, iomanip, ios_base,
      basic_ios

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.3.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    char_traits
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      char_traits_ - A traits class	providing types	and operations to the
      basic_string container and iostream classes.

    SYNOPSIS

      #include <string>
      template <class charT> struct	char_traits
      struct char_traits<char>; .
      struct char_traits<wchar_t>;

    DESCRIPTION

      The char_traits struct provides elementary operations	to
      instantiations of basic_string and iostream classes.  As with all
      traits classes, char_traits is used to specialize	the behavior
      of	a template.  In	this case, the traits class	provides
      functions based on character type to the basic_string template
      and to the templates that are part of the iostreams library.

      Specializations of char_traits are provided for char and wchar_t.
      These are used to define, respectively, string and wstring,	 cout
      and wcout, etc.

    INTERFACE

      template <class charT> struct	char_traits .
      {
      typedef charT			   char_type;
      typedef int			   int_type;
      typedef streampos		   pos_type;
      typedef streamoff		   off_type;
      typedef mbstate_t		   state_type;

      static void assign (char_type&, const	char_type&);
      static char_type* assign (char_type*,	size_t,	const char_type&);

      static bool eq (const	char_type&, const char_type&);
      static bool lt (const	char_type&, const char_type&);

      static int compare (const char_type*,	const char_type*, size_t);
      static size_t	length (const char_type	* s);
      static const char_type*
       find	(const char_type*, int,	const char_type&);
      static char_type* move (char_type*,  const char_type*, size_t);
      static char_type* copy (char_type*,  const char_type*, size_t);

      static int_type not_eof(const	int_type& c);
      static char_type to_char_type(const int_type&	c);
      static int_type to_int_type(const char_type& c);
      static bool eq_int_type(const	int_type& c1, const int_type& c2);
      static int_type eof();
      };

    TYPE

      char_type
         The basic character type. Same as the template parameter.

      int_type
         A type that  can represent all the character values
         of char_type as	well as	and end	of file	value.

      pos_type
         A type used to represent a	position within	a stream buffer.

      off_type
         A type used to represent an offset	to a  position within a	stream
         buffer.

      state_type
         A type used to represent the state	class or type that is applied
         to the codecvt facet.  This type is only relevant	for streams
         with a underlying character type that is multi-byte.

    OPERATIONS

      static
      void assign(char_type& c1, const char_type& c2)
         Assigns one character value to another.  The value	of c2 is
         assigned to c1.

      static
      char_type* assign(char_type* s, size_t n, const char_type& a)
         Assigns one character value to n elements of a character array.
         The value of a	is assigned to n elements of s.

      static
      bool eq(const	char_type& c1, const char_type&	c2)
         Returns true if c1	equals c2.

      static
      bool lt(const	char_type& c1, const char_type&	c2)
         Returns true if c1	is less	than c2.

      static
      int compare(const char_type* s1, const char_type* s2,
    	     size_t n)
         Compares n values from s1 with n values	from s2.  Return 1 if
         s1 is greater than s2, -1 if s1	is less	than s2, or 0 if they
         are equal.

      static
      size_t length(const char_type	* s)
         Returns the length	of the null terminated character array s.  The
         eos terminator	is not counted.

      static
      const	char_type* find(const char_type* s, int	n,
    	const char_type& a)
         Looks for the value of a in s.  Only	n elements of s	are
         examined. Returns a pointer to	the matched element if one is
         found.  Otherwise	returns	s + n.

      static
      char_type* move(char_type* s1, const char_type* s2, size_t n)
         Moves n values from s1 to s2.  The	ranges of (s1,s1+n) and
         (s2,s2+n) may overlap.

      static
      char_type* copy(char_type* s1, const char_type* s2, size_t n)
         Copy n values from	s1 to s2. The ranges of	(s1,s1+n) and
         (s2,s2+n)	may not overlap.

      static
      int_type not_eof(const int_type& c)
         Returns c if c is not equal to eof(),  otherwise returns 0.

      static
      int_type to_char_type(const int_type&	c)
         Returns the char_type representation of c.	 This value may	not be
         useful if	no such	representation exists.

      static
      int_type to_int_type(const char_type&	c)
         Returns the int_type representation of c.

      static
      bool eq_int_type(const int_type& c1, const int_type& c2)
         Returns true if c1	equals c2.

      static
      int_type eof()
         Returns EOF.

    SEE ALSO

      basic_string,	traits,	basic_ostream, basic_istream, cout, cin,
      wcout,	wcin

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    cin
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      cin

    SYNOPSIS

      #include <iostream>
      extern istream cin;

    DESCRIPTION
    istream cin;
         The object	cin controls input from	a stream buffer	associated
         with	the object stdin declared in <cstdio>.	By default,
         the	standard C and C++ streams are syn chronized, but you
         can improve performance by using	the ios_base member function
         synch_with_stdio to desynchronize	them.

         After the object cin is initialized, cin.tie() returns &cout,
         which implies that cin and cout are synchronized.

    EXAMPLES

      //
      // cin example one
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       int i;
       float f;
       char	c;

        //read an integer, a float and a character from stdin
       cin >> i >> f >> c;

        // output i, f and c to stdout
       cout	<< i <<	endl <<	f << endl << c << endl;
      }

      //
      // cin example two
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       char	p[50];

        // remove all the white spaces
       cin >> ws;

        // read characters from stdin until	a newline
        // or 49 characters	have been read
       cin.getline(p,50);

        // output the result to stdout
       cout	<< p;
      }

      When inputting "  Grendel the monster" (newline) in	the previous
      test, the output will be "Grendel the monster". The	manipulator
      ws removes spaces.

    SEE ALSO

      basic_istream, iostream, basic_filebuf,
      cout, cerr,	clog, wcin, wcout,
      wcerr, wclog, ios_base, basic_ios

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.3.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    cout
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      cout

    SYNOPSIS

      #include <iostream>
      extern ostream cout;

    DESCRIPTION

      ostream cout;
         The object	cout controls output to	a stream buffer	associated
         with	the object stdout declared in <cstdio>. By default the
         standard C and C++ streams are synchronized, but performance
         improvement can be achieved by using the ios_base	member
         function	synch_with_stdio to desynchronize them.

         After the object cin is initialized, cin.tie() returns &cout,
         which implies that cin and cout are synchronized.

    FORMATTING

      The formatting is done through member	functions or manipulators.

      Manipulators			Member functions

      showpos			setf(ios_base::showpos)
      noshowpos			unsetf(ios_base::showpos)
      showbase			setf(ios_base::showbase)
      noshowbase			unsetf(ios_base::showbase)
      uppercase			setf(ios_base::uppercase)
      nouppercase			unsetf(ios_base::uppercase)
      showpoint			setf(ios_base::showpoint)
      noshowpoint			unsetf(ios_base::showpoint)
      boolalpha			setf(ios_base::boolalpha)
      noboolalpha			unsetf(ios_base::boolalpha)
      unitbuf			setf(ios_base::unitbuf)
      nounitbuf			unsetf(ios_base::unitbuf)
      internal			setf(ios_base::internal,
    				   ios_base::adjustfield)
      left				setf(ios_base::left,
    				   ios_base::adjustfield)
      right				setf(ios_base::right,
    				   ios_base::adjustfield)
      dec				setf(ios_base::dec,
    				   ios_base::basefield)
      hex				setf(ios_base::hex,
    				   ios_base::basefield)
      oct				setf(ios_base::oct,
    				   ios_base::basefield)
      fixed				setf(ios_base::fixed,
    				   ios_base::floatfield)
      scientific			setf(ios_base::scientific,
    				   ios_base::floatfield)
      resetiosflags
       (ios_base::fmtflags flag)	setf(0,flag)
      setiosflags
      (ios_base::fmtflags flag)	setf(flag)
      setbase(int base)		See above
      setfill(char_type c)		fill(c)
      setprecision(int n)		precision(n)
      setw(int n)			width(n)
      endl
      ends
      flush				flush( )

    DESCRIPTION

      showpos   Generates a	+ sign in non-negative generated numeric output.

      showbase   Generates a prefix	indicating the numeric base of generated
    	     integer output.

      uppercase   Replaces certain lowercase letters with their uppercase
    	      equivalents in generated output.

      showpoint   Generates	a decimal-point	character unconditionally in
                  generated floating-point output.

      boolalpha   Insert and extract bool type in alphabetic format.

      unitbuf   Flushes output after each output operation.

      internal   Adds fill characters at a designated internal point in
                 certain generated output, or identical to right if	no
                 such	point is designated.

      left	 Adds fill characters on the right (final positions) of	certain
             generated	output.

      right	  Adds fill characters on the left (initial positions) of
              certain generated output.

      dec	Converts integer input or generates integer output in decimal
            base.

      hex	Converts integer input or generates integer output in hexadecimal
    	base.

      oct	Converts integer input or generates integer output in octal base.

      fixed	  Generates floating-point output in fixed-point notation.

      scientific   Generates floating-point	output in scientific notation.

      resetiosflagss

      (ios_base::fmtflags flag)   Resets the fmtflags field	flag.

      setiosflags

      (ios_base::fmtflags flag)   Sets up the flag flag.

      setbase(int base)   Converts integer input or	generates integer
                          output in base base. The parameter base can
                          be 8, 10 or 16.

      setfill(char_type c)	 Sets the character used to pad	(fill) an output
    			 conversion to the specified field width.

      setprecision(int n)	Set the	precision (number of digits after the
                            decimal point) to generate on certain output
                            conversions.

      setw(int n)	Sets the field with (number of characters) to generate on
    		certain	output conversions

      endl	 Inserts a newline character into the output sequence and flush
        	 the output	buffer.

      ends	 Inserts a null	character into the output sequence.

      flush	  Flush	the output buffer.

    DEFAULT	VALUES

      precision()		 6
      width()		 0
      fill()		 the space character
      flags()		 skipws	| dec
      getloc()		 locale::locale()

    EXAMPLES

      //
      // cout example one
      //
      #include<iostream>
      #include<iomanip>

      void main ( )
      {
       using namespace std;

       int i;
       float f;

        // read an integer and a float from	stdin
       cin >> i >> f;

        // output the integer and goes at the line
       cout	<< i <<	endl;

        // output the float	and goes at the	line
       cout	<< f <<	endl;

        // output i	in hexa
       cout	<< hex << i << endl;

        // output i	in octal and then in decimal
       cout	<< oct << i << dec << i	<< endl;

        // output i	preceded by its	sign
       cout	<< showpos << i	<< endl;

        // output i	in hexa
       cout	<< setbase(16) << i << endl;

        // output i	in dec and pad to the left with	character
        // @ until a width of 20
        // if you input 45 it outputs 45@@@@@@@@@@@@@@@@@@
       cout	<< setfill('@')	<< setw(20) << left << dec << i;
       cout	<< endl;

        // output the same result as the code just above
        // but uses	member functions rather	than manipulators
       cout.fill('@');
       cout.width(20);
       cout.setf(ios_base::left, ios_base::adjustfield);
       cout.setf(ios_base::dec, ios_base::basefield);
       cout	<< i <<	endl;

        // outputs f in scientific notation	with
        // a precision of 10 digits
       cout	<< scientific << setprecision(10) << f << endl;

        // change the precision to 6 digits
        // equivalents to cout << setprecision(6);
       cout.precision(6);

        // output f	and goes back to fixed notation
       cout	<< f <<	fixed << endl;

      }

      //
      // cout example two
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       char	p[50];

       cin.getline(p,50);

       cout	<< p;
      }

      //
      // cout example three
      //
      #include <iostream>
      #include <fstream>

      void main ( )
      {
       using namespace std;

        // open the	file "file_name.txt"
        // for reading
       ifstream in("file_name.txt");

        // output the all file to stdout
       if (	in )
         cout << in.rdbuf();
       else
          {
           cout << "Error while opening the	file";
           cout << endl;
          }
      }

    WARNINGS

      Keep in mind that the	manipulator endl flushes the stream buffer.
      Therefore it is	recommended to use '0 if your only intent is
      to	go at the line.	It will greatly improve performance when
      C and C++ streams are not synchronized.

    SEE ALSO

      basic_ostream, iostream, basic_filebuf,
      cin,	cerr, clog, wcin, wcout,
      wcerr, wclog, iomanip

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.3.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ctype
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      ctype, ctype<char> - A facet that provides character classification
      facilities.	(The description for ctype<char>, a specialization of
      ctype, follows the ctype description.)

    SYNOPSIS

      #include <locale>
      class	ctype_base;
      template <class charT> class ctype;

    SPECIALIZATION

      class	ctype<char>;

    DESCRIPTION

      ctype<charT>	is the character classification	facet.	This facet
      provides facilities for classifying characters	and performing
      simple conversions. ctype<charT>	provides conversions for upper
      to lower	and lower to upper case.	 The facet also
      provides conversions between charT, and	char. ctype<charT>
      relies on ctype_base for a set of masks	that identify the
      various classes of characters.  These	classes	are:

      space

      print

      cntrl

      upper

      lower

      alpha

      digit

      punct

      xdigit

      alnum

      graph

      The masks are	passed to member functions of ctype in order to	obtain
      verify the classifications of a character or	range of characters.

    INTERFACE

      class	ctype_base {
      public:
       enum	mask {
         space, print, cntrl, upper, lower,
         alpha, digit, punct, xdigit,
         alnum=alpha|digit,	graph=alnum|punct
        };
      };

      template <class charT>
      class	ctype :	public locale::facet, public ctype_base	{
       public:
         typedef charT char_type;
         explicit ctype(size_t);
         bool	  is(mask, charT) const;
         const charT* is(const charT*,
    		     const charT*, mask*) const;
         const charT* scan_is(mask,
    			  const	charT*,
    			  const	charT*)	const;
         const charT* scan_not(mask,
    			   const charT*,
    			   const charT*) const;
         charT	  toupper(charT) const;
         const charT* toupper(charT*, const	charT*)	const;
         charT	  tolower(charT) const;
         const charT* tolower(charT*, const	charT*)	const;
         charT	  widen(char) const;
         const char*  widen(const char*,
    		      const char*, charT*) const;
         char	  narrow(charT,	char) const;
         const charT* narrow(const charT*, const charT*,
    			 char, char*) const;
         static locale::id id;

       protected:
           ~ctype();  // virtual
         virtual bool	  do_is(mask, charT) const;
         virtual const charT* do_is(const charT*,
    				const charT*,
    				mask*) const;
         virtual const charT* do_scan_is(mask,
    				     const charT*,
    				     const charT*) const;
         virtual const charT* do_scan_not(mask,
    				      const charT*,
    				      const charT*) const;
         virtual charT	  do_toupper(charT) const;
         virtual const charT* do_toupper(charT*,
    				     const charT*) const;
         virtual charT	  do_tolower(charT) const;
         virtual const charT* do_tolower(charT*,
    				     const charT*) const;
         virtual charT	  do_widen(char) const;
         virtual const char*  do_widen(const char*,
    				   const char*,
    				   charT*) const;
         virtual char	  do_narrow(charT, char) const;
         virtual const charT* do_narrow(const charT*,
    				    const charT*,
    				    char, char*) const;
      };

    TYPE

      char_type
         Type of character the facet is instantiated on.

    CONSTRUCTOR AND	DESTRUCTOR

      explicit ctype(size_t	refs = 0)
         Construct a ctype facet.  If the refs argument is 0 then
         destruction of the object	is delegated to	the locale, or
         locales,	containing it. This allows the	user to	ignore
         lifetime	management issues.  On the other had, if	refs
         is 1 then	the object must	be explicitly deleted; the locale will
         not do so.  In this case, the	object can be maintained
         across	the lifetime of multiple locales.

      ~ctype();  //	virtual	and protected
         Destroy the facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the ctype facet	provide	an interface to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	public widen function
      simply calls its protected cousin do_widen.

      bool
      is(mask m, charT c) const;
      const	charT*

      is(const charT* low,
        const charT* high, mask* vec) const;
         Returns do_is(m,c)	or do_is(low,high,vec).

      char
      narrow(charT c, char dfault) const;
      const	charT*
      narrow(const charT* low, const charT*, char dfault,
    	char* to) const;
         Returns do_narrow(c,dfault) or do_narrow(low,high,dfault,to).

      const	charT*
      scan_is(mask m, const	charT*,	const charT* high) const;
         Returns do_scan_is(m,low,high).

      const	charT*
      scan_not(mask	m, const charT*	low, const charT* high)	const;
         Returns do_scan_not(m,low,high).

      charT
      tolower(charT	c) const;
      const	charT*
      tolower(charT* low, const charT* high) const;
         Returns do_tolower(c) or do_tolower(low,high).

      charT
      toupper(charT) const;
      const	charT*
      toupper(charT* low, const charT* high) const;
         Returns do_toupper(c) or do_toupper(low,high).

      charT
      widen(char c)	const;
      const	char*
      widen(const char* low, const char* high, charT* to) const;
         Returns do_widen(c) or do_widen(low,high,to).

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PROTECTED MEMBER FUNCTIONS

      virtual bool
      do_is(mask m,	charT c) const;
         Returns true if c matches the classification indicated by the
         mask	m, where m is	one of the values available from
         ctype_base.  For instance, the following call	returns	true
         since 'a' is an alphabetic	character:

           ctype<char>().is(ctype_base::alpha,'a');

         See ctype_base  for a description of the masks.

      virtual const	charT*
      do_is(const charT* low, const	charT* high,
           mask* vec) const;
         Fills vec with every mask from ctype_base that applies to the
         range of characters	indicated by [low,high).   See
         ctype_base  for a description of	the masks.  For	instance,
         after	the following call v would contain {alpha, lower,
         print,alnum	,graph}:

           char a[]	= "abcde";
           ctype_base::mask	v[12];
           ctype<char>().is(a,a+5,v);

         This function returns high.

      virtual char
      do_narrow(charT, char	dfault)	const;
         Returns the appropriate char representation for c,	if such
         exists.	 Otherwise do_narrow returns dfault.

      virtual const	charT*
      do_narrow(const charT* low, const charT* high,
    	   char	dfault,	char* dest) const;
         Converts each character in	the range [low,high) to	its char
         representation, if such exists.  If a char representation is
         not available then the character will	be converted to
         dfault.	Returns	high.

      virtual const	charT*
      do_scan_is(mask m, const charT* low, const charT* high) const;
         Finds the first character in the range [low,high) that matches
         the	classification	indicated by the mask m.

      virtual const	charT*
      do_scan_not(mask m, const charT* low,	const charT* high) const;
         Finds the first character in the range [low,high) that does not
         match the classification	indicated by the mask m.

      virtual charT
      do_tolower(charT) const;
         Returns the lower case representation of c, if such exists,
         otherwise returns c;

      virtual const	charT*
      do_tolower(charT* low, const charT* high) const;
         Converts each character in	the range [low,high) to	its lower case
         representation, if	such exists.  If a lower case representation
         does not exist then	the character is not changed.  Returns
         high.

      virtual charT
      do_toupper(charT c) const;
         Returns the upper case representation of c, if such exists,
         otherwise returns c;

      virtual const	charT*
      do_toupper(charT* low, const charT* high) const;
         Converts each character in	the range [low,high) to	its upper case
         representation, if	such exists.  If an upper case representation
         does not exist then the	character is not changed.  Returns
         high.

      virtual charT
      do_widen(char	c) const;
         Returns the appropriate charT representation for c.

      virtual const	char*
      do_widen(const char* low, const char*	high,charT* dest) const;
         Converts each character in	the range [low,high) to	its charT
         representation. Returns high.

    EXAMPLE

      //
      // ctype.cpp
      //

      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;
       string s1("blues Power");

        // Get a reference to the ctype<char> facet
       const ctype<char>& ct =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
           use_facet<ctype<char> >(loc);
      #else
           use_facet(loc,(ctype<char>*)0);
      #endif

        // Check the classification	of the 'a' character
       cout	<< ct.is(ctype_base::alpha,'a')	<< endl;
       cout	<< ct.is(ctype_base::punct,'a')	<< endl;

        // Scan for	the first upper	case character
       cout	<< (char)*(ct.scan_is(ctype_base::upper,
    			   s1.begin(),s1.end())) << endl;

        // Convert characters to upper case
       ct.toupper(s1.begin(),s1.end());
       cout	<< s1 << endl;

       return 0;
      }

    SEE ALSO

      locale, facets, collate, ctype<char>,	ctype_byname

    NAME

      ctype<char> -	A specialization of the	ctype facet.

    SYNOPSIS

      #include <locale>

      class	ctype<char>;

    DESCRIPTION

      This specialization of the ctype<charT>  template provides inline
      versions of ctype's member functions.	The facet provides the same
      public interface, and uses the same set	of masks, as the ctype
      template.

    INTERFACE

      template <>
      class	ctype<char> : public locale::facet, public ctype_base {
       public:
         typedef char char_type;
         explicit ctype(const mask*	= 0, bool = false,
    		    size_t = 0);
         bool	  is(mask, char) const;
         const charT* is(const char*,
    		     const char*, mask*) const;
         const charT* scan_is(mask,
    			  const	char*,
    			  const	char*) const;
         const charT* scan_not(mask,
    			   const char*,
    			   const char*)	const;
         charT	  toupper(char)	const;
         const charT* toupper(char*, const charT*) const;
         charT	  tolower(char)	const;
         const charT* tolower(char*, const char*) const;
         charT	  widen(char) const;
         const char*  widen(const char*,
    		      const char*, char*) const;
         char	  narrow(char, char) const;
         const charT* narrow(const char*, const char*,
    			 char, char*) const;
         static locale::id id;
         static const size_t table_size = 256;

       protected:
         const mask* table() const throw();
         static const mask*	classic_table()	throw();

      ~ctype();  //	virtual
         virtual charT	  do_toupper(charT) const;
         virtual const charT* do_toupper(charT*,
    				     const charT*) const;
         virtual charT	  do_tolower(charT) const;
         virtual const charT* do_tolower(charT*,
    				     const charT*) const;
      };

    TYPE

      char_type
         Type of character the facet is instantiated on.

    CONSTRUCTORS AND DESTRUCTORS

      explicit ctype(const mask* tbl = 0, bool del = false,
    		size_t refs = 0)
         Construct a ctype facet. The three	parameters set up the
         following	conditions:

         +	     The tbl argument must be either 0 or an array of at least
    	  table_size elements.	 If tbl	is non zero then the supplied
              table will be used for character classification.

         +	     If	tbl is non zero, and del is true then the tbl array will
              be deleted by the destructor, so	the calling program need
              not concern itself with the lifetime of the facet.

         +	     If	the refs argument is 0 then destruction	of the object
              itself is delegated to the locale, or locales, containing it.
              This allows the user to ignore lifetime management issues.  On
              the other had, if refs  is 1	then the object	must be	explicitly
              deleted; the locale will not do so.  In this case,	the object
              can be maintained across the lifetime of multiple locales.

      ~ctype();  //	virtual	and protected
         Destroy the facet.	 If the	constructor was	called with a non-zero
         tbl argumentand a true	del argument, then the array supplied
         by the tbl argument will be deleted

    PUBLIC MEMBER FUNCTIONS

      The public members of	the ctype<char>	facet specialization do	not
      all	serve the same purpose as the functions in the template.  In
      many cases these functions implement functionality, rather than just
      forwarding a call	to a protected implementation function.

      static const mask*
      classic_table() throw();
         Returns a pointer to a table_size character array that represents
         the classifications of	characters in the "C" locale.

      bool
      is(mask m, charT c) const;
         Determines	if the character c has the classification indicated by
         the mask  m.  Returns table()[(unsigned char)c]  &  m.

      const	charT*
      is(const charT* low,
        const charT* high, mask* vec) const;
         Fills vec with every mask from ctype_base that applies to the
         range of characters	indicated by [low,high).   See
         ctype_base  for a description of	the masks.  For	instance,
         after	the following call v would contain {alpha, lower,
         print,,alnum ,graph}:

           char a[]	= "abcde";
           ctype_base::mask	v[12];
           ctype<char>().do_is(a,a+5,v);

         This function returns high.

      char
      narrow(charT c, char dfault) const;
         Returns  c.

      const	charT*
      narrow(const charT* low, const charT*, char dfault,
    	char* to) const;
         Performs ::memcpy(to,low,high-low).  Returns high.

      const	charT*
      scan_is(mask m, const	charT*,	const charT* high) const;
         Finds the first character in the range [low,high) that matches
         the	classification	indicated by the mask m. The
         classification is matched by checking for table()[(unsigned char)
         p] & m, where	p is in	the range [low,high).  Returns the
         first p that matches, or high if none do.

      const	charT*
      scan_not(mask	m, const charT*	low, const charT* high)	const;
         Finds the first character in the range [low,high) that does not
         match the classification	indicated by the mask m.   The
         classification is matched by	checking for
         !(table()[(unsigned char) p] & m),	where p	is in the range
         [low,high).  Returns the	first p	that matches, or high if none
         do.

      const	mask*
      table() const	throw();
         If	the tbl	argument that was passed to the	constructor was
         non-zero, then this function	returns	that argument,
         otherwise it returns classic_table().

      charT
      tolower(charT	c) const;
      const	charT*
      tolower(charT* low, const charT* high) const;
         Returns do_tolower(c) or do_tolower(low,high).

      charT
      toupper(charT) const;
      const	charT*
      toupper(charT* low, const charT* high) const;
         Returns do_toupper(c) or do_toupper(low,high).

      charT
      widen(char c)	const;
         Returns c.

      const	char*
      widen(const char* low, const char* high, charT* to) const;
         Performs ::memcpy(to,low,high-low.	Returns	high.

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PROTECTED MEMBER FUNCTIONS

      virtual charT
      do_tolower(charT) const;
         Returns the lower case representation of c, if such exists,
         otherwise returns c;

      virtual const	charT*
      do_tolower(charT* low, const charT* high) const;
         Converts each character in	the range [low,high) to	its lower case
         representation, if	such exists.  If a lower case representation
         does not exist then	the character is not changed.  Returns
         high.

      virtual charT
      do_toupper(charT c) const;
         Returns the upper case representation of c, if such exists,
         otherwise returns c;

      virtual const	charT*
      do_toupper(charT* low, const charT* high) const;
         Converts each character in	the range [low,high) to	its upper case
         representation, if	such exists.  If an upper case representation
         does not exist then the	character is not changed.  Returns
         high.

    SEE ALSO

      locale, facets, collate, ctype<char>,	ctype_byname

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    filebuf
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_filebuf,filebuf

      This page describes the ANSI basic_filebuf class.  If	you would like
      information on the	pre-ANSI filebuf class,	use the	command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_filebuf
      : public basic_streambuf<charT, traits>

    DESCRIPTION

      The template class basic_filebuf is derived from basic_streambuf.
      It	associates the input or output sequence with a file. Each
      object of type basic_filebuf<charT, traits> controls	two character
      sequences:

      +	  a character input sequence

      +	  a character output sequence

      The restrictions on reading  and writing a sequence controlled by an
      object of class basic_filebuf<charT,traits> are the same as for
      reading and writing with the Standard	C library files.

      If the file is not open for reading the input	sequence cannot	be
      read. If the file is not open for writing the output sequence cannot
      be written. A joint	file position is maintained for	both the input
      and output sequences.

      A file provides byte sequences. So the basic_filebuf	class treats a
      file as the external source (or sink) byte	sequence. In order to
      provide the contents of a	file as	wide character sequences, a
      wide-oriented file buffer called wfilebuf converts wide
      character sequences to multibytes character sequences (and vice
      versa) according to the current locale being used	in the stream
      buffer.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_filebuf
      : public basic_streambuf<charT, traits> {

      public:

       typedef traits			traits_type;
       typedef charT			char_type;
       typedef typename traits::int_type	int_type;
       typedef typename traits::pos_type	pos_type;
       typedef typename traits::off_type	off_type;

       basic_filebuf();
       basic_filebuf(int fd);

       virtual ~basic_filebuf();

       bool	is_open() const;

       basic_filebuf<charT,	traits>* open(const char *s,
    				      ios_base::openmode,
    				      long protection =	0666);

       basic_filebuf<charT,	traits>* open(int fd);

       basic_filebuf<charT,	traits>* close();

      protected:

       virtual int	    showmanyc();

       virtual int_type overflow(int_type c	= traits::eof());

       virtual int_type pbackfail(int_type c = traits::eof());

       virtual int_type underflow();

       virtual basic_streambuf<charT,traits>*
         setbuf(char_type *s,streamsize n);

       virtual pos_type seekoff(off_type off,
    			    ios_base::seekdir way,
    			    ios_base::openmode which =
    			    ios_base::in | ios_base::out);

       virtual pos_type seekpos(pos_type sp,
    			    ios_base::openmode which =
    			    ios_base::in | ios_base::out);

       virtual int sync();

       virtual streamsize xsputn(const char_type* s, streamsize n);

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      filebuf
         The type filebuf is an instantiation of class basic_filebuf on type
         char:

           typedef basic_filebuf<char> filebuf;

      int_type
         The type int_type is a synonym of type traits::in_type.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wfilebuf
         The type wfilebuf is an instantiation of class basic_filebuf on type
         wchar_t:

           typedef basic_filebuf<wchar_t> wfilebuf;

    CONSTRUCTORS

      basic_filebuf();
         Constructs	an object of class basic_filebuf<charT,traits>,
         initializing the base class with basic_streambuf<charT,traits>().

      basic_filebuf(int fd);
         Constructs	an object of class basic_filebuf<charT,traits>,
         initializing the base class with basic_streambuf<charT,traits>(),
         then calls open(fd). This function is	not described in the
         C++ standard, and is provided as an extension in order to
         manipulate pipes, sockets or other UNIX devices, that	can be
         accessed	through	file descriptors.

    DESTRUCTOR

      virtual ~basic_filebuf();
         Calls close() and destroys	the object.

    MEMBER FUNCTIONS

      basic_filebuf<charT,traits>*
      close();
         If	is_open() == false, returns a null pointer. Otherwise, closes the
         file, and returns *this.

      bool
      is_open() const;
         Returns true if the associated file is open.

      basic_filebuf<charT,traits>*
      open(const char* s, ios_base::openmode mode, long protection = 0666);
         If	is_open() == true, returns a null pointer.  Otherwise opens
         the	file, whose name	is stored in the
         null-terminated byte-string s.	 The file open modes	are
         given by their C-equivalent	description (see the C func-
         tion fopen):

         in			     "w"
         in|binary		     "rb"
         out		     "w"
         out|app		     "a"
         out|binary		     "wb"
         out|binary|app	     "ab"
         out|in		     "r+"
         out|in|app		     "a+"
         out|in|binary	     "r+b"
         out|in|binary|app	     "a+b"
         trunc|out		     "w"
         trunc|out|binary	     "wb"
         trunc|out|in	     "w+"
         trunc|out|in|binary     "w+b"

         The third argument, protection, is	used as	the file permission.
         It	does not appear	in the Standard	C++ description	of the
         function	open and is provided as an extension. It determines
         the file read/write/execute permissions under UNIX.  It is more
         limited under DOS	since files are always readable and do not
         have special execute permission. If the	open function fails,
         it	returns	a null pointer.

      basic_filebuf<charT,traits>*
      open(int fd);
         Attaches the file previously opened and identified	by its file
         descriptor fd, to	the basic_filebuf object. This
         function	is not described in the C++ standard, and is provided
         as an extension in order	to manipulate pipes, sockets or other
         UNIX devices, that	can be accessed	through	file descriptors.

      int_type
      overflow(int_type c =	traits::eof() );
         If	the output sequence has	a put position available, and c	is not
         traits::eof(), then write c into it. If there is no position
         available, the function output the content of	the buffer to
         the associated file and then write	c at the new current put
         position. If the operation fails, the function returns
         traits::eof(). Otherwise it returns traits::not_eof(c). In wide
         characters file buffer, overflow converts the internal wide
         characters to their external multibytes representation by	using
         the locale::codecvt facet	located	in the locale object imbued in
         the stream buffer.

      int_type
      pbackfail(int_type c = traits::eof() );
         Puts back the character designated	by c into the input sequence.
         If traits::eq_int_type(c,traits::eof()) returns true,	move
         the input sequence one position backward. If	the operation
         fails, the function returns traits::eof(). Otherwise it returns
         traits::not_eof(c).

      pos_type
      seekoff(off_type off,	ios_base::seekdir way,	  ios_base::openmode
      which = ios_base::in | ios_base::out);
         If	the open mode is in | out, alters the stream position of both
         the input and the output sequence. If the open	mode is	in,
         alters the stream position of only the input	sequence, and
         if it is out, alters the stream position of only the output
         sequence. The new position is calculated by combining the two
         parameters off (displacement) and way (reference point). If
         the current position of	the sequence is	invalid	before repo-
         sitioning,	the operation fails and	the return value is
         pos_type(off_type(-1)). Otherwise the function returns the
         current	new position. File buffers using locale::codecvt facet
         performing state dependent conversion, only	support
         seeking	to the beginning of the	file, to	the current
         position, or to a position previously obtained by a	call
         to	one of the iostreams seeking functions.

      pos_type
      seekpos(pos_type sp,ios_base::openmode      which = ios_base::in |
      ios_base::out);
         If	the open mode is in | out, alters the stream position of both
         the input and the output sequence. If the open	mode is	in,
         alters the stream position of only the input	sequence, and
         if it is out, alters the stream position of only the output
         sequence. If the current position of the sequence is invalid
         before	repositioning, the operation fails and the return
         value is pos_type(off_type(-1)). Otherwise the function returns
         the current new position. File buffers using locale::codecvt
         facet	performing state dependent conversion, only support
         seeking to the beginning of the file, to the current position,
         or to a	position previously obtained by a call	to one of the
         iostreams	seeking	functions.

      basic_filebuf<charT,traits>*
      setbuf(char_type*s, streamsize n);
         If	s is not a null	pointer, output	the content of the current
         buffer to the associated file, then delete the current buffer and
         replace it	by s. Otherwise resize the current buffer to size n
         after outputting its	content to the associated file if
         necessary.

      int
      sync();
         Synchronizes the content of the external file, with its image
         maintained in	memory by the file buffer. If the function
         fails, it returns -1, otherwise it returns 0.

      int_type
      underflow();
         If	the input sequence has a read position available, returns the
         content of	this position. Otherwise fills up the buffer by
         reading	characters from the associated file and if it
         succeeds, returns the content of the new current position. The
         function	returns	traits::eof() to indicate failure. In wide
         characters file buffer, underflow	converts the external
         mutltibytes characters to their wide character representation by
         using the locale::codecvt facet located in the locale object
         imbued in the stream buffer.

      streamsize
      xsputn(const char_type* s, streamsize	n);
         Writes up to n characters to the output sequence. The characters
         written are obtained from successive elements of the array	whose
         first element is	designated by s. The function returns the
         number of characters written.

    EXAMPLES

      //
      // stdlib/examples/manual/filebuf.cpp
      //
      #include<iostream>
      #include<fstream>
      void main ( )
      {
       using namespace std;
        // create a	read/write file-stream object on tiny char
        // and attach it to	the file "filebuf.out"
       ofstream out("filebuf.out",ios_base::in |	       ios_base::out);
        // tie the istream object to the ofstream object
       istream in(out.rdbuf());
        // output to out
       out << "Il errait comme un ame en peine";
        // seek to the beginning of	the file
       in.seekg(0);
        // output in to the	standard output
       cout	<< in.rdbuf() << endl;
        // close the file "filebuf.out"
       out.close();
        // open the	existing file "filebuf.out"
        // and truncate it
       out.open("filebuf.out",ios_base::in |       ios_base::out |
       ios_base::trunc);
        // set the buffer size
       out.rdbuf()->pubsetbuf(0,4096);
        // open the	source code file
       ifstream ins("filebuf.cpp");
        //output it	to filebuf.out
       out << ins.rdbuf();
        // seek to the beginning of	the file
       out.seekp(0);
        // output the all file to the standard output
       cout	<< out.rdbuf();
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_ifstream, basic_ofstream,
      basic_fstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.8.1.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    fpos
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      fpos

    SYNOPSIS

      #include <rw/iotraits>
      template<class stateT	= mbstate_t>
      class	fpos

    DESCRIPTION

      The template class fpos<stateT> is used by the iostream classes to
      maintain positioning information. It maintains	three kinds of
      information:  the absolute position, the conversion state and the
      validity of the stored position. Streams instantiated on tiny
      characters use	streampos as their positioning type, whereas
      streams instantiated on wide characters use wstreampos, but both are
      defined as fpos<mbstate_t>.

    INTERFACE

      template <class stateT = mbstate_t>
      class	fpos {

      public:

       typedef stateT  state_type;

       fpos(long off = 0);
       fpos(state_type);

       state_type	state(state_type);
       state_type	state () const;

      };

    TYPES

      state_type
         The type state_type holds the conversion state, and is compatible
         with the function locale::codecvt(). By	default	it is defined
         as mbstate_t.

    PUBLIC CONSTRUCTORS

      fpos(long off	=0);
         Constructs	an fpos	object,	initializing its position with off and
         its conversion	state with the default stateT constructor.
         This	function is not described in the C++ standard.

      fpos(state_type st);
         Construct an fpos object, initializing its	conversion state with
         st, its position with the start position, and its status to good.

    PUBLIC MEMBER FUNCTIONS

      state_type
      state() const;
         Returns the conversion state stored in the	fpos object.

      state_type
      state(state_type st);
         Store st as the new conversion state in the fpos object and
         return	its previous value.

    VALID OPERATIONS

      In the following,

      +	  P refers to type fpos<stateT>

      +	  p and	q refer	to an value of type fpos<stateT>

      +	  O refers to the offset type (	streamoff, wstreamoff, long _)

      +	  o refers to a	value of the offset type

      +	  i refers to a	value of type int

      Valid	operations:

      P p( i );    Constructs from int.

      P p =	i;   Assigns from int.

      P( o )   Converts from offset.

      O( p )   Converts to offset.

      p == q   Tests for equality.

      p != q   Tests for inequality.

      q = p	+ o   Adds offset.

      p += o   Adds	offset.

      q = p	-o   Subtracts offset.

      q -= o   Subtracts offset.

      o = p	- q   Returns offset.

    SEE ALSO

      iosfwd, char_traits

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.4.

      Amendment 1 to the C Standard.

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    fstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_fstream,fstream,ofstream

      This page describes the ANSI basic_fstream class.  If	you would like
      information on the	pre-ANSI fstream class,	use the	command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_fstream
      : public basic_iostream<charT, traits>

    DESCRIPTION

      The template class basic_fstream<charT,traits> supports reading and
      writing to named files or other devices associated with a file
      descriptor. It	uses a basic_filebuf object to control the
      associated sequences. It inherits from basic_iostream and can
      therefore	use all	the formatted and unformatted input	and
      output functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_fstream
      : public basic_iostream<charT, traits> {

      public:

       typedef basic_ios<charT, traits>   ios_type;

       typedef charT		       char_type;
       typedef traits		       traits_type;
       typedef typename traits::int_type  int_type;
       typedef typename traits::pos_type  pos_type;
       typedef typename traits::off_type  off_type;

       basic_fstream();

       explicit basic_fstream(const	char *s, ios_base::openmode
    			  mode = ios_base::in |	ios_base::out,
    			  long protection = 0666);

       explicit basic_fstream(int fd);

       basic_fstream(int fd, char_type *buf, int len);

       virtual ~basic_fstream();

       basic_filebuf<charT,	traits>	*rdbuf() const;

       bool	is_open();

       void	open(const char	*s, ios_base::openmode mode =
    	     ios_base::in | ios_base::out,
    	     long protection = 0666);

       void	close();

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      fstream
         The type fstream is an instantiation of class basic_fstream on type
         char:

           typedef basic_fstream<char> fstream;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

      wfstream
         The type wfstream is an instantiation of class basic_fstream  on
         type wchar_t:

           typedef basic_fstream<wchar_t> wfstream;

    CONSTRUCTORS

      basic_fstream();
         Constructs	an object of class basic_fstream<charT,traits>,
         initializing the base class basic_iostream with	the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). After construction,
         a file can be attached to the basic_ftream object by using the
         open() member function.

      basic_fstream(const char* s,
    	       ios_base::openmode mode=
    	       ios_base::in | iosw_base::out,
    	       long protection=	0666);
        Constructs an	object of class	basic_fstream<charT,traits>,
        initializing the base	class basic_iostream with the associ-
        ated file buffer, which is initialized by calling the
        basic_filebuf	constructor basic_filebuf<charT,traits>().
        The constructor then calls the open function
        open(s,mode,protection) in order to attach the file, whose
        name is pointed at by	s, to the basic_ftream object. The
        third	argument, protection, is used as the file permission.
        It does not appear in	the Standard C++ description and is
        provided as an extension. It determines the file
        read/write/execute permissions under UNIX.  It is more lim-
        ited under DOS since files are always	readable and do	not
        have special execute permission.

      explicit basic_fstream(int fd);
         Constructs	an object of class basic_fstream<charT,traits>,
         initializing the base class basic_iostream with	the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_ftream object. This
         constructor	is not described in the C++ standard, and
         is provided as an extension in order to	manipulate pipes,
         sockets or other UNIX	devices, that can be accessed through
         file descriptors. If the function fails, it sets
         ios_base::failbit.

      basic_fstream(int fd,	char_type* buf,int len);
         Constructs	an object of class basic_fstream<charT,traits>,
         initializing the base class basic_iostream with	the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_ftream object. The
         underlying buffer is	then replaced by calling the
         basic_filebuf member function, setbuf(), with parameters	buf
         and	len. This constructor is not described in the C++
         standard, and is provided as an extension in order	to manipulate
         pipes, sockets, or other UNIX devices that can be	accessed
         through file descriptors. It also maintains compatibility with
         the old iostreams library. If the function fails, it	sets
         ios_base::failbit.

    DESTRUCTOR

      virtual ~basic_fstream();
         Destroys an object	of class basic_fstream.

    MEMBER FUNCTIONS

      void
      close();
         Calls the associated basic_filebuf	function close() and if	this
         function fails, it calls the basic_ios member function
         setstate(failbit).

      bool
      is_open();
         Calls the associated basic_filebuf	function is_open() and return
         its result.

      void
      open(const char* s,ios_base::openmode	=
          ios_base::out | ios_base::in,
          long protection =	0666);
          Calls the associated basic_filebuf function open(s,mode,protection)
          and, if this function fails at	opening	the file, calls	the basic_ios
          member	function setstate(failbit). The	third argument protection is
          used as the file permissions. It does not appear in the Standard C++
          description and is provided as	an extension. It determines the	file
          read/write/execute permissions	under UNIX. It is more limited under
          DOS since files are always readable and do not	have special execute
          permission.

      basic_filebuf<charT,traits>*
      rdbuf() const;
         Returns a pointer to the basic_filebuf associated with the	stream.

    EXAMPLES

      //
      // stdlib/examples/manual/fstream.cpp
      //
      #include<iostream>
      #include<bidirec>
      void main ( )
      {
         using namespace std;

          // create	a bi-directional fstream object
         fstream inout("fstream.out");

          // output	characters
         inout << "Das ist die rede	von einem man" << endl;
         inout << "C'est l'histoire	d'un home" << endl;
         inout << "This is the story of a man" << endl;

         char p[100];

          // seek back to the beginning of the file
         inout.seekg(0);

          // extract the first line
         inout.getline(p,100);

          // output	the first line to stdout
         cout << endl << "Deutch :"	<< endl;
         cout << p;

         fstream::pos_type pos = inout.tellg();

          // extract the seconf line
         inout.getline(p,100);

          // output	the second line	to stdout
         cout << endl << "Francais :" << endl;
         cout << p;

          // extract the third line
         inout.getline(p,100);

          // output	the third line to stdout
         cout << endl << "English :" << endl;
         cout << p;

          // move the put sequence before the second line
         inout.seekp(pos);

          // replace the second line
         inout << "This is the story of a man" << endl;

          // replace the third line
         inout << "C'est l'histoire	d'un home";

          // seek to the beginning of the file
         inout.seekg(0);

          // output	the all	content	of the fstream object to stdout
         cout << endl << endl << inout.rdbuf();
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_filebuf, basic_ifstream, basic_ofstream

      Working Paper	for Draft Proposed International Standard for Information
      Systems--Programming Language	C++, Section 27.8.1.11

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ifstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ifstream,fstream

      This page describes the ANSI basic_ifstream class.  If you would
      like information on the pre-ANSI ifstream class, use the command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ifstream
      : public basic_istream<charT,	traits>

    DESCRIPTION

      The template class basic_ifstream<charT,traits> supports reading
      from	named files	or other devices associated with a file
      descriptor. It uses a basic_filebuf	object to control the
      associated sequences.  It	inherits from basic_istream	and
      can	therefore use all the formatted	and unformatted	input
      functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ifstream
      : public basic_istream<charT,	traits>	{

      public:

       typedef basic_ios<charT, traits>    ios_type;

       typedef traits		       traits_type;
       typedef charT		       char_type;
       typedef typename traits::int_type   int_type;
       typedef typename traits::pos_type   pos_type;
       typedef typename traits::off_type   off_type;

       basic_ifstream();

       explicit basic_ifstream(const char *s,
    			   ios_base::openmode mode =
    			   ios_base::in,
    			   long	protection = 0666);

       explicit basic_ifstream(int fd);

       basic_ifstream(int fd, char_type* buf, int len);

       virtual ~basic_ifstream();

       basic_filebuf<charT,	traits>	*rdbuf() const;

       bool	is_open();

       void	open(const char	*s, ios_base::openmode mode =
    	     ios_base::in, long	protection = 0666);

       void	close();

      };

    TYPES

      char_type

      The type char_type	is a synonym for the template parameter	charT.

      ifstream
         The type ifstream is an instantiation of class basic_ifstream on
         type char:

           typedef basic_ifstream<char> ifstream;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

      wifstream
         The type wifstream	is an instantiation of class basic_ifstream on
         type wchar_t:

           typedef basic_ifstream<wchar_t> wifstream;

    CONSTRUCTORS

      basic_ifstream();
         Constructs	an object of class basic_ifstream<charT,traits>,
         initializing the base class basic_istream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). After construction,
         a file can be attached to the basic_iftream object by using the
         open member function.

      basic_ifstream(const char* s,
    		ios_base::openmode mode= ios_base::in,
    		long protection= 0666);
    	Constructs an object	of class
    	basic_ifstream<charT,traits>, initializing the base class
    	basic_istream with the associated file buffer, which	is
    	initialized by calling the basic_filebuf constructor
    	basic_filebuf<charT,traits>(). The constructor then calls
    	the open function open(s,mode,protection) in	order to
    	attach the file whose name is pointed at by s, to the
    	basic_iftream object. The third argument protection pro-
    	vides file permissions. It does not appear in the Standard
    	C++ description and is provided as an extension. It deter-
    	mines the file read/write/execute permissions under UNIX.
    	It is more limited under DOS	since files are	always read-
    	able	and do not have	special	execute	permission.

      explicit basic_ifstream(int fd);
         Constructs	an object of class basic_ifstream<charT,traits>,
         initializing the base class basic_istream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_iftream	object.	This
         constructor is not described in the C++ standard, and	is
         provided as an extension in order to	manipulate pipes,
         sockets or other UNIX	devices, that can be accessed through
         file descriptors. If the function fails, it sets
         ios_base::failbit.

      basic_ifstream(int fd, char_type* buf,int len);
         Constructs	an object of class basic_ifstream<charT,traits>,
         initializing the base class basic_istream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). The	constructor
         then calls the basic_filebuf open	function open(fd) in order to
         attach the file descriptor	fd to the basic_iftream	object.	The
         underlying buffer is then replaced by calling the basic_filebuf
         member function setbuf with parameters buf and len.	This
         constructor is not	described in the C++ standard, and is
         provided as an extension in order to manipulate pipes, sockets or
         other UNIX devices, that can be	accessed through file
         descriptors. It also maintains compatibility with the old
         iostreams library. If the function fails, it	sets
         ios_base::failbit.

    DESTRUCTOR

      virtual ~basic_ifstream();
         Destroys an object	of class basic_ifstream.

    MEMBER FUNCTIONS

      void
      close();
         Calls the associated basic_filebuf	function close() and if	this
         function fails, it calls the basic_ios member function
         setstate(failbit).

      bool
      is_open();
         Calls the associated basic_filebuf	function is_open() and return
         its result.

      void
      open(const char* s,ios_base::openmode	=
          ios_base::in, long protection = 0666);
         Calls the associated basic_filebuf function
         open(s,mode,protection). If this function fails	opening	the
         file, it calls the basic_ios member	function
         setstate(failbit). The	third argument protection provides
         file	permissions. It	does not appear	in the Standard	C++
         description and is provided as	an extension. It determines
         the	file read/write/execute permissions	under UNIX. It
         is more limited under DOS since files are always readable and do
         not	have special execute permission.

      basic_filebuf<charT,traits>*
      rdbuf() const;
         Returns a pointer to the basic_filebuf associated with the
         stream.

    EXAMPLES

      //
      // stdlib/examples/manual/ifstream.cpp
      //
      #include<iostream>
      #include<fstream>
      #include<iomanip>

      void main ( )
      {
       using namespace std;

       long	  l= 20;
       char	  *ntbs="Le minot passait la piece a frotter";
       char	  c;
       char	  buf[50];

      try {

        // create a	read/write file-stream object on char
        // and attach it to	an ifstream object
       ifstream in("ifstream.out",ios_base::in |
    	       ios_base::out | ios_base::trunc);

        // tie the ostream object to the ifstream object
       ostream out(in.rdbuf());

        // output ntbs in out
       out << ntbs << endl;

        // seek to the beginning of	the file
       in.seekg(0);

        // output each word	on a separate line
       while ( in.get(c) )
         {
          if ( char_traits<char>::eq(c,' ')	)
           cout << endl;
          else
           cout << c;
         }
       cout	<< endl	<< endl;

        // move back to the	beginning of the file
       in.seekg(0);

        // clear the state flags
       in.clear();

        // does the	same thing as the previous code
        // output each word	on a separate line
       while ( in >> buf )
        cout << buf	<< endl;

       cout	<< endl	<< endl;

        // output the base info before each	integer
       out << showbase;

       ostream::pos_type pos= out.tellp();

        // output l	in hex with a field with of 20
       out << hex << setw(20) << l << endl;

        // output l	in oct with a field with of 20
       out << oct << setw(20) << l << endl;

        // output l	in dec with a field with of 20
       out << dec << setw(20) << l << endl;

        // move back to the	beginning of the file
       in.seekg(0);

        // output the all file
       cout	<< in.rdbuf();

        // clear the flags
       in.clear();

        // seek the	input sequence to pos
       in.seekg(pos);

       int a,b,d;

        // read the	previous outputted integer
       in >> a >> b	>> d;

        // output 3	times 20
       cout	<< a <<	endl <<	b << endl << d << endl;

      }
       catch( ios_base::failure& var )
         {
           cout << var.what();
         }

      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_filebuf, basic_ofstream, basic_fstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.8.1.5

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ios
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ios,ios

      This page describes the ANSI ios class.  If you would	like
      information on the pre-ANSI ios class, use the command:

           help cxxl

    SYNOPSIS

      #include <ios>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ios : public ios_base

    DESCRIPTION

      The class basic_ios is a base	class that provides the	common
      functionality required by all streams. It maintains	state
      information that reflects	the integrity of the stream and stream
      buffer. It	also maintains the link between the stream classes and
      the stream buffers classes via	the rdbuf member functions.
      Classes derived from basic_ios specialize operations for input, and
      output.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ios : public ios_base {

        public:

         typedef basic_ios<charT, traits>		ios_type;
         typedef basic_streambuf<charT, traits>	streambuf_type;
         typedef basic_ostream<charT, traits>	ostream_type;

         typedef typename traits::char_type		char_type;
         typedef traits				traits_type;

         typedef typename traits::int_type		int_type;
         typedef typename traits::off_type		off_type;
         typedef typename traits::pos_type		pos_type;

         explicit basic_ios(basic_streambuf<charT, traits> *sb_arg);
         virtual ~basic_ios();

         char_type fill() const;
         char_type fill(char_type ch);

         void exceptions(iostate except);
         iostate exceptions() const;

         void clear(iostate	state =	goodbit);

         void setstate(iostate state);
         iostate rdstate() const;

         operator void*() const;
         bool operator!() const;

         bool good() const;
         bool eof()	const;
         bool fail() const;
         bool bad()	const;

         ios_type& copyfmt(const ios_type& rhs);

         ostream_type *tie() const;
         ostream_type *tie(ostream_type *tie_arg);

         streambuf_type *rdbuf() const;
         streambuf_type *rdbuf( streambuf_type *sb);

         locale imbue(const	locale&	loc);

         char narrow(charT,	char) const;
         charT widen(char) const;

        protected:

         basic_ios();

         void init(basic_streambuf<charT, traits> *sb);
      };

    TYPES

      char_type
         The type char_type	is a synonym of	type traits::char_type.

      ios
         The type ios is an	instantiation of basic_ios on char:

           typedef basic_ios<char> ios;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is a synonym for	basic_ios<charT, traits>.

      off_type
         The type off_type is a synonym of type traits::off_type.

      ostream_type
         The type ostream_type is a	synonym	for basic_ostream<charT, traits>.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      streambuf_type
         The type streambuf_type is	a synonym for
         basic_streambuf<charT, traits>.

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

      wios
         The type wios is an instantiation of basic_ios on wchar_t:

           typedef basic_ios<wchar_t> wios;

    PUBLIC CONSTRUCTORS

      explicit basic_ios(basic_streambuf<charT, traits>* sb);
         Constructs	an object of class basic_ios, assigning	initial	values
         to its member objects by calling init(sb). If sb is a null
         pointer, the stream is	positioned in error state, by
         triggering its badbit.

      basic_ios();
         Constructs	an object of class basic_ios leaving its member
         objects	uninitialized.	The object must	be initialized
         by calling the init member function before using it.

    PUBLIC DESTRUCTOR

      virtual ~basic_ios();
         Destroys an object	of class basic_ios.

    PUBLIC MEMBER FUNCTIONS

      bool
      bad()	const;
         Returns true if badbit is set in rdstate().

      void
      clear(iostate	state =	goodbit);
         If	(state & exception()) == 0, returns.  Otherwise, the function
         throws an	object of class	ios_base::failure. After the call
         returns state	== rdstate().

      basic_ios&
      copyfmt(const	basic_ios& rhs);
         Assigns to	the member objects of *this the	corresponding member
         objects of	rhs, with the following	exceptions:

         +	     rdstate() and rdbuf() are left unchanged

         +	     calls ios_base::copyfmt

         +	     exceptions() is altered last by calling
           	     exceptions(rhs.exceptions())

      bool
      eof()	const;
         Returns true if eofbit is set in rdstate().

      iostate
      exceptions() const;
         Returns a mask that determines what elements set in rdstate()
         cause exceptions	to be thrown.

      void
      exceptions(iostate except);
         Set the exception mask to except then calls clear(rdstate()).

      bool
      fail() const;
         Returns true if failbit or	badbit is set in rdstate().

      char_type
      fill() const;
         Returns the character used	to pad (fill) an output	conversion to
         the specified field width.

      char_type
      fill(char_type fillch);
         Saves the field width value then replaces it by fillch and
         returns	the previously	saved value.

      bool
      good() const;
         Returns rdstate() == 0.

      locale
      imbue(const locale& loc);
         Saves the value returned by getloc() then assigns loc to a
         private	variable and if rdbuf() != 0 calls
         rdbuf()->pubimbue(loc) and returns the previously	saved value.

      void
      init(basic_streambuf<charT,traits>* sb);
         Performs the following initialization:

         rdbuf()	  sb
         tie()	  0
         rdstate()	  goodbit if sb	is not null otherwise badbit
         exceptions() goodbit
         flags()	  skipws | dec
         width()	  0
         precision()  6
         fill()	  the space character
         getloc()	  locale::locale()

      char
      narrow(charT c, char dfault) const;
         Uses the stream's locale to convert the wide character c to a
         tiny	character, and	then returns it. If no
         conversion exists, it returns the character dfault.

      bool
      operator!() const;
         Returns fail() ? 1	: 0;

      streambuf_type*
      rdbuf() const;
         Returns a pointer to the stream buffer associated with the
         stream.

      streambuf_type*
      rdbuf(streambuf_type*	sb);
         Associates	a stream buffer	with the stream. All the input and
         output will be directed to this stream buffer. If	sb is a	null
         pointer, the stream is positioned in error state, by triggering
         its badbit.

      iostate
      rdstate() const;
         Returns the control state of the stream.

      void
      setstate(iostate state);
         Calls clear(rdstate() | state).

      ostream_type*
      tie()	const;
         Returns an	output sequence	that is	tied to	(synchronized with)
         the sequence controlled by the	stream buffer.

      ostream_type*
      tie(ostream_type* tiestr);
         Saves the tie() value then	replaces it by tiestr and returns the
         value previously	saved.

      operator
      void*() const;
         Returns fail() ? 0	: 1;

      charT
      widen(char c)	const;

         Uses the stream's locale to convert the tiny character c to a
         wide	character, then returns it.

    SEE ALSO

      ios_base, basic_istream, basic_ostream,
      basic_streambuf, char_traits

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++.

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    iosfwd
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      iosfwd

    DESCRIPTION

      The header iosfwd forward declares the input/output library template
      classes and specializes them for wide	and tiny characters. It	also
      defines the positional types used in class char_traits instantiated
      on tiny and wide characters.

    SYNOPSIS

      #include <iosfwd>

      // forward declare the traits	class
      template<class charT>	struct char_traits;

      // forward declare the positioning class
      template<class stateT> class fpos;

      // forward declare the state class
      class	mbstate_t;

      // forward declare the allocator class
      template<class T> class allocator;

      // forward declare the iostreams template classes
      template<class charT,class traits=char_traits<charT>>
         class basic_ios;
      template<class charT,class traits=char_traits<charT>>
         class basic_streambuf;
      template<class charT,class traits=char_traits<charT>>
         class basic_istream;
      template<class charT,class traits=char_traits<charT>>
         class basic_ostream;
      template<class charT,class traits=char_traits<charT>,
    	  class	Allocator = allocator<void> >
         class basic_stringbuf;
      template<class charT,class traits=char_traits<charT>,
    	  class	Allocator = allocator<void> >
         class basic_istringstream;
      template<class charT,class traits=char_traits<charT>,
    	  class	Allocator = allocator<void> >
         class basic_ostringstream;
      template<class charT,class traits=char_traits<charT>>
         class basic_filebuf;
      template<class charT,class traits=char_traits<charT>>
         class basic_ifstream;
      template<class charT,class traits=char_traits<charT>>
         class basic_ofstream;
      template<class charT,class traits=char_traits<charT>>
         class ostreambuf_iterator;
      template<class charT,class traits=char_traits<charT>>
         class istreambuf_iterator;
      template<class charT,class traits=char_traits<charT>>
         class basic_iostream;
      template<class charT,class traits=char_traits<charT>,
    	  class	Allocator = allocator<void> >
         class basic_stringstream;
      template<class charT,class traits=char_traits<charT>>
         class basic_fstream;

      // specializations on	tiny characters
      typedef basic_ios<char>	       ios;
      typedef basic_streambuf<char>	       streambuf;
      typedef basic_istream<char>	       istream;
      typedef basic_ostream<char>	       ostream;
      typedef basic_stringbuf<char>	       stringbuf;
      typedef basic_istringstream<char>    istringstream;
      typedef basic_ostringstream<char>    ostringstream;
      typedef basic_filebuf<char>	       filebuf;
      typedef basic_ifstream<char>	       ifstream;
      typedef basic_ofstream<char>	       ofstream;
      typedef basic_iostream<char>	       iostream;
      typedef basic_stringstream<char>     stringstream;
      typedef basic_fstream<char>	       fstream;

      // specializations on	wide characters
      typedef basic_ios<wchar_t>	       wios;
      typedef basic_streambuf<wchar_t>     wstreambuf;
      typedef basic_istream<wchar_t>       wistream;
      typedef basic_ostream<wchar_t>       wostream;
      typedef basic_stringbuf<wchar_t>     wstringbuf;
      typedef basic_istringstream<wchar_t> wistringstream;
      typedef basic_ostringstream<wchar_t> wostringstream;
      typedef basic_filebuf<wchar_t>       wfilebuf;
      typedef basic_ifstream<wchar_t>      wifstream;
      typedef basic_ofstream<wchar_t>      wofstream;
      typedef basic_iostream<wchar_t>      wiostream;
      typedef basic_stringstream<wchar_t>  wstringstream;
      typedef basic_fstream<wchar_t>       wfstream;

      // positional	types used by char_traits
      typedef fpos<mbstate_t> streampos;
      typedef fpos<mbstate_t> wstreampos;

      typedef long		  streamoff;
      typedef long		  wstreamoff;

    SEE ALSO

      fpos, char_traits, basic_ios,
      basic_streambuf, basic_istream, basic_ostream,
      basic_iostream,

      basic_stringbuf, basic_istringstream,
      basic_ostringstream,	basic_stringstream,
      basic_filebuf, basic_ifstream, basic_ofstream,
      basic_fstream, istreambuf_iterator,
      ostreambuf_iterator

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.2

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    istream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_istream,istream

      This page describes the ANSI basic_istream class.  If	you would like
      information on the	pre-ANSI istream class,	use the	command:

           help cxxl

    SYNOPSIS

      #include <istream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_istream
      : virtual public basic_ios<charT, traits>

    DESCRIPTION

      The class basic_istream defines a number of member function
      signatures that assist in reading and	interpreting input from
      sequences controlled by	a stream buffer.

      Two groups of	member function	signatures share common	properties:
      the formatted input functions (or extractors) and the unformatted
      input functions. Both groups of input functions obtain	(or
      extract) input characters by calling basic_streambuf member
      functions. They both begin by constructing an object of class
      basic_istream::sentry	and, if	this object is in good state after
      construction, the function endeavors to	obtain the requested
      input. The sentry object performs exception safe initialization,
      such as controlling the status of the stream	or locking it
      in multithread environment.

      Some formatted input functions parse characters extracted from the
      input sequence, converting the result to a value of	some scalar
      data type, and storing the converted	value in an object of that
      scalar type.	The conversion behavior	is locale dependent,
      and directly depend on the	locale object imbued in the
      stream.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_istream
      : virtual public basic_ios<charT, traits> {

      public:

      typedef basic_istream<charT, traits>	  istream_type;
      typedef basic_ios<charT, traits>	  ios_type;
      typedef basic_streambuf<charT, traits>  streambuf_type;

      typedef traits		      traits_type;
      typedef charT			      char_type;
      typedef typename traits::int_type   int_type;
      typedef typename traits::pos_type   pos_type;
      typedef typename traits::off_type   off_type;

      explicit basic_istream(basic_streambuf<charT,	traits>	*sb);
      virtual ~basic_istream();

      class	sentry
        {
          public:

           inline explicit sentry(basic_istream<charT,traits>&,
    			      bool noskipws = 0);
    	 ~sentry();
    	operator bool ();
        };

      istream_type&	operator>>(istream_type& (*pf)(istream_type&));
      istream_type&	operator>>(ios_base& (*pf)(ios_base&));
      istream_type&	operator>>(ios_type& (*pf)(ios_type&));

      istream_type&	operator>>(bool& n);
      istream_type&	operator>>(short& n);
      istream_type&	operator>>(unsigned short& n);
      istream_type&	operator>>(int&	n);
      istream_type&	operator>>(unsigned int& n);
      istream_type&	operator>>(long& n);
      istream_type&	operator>>(unsigned long& n);
      istream_type&	operator>>(float& f);
      istream_type&	operator>>(double& f);
      istream_type&	operator>>(long	double&	f);

      istream_type&	operator>>(void*& p);

      istream_type&	operator>>(streambuf_type& sb);
      istream_type&	operator>>(streambuf_type *sb);

      int_type get();

      istream_type&	get(char_type *s, streamsize n,	char_type delim);
      istream_type&	get(char_type *s, streamsize n);

      istream_type&	get(char_type& c);

      istream_type&	get(streambuf_type& sb,char_type delim);
      istream_type&	get(streambuf_type& sb);

      istream_type&	getline(char_type *s, streamsize n,char_type delim);
      istream_type&	getline(char_type *s, streamsize n);

      istream_type&	ignore(streamsize n = 1,
    		       int_type	delim =	traits::eof());

      istream_type&	read(char_type *s, streamsize n);

      streamsize readsome(char_type	*s, streamsize n);

      int peek();

      pos_type tellg();

      istream_type&	seekg(pos_type&);
      istream_type&	seekg(off_type&, ios_base::seekdir);

      istream_type&	putback(char_type c);
      istream_type&	unget();

      streamsize gcount() const;

      int sync();

      protected:

      explicit basic_istream( );

      };

      //global function

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      ws(basic_istream<charT, traits>&);
      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>> (basic_istream<charT, traits>&, charT&);
      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>> (basic_istream<charT, traits>&, charT*);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, unsigned char&);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, signed char&);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, unsigned char*);
      template<class traits>
      basic_istream<char, traits>&
      operator>> (basic_istream<char, traits>&, signed char*);

    TYPES

      char_type
         The type char_type	is a synonym for them template parameter charT.

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is a synonym for	basic_ios<charT, traits> .

      istream
         The type istream is an instantiation of class basic_istream on type
         char:

           typedef basic_istream<char> istream;

      istream_type
         The type istream_type is a	synonym	for basic_istream<charT, traits>.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      streambuf_type
         The type streambuf_type is	a synonym for basic_streambuf<charT,
         traits> .

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

      wistream
         The type wistream is an instantiation of class basic_istream on type
         wchar_t:

         typedef basic_istream<wchar_t> wistream;

    PUBLIC CONSTRUCTOR

      explicit basic_istream(basic_streambuf<charT,	traits>* sb);
         Constructs	an object of class basic_istream, assigning initial
         values to the base class by calling basic_ios::init(sb).

    PUBLIC DESTRUCTOR

      virtual ~basic_istream();
         Destroys an object	of class basic_istream.

    SENTRY CLASS

      explicit sentry(basic_istream<charT,traits>&,	bool noskipws=0);
         Prepares for formatted or unformatted input. First	if the
         basic_ios member function tie() is not a null pointer, the
         function synchronizes the output	sequence with any associated
         stream. If	noskipws is zero and the ios_base member function
         flags() & skipws is nonzero, the function extracts and discards
         each	character as long as the next available	input
         character is a white space	character. If after any	preparation is
         completed the	basic_ios member function good() is true, the
         sentry conversion function operator bool() will	return true.
         Otherwise it will return false. In multithread environment the
         sentry object constructor is responsible for locking the stream
         and the	stream buffer associated with the stream.

      ~sentry();
         Destroys an object	of class sentry. In multithread	environment,
         the sentry object	destructor is responsible for
         unlocking	the stream and the stream buffer associated with the
         stream.

      operator bool();
         If	after any preparation is completed the basic_ios member
         function good() is true, the sentry	conversion function
         operator bool() will return true else it will return false.

    EXTRACTORS

      istream_type&
      operator>>(istream_type&
    	    (*pf) (istream_type&));
    	       Calls pf(*this),	then return *this. See,	for example, the
    	       function	signature ws(basic_istream&).

      istream_type&
      operator>>(ios_type& (*pf) (ios_type&));
         Calls pf(*this), then return *this.

      istream_type&
      operator>>(ios_base& (*pf) (ios_base&));
         Calls pf(*this), then return *this. See, for example, the
         function	signature dec(ios_base&).

      istream_type&
      operator>>(bool& n);
         Converts a	Boolean	value, if one is available, and	stores it in
         n.	If the ios_base member function flag() & ios_base::boolalpha
         is false	it tries to read an integer value, which if found must
         be 0 or 1. If the boolalpha flag is true, it	reads
         characters until it determines whether the characters read are
         correct according to the locale function numpunct<>::truename()
         or numpunct<>::falsename().	If no match is found, it
         calls the basic_ios member function setstate(failbit), which may
         throw ios_base::failure.

      istream_type&
      operator>>(short& n);
         Converts a	signed short integer, if one is	available, and stores
         it in n,	then returns *this.

      istream_type&
      operator>>(unsigned short& n);
         Converts an unsigned short	integer, if one	is available, and
         stores it in	n, then	return *this.

      istream_type&
      operator>>(int& n);
         Converts a	signed integer,	if one is available, and stores	it in
         n, then return *this.

      istream_type&
      operator>>(unsigned int& n);
         Converts an unsigned integer, if one is available,	and stores it
         in n, then return *this.

      istream_type&
      operator>>(long& n);
         Converts a	signed long integer, if	one is available, and stores
         it	in n, then returns *this.

      istream_type&
      operator>>(unsigned long& n);
         Converts an unsigned long integer,	if one is available, and
         stores	it in n,	then returns *this.

      istream_type&
      operator>>(float& f);
         Converts a	float, if one is available, and	stores it in f,	then
         returns *this.

      istream_type&
      operator>>(double& f);
         Converts a	double,	if one is available, and stores	it in f, then
         returns *this.

      istream_type&
      operator>>(long double& f);
         Converts a	long double, if	one is available, and stores it	in f,
         then returns *this.

      istream_type&
      operator>>(void*& p);
         Extracts a	void pointer, if one is	available, and stores it in p,
         then return *this.

      istream_type&
      operator>>(streambuf_type* sb);
         If	sb is null, calls the basic_ios	member function
         setstate(badbit), which may throw ios_base::failure.
         Otherwise extracts characters from *this and inserts them in the
         output sequence controlled by sb. Characters are extracted
         and inserted until any of the following	occurs:

         +	     end-of-file occurs	on the input sequence

         +	     inserting in the output sequence fails

         +	     an	exception occurs

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. If failure was due to	catching an exception
         thrown while extracting characters from sb and failbit is on in
         exception(), then the caught exception is	rethrown.

      istream_type&
      operator>>(streambuf_type& sb);
         Extracts characters from *this and	inserts	them in	the output
         sequence controlled	by sb. Characters are extracted	and
         inserted until any of the following occurs:

         +	     end-of-file occurs	on the input sequence

         +	     inserting in the output sequence fails

         +	     an	exception occurs

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. If failure was due to	catching an exception
         thrown while extracting characters from sb and failbit is on in
         exception(), then the caught exception is	rethrown.

    UNFORMATTED FUNCTIONS

      streamsize
      gcount() const;
         Returns the number	of characters extracted	by the last
         unformatted	input member function called.

      int_type
      get();
         Extracts a	character, if one is available.	Otherwise, the
         function	calls the basic_ios member function setstate(failbit),
         which may	throw ios_base::failure.	Returns	the character
         extracted	or traits::eof() if none is available.

      istream_type&
      get(char_type& c);
         Extracts a	character, if one is available,	and assigns it to c.
         Otherwise, the function	calls the basic_ios member function
         setstate(failbit),	which may throw	ios_base::failure.

      istream_type&
      get(char_type* s, streamsize n,char_type delim);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. Characters
         are extracted and stored	until any of the following occurs:

         +	     n-1 characters are	stored

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	== delim.

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. In any case, it stores a null character into
         the next successive location	of the array.

      istream_type&
      get(char_type* s, streamsize n);
         Calls get(s,n,widen('0)).

      istream_type&
      get(streambuf_type& sb,char_type delim);
         Extracts characters and inserts them in the output	sequence
         controlled by	sb. Characters are extracted and inserted
         until	any of the following occurs:

         +	     end-of-file occurs	on the input sequence

         +	     inserting in the output sequence fails

         +	     the next available	input character	== delim.

         +	     an	exception occurs

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. If failure was due to	catching an exception
         thrown while extracting characters from sb and failbit is on in
         exception(), then the caught exception is	rethrown.

      istream_type&
      get(streambuf_type& sb);
         Calls get(sb,widen('0)).

      istream_type&
      getline(char_type* s,	streamsize n, char_type	delim);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. Characters
         are extracted and stored	until any of the following occurs:

         +	     n-1 characters are	stored

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	== delim.

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. In any case, it stores a null character into
         the next successive location	of the array.

      istream_type&
      getline(char_type* s,	streamsize n);
         Calls getline(s,n,widen('0)).

      istream_type&
      ignore(streamsize n=1, int_type delim=traits::eof());
         Extracts characters and discards them. Characters are extracted
         until any of the	following occurs:

         +	     n characters are extracted

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	== delim.

      int_type
      peek();
         Returns traits::eof() if the basic_ios member function good()
         returns false. Otherwise, returns the next	available character.
         Does not increment the current get pointer.

      istream_type&
      putback(char_type c);
         Insert c in the putback sequence.

      istream_type&
      read(char_type* s, streamsize	n);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. Characters
         are extracted and stored	until any of the following occurs:

         +	     n characters are stored

         +	     end-of-file occurs	on the input sequence

         If	the function does not store n characters, it calls the
         basic_ios member function setstate(failbit),	which may
         throw	ios_base::failure.

      streamsize
      readsome(char_type* s, streamsize n);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. If
         rdbuf()->in_avail() == -1, calls the basic_ios member function
         setstate(eofbit).

         +	     If	rdbuf()->in_avail() == 0, extracts no characters

         +	     If	rdbuf()->in_avail() > 0, extracts min( rdbuf()->in_avail(),
    	  n)

         In	any case the function returns the number of characters extracted.

      istream_type&
      seekg(pos_type& pos);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(pos), which will position the current pointer
         of the input sequence at the position designated by pos.

      istream_type&
      seekg(off_type& off, ios_base::seekdir dir);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(off,dir), which will position the current
         pointer of the input sequence	at the position	designated by
         off and dir.

      int
      sync();
         If	rdbuf()	is a null pointer, return -1. Otherwise, calls
         rdbuf()- >pubsync()	and if that function returns -1	calls
         the basic_ios member function setstate(badbit).	The purpose of
         this function is	to synchronize the internal input buffer,
         with the external sequence of characters.

      pos_type
      tellg();
         If	the basic_ios member function fail() returns true, tellg()
         returns pos_type(off_type(-1)) to indicate	failure. Otherwise it
         returns the current position of the input sequence by calling
         rdbuf()- >pubseekoff(0,cur,in).

      istream_type&
      unget();
         If	rdbuf()	is not null, calls rdbuf()->sungetc(). If rdbuf() is
         null or if	sungetc() returns traits::eof(), calls the basic_ios
         member function setstate(badbit).

    NON MEMBER FUNCTIONS

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& is, charT& c);
         Extracts a	character if one is available, and stores it in	c.
         Otherwise the function calls	the basic_ios member function
         setstate(failbit), which may throw ios_base::failure.

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& is, charT* s);
         Extracts characters and stores them into successive locations of
         an array whose first element is designated by	s. If the
         ios_base member function is.width() is greater than zero, then
         is.width() is the maximum number of characters stored. Characters
         are extracted and stored until any of the	following occurs:

         +	     if	is.witdh()>0, is.witdh()-1 characters are extracted

         +	     end-of-file occurs	on the input sequence

         +	     the next available	input character	is a white space.

         If	the function stores no characters, it calls the	basic_ios
         member function setstate(failbit), which may throw
         ios_base::failure. In any case, it then stores a null character
         into	the next successive location of	the array and calls
         width(0).

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, unsigned char& c);
         Returns is	>> (char&)c.

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, signed char& c);
         Returns is	>> (char&)c.

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, unsigned char* c);
         Returns is	>> (char*)c.

      Template<class traits>
      basic_istream<char, traits>&
      operator>>(basic_istream<char, traits>& is, signed char* c);
         Returns is	>> (char*)c.

      template<class charT,	class traits>
      basic_istream<charT, traits>&
      ws(basic_istream<charT, traits>& is);
         Skips any white space in the input	sequence and returns is.

    EXAMPLES

      //
      // stdlib/examples/manual/istream1.cpp
      //
      #include<iostream>
      #include<istream>
      #include<fstream>

      void main ( )
      {
       using namespace std;

       float f= 3.14159;
       int	 i= 3;
       char	 s[200];

        // open a file for read and	write operations
       ofstream out("example", ios_base::in	| ios_base::out
    		 | ios_base::trunc);

        // tie the istream object to the ofstream filebuf
       istream  in (out.rdbuf());

        // output to the file
       out << "Annie is the	Queen of porting" << endl;
       out << f << endl;
       out << i << endl;

        // seek to the beginning of	the file
       in.seekg(0);

       f = i = 0;

        // read from the file using	formatted functions
       in >> s >> f	>> i;

        // seek to the beginning of	the file
       in.seekg(0,ios_base::beg);

        // output the all file to the standard output
       cout	<< in.rdbuf();

        // seek to the beginning of	the file
       in.seekg(0);

        // read the	first line in the file
        // "Annie is the Queen of porting"
       in.getline(s,100);

       cout	<< s <<	endl;

        // read the	second line in the file
        // 3.14159
       in.getline(s,100);

       cout	<< s <<	endl;

        // seek to the beginning of	the file
       in.seekg(0);

        // read the	first line in the file
        // "Annie is the Queen of porting"
       in.get(s,100);

        // remove the newline character
       in.ignore();

       cout	<< s <<	endl;

        // read the	second line in the file
        // 3.14159
       in.get(s,100);

       cout	<< s <<	endl;

        // remove the newline character
       in.ignore();

        // store the current file position
       istream::pos_type position =	in.tellg();

       out << "replace the int" << endl;

        // move back to the	previous saved position
       in.seekg(position);

        // output the remain of the	file
        // "replace	the int"
        // this is equivalent to
        // cout << in.rdbuf();
       while( !char_traits<char>::eq_int_type(in.peek(),
       char_traits<char>::eof()) )
        cout << char_traits<char>::to_char_type(in.get());

       cout	<< "0 << flush;
      }

      //
      // istream example two
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       char	p[50];

        // remove all the white spaces
       cin >> ws;

        // read characters from stdin until	a newline
        // or 49 characters	have been read
       cin.getline(p,50);

        // output the result to stdout
       cout	<< p;
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_iostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.6.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    iostream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_iostream,iostream

      This page describes the ANSI basic_iostream class.  If you would
      like information on the pre-ANSI iostream class, use the command:

           help cxxl

    SYNOPSIS

      #include <istream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_iostream
      : public basic_istream<charT,	traits>,
      public basic_ostream<charT, traits>

    DESCRIPTION

      The class basic_iostream inherits a number of	functions from classes
      basic_ostream<charT, traits> and basic_istream<charT,	traits>. They
      assist in formatting	and interpreting sequences of characters
      controlled by a stream buffer. Two groups of functions share common
      properties, the formatted functions	and the	unformatted functions.

    INTERFACE

      template<class charT,	class traits>
      class	basic_iostream
      : public basic_istream<charT,	traits>,
       public basic_ostream<charT, traits>

      {

      public:

       explicit basic_iostream(basic_streambuf<charT, traits> *sb);
       virtual ~basic_iostream();

      protected:

       explicit basic_iostream();

      };

    PUBLIC CONSTRUCTORS

      explicit basic_iostream(basic_streambuf<charT, traits>* sb);
         Constructs	an object of class basic_iostream, assigning initial
         values to	the base class by calling basic_istream<charT,
         traits>(sb) and basic_ostream<charT, traits>(sb).

      explicit basic_iostream();
         Constructs	an object of class basic_iostream, assigning initial
         values to	the base class by calling basic_istream<charT,
         traits>() and basic_ostream<charT, traits>(). After construction
         the object has its badbit set.

    DESTRUCTOR

      virtual ~basic_iostream();
         Destroys an object	of class basic_iostream.

    EXAMPLES

      See basic_istream and	basic_ostream examples.

    COMPATIBILITY

      [Digital]  The ANSI Standard Library provides	two macros which
      enable	or disable use of the ANSI iostream package at compile
      time.

      ______________________________________________________________
      Macro			  Description
      ______________________________________________________________
      __USE_STD_IOSTREAM	  Use the ANSI Standard	iostream package
      __NO_USE_STD_IOSTREAM	  Use the pre-ANSI iostream package
      ______________________________________________________________

      See help cxxl for more details.

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_istream, basic_ostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section
      27.6.1.4.1

    STANDARDS CONFORMANCE

      ANSI X3J16/ISO WG21 Joint C++	Committee

    ios_base
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      ios_base

    SYNOPSIS

      #include <ios>
      class	ios_base;

    DESCRIPTION

      The class ios_base defines several member types:

      +	  A class failure derived from exception.

      +	  A class Init.

      +	  Three	bitmask	types, fmtflags, iostate and openmode.

      +	  Two enumerated types,	seekdir, and event.

      It maintains several kinds of	data:

      +	  Control information that influences how to interpret (format)
           input sequences and how to generate (format) output sequences.

      +	  Locale object	used within the	stream classes.

      +	  Additional information that is stored	by the program for its
           private use.

    INTERFACE

      class	ios_base {

      public:

        class failure : public exception {

           public:

    	   explicit failure(const string& msg);
    	   virtual ~failure() throw();
    	   virtual const char* what() const throw();
          };

        typedef int	     iostate;

        enum io_state {
    		    goodbit	= 0x00,
    		    badbit	= 0x01,
    		    eofbit	= 0x02,
    		    failbit	= 0x04
    		   };

        typedef int	     openmode;

        enum open_mode {
    		     app	 = 0x01,
    		     binary	 = 0x02,
    		     in		 = 0x04,
    		     out	 = 0x08,
    		     trunc	 = 0x10,
    		     ate	 = 0x20
    		    };

        typedef int	     seekdir;

        enum seek_dir {
    		      beg	  = 0x0,
    		      cur	  = 0x1,
    		      end	  = 0x2
    		   };

        typedef int	     fmtflags;

        enum fmt_flags {
    		     boolalpha	 = 0x0001,
    		     dec	 = 0x0002,
    		     fixed	 = 0x0004,
    		     hex	 = 0x0008,
    		     internal	 = 0x0010,
    		     left	 = 0x0020,
    		     oct	 = 0x0040,
    		     right	 = 0x0080,
    		     scientific	 = 0x0100,
    		     showbase	 = 0x0200,
    		     showpoint	 = 0x0400,
    		     showpos	 = 0x0800,
    		     skipws	 = 0x1000,
    		     unitbuf	 = 0x2000,
    		     uppercase	 = 0x4000,
    		     adjustfield = left	| right	| internal,
    		     basefield	 = dec | oct | hex,
    		     floatfield	 = scientific |	fixed
    		    };

        enum event	   {
    		     erase_event   = 0x0001,
    		     imbue_event   = 0x0002,
    		     copyfmt_event = 0x004
    		    };

        typedef void (*event_callback) (event, ios_base&, int index);

        void register_callback(event_callback fn, int index);

        class Init;

        fmtflags flags() const;
        fmtflags flags(fmtflags fmtfl);
        fmtflags setf(fmtflags fmtfl);
        fmtflags setf(fmtflags fmtfl, fmtflags mask);

        void unsetf(fmtflags mask);

        ios_base& copyfmt(const ios_base& rhs);

        streamsize precision() const;
        streamsize precision(streamsize prec);

        streamsize width() const;
        streamsize width(streamsize	wide);

        locale imbue(const locale& loc);
        locale getloc() const

        static int xalloc();

        long&  iword(int index);
        void*& pword(int index);

        bool synch_with_stdio(bool sync = true);
        bool is_synch();

       protected:

        ios_base();
         ~ios_base();

       private:

        union ios_user_union {
    			    long  lword;
    			    void* pword;
    			  };

        union ios_user_union *userwords_;
      };

      ios_base& boolalpha(ios_base&);
      ios_base& noboolalpha(ios_base&);
      ios_base& showbase(ios_base&);
      ios_base& noshowbase(ios_base&);
      ios_base& showpoint(ios_base&);
      ios_base& noshowpoint(ios_base&);
      ios_base& showpos(ios_base&);
      ios_base& noshowpos(ios_base&);
      ios_base& skipws(ios_base&);
      ios_base& noskipws(ios_base&);
      ios_base& uppercase(ios_base&);
      ios_base& nouppercase(ios_base&);
      ios_base& internal(ios_base&);
      ios_base& left(ios_base&);
      ios_base& right(ios_base&);
      ios_base& dec(ios_base&);
      ios_base& hex(ios_base&);
      ios_base& oct(ios_base&);
      ios_base& fixed(ios_base&);
      ios_base& scientific(ios_base&);
      ios_base& unitbuf(ios_base&);
      ios_base& nounitbuf(ios_base&);

    TYPES

      fmtflags
         The type fmtflags is a bitmask type. Setting its elements has the
         following effects:

         showpos   Generates a + sign in non-negative generated numeric
                   output.

         showbase	Generates a prefix indicating the numeric base of
                    generated integer	output.

         uppercase	 Replaces certain lowercase letters with their uppercase
    		 equivalents in	generated output.

         showpoint	 Generates a decimal-point character unconditionally in
                     generated	floating-point output.

         boolalpha	 Inserts and extracts bool type	in alphabetic format.

         unitbuf   Flushes output after each output	operation.

         internal	Adds fill characters at	a designated internal point
                    in certain generated output, or identical to right if
                    no such	point is designated.

         left   Adds fill characters on the	right (final positions)	of
                certain generated output.

         right   Adds fill characters on the left (initial positions) of
                 certain generated output.

         dec   Converts integer input or generates integer output in decimal
    	   base.

         hex   Converts integer input or generates integer output in
               hexadecimal base.

         oct   Converts integer input or generates integer output in octal
               base.

         fixed   Generates floating-point output in	fixed-point notation.

         scientific	  Generates floating-point output in scientific	notation.

         skipws   Skips leading white space	before certain input operation.

      iostate
         The type iostate is a bitmask type. Setting its elements has the
         following effects:

         badbit   Indicates	a loss of integrity in an input	or output
                  sequence.

         eofbit   Indicates	that an	input operation	reached	the end	of an
                  input sequence.

         failbit   Indicates that an input operation failed	to read	the
                   expected characters, or that an output operation failed
                   to generate the desired characters.

      openmode
         The type openmode is a bitmask type. Setting its elements has the
         following effects:

         app   Seeks to the	end before writing.

         ate   Opens and seek to end immediately after opening.

         binary   Performs input and output	in binary mode.

         in	  Opens	for input.

         out   Opens for output.

         trunc   Truncates an existing stream when opening.

      seekdir
         The type seekdir is a bitmask type. Setting its elements has the
         following effects:

         beg   Requests a seek relative to the beginning of	the stream.

         cur   Requests a seek relative to the current position within the
    	   sequence.

         end   Requests a seek relative to the current end of the sequence.

      event_callback
         The type event_callback is	the type of the	callback function used
         as a parameter in the function register_callback. These
         functions allow	you to	use the	iword, pword mechanism in an
         exception-safe environment.

    PUBLIC CONSTRUCTOR

      ios_base();
         The ios_base members have an indeterminate	value after
         construction.

    PUBLIC DESTRUCTOR

      ~ios_base();
         Destroys an object	of class ios_base. Calls each registered
         callback pair (fn, index) as (*fn)(erase_event,*this, index) at
         such a time	that any ios_base member function called from
         within fn	has well-defined results.

    PUBLIC MEMBER FUNCTIONS

      ios_base&
      copyfmt(const	ios_base& rhs);
         Assigns to	the member objects of *this the	corresponding member
         objects of	rhs. The content of the	union pointed at by pword and
         iword is copied, not the pointers itself. Before copying any
         parts of rhs, calls each registered callback pair (fn,index) as
         (*fn)(erase_even,*this, index). After all parts have been
         replaced, calls each callback pair that was copied from rhs as
         (*fn)(copy_event,*this,index).

      fmtflags
      flags() const;
         Returns the format	control	information for	both input and output

      fmtflags
      flags(fmtflags fmtfl);
         Saves the format control information, then	sets it	to fmtfl and
         returns the previously saved value.

      locale
      getloc() const;
         Returns the imbued	locale,	to be used to perform locale-dependent
         input and output	operations. The	default	locale,
         locale::locale(), is used if no	other locale object has	been
         imbued in the stream by a call to the imbue function.

      locale
      imbue(const locale& loc);
         Saves the value returned by getloc() then assigns loc to a
         private	variable and calls each registered callback pair
         (fn, index) as (*fn)(imbue_event,*this, index). It then returns
         the previously saved value.

      bool
      is_sync();
         Returns true if the C++ standard streams and the standard C
         streams are synchronized, otherwise returns false. This function
         is not part of the C++ standard.

      long&
      iword(int idx);
         Returns userwords_[idx].lword. If userwords_ is a null pointer,
         allocates a union of long and void* of	unspecified size and
         stores a pointer to	its first element in  userwords_. The
         function then extends the	union pointed at	by userwords_
         as necessary to include the element userwords_[idx]. Each newly
         allocated element of the union	is initialized to zero. The
         reference returned may become invalid after another call to the
         object's iword	or pword member	with a different index,	after
         a call to its copyfmt member, or when the object is destroyed.

      streamsize
      precision() const;
         Returns the precision (number of digits after the decimal point)
         to generate on certain output conversions.

      streamsize
      precision(streamsize prec);
         Saves the precision then sets it to prec and returns the
         previously saved value.

      void*&
      pword(int idx);
         Returns userword_[idx].pword. If userwords_ is a null pointer,
         allocates a union of	long and void* of unspecified size and
         stores a	pointer	to its first element in userwords_. The
         function then	extends	the union pointed at	by userwords_
         as necessary to include the element userwords_[idx]. Each newly
         allocated element of the array	is initialized to zero. The
         reference returned may become invalid after another call to the
         object's pword	or iword member	with different index, after a
         call to its copyfmt member, or when the object is destroyed.

      void
      register_callback(event_callback fn, int index);
         Registers	the pair (fn, index) such that during calls to
         imbue(),copyfmt(),	or ~ios_base(),	the function fn	is called with
         argument index.  Functions registered are called when an event
         occurs,	in opposite order of registration.  Functions
         registered while a callback function is active	are not	called
         until the next event. Identical pairs are not merged; a function
         registered twice is called twice per event.

      fmtflags
      setf(fmtflags	fmtfl);
         Saves the format control information, then	sets it	to fmtfl and
         returns the previously saved value.

      fmtflags
      setf(fmtflags	fmtfl, fmtflags	mask);
         Saves the control information, then	clears mask in
         flags(),sets fmtfl & mask in flags() and returns the previously
         saved value.

      bool
      sync_with_stdio(bool sync = true);
         Called with a false argument, it allows the C++ standard streams
         to operate independently of the standard C streams, which will
         greatly improve performance when using the	C++ standard streams.
         Called with a true argument it restores the default
         synchronization. The	return value of	the function is	the
         status of the synchronization at the time of the call.

      void
      unsetf(fmtflags mask);
         Clears mask in flags().

      streamsize
      width() const;
         Returns the field width (number of	characters) to generate	on
         certain output conversions.

      streamsize
      width(streamsize wide);
         Saves the field width then	sets it	to wide	and returns the
         previously saved value.

      static int
      xalloc();
         Returns the next static index that	can be used with pword and
         iword. This is useful if you want	to share data between several
         stream objects.

    THE CLASS FAILURE

      The class failure defines the	base class for the types of all
      objects thrown as exceptions,	by functions in	the iostreams library,
      to report errors detected during stream	buffer operations.

      explicit failure(const string& msg);
         Constructs	an object of class failure, initializing the base
         class	with exception(msg).

      const	char*
      what() const;
         Returns the message msg with which	the exception was created.

    CLASS INIT

      The class Init describes an object whose construction	ensures	the
      construction of the eight objects declared in	<iostream>
      that	associate file stream buffers with the standard C streams.

    NON-MEMBER FUNCTIONS

      ios_base&
      boolalpha(ios_base& str);
         Calls str.setf(ios_base::boolalpha) and returns str.

      ios_base&
      dec(ios_base&	str);
         Calls str.setf(ios_base::dec, ios_base::basefield)	and returns
         str.

      ios_base&
      fixed(ios_base& str);
         Calls str.setf(ios_base::fixed, ios_base::floatfield) and returns
         str.

      ios_base&
      hex(ios_base&	str);
         Calls str.setf(ios_base::hex, ios_base::basefield)	and returns str.

      ios_base&
      internal(ios_base& str);
         Calls str.setf(ios_base::internal,	ios_base::adjustfield) and
         returns str.

      ios_base&
      left(ios_base& str);
         Calls str.setf(ios_base::left, ios_base::adjustfield) and returns
         str.

      ios_base&
      noboolalpha(ios_base&	str);
         Calls str.unsetf(ios_base::boolalpha) and returns str.

      ios_base&
      noshowbase(ios_base& str);
         Calls str.unsetf(ios_base::showbase) and returns str.

      ios_base&
      noshowpoint(ios_base&	str);
         Calls str.unsetf(ios_base::showpoint) and returns str.

      ios_base&
      noshowpos(ios_base& str);
         Calls str.unsetf(ios_base::showpos) and returns str.

      ios_base&
      noskipws(ios_base& str);
         Calls str.unsetf(ios_base::skipws)	and returns str.

      ios_base&
      nounitbuf(ios_base& str);
         Calls str.unsetf(ios_base::unitbuf) and returns str.

      ios_base&
      nouppercase(ios_base&	str);
         Calls str.unsetf(ios_base::uppercase) and returns str.

      ios_base&
      oct(ios_base&	str);
         Calls str.setf(ios_base::oct, ios_base::basefield)	and returns str.

      ios_base&
      right(ios_base& str);
         Calls str.setf(ios_base::right, ios_base::adjustfield) and	returns
         str.

      ios_base&
      scientific(ios_base& str);
         Calls str.setf(ios_base::scientific, ios_base::floatfield)	and
         returns str.

      ios_base&
      showbase(ios_base& str);
         Calls str.setf(ios_base::showbase)	and returns str.

      ios_base&
      showpoint(ios_base& str);
         Calls str.setf(ios_base::showpoint) and returns str.

      ios_base&
      showpos(ios_base& str);
         Calls str.setf(ios_base::showpos) and returns str.

      ios_base&
      skipws(ios_base& str);
         Calls str.setf(ios_base::skipws) and returns str.

      ios_base&
      unitbuf(ios_base& str);
         Calls str.setf(ios_base::unitbuf) and returns str.

      ios_base&
      uppercase(ios_base& str);
         Calls str.setf(ios_base::uppercase) and returns str.

    SEE ALSO

      basic_ios, basic_istream, basic_ostream,
      char_traits

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.4.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    istringstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_istringstream

    SYNOPSIS

      #include <sstream>
      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_istringstream
      : public basic_istream<charT,	traits>

    DESCRIPTION

      The template class basic_istringstream<charT,traits,Allocator>
      provides functionality	to read	from an	array in memory. It
      supports reading objects of class
      basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
      object to control the	associated storage. It inherits	from
      basic_istream and therefore	can use	all the	formatted and
      unformatted input	functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_istringstream
      : public basic_istream<charT,	traits>	{

      public:

       typedef basic_stringbuf<charT, traits, Allocator>  sb_type;
       typedef basic_ios<charT, traits>		      ios_type;

       typedef basic_string<charT, traits, Allocator>     string_type;

       typedef traits			    traits_type;
       typedef charT			    char_type;
       typedef typename traits::int_type	    int_type;
       typedef typename traits::pos_type	    pos_type;
       typedef typename traits::off_type	    off_type;

       explicit basic_istringstream(ios_base::openmode which =
    				ios_base::in);

       explicit basic_istringstream(const string_type& str,
    				ios_base::openmode which =
    				ios_base::in);

       virtual ~basic_istringstream();

       basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
       string_type str() const;

       void	str(const string_type& str);

      };

    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.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      istringstream
         The type istringstream is an instantiation	of class
         basic_istringstream on	type char:

           typedef basic_istringstream<char> istringstream;

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      sb_type
         The type sb_type is an instantiation of class basic_stringbuf on
         type charT.

      string_type
         The type string_type is an	instantiation of class basic_string on
         type charT.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wistringstream
         The type wistringstream is	an instantiation of class
         basic_istringstream on	type wchar_t:

           typedef basic_istringstream<wchar_t> wistringstream;

    CONSTRUCTORS

      explicit basic_istringstream(ios_base::openmode which	=
    		     ios_base::in);
    	Constructs an object of	class basic_istringstream,
    	initializing the base class basic_istream with the
    	associated string buffer. The string buffer is ini-
    	tialized by calling the	basic_stringbuf	constructor
    	basic_stringbuf<charT,traits,Allocator>(which).

      explicit basic_istringstream(const string_type& str,
    		     ios_base::openmode	which =
    		     ios_base::in);
    	Constructs an object of	class basic_istringstream,
    	initializing the base class basic_istream with the
    	associated string buffer. The string buffer is ini-
    	tialized by calling the	basic_stringbuf	constructor
    	basic_stringbuf<charT,traits,Allocator>(str,which).

    DESTRUCTOR

      virtual ~basic_istringstream();
         Destroys an object	of class basic_istringstream.

    MEMBER FUNCTIONS

      basic_stringbuf<charT,traits,Allocator>*
      rdbuf() const;
         Returns a pointer to the basic_stringbuf associated with the
         stream.

      string_type
      str()	const;
         Returns a string object of	type string_type, which	contains a
         copy	of the underlying buffer contents.

      void
      str(const string_type& str);
         Clears the	string buffer and copies the string object str into
         it.	If the opening mode is in, initialize	the input
         sequence to point at the first character of	the buffer. If
         the opening mode	is out,	initialize the output	sequence to
         point at the first character of the	buffer.	If the opening
         mode is out | app, initialize the output sequence to point at
         the last character of the buffer.

    EXAMPLES

      //
      // stdlib/examples/manual/istringstream.cpp
      //
      #include<iostream>
      #include<sstream>
      #include<string>
      #include<iomanip>

      void main ( )
      {
       using namespace std;

       long	  l= 20;
       wchar_t *ntbs=L"Il avait l'air heureux";
       wchar_t c;
       wchar_t buf[50];

        // create a	read/write string-stream object	on wide	char
        // and attach it to	an wistringstream object
       wistringstream in(ios_base::in | ios_base::out);

        // tie the ostream object to the wistringstream object
       wostream out(in.rdbuf());

        // output ntbs in out
       out << ntbs;

        // output each word	on a separate line
       while ( in.get(c) )
         {
          if ( c ==	L' ' )
           wcout <<	endl;
          else
           wcout <<	c;
         }
       wcout << endl << endl;

        // move back the input sequence to the beginning
       in.seekg(0);

        // clear the state flags
       in.clear();

        // does the	same thing as the previous code
        // output each word	on a separate line
       while ( in >> buf )
        wcout << buf << endl;

       wcout << endl << endl;

        // create a	tiny string object
       string test_string("Il dormait pour l'eternite");

        // create a	read/write string-stream object	on char
        // and attach it to	an istringstream object
       istringstream in_bis(ios_base:: in |	ios_base::out |
    			ios_base::app );

        // create an ostream object
       ostream out_bis(in_bis.rdbuf());

        // initialize the string buffer with test_string
       in_bis.str(test_string);

       out_bis << endl;

        // output the base info before each	integer
       out_bis << showbase;

       ostream::pos_type pos= out_bis.tellp();

        // output l	in hex with a field with of 20
       out_bis << hex << setw(20) << l << endl;

        // output l	in oct with a field with of 20
       out_bis << oct << setw(20) << l << endl;

        // output l	in dec with a field with of 20
       out_bis << dec << setw(20) << l << endl;

        // output the all buffer
       cout	<< in_bis.rdbuf();

        // seek the	input sequence to pos
       in_bis.seekg(pos);

       int a,b,d;

        // read the	previous outputted integer
       in_bis >> a >> b >> d;

        // output 3	times 20
       cout	<< a <<	endl <<	b << endl << d << endl;

      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_stringbuf, basic_string,
      basic_ostringstream,	basic_stringstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.7.2

    STANDARDS CONFORMANC

      ANSI X3J16/ISO WG21 Joint C++	Committee

    istrstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      istrstream

    SYNOPSIS

      #include <strstream>
      class	istrstream
      : public basic_istream<char>

    DESCRIPTION

      The class istrstream provides	functionality to read characters from
      an array	in memory. It uses a private strstreambuf object to
      control the	associated array object. It inherits from
      basic_istream<char> and	therefore can use all the formatted
      and unformatted	input functions.

    INTERFACE

      class	istrstream : public basic_istream<char>	{

      public:

       typedef char_traits<char>		 traits;

       typedef char				char_type;
       typedef typename traits::int_type	int_type;
       typedef typename traits::pos_type	pos_type;
       typedef typename traits::off_type	off_type;

       explicit istrstream(const char *s);
       istrstream(const char *s, streamsize	n);
       explicit istrstream(char *s);
       istrstream(char *s, streamsize n);

       virtual ~istrstream();

       strstreambuf	*rdbuf() const;

       char	*str();

      };

    TYPES

      char_type
         The type char_type	is a synonym of	type char.

      int_type
         The type int_type is a synonym of type traits::in_type.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits
         The type traits is	a synonym of type char_traits<char>.

    CONSTRUCTORS

      explicit istrstream(const char* s);
      explicit istrstream(char* s);
         Constructs	an object of class istrstream, initializing the	base
         class basic_istream<char> with the associated strstreambuf
         object. The strstreambuf object is initialized	by calling
         strstreambuf(s,0), where s shall designate the first element of
         an NTBS.

      explicit istrstream(const char* s, streamsize	n);
      explicit istrstream(char* s, streamsize n);
         Constructs	an object of class istrstream, initializing the	base
         class basic_istream<char> with the associated strstreambuf
         object. The strstreambuf object is initialized	by calling
         strstreambuf(s,n), where s shall designate the first element of
         an array whose length	is n elements, and	n shall	be
         greater than	zero.

    DESTRUCTORS

      virtual ~istrstream();
         Destroys an object	of class istrstream.

    MEMBER FUNCTIONS

      char*
      str();
         Returns a pointer to the underlying array object which may
         be null.

      strstreambuf*
      rdbuf() const;
         Returns a pointer to the private strstreambuf object associated
         with the stream.

    EXAMPLES

      //
      // stdlib/examples/manual/istrstream.cpp
      //
      #include<iostream>
      #include<strstream>

      void main ( )
      {
       using namespace std;

       const char* p="C'est	pas l'homme qui	prend la mer, ";
       char* s="c'est la mer qui prend l'homme";

        // create an istrstream object and initialize
        // the underlying strstreambuf with	p
       istrstream in_first(p);

        // create an istrstream object and initialize
        // the underlying strstreambuf with	s
       istrstream in_next(s);

        // create an ostrstream object
       ostrstream out;

        // output the content of in_first and
        // in_next to out
       out << in_first.rdbuf() << in_next.str();

        // output the content of out to stdout
       cout	<< endl	<< out.rdbuf() << endl;

        // output the content of in_first to stdout
       cout	<< endl	<< in_first.str();

        // output the content of in_next to	stdout
       cout	<< endl	<< in_next.rdbuf() << endl;

      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      strstreambuf, ostrstream, strstream(3c++)

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Annex D
      Compatibility features Section D.6.2

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ofstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ofstream,ofstream

      This page describes the -ANSI	basic_ofstream class.  If you would
      like information on the pre-ANSI ofstream class, use the command:

           help cxxl

    SYNOPSIS

      #include <fstream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ofstream
      : public basic_ostream<charT,	traits>

    DESCRIPTION

      The template class basic_ofstream<charT,traits> supports writing
      into	named files	or other devices associated with a file
      descriptor. It uses a basic_filebuf	object to control the
      associated sequences. It inherits	from basic_ostream	and
      can	therefore use all the formatted	and unformatted	output
      functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ofstream
      : public basic_ostream<charT,	traits>	{

      public:

       typedef basic_ios<charT, traits>    ios_type;

       typedef charT		       char_type;
       typedef traits		       traits_type;
       typedef typename traits::int_type   int_type;
       typedef typename traits::pos_type   pos_type;
       typedef typename traits::off_type   off_type;

       basic_ofstream();

       explicit basic_ofstream(const char *s,
    			   ios_base::openmode mode =
    			   ios_base::out,
    			   long	protection = 0666);

       explicit basic_ofstream(int fd);

       basic_ofstream(int fd, char_type* buf, int len);

       virtual ~basic_ofstream();

       basic_filebuf<charT,	traits>	*rdbuf() const;

       bool	is_open();

       void	open(const char	*s, ios_base::openmode mode =
    	     ios_type::out, long protection = 0666);

       void	close();

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      ofstream
         The type ofstream is an instantiation of  class basic_ofstream on
         type char:

           typedef basic_ofstream<char> ofstream;

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wofstream
         The type wofstream	is an instantiation of class basic_ofstream on
         type wchar_t:

           typedef basic_ofstream<wchar_t> wofstream;

    CONSTRUCTORS

      basic_ofstream();
         Constructs	an object of class basic_ofstream<charT,traits>,
         initializing the base class basic_ostream with the associated
         file buffer, which is initialized by calling the	basic_filebuf
         constructor basic_filebuf<charT,traits>(). After construction a
         file can be attached to	the basic_oftream object using the
         open	member function.

      basic_ofstream(const char* s,
    		ios_base::openmode mode= ios_base::in,
    		long protection= 0666);
    	Constructs an object	of class
    	basic_ofstream<charT,traits>,  initializing the base	class
    	basic_ostream with the associated file buffer, which	is
    	initialized by calling the basic_filebuf constructor
    	basic_filebuf<charT,traits>(). The constructor then calls
    	the open function open(s,mode,protection) in	order to
    	attach the file whose name is pointed at by s, to the
    	basic_oftream object. The third argument, protection, is
    	used	as the file permissions. It does not appear in the
    	Standard C++	description and	is provided as an extension.
    	It determines the file read/write/execute permissions
    	under UNIX.	It is more limited under DOS since files are
    	always readable and do not have special execute permis-
    	sion.

      explicit basic_ofstream(int fd);
         Constructs	an object of class basic_ofstream<charT,traits>,
         initializing the base class	basic_ostream with the
         associated file buffer, which is	initialized by calling the
         basic_filebuf constructor basic_filebuf<charT,traits>(). The
         constructor then calls the basic_filebuf open	function
         open(fd) in order to attach the file descriptor	fd to the
         basic_oftream	 object. This constructor is not described in
         the C++ standard, and	is provided as an extension in order
         to	manipulate pipes, sockets or other UNIX	devices, that can be
         accessed through file descriptors. If the function fails, it sets
         ios_base::failbit.

      basic_ofstream(int fd, char_type* buf,int len);
         Constructs	an object of class basic_ofstream<charT,traits>,
         initializing the base class	basic_ostream with the
         associated file buffer, which is	initialized by calling the
         basic_filebuf constructor basic_filebuf<charT,traits>(). The
         constructor then calls the basic_filebuf open	function
         open(fd) in order to attach the file descriptor	fd to the
         basic_oftream	 object. The underlying	buffer is then
         replaced by calling the basic_filebuf	member function	setbuf
         with parameters	buf and	len. This constructor is not described
         in the C++ standard, and is provided as an extension in order
         to manipulate pipes, sockets or	other UNIX devices, that can
         be	accessed through file descriptors. It also maintains
         compatibility with the old iostreams library. If the function
         fails, it	sets ios_base::failbit.

    DESTRUCTOR

      virtual ~basic_ofstream();
         Destroys an object	of class basic_ofstream.

    MEMBER FUNCTIONS

      void
      close();
         Calls the associated basic_filebuf	function close() and if	this
         function fails, it calls the basic_ios member function
         setstate(failbit).

      bool
      is_open();
         Calls the associated basic_filebuf	function is_open() and return
         its result.

      void
      open(const char* s,ios_base::openmode	=
    	   ios_base::out, long protection = 0666);
         Calls the	associated basic_filebuf function
         open(s,mode,protection) and, if this function fails opening the
         file, calls the basic_ios	member function	setstate(failbit). The
         third	argument, protection, is used as the file permis-
         sions. It	does not appear	in the Standard	C++ description	and is
         provided as an	extension. It determines the file
         read/write/execute permissions under UNIX, and is	more limited
         under DOS	since files are	always readable	and do not have	spe-
         cial execute permission.

      basic_filebuf<charT,traits>*
      rdbuf() const;
         Returns a pointer to the basic_filebuf associated with the	stream.

    EXAMPLES

      See basic_fstream, basic_ifstream and	basic_filebuf examples.

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_filebuf, basic_ifstream, basic_fstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.8.1.8

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ostream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ostream

    SYNOPSIS

      #include <ostream>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_ostream
      : virtual public basic_ios<charT, traits>

    DESCRIPTION

      The class basic_ostream defines a number of member function
      signatures that assist in formatting and writing output to sequences
      controlled by a stream buffer.

      Two groups of	member function	signatures share common	properties:
      the formatted output	functions (or insertors) and the
      unformatted output functions. Both groups of	functions
      insert characters by calling basic_streambuf member functions. They
      both begin by constructing an object of class basic_ostream::sentry
      and, if this object is	in good	state after construction,
      the function tries to perform the requested output. The	sen-
      try object performs exception-safe initialization, such as
      controlling the status of the	stream or locking it in	multithread
      environment.

      Some formatted output	functions generate the requested output	by
      converting a value from some scalar to text form	and inserting
      the converted text in the output sequence. The conversion behavior
      is locale dependent, and directly depend on the locale	object
      imbued in the stream.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_ostream
      :virtual public basic_ios<charT, traits> {

      public:

       typedef basic_ostream<charT,	traits>	  ostream_type;
       typedef basic_ios<charT, traits>	  ios_type;

       typedef traits			  traits_type;
       typedef charT			  char_type;

       typedef typename traits::int_type	  int_type;
       typedef typename traits::pos_type	  pos_type;
       typedef typename traits::off_type	  off_type;

       explicit basic_ostream(basic_streambuf<charT, traits> *sb);
       virtual ~basic_ostream();

      class	sentry {

       public:

          explicit sentry(basic_ostream<charT,traits>&);
           ~sentry();
          operator bool ();

        };

       ostream_type& operator<<(ostream_type& (*pf)(ostream_type&));
       ostream_type& operator<<(ios_base& (*pf)(ios_base&));
       ostream_type& operator<<(ios_type& (*pf)(ios_type&));

       ostream_type& operator<<(bool n);
       ostream_type& operator<<(short n);
       ostream_type& operator<<(unsigned short n);
       ostream_type& operator<<(int	n);
       ostream_type& operator<<(unsigned int n);
       ostream_type& operator<<(long n);
       ostream_type& operator<<(unsigned long n);
       ostream_type& operator<<(float f);
       ostream_type& operator<<(double f);
       ostream_type& operator<<(long double	f);

       ostream_type& operator<<(void *p);

       ostream_type& operator<<(basic_streambuf<char_type, traits>&	sb);
       ostream_type& operator<<(basic_streambuf<char_type, traits> *sb);

       ostream_type& put(char_type c);

       ostream_type& write(const char_type *s, streamsize n);

       ostream_type& flush();

       ostream_type& seekp(pos_type	);
       ostream_type& seekp(off_type	, ios_base::seekdir );
       pos_type tellp();

      protected:

       basic_ostream();

      };

      //global functions

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, charT);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, char);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, char);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, const charT*);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>&, const char*);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, const	char*);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, unsigned char);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, signed char);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, const	unsigned char*);

      template <class traits>
      basic_ostream<char,traits>&
      operator<<(basic_ostream<char,traits>&, const	signed char*);

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      endl(basic_ostream<charT, traits>& os);

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      ends(basic_ostream<charT, traits>& os);

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      flush(basic_ostream<charT, traits>& os);

    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.

      ios_type
         The type ios_type is a synonym for	basic_ios<charT, traits>.

      off_type
         The type off_type is a synonym of type traits::off_type.

      ostream
         The type ostream is an instantiation of class basic_ostream on type
         char:

           typedef basic_ostream<char> ostream;

      ostream_type
         The type ostream_type is a	synonym	for basic_ostream<charT, traits>.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wostream
         The type wostream is an instantiation of class basic_ostream on type
         wchar_t:

           typedef basic_ostream<wchar_t> wostream;

    CONSTRUCTOR

      explicit basic_ostream(basic_streambuf<charT,	traits>* sb);
         Constructs	an object of class basic_ostream, assigning initial
         values to the base class by calling
         basic_ios<charT,traits>::init(sb).

    DESTRUCTOR

      virtual ~basic_ostream();
         Destroys an object	of class basic_ostream.

    SENTRY CLASS

      explicit sentry(basic_ostream<charT,traits>&);
         Prepares for formatted or unformatted output. First if the
         basic_ios member function tie() is not a null pointer, the
         function synchronizes the output	sequence with any associated
         stream. If	after any preparation is	completed the
         basic_ios	member function	good() is true,	the sentry conversion
         function operator bool () will return true. Otherwise it will
         return false. In multithread environment the sentry object
         constructor is	responsible for	locking	the stream and the
         stream buffer associated with the stream.

      ~sentry();
         Destroys an object	of class sentry. If the	ios_base member
         function flags() & unitbuf == true,	then flush the buffer.
         In multithread environment the sentry object destructor is
         responsible for unlocking the stream	and the	stream buffer
         associated with the stream.

      operator bool();
         If	after any preparation is completed the ios_base	member
         function good() is true, the sentry	conversion function
         operator bool() will return true else it will return false.

    INSERTORS

      ostream_type&
      operator<<(ostream_type& (*pf) (ostream_type&));
         Calls pf(*this), then return *this. See, for example, the
         function	signature endl(basic_ostream&).

      ostream_type&
      operator<<(ios_type& (*pf) (ios_type&));
         Calls pf(*this), then return *this.

      ostream_type&
      operator<<(ios_base& (*pf) (ios_base&));
         Calls pf(*this), then return *this. See, for example, the
         function	signature dec(ios_base&).

      ostream_type&
      operator<<(bool n);
         Converts the boolean value	n, and outputs it into the
         basic_ostream object's buffer. If the ios_base member function
         flag() & ios_base::boolalpha is false it tries to write an
         integer value, which must be 0 or 1. If	the boolalpha flag is
         true, it writes characters according to the locale function
         numpunct<>::truename() or numpunct<>::falsename().

      ostream_type&
      operator<<(short n);
         Converts the signed short integer n, and output it	into the
         stream buffer, then return *this.

      ostream_type&
      operator<<(unsigned short n);
         Converts the unsigned short integer n, and	output it into the
         stream buffer, then return *this.

      ostream_type&
      operator<<(int n);
         Converts the signed integer n, and	output it into the stream
         buffer, then return *this.

      ostream_type&
      operator<<(unsigned int n);
         Converts the unsigned integer n, and output it into the stream
         buffer, then return *this.

      ostream_type&
      operator<<(long n);
         Converts the signed long integer n, and output it into the	stream
         buffer, then return *this.

      ostream_type&
      operator<<(unsigned long n);
         Converts the unsigned long	integer	n, and output it into the
         stream buffer, then return *this.

      ostream_type&
      operator<<(float f);
         Converts the float	f and output it	into the stream	buffer,	then
         return *this.

      ostream_type&
      operator<<(double f);
         Converts the double f and output it into the stream buffer, then
         return *this.

      ostream_type&
      operator<<(long double f);
         Converts the long double f	and output it into the stream buffer,
         then return *this.

      ostream_type&
      operator<<(void *p);
         Converts the pointer p, and output	it into	the stream buffer,
         then return *this.

      ostream_type&
      operator<<(basic_streambuf<charT,traits> *sb);
         If	sb is null calls the basic_ios member function
         setstate(badbit). Otherwise gets characters from sb and
         inserts	them into the stream buffer until any of the
         following occurs:

         +	     end-of-file occurs	on the input sequence.

         +	     inserting in the output sequence fails

         +	     an	exception occurs while getting a character from	sb

         If	the function inserts no	characters or if it stopped because an
         exception was thrown while extracting a	character, it calls
         the	basic_ios member function setstate(failbit).	If an
         exception	was thrown while extracting	a character it is
         rethrown.

      ostream_type&
      operator<<(basic_streambuf<charT,traits>& sb);
         Gets characters from sb and inserts them into the stream buffer
         until any of the	following occurs:

         +	     end-of-file occurs	on the input sequence.

         +	     inserting in the output sequence fails

         +	     an	exception occurs while getting a character from	sb

         If	the function inserts no	characters or if it stopped because an
         exception was thrown while extracting a	character, it calls
         the	basic_ios member function setstate(failbit).	If an
         exception was thrown while extracting	a character it is
         rethrown.

    UNFORMATTED FUNCTIONS

      ostream_type&
      flush();
         If	rdbuf()	is not a null pointer, calls rdbuf()->pubsync()	and
         returns *this. If that function returns -1	calls
         setstate(badbit).

      ostream_type&
      put(char_type	c);
         Inserts the character c. If the operation fails, calls the
         basic_ios member function setstate(badbit).

      ostream_type&
      seekp(pos_type pos);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(pos), which will position the current pointer
         of the output sequence at	the position designated	by pos.

      ostream_type&
      seekp(off_type off, ios_base::seekdir	dir);
         If	the basic_ios member function fail() returns false, executes
         rdbuf()->pubseekpos(off,dir), which will position the current
         pointer of the output	sequence at the	position designated by
         off and dir.

      pos_type
      tellp();
         If	the basic_ios member function fail() returns true, tellp()
         returns pos_type(off_type(-1)) to indicate	failure. Otherwise it
         returns the current position of the output sequence by
         calling	rdbuf()-> pubseekoff(0,cur, out).

      ostream_type&
      write(const char_type* s, streamsize n);
         Obtains characters	to insert from successive locations of an
         array	whose first element is designated by s. Characters are
         inserted until either of	the following occurs:

         +	     n characters are inserted

         +	     inserting in the output sequence fails

         In	the second case	the function calls the basic_ios member
         function setstate(badbit). The function returns *this.

    NON MEMBER FUNCTIONS

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      endl(basic_ostream<charT, traits>& os);
         Outputs a newline character and flush the buffer, then returns
         os.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      ends(basic_ostream<charT, traits>& os);
         Inserts a null character into the output sequence,	then returns os.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      flush(basic_ostream<charT, traits>& os);
         Flushes the buffer, then returns os.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, charT c);
         Outputs the character c of	type charT into	the basic_ostream
         object's buffer. Both the stream and the stream buffer are
         instantiated on type charT. Padding is not ignored.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, char c);
         Outputs the character c of	type char into the basic_ostream
         object's buffer. Both the stream and the stream buffer are
         instantiated on type charT. Conversion from characters of type
         char to characters of type charT is performed	by the
         basic_ios member	function widen.	padding	is not ignored.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, char c);
         Outputs the character c of	type char into the basic_ostream
         object's buffer. Both the stream and the stream buffer are
         instantiated on type char. Padding is not ignored.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, const charT* s);
         Outputs the null-terminated-byte-string s of type charT* into the
         basic_ostream object's buffer. Both the stream and	the stream
         buffer are instantiated on type charT.

      template<class charT,	class traits>
      basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, const char* s);
         Outputs the null-terminated-byte-string s of type char* into the
         basic_ostream object's buffer. Both the stream and	the stream
         buffer are instantiated on type charT. Conversion from characters
         of type char to characters	of type	charT is performed by the
         basic_ios member function widen.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, const char* s);
         Outputs the null-terminated-byte-string s of type char* into the
         basic_ostream object's buffer. Both the stream and	the stream
         buffer are instantiated on type char.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, unsigned char c);
         Returns os	<< (char)c.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, signed char c);
         Returns os	<< (char)c.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, unsigned char* c);
         Returns os	<< (char*)c.

      template<class traits>
      basic_ostream<char, traits>&
      operator<<(basic_ostream<char, traits>& os, signed char* c);
         Returns os	<< (char*)c.

    FORMATTING

      The formatting is done through member	functions or manipulators.

      Manipulators		      Member Functions

      showpos		      setf(ios_base::showpos)
      noshowpos		      unsetf(ios_base::showpos)
      showbase		      setf(ios_base::showbase)
      noshowbase		      unsetf(ios_base::showbase)
      uppercase		      setf(ios_base::uppercase)
      nouppercase		      unsetf(ios_base::uppercase)
      showpoint		      setf(ios_base::showpoint)
      noshowpoint		      unsetf(ios_base::showpoint)
      boolalpha		      setf(ios_base::boolalpha)
      noboolalpha		      unsetf(ios_base::boolalpha)
      unitbuf		      setf(ios_base::unitbuf)
      nounitbuf		      unsetf(ios_base::unitbuf)
      internal		      setf(ios_base::internal,
    				 ios_base::adjustfield)
      left			      setf(ios_base::left,
    				 ios_base::adjustfield)
      right			      setf(ios_base::right,
    				 ios_base::adjustfield)
      dec			      setf(ios_base::dec,
    				 ios_base::basefield)
      hex			      setf(ios_base::hex,
    				 ios_base::basefield)
      oct			      setf(ios_base::oct,
    				 ios_base::basefield)
      fixed			      setf(ios_base::fixed,
    				 ios_base::floatfield)
      scientific		      setf(ios_base::scientific,
    				 ios_base::floatfield)
      resetiosflags
       (ios_base::fmtflags flag)  setf(0,flag)
      setiosflags
       (ios_base::fmtflags flag)  setf(flag)
      setbase(int base)	      See above
      setfill(char_type c)	      fill(c)
      setprecision(int n)	      precision(n)
      setw(int n)		      width(n)

    DESCRIPTION

      showpos   Generates a	+ sign in non-negative generated numeric output

      showbase   Generates a prefix	indicating the numeric base of generated
    	     integer output

      uppercase   Replaces certain lowercase letters with their uppercase
    	      equivalents in generated output

      showpoint   Generates	a decimal-point	character unconditionally in
                  generated floating-point output

      boolalpha   Insert and extract bool type in alphabetic format

      unitbuf   Flushes output after each output operation

      internal   Adds fill characters at a designated internal point in
                 certain generated output, or identical to right if	no such
                 point is designated

      left	 Adds fill characters on the right (final positions) of	certain
             generated	output

      right	  Adds fill characters on the left (initial positions) of certain
    	  generated output

      dec	Converts integer input or generates integer output in decimal
            base

      hex	Converts integer input or generates integer output in hexadecimal
    	base

      oct	Converts integer input or generates integer output in octal base

      fixed	  Generates floating-point output in fixed-point notation

      scientific   Generates floating-point	output in scientific notation

      resetiosflagss

      (ios_base::fmtflags flag)   Resets the fmtflags field	flag

      setiosflags

      (ios_base::fmtflags flag)   Set up the flag flag

      setbase(int base)   Converts integer input or	generates integer output
                          in base base. The parameter base can	be 8, 10
                          or 16.

      setfill(char_type c)	 Set the character used	to pad (fill) an output
    			 conversion to the specified field width

      setprecision(int n)	Set the	precision (number of digits after the
                            decimal point) to generate on certain output
                            conversions

      setw(int n)	Set the	field with (number of characters) to generate on
                    certain output conversions

    EXAMPLES

      //
      // stdlib/examples/manual/ostream1.cpp
      //
      #include<iostream>
      #include<ostream>
      #include<sstream>
      #include<iomanip>

      void main ( )
      {
        using namespace std;

        float f= 3.14159;
        int	  i= 22;
        char* s= "Randy is the king	of stdlib";

         //	create a read/write stringbuf object on	tiny char
         //	and attach it to an istringstream object
        istringstream in( ios_base::in | ios_base::out );

         //	tie the	ostream	object to the istringstream object
        ostream out(in.rdbuf());

        out	<< "test beginning !" << endl;

         //	output i in hexadecimal
        out	<< hex << i <<endl;

         //	set the	field width to 10
         //	set the	padding	character to '@'
         //	and output i in	octal
        out	<< setw(10) << oct << setfill('@') << i	<< endl;

         //	set the	precision to 2 digits after the	separator
         //	output f
        out	<< setprecision(3) << f	<< endl;

         //	output the 17 first characters of s
        out.write(s,17);

         //	output a newline character
        out.put('0);

         //	output s
        out	<< s <<	endl;

         //	output the all buffer to standard output
        cout << in.rdbuf();
      }

      //
      // stdlib/examples/manual/ostream2.cpp
      //
      #include<iostream>
      #include<ostream>
      #include<sstream>

      void main ( )
      {
        using namespace std;

        float f= 3.14159;
        wchar_t* s=	L"Kenavo !";

         //	create a read/write stringbuf object on	wide char
         //	and attach it to an wistringstream object
        wistringstream in( ios_base::in | ios_base::out );

         //	tie the	wostream object	to the wistringstream object
        wostream out(in.rdbuf());

        out	<< L"test beginning !" << endl;

         //	output f in scientific format
        out	<< scientific << f <<endl;

         //	store the current put-pointer position
        wostream::pos_type pos = out.tellp();

         //	output s
        out	<< s <<	endl;

         //	output the all buffer to standard output
        wcout << in.rdbuf()	<< endl;

         //	position the get-pointer
        in.seekg(pos);

         //	output s
        wcout << in.rdbuf()	<< endl;
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_iostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.6.2.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ostringstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_ostringstream

    SYNOPSIS

      #include <sstream>
      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_ostringstream
      : public basic_ostream<charT,	traits>

    DESCRIPTION

      The template class basic_ostringstream<charT,traits,Allocator>
      provides functionality	to write to an array in	memory.	It
      supports writing objects of class
      basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
      object to control the	associated storage. It inherits	from
      basic_ostream and therefore	can use	all the	formatted and
      unformatted output functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_ostringstream
      : public basic_ostream<charT,	traits>	{

      public:

       typedef basic_stringbuf<charT, traits, Allocator> sb_type;
       typedef basic_ios<charT, traits>		     ios_type;

       typedef basic_string<charT, traits, Allocator>    string_type;

       typedef traits			    traits_type;
       typedef charT			    char_type;
       typedef typename traits::int_type	    int_type;
       typedef typename traits::pos_type	    pos_type;
       typedef typename traits::off_type	    off_type;

       explicit basic_ostringstream(ios_base::openmode which =
    				ios_base::out);

       explicit basic_ostringstream(const string_type& str,
    				ios_base::openmode which =
    				ios_base::out);

       virtual ~basic_ostringstream();

       basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
       string_type str() const;

       void	str(const string_type& str);

      };

    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.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      ostringstream
         The type ostringstream is an instantiation	of class
         basic_ostringstream on	type char:

           typedef basic_ostringstream<char> ostringstream;

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      sb_type
         The type sb_type is an instantiation of class basic_stringbuf
         on type charT.

      string_type
         The type string_type is an	instantiation of class basic_string
         on type charT.

      traits_type
         The type traits_type is a synonym for the template	parameter
         traits.

      wostringstream
         The type wostringstream is	an instantiation of class
         basic_ostringstream on	type wchar_t:

           typedef basic_ostringstream<wchar_t> wostringstream;

    CONSTRUCTORS

      explicit basic_ostringstream(ios_base::openmode which	=
    			      ios_base::out);
    	Constructs an object of class
    	basic_ostringstream, initializing the base
    	class basic_ostream with the associated
    	string	buffer.	The string buffer is initial-
    	ized by calling the basic_stringbuf con-
    	structor
    	basic_stringbuf<charT,traits,Allocator>(which).

      explicit basic_ostringstream(const string_type& str,
    			      ios_base::openmode which =
    			      ios_base::out);
    	Constructs an object of class
    	basic_ostringstream, initializing the base
    	class basic_ostream with the associated
    	string	buffer.	The string buffer is initial-
    	ized by calling the basic_stringbuf con-
    	structor
    	basic_stringbuf<charT,traits,Allocator>(str,which).

    DESTRUCTOR

      virtual ~basic_ostringstream();
         Destroys an object	of class basic_ostringstream.

    MEMBER FUNCTIONS

      basic_stringbuf<charT,traits,Allocator>*
      rdbuf() const;
         Returns a pointer to the basic_stringbuf associated with the
         stream.

      string_type
      str()	const;
         Returns a string object of	type string_type whose contents	is a
         copy of the underlying buffer contents.

      void
      str(const string_type& str);
         Clears the	underlying string buffer and copies the	string object
         str into it. If the opening mode is in, initialize the	input
         sequence to point at the first	character of the buffer. If
         the	opening	mode is	out, initialize	the output sequence to
         point at	the first character of the buffer. If	the opening
         mode is out	| app, initialize the output sequence to
         point at the last character of the buffer.

    EXAMPLES

      See basic_stringstream, basic_istringstream and basic_stringbuf
      examples.

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_stringbuf, basic_string,
      basic_istringstream,	basic_stringstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.7.2.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ostrstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      ostrstream

    SYNOPSIS

      #include <strstream>
      class	ostrstream
      : public basic_ostream<char>

    DESCRIPTION

      The class ostrstream provides	functionality to write to an array in
      memory. It uses a private strstreambuf object	to control the
      associated array object. It inherits from basic_ostream<char> and
      therefore can use all the formatted and	unformatted output
      functions.

    INTERFACE

      class	ostrstream
      : public basic_ostream<char> {

      public:

       typedef char_traits<char>		 traits;

       typedef char				char_type;
       typedef typename traits::int_type	int_type;
       typedef typename traits::pos_type	pos_type;
       typedef typename traits::off_type	off_type;

       ostrstream();
       ostrstream(char *s, int n,
    	      ios_base::openmode = ios_base::out);

       virtual ~ostrstream();

       strstreambuf	*rdbuf() const;

       void	freeze(int freezefl = 1);

       char	*str();

       int pcount()	const;

      };

    TYPES

      char_type
         The type char_type	is a synonym of	type char.

      int_type
         The type int_type is a synonym of type traits::in_type.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits
         The type traits is	a synonym of type char_traits<char>.

    CONSTRUCTORS

      ostrstream();

         Constructs	an object of class ostrstream, initializing the	base
         class basic_ostream<char> with the associated strstreambuf
         object. The strstreambuf object is initialized	by calling its
         default constructor strstreambuf().

      ostrstream(char* s,int n, ios_base::openmode
    	    mode = ios_base::out);
         Constructs an object of class ostrstream, initializing the base
         class basic_ostream<char> with the associated strstreambuf
         object. The strstreambuf object is initialized by calling one of
         two constructors:

    	       +       if mode & app ==	0 calls	strstreambuf(s,n,s)

    	       +       Otherwise calls strstreambuf(s,n,s + ::strlen(s))

    DESTRUCTOR

      virtual ~ostrstream();
         Destroys an object	of class ostrstream.

    MEMBER FUNCTIONS

      void
      freeze(bool freezefl = 1);
         If	the mode is dynamic, alters the	freeze status of the dynamic
         array object as follows:

         +	     If	freezefl is false, the function	sets the freeze	status
              to frozen.

         +	     Otherwise,	it clears the freeze status.

      int
      pcount() const;
         Returns the size of the output sequence.

      strstreambuf*
      rdbuf() const;
         Returns a pointer to the private strstreambuf object associated
         with the stream.

      char*
      str();
         Returns a pointer to the underlying array object which may	be null.

    EXAMPLES

      See strstream, istrstream and	strstreambuf examples.

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      strstreambuf, istrstream, strstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Annex D
      Compatibility features Section D.6.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    smanip
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      smanip, smanip_fill

    SYNOPSIS

      #include <iomanip>
      template<class T> class smanip;
      template<class T, class traits> class	smanip_fill;

    DESCRIPTION

      The template classes smanip and smanip_fill are helper classes used
      to implement parameterized manipulators.	The class smanip is
      used as the return type for manipulators that do not need	to
      carry information about the character	type of	the stream they	are
      applied to.	This is	the case for resetiosflags, setiosflags,
      setbase, setprecision and	setw. The class smanip_fill is used as
      the return type for manipulators that do need to carry
      information about the character	type of	the stream they	are
      applied to. This is the case for setfill.

    INTERFACE

      template<class T>
      class	smanip {

      public:

       smanip(ios_base& (*pf) (ios_base&, T), T manarg);

      };

      template<class T, class traits>
      class	smanip_fill {

      public:

       smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T, traits>&,
    	       T), T manarg);

      };

      // parameterized manipulators

      smanip<ios_base::fmtflags> resetiosflag(ios_base::fmtflags mask);
      smanip<ios_base::fmtflags> setiosflag(ios_base::fmtflags mask);
      smanip<int>		     setbase(int base);
      smanip<int>		     setprecision(int n);
      smanip<int>		     setw(int n);

      template <class charT>
      smanip_fill<charT, char_traits<charT>	> setfill(charT	c);

      // overloaded	extractors

      template <class charT, class traits, class T>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);

      template <class charT, class traits>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is,
      const	smanip_fill<charT,char_traits<charT> >&	a);

      // overloaded	insertors

      template <class charT, class traits, class T>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>& is, const smanip<T>& a);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator>>(basic_ostream<charT,traits>& is,
      const	smanip_fill<charT,char_traits<charT> >&	a);

    CLASS SMANIP CONSTRUCTOR

      smanip(ios_base& (*pf) (ios_base&, T), T manarg);
         Constructs	an object of class smanip that stores a	function
         pointer pf, that will be called with argument manarg, in order
         to perform the manipulator task. The call to pf is performed in
         the insertor or extractor overloaded	on type	smanip.

    CLASS SMANIP_FILL CONSTRUCTOR

      smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T,	traits>&,T), T
      manarg);
         Constructs	an object of class smanip_fill that stores a function
         pointer pf, that will be called with argument manarg, in order to
         perform the manipulator task. The call	to pf is performed in
         the insertor or extractor overloaded on type smanip_fill.

    MANIPULATORS

      smanip<ios_base::fmtflags>
      resetiosflag(ios_base::fmtflags mask);
         Resets the	ios_base::fmtflags designated by mask in the stream to
         which it	is applied.

      smanip<int>
      setbase(int base);
         Sets the base for the output or input of integer values in	the
         stream to which it is applied. The valid values for mask are
         8, 10, 16.

      template <class charT>
      smanip_fill<charT, char_traits<charT>	>
      setfill(charT	c);
         Sets the fill character in	the stream it is applied to.

      smanip<ios_base::fmtflags>
      setiosflag(ios_base::fmtflags	mask);
         Sets the ios_base::fmtflags designated by mask in the stream it
         is applied to.

      smanip<int>
      setprecision(int n);
         Sets the precision	for the	output of floating point values	in the
         stream to	which it is applied.

      smanip<int>
      setw(int n);
         Set the field width in the	stream to which	it is applied.

    EXTRACTORS

      template <class charT, class traits, class T>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);
         Applies the function stored in the	parameter of type smanip<T>,
         on	the stream is.

      template <class charT, class traits>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is,
    	    const smanip_fill<charT,char_traits<charT> >& a);
         Applies the function stored in the parameter of type
         smanip_fill<charT, char_traits<charT> >,	on the stream is.

    INSERTORS

      template <class charT, class traits, class T>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>& os, const smanip<T>& a);
         Applies the function stored in the	parameter of type smanip<T>,
         on	the stream os.

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>& os,
    	    const smanip_fill<charT,char_traits<charT> >& a);
         Applies the function stored in the parameter of type
         smanip_fill<charT, char_traits<charT> >,	on the stream os.

    SEE ALSO

      ios_base, basic_ios, basic_istream,
      basic_ostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.6.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    smanip_fill
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      smanip, smanip_fill

    SYNOPSIS

      #include <iomanip>
      template<class T> class smanip;
      template<class T, class traits> class	smanip_fill;

    DESCRIPTION

      The template classes smanip and smanip_fill are helper classes used
      to implement parameterized manipulators.	The class smanip is
      used as the return type for manipulators that do not need	to
      carry information about the character	type of	the stream they	are
      applied to.	This is	the case for resetiosflags, setiosflags,
      setbase, setprecision and	setw. The class smanip_fill is used as
      the return type for manipulators that do need to carry
      information about the character	type of	the stream they	are
      applied to. This is the case for setfill.

    INTERFACE

      template<class T>
      class	smanip {

      public:

       smanip(ios_base& (*pf) (ios_base&, T), T manarg);

      };

      template<class T, class traits>
      class	smanip_fill {

      public:

       smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T, traits>&,
    	       T), T manarg);

      };

      // parameterized manipulators

      smanip<ios_base::fmtflags> resetiosflag(ios_base::fmtflags mask);
      smanip<ios_base::fmtflags> setiosflag(ios_base::fmtflags mask);
      smanip<int>		     setbase(int base);
      smanip<int>		     setprecision(int n);
      smanip<int>		     setw(int n);

      template <class charT>
      smanip_fill<charT, char_traits<charT>	> setfill(charT	c);

      // overloaded	extractors

      template <class charT, class traits, class T>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);

      template <class charT, class traits>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is,
      const	smanip_fill<charT,char_traits<charT> >&	a);

      // overloaded	insertors

      template <class charT, class traits, class T>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>& is, const smanip<T>& a);

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator>>(basic_ostream<charT,traits>& is,
      const	smanip_fill<charT,char_traits<charT> >&	a);

    CLASS SMANIP CONSTRUCTOR

      smanip(ios_base& (*pf) (ios_base&, T), T manarg);
         Constructs	an object of class smanip that stores a	function
         pointer pf, that will be called with argument manarg, in order
         to perform the manipulator task. The call to pf is performed in
         the insertor or extractor overloaded	on type	smanip.

    CLASS SMANIP_FILL CONSTRUCTOR

      smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T,	traits>&,T), T
      manarg);
         Constructs	an object of class smanip_fill that stores a function
         pointer pf, that will be called with argument manarg, in order to
         perform the manipulator task. The call	to pf is performed in
         the insertor or extractor overloaded on type smanip_fill.

    MANIPULATORS

      smanip<ios_base::fmtflags>
      resetiosflag(ios_base::fmtflags mask);
         Resets the	ios_base::fmtflags designated by mask in the stream to
         which it	is applied.

      smanip<int>
      setbase(int base);
         Sets the base for the output or input of integer values in	the
         stream to which it is applied. The valid values for mask are
         8, 10, 16.

      template <class charT>
      smanip_fill<charT, char_traits<charT>	>
      setfill(charT	c);
         Sets the fill character in	the stream it is applied to.

      smanip<ios_base::fmtflags>
      setiosflag(ios_base::fmtflags	mask);
         Sets the ios_base::fmtflags designated by mask in the stream it
         is applied to.

      smanip<int>
      setprecision(int n);
         Sets the precision	for the	output of floating point values	in the
         stream to	which it is applied.

      smanip<int>
      setw(int n);
         Set the field width in the	stream to which	it is applied.

    EXTRACTORS

      template <class charT, class traits, class T>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);
         Applies the function stored in the	parameter of type smanip<T>,
         on	the stream is.

      template <class charT, class traits>
      basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is,
    	    const smanip_fill<charT,char_traits<charT> >& a);
         Applies the function stored in the parameter of type
         smanip_fill<charT, char_traits<charT> >,	on the stream is.

    INSERTORS

      template <class charT, class traits, class T>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>& os, const smanip<T>& a);
         Applies the function stored in the	parameter of type smanip<T>,
         on	the stream os.

      template <class charT, class traits>
      basic_ostream<charT,traits>&
      operator<<(basic_ostream<charT,traits>& os,
    	    const smanip_fill<charT,char_traits<charT> >& a);
         Applies the function stored in the parameter of type
         smanip_fill<charT, char_traits<charT> >,	on the stream os.

    SEE ALSO

      ios_base, basic_ios, basic_istream,
      basic_ostream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.6.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    streambuf
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_streambuf,streambuf

      This page describes the ANSI streambuf class.	 If you	would like
      information on the pre-ANSI streambuf class,	use the
      command:

           help cxxl

    SYNOPSIS

      #include <streambuf>
      template<class charT,	class traits = char_traits<charT> >
      class	basic_streambuf;

    DESCRIPTION

      The class template basic_streambuf<charT,traits> serves as an
      abstract base class	for deriving various stream buffers whose
      objects each control two character sequences:

      +	  A character input sequence;

      +	  A character output sequence.

      Each sequence	is characterized by three pointers which, if non-null,
      all point	into the same charT array object. The array object
      represents, at any moment, a subsequence	of characters from the
      sequence. Operations performed on a sequence	alter the values
      stored	in these pointers, perform reads and writes directly
      to or	from associated	sequences, and alter "the stream position" and
      conversion state as needed to maintain this subsequence	rela-
      tionship. The	three pointers are:

      +	  The beginning	pointer, or lowest element address in the array;

      +	  The next pointer, or next element address that is a current
           candidate for	reading	or writing;

      +	  The end pointer, or first element address beyond the end of the
           array.

      Stream buffers can impose various constraints	on the sequences they
      control,	including:

      +	  The controlled input sequence	may be unreadable;

      +	  The controlled output	sequence may be	unwritable;

      +	  The controlled sequences can be associated with the contents of
           other representations for character sequences, such as external
           files;

      +	  The controlled sequences can impose limitations on how the
           program can read	characters from	a sequence, write characters to
           a sequence, put characters back into	an input sequence, or alter
           the	stream position.

    INTERFACE

      template<class charT,	class traits = char_traits<charT> >
      class	basic_streambuf	{

      public:

      typedef charT			      char_type;
      typedef traits		      traits_type;

      typedef typename traits::int_type    int_type;
      typedef typename traits::pos_type    pos_type;
      typedef typename traits::off_type    off_type;

      virtual ~basic_streambuf();

      locale pubimbue( const locale& loc);
      locale getloc() const;

      basic_streambuf<char_type, traits> *
        pubsetbuf(char_type	*s, streamsize n);

      pos_type pubseekoff(off_type off, ios_base::seekdir way,
    		      ios_base::openmode which =
    		      ios_base::in | ios_base::out);

      pos_type pubseekpos(pos_type sp, ios_base::openmode which =
    		      ios_base::in | ios_base::out);

      int pubsync();

      ios_base::openmode which_open_mode();

      streamsize   in_avail();

      int_type snextc();

      int_type sbumpc();

      int_type sgetc();

      streamsize sgetn(char_type *s, streamsize n);

      int_type sputbackc(char_type c);

      int sungetc();

      int_type sputc(char_type c);

      streamsize sputn(const char_type *s, streamsize n);

      protected:

      basic_streambuf();

      char_type *eback() const;
      char_type *gptr() const;
      char_type *egptr() const;

      void gbump(int n);

      void setg(char_type *gbeg_arg,char_type *gnext_arg,
    	    char_type *gend_arg);

      char_type *pbase() const;
      char_type *pptr() const;
      char_type *epptr() const;

      void pbump(int n);

      void setp(char_type *pbeg_arg,char_type *pend_arg);

      virtual void imbue( const locale& loc);

      virtual int_type overflow(int_type c = traits::eof());

      virtual int_type pbackfail(int_type c	= traits::eof());

      virtual int showmanyc();

      virtual int_type underflow();

      virtual int_type uflow();

      virtual streamsize xsgetn(char_type *s, streamsize n);

      virtual streamsize xsputn(const char_type *s,	streamsize n);

      virtual pos_type seekoff(off_type off,ios_base::seekdir way,
    			   ios_base::openmode which =
    			   ios_base::in	| ios_base::out);

      virtual pos_type seekpos(pos_type sp,ios_base::openmode which	=
    			   ios_base::in	| ios_base::out);

      virtual basic_streambuf<charT, traits>*
        setbuf(char_type *s, streamsize n);

      virtual int sync();

      };

    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.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      streambuf
         The type streambuf	is an instantiation of class basic_streambuf
         on	type char:

           typedef basic_streambuf<char> streambuf;

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wstreambuf
         The type wstreambuf is an instantiation of	 class basic_streambuf on
         type wchar_t:

           typedef basic_streambuf<wchar_t>	wstreambuf;

    PUBLIC CONSTRUCTOR

      basic_streambuf();
         Constructs	an object of class basic_streambuf and initializes all
         its pointer member objects to null pointers and the getloc()
         member function to	return the value of locale::locale().

    PUBLIC DESTRUCTOR

      virtual ~basic_streambuf();
         Destroys an object	of class basic_streambuf.

    PUBLIC MEMBER FUNCTIONS

      locale
      getloc() const;
         If	pubimbue() has ever been called, returns the last value	of loc
         supplied, otherwise, the default locale locale::locale() in
         effect at	the time of construction.

      streamsize
      in_avail();
         If	a read position	is available, returns the number of available
         character in the	input sequence.	Otherwise calls	the protected
         function showmanyc().

      locale
      pubimbue(const locale& loc);
         Calls the protected function imbue(loc).

      pos_type
      pubseekoff(off_type off, ios_base::seekdir way,
    	    ios_base::openmode which =
    	    ios_base::in | ios_base::out );
    	       Calls the protected function seekoff(off,way,which).

      pos_type
      pubseekpos(pos_type sp, ios_base::openmode which=
    	    ios_base::in | ios_base::out );
    	       Calls the protected function seekpos(sp,which).

      basic_streambuf<char_type,traits>*
      pubsetbuf(char_type* s,streamsize n);
         Calls the protected function setbuf(s,n) .

      int
      pubsync();
         Calls the protected function sync().

      int_type
      sbumpc();
         If	the input sequence read	position is not	available, calls the
         function uflow(), otherwise	returns	*gptr()	and increments
         the next	pointer	for the input sequence.

      int_type
      sgetc();
         If	the input sequence read	position is not	available, calls the
         protected function underflow(), otherwise returns *gptr() .

      streamsize
      sgetn(char_type* s, streamsize n);
         Calls the protected function xsgetn(s,n).

      int_type
      snextc();
         Calls the function	sbumpc() and if	it returns traits::eof(),
         returns traits::eof(); otherwise calls the	function sgetc() .

      int_type
      sputbackc(char_type c);
         If	the input sequence putback position is not available, or if
         traits::eq(c,gptr() [-1]) returns false, calls the	protected
         function pbackfail(c), otherwise decrements	the next
         pointer for the input sequence and returns *gptr().

      int_type
      sputc(char_type c);
         If	the output sequence write position is not available, calls the
         protected function overflow(traits::to_int_type( c )).
         Otherwise, stores c at	the next pointer for the output
         sequence, increments the pointer, and returns *pptr() .

      streamsize
      sputn(const char_type* s, streamsize n);
         Calls the protected function xsputn(s,n).

      int_type
      sungetc();
         If	the input sequence putback position is not available, calls
         the	protected function pbackfail(). Otherwise decrements
         the next	pointer	for the input sequence	and returns *gptr().

      ios_base::openmode
      which_open_mode();
         Returns the mode in which the stream buffer is opened. This
         function is not described in the C++ standard.

    PROTECTED MEMBER FUNCTIONS

      char_type*
      eback() const;
         Returns the beginning pointer for the input sequence.

      char_type*
      egptr() const;
         Returns the end pointer for the input sequence.

      char_type*
      epptr() const;
         Returns the end pointer for the output sequence.

      void
      gbump(int n);
         Advances the next pointer for the input sequence by n.

      char_type*
      gptr() const;
         Returns the next pointer for the input sequence.

      void
      imbue(const locale&);
         Changes any translations based on locale. The default behavior is
         to do nothing, this function has	to be overloaded in the
         classes	derived	from basic_streambuf. The purpose of this
         function is to allow the derived class to be informed of changes
         in	locale at the time they	occur. The new imbued	locale object
         is only used by the stream buffer, it does not affect the	stream
         itself.

      int_type
      overflow(int_type c =	traits::eof() );
         The member	functions sputc() and sputn() call this	function in
         case that not enough	room can be found in the put buffer to
         accommodate the argument character sequence. The function
         returns traits::eof() if it fails to	make more room
         available, or to	empty the buffer by writing the characters
         to their output	device.

      int_type
      pbackfail(int_type c = traits::eof() );
         If	c is equal to traits::eof(), gptr() is moved back one position
         otherwise c is prepended. The function returns traits::eof() to
         indicate failure.

      char_type*
      pbase() const;
         Returns the beginning pointer for the output sequence.

      void
      pbump(int n);
         Advances the next pointer for the output sequence by n.

      char_type*
      pptr() const;
         Returns the next pointer for the output sequence.

      pos_type
      seekoff(off_type off,	ios_base::seekdir way,
    	 ios_base::openmode which =
    	 ios_base::in |	ios_base::out );
         Alters the stream positions within one or more of the
         controlled sequences in a way that is defined separately for each
         class derived from basic_streambuf. The default behavior is to
         return an object of type pos_type that stores an invalid stream
         position.

      pos_type
      seekpos(pos_type sp, ios_base::openmode which=
    	 ios_base::in |	ios_base::out );
         Alters the stream positions within one or more of the
         controlled sequences in a way that is defined separately for each
         class derived from basic_streambuf. The default behavior is to
         return an object of class pos_type	that stores an invalid stream
         position.

      basic_streambuf*
      setbuf(char_type* s, streamsize n);
         Performs an operation that	is defined separately for each class
         derived from basic_streambuf. The purpose of this function	is to
         allow the	user to	provide	his own	buffer,	or to resize the
         current buffer.

      void
      setg(char_type* gbeg,	char_type* gnext, char_type* gend);
         Sets up private member for	the following to be true:

         eback() ==	gbeg, gptr() ==	gnext and egptr() == gend

      void
      setp(char_type* pbeg,	char_type* pend);
         Sets up private member for	the following to be true:

         pbase() ==	pbeg, pptr() ==	pbeg and epptr() == pend

      int
      showmanyc();
         Returns the number	of characters available	in the internal
         buffer,	or -1.

      int
      sync();
         Synchronizes the controlled sequences with	the internal buffer,
         in	a way that is defined separately	for each class derived
         from basic_streambuf. The default behavior is to	do nothing. On
         failure the return value	is -1.

      int_type
      underflow();
         The public	members	of basic_streambuf call	this function only if
         gptr() is	null or	gptr() >= egptr(). This	function returns the
         character pointed at	by gptr() if gptr() is not null	and if
         gptr() <	egptr(). Otherwise the	function try to	read
         character into the	buffer,	and if it fails return traits::eof().

      int_type
      uflow();
         Calls underflow() and if underflow() returns traits::eof(),
         returns traits::eof(). Otherwise, does gbump(1) and returns the
         value of *gptr().

      streamsize
      xsgetn(char_type* s, streamsize n);
         Assigns up	to n characters	to successive elements of the array
         whose first element is designated by s. The characters are read
         from the	input sequence. Assigning stops when either n
         characters	have been assigned or a call to sbumpc()	would
         return traits::eof(). The	function returns the number of
         characters read.

      streamsize
      xsputn(const char_type* s, streamsize	n);
         Writes up to n characters to the output sequence. The characters
         written are obtained from successive elements of the array	whose
         first element is	designated by s. Writing stops when either n
         characters	have been written or	a call to sputc() would	return
         traits::eof(). The function returns the number	of characters
         written.

    SEE ALSO

      char_traits,	basic_filebuf,	basic_stringbuf,
      strstreambuf

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.5

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    stringbuf
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_stringbuf

    SYNOPSIS

      #include <sstream>
      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_stringbuf
      : public basic_streambuf<charT, traits>

    DESCRIPTION

      The class basic_stringbuf is derived from basic_streambuf.  Its
      purpose is to associate the input or output sequence with a sequence
      of arbitrary characters.  The sequence can	be initialized from,
      or	made available as, an object of class basic_string.	Each
      object of type basic_stringbuf<charT, traits,Allocator> controls two
      character sequences:

      +	  A character input sequence;

      +	  A character output sequence.

      Note:	see basic_streambuf.

      The two sequences are	related	to each	other, but are manipulated
      separately. This allows you to read and write	characters at
      different	positions	in objects of type basic_stringbuf
      without any conflict	(as opposed to the basic_filebuf objects,
      in which a joint file position is maintained).

    INTERFACE

      template<class charT,	class traits = char_traits<charT>,
    	  class	allocator<void>	>
      class	basic_stringbuf
      : public basic_streambuf<charT, traits> {

       public:

        typedef basic_ios<charT, traits>	 ios_type;

        typedef basic_string<charT,	traits,
    			 Allocator>	 string_type;

        typedef charT			 char_type;
        typedef typename traits::int_type	 int_type;
        typedef typename traits::pos_type	 pos_type;
        typedef typename traits::off_type	 off_type;

        explicit basic_stringbuf(ios_base::openmode	which =
    			      (ios_base::in | ios_base::out));

        explicit basic_stringbuf(const string_type&	str,
    			     ios_base::openmode	which =
    			      (ios_base::in | ios_base::out));

        virtual ~basic_stringbuf();

        string_type	str() const;
        void str(const string_type&	str_arg);

      protected:

        virtual int_type overflow(int_type c = traits::eof());

        virtual int_type pbackfail(int_type	c = traits::eof());

        virtual int_type underflow();

        virtual basic_streambuf<charT,traits>*
         setbuf(char_type *s,streamsize n);

        virtual pos_type seekoff(off_type off, ios_base::seekdir way,
    			     ios_base::openmode	which =
    			     ios_base::in | ios_base::out);

        virtual pos_type seekpos(pos_type sp,
    			     ios_base::openmode	which =
    			     ios_base::in | ios_base::out);

        virtual streamsize xsputn(const char_type* s, streamsize n);

      };

    TYPES

      char_type
         The type char_type	is a synonym for the template parameter	charT.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      string_type
         The type string_type is an	instantiation of class basic_string on
         type charT.

      stringbuf
         The type stringbuf	is an instantiation of class basic_stringbuf
         on	type char:

         typedef basic_stringbuf<char> stringbuf;

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wstringbuf
         The type wstringbuf is an instantiation of	class basic_stringbuf on
         type wchar_t:

         typedef basic_stringbuf<wchar_t> wstringbuf;

    CONSTRUCTORS

      explicit basic_stringbuf(ios_base::openmode which =
    		 ios_base::in |	ios_base::out);
         Constructs an object of class basic_stringbuf, initializing
         the base class with basic_streambuf(), and initializing	the
         open mode with which.

      explicit basic_stringbuf(const string_type& str,
    		 ios_base::openmode which =
    		 ios_base::in |	ios_base::out);
         Constructs an object of class basic_stringbuf, initializing
         the base class with basic_streambuf(), and initializing	the
         open mode with which. The string object str	is copied to
         the  underlying buffer. If the opening mode is in,	initialize the
         input sequence to point at the first character of the buffer. If
         the opening mode is out, it initializes	the output sequence to
         point at	the first character of the buffer. If	the opening
         mode is out	| app, it initializes	the output sequence to
         point at	the last character of the buffer.

    DESTRUCTOR

      virtual ~basic_stringbuf();
         Destroys an object	of class basic_stringbuf.

    MEMBER FUNCTIONS

      int_type
      overflow(int_type c =	traits::eof() );
         If	the output sequence has	a put position available, and c	is not
         traits::eof(), then this functions	writes c into it. If there is
         no position available, the function increases	the size of
         the	buffer by allocating	more memory and	then writes c
         at the new current put position. If the operation fails, the
         function	returns	traits::eof(). Otherwise it returns
         traits::not_eof(c).

      int_type
      pbackfail( int_type c	= traits::eof()	);
         Puts back the character designated	by c into the input sequence.
         If traits::eq_int_type(c,traits::eof()) returns true,	the
         function moves the input sequence	one position backward. If the
         operation	fails, the function returns traits::eof(). Otherwise
         it returns traits::not_eof(c).

      pos_type
      seekoff(off_type off,	ios_base::seekdir way,
    	 ios_base::openmode which =
    	 ios_base::in |	ios_base::out);
         If the open	mode is	in | out, this function	alters the
         stream position of	both the input and the output sequences. If
         the	open mode is in,	it alters the stream position
         of only the input sequence, and if it	is out,	it alters the
         stream position of the output sequence. The new position is
         calculated by combining the two	parameters off (displacement)
         and way (reference point). If the	current	position of the
         sequence is invalid before repositioning, the operation fails
         and the return	value is pos_type(off_type(-1)). Otherwise the
         function returns the current new	position.

      pos_type
      seekpos(pos_type sp,ios_base::openmode which =
    	 ios_base::in |	ios_base::out);
         If the open	mode is	in | out, seekpos() alters the stream
         position of both the input and the output sequences. If	the
         open mode is in, it alters the stream	position of the	input
         sequence only, and	if the open mode is out, it alters the stream
         position of the output sequence only. If the current position of
         the sequence is invalid before repositioning, the operation
         fails and the return value is pos_type(off_type(-1)). Otherwise
         the function returns the	current	new position.

      basic_streambuf<charT,traits>*
      setbuf(char_type*s, streamsize n);
         If	the string buffer object is opened in output mode, proceed as
         follows:

         if	s is not a null	pointer	and n is greater than the content of
         the current buffer, replace it	(copy its contents) by the
         buffer of size n pointed at	by s. In the case where	s is a
         null pointer and	n is greater than the content of the current
         buffer, resize it to size n. If the function fails, it
         returns	a null pointer.

      string_type
      str()	const;
         Returns a string object of	type string_type whose content is a
         copy of the underlying buffer contents.

      void
      str(const string_type& str_arg);
         Clears the	underlying buffer and copies the string	object str_arg
         into it. If the	opening	mode is	in, initializes	the input
         sequence to point at	the first character of the buffer. If
         the opening mode is out, the function initializes the output
         sequence to point at the first character of	the buffer. If
         the opening mode	is out | app, it initializes the output
         sequence to point at the last character of the	buffer.

      int_type
      underflow();
         If	the input sequence has a read position available, the function
         returns the contents of this position. Otherwise it tries to
         expand the input sequence to match the output	sequence and
         if	possible returns the content of	the new	current	position. The
         function returns traits::eof() to	indicate failure.

      streamsize
      xsputn(const char_type* s, streamsize	n);
         Writes up to n characters to the output sequence. The characters
         written are obtained from successive elements of the array	whose
         first element is	designated by s. The function returns the
         number of characters written.

    EXAMPLES

      //
      // stdlib/examples/manual/stringbuf.cpp
      //
      #include<iostream>
      #include<sstream>
      #include<string>

      void main ( )
      {
       using namespace std;

        // create a	read/write string-stream object	on tiny	char
        // and attach it to	an ostringstream object
       ostringstream out_1(ios_base::in | ios_base::out);

        // tie the istream object to the ostringstream object
       istream in_1(out_1.rdbuf());

        // output to out_1
       out_1 << "Here is the first output";

        // create a	string object on tiny char
       string  string_ex("l'heure est grave	!");

        // open a read only	string-stream object on	tiny char
        // and initialize it
       istringstream in_2(string_ex);

        // output in_1 to the standard output
       cout	<< in_1.str() << endl;

        // output in_2 to the standard output
       cout	<< in_2.rdbuf()	<< endl;

        // reposition in_2 at the beginning
       in_2.seekg(0);

       stringbuf::pos_type pos;

        // get the current put position
        // equivalent to
        // out_1.tellp();
       pos = out_1.rdbuf()->pubseekoff(0,ios_base::cur,
    				   ios_base::out);

        // append the content of stringbuffer
        // pointed at by in_2 to the one
        // pointed at by out_1
       out_1 << ' '	<< in_2.rdbuf();

        // output in_1 to the standard output
       cout	<< in_1.str() << endl;

        // position	the get	sequence
        // equivalent to
        // in_1.seekg(pos);
       in_1.rdbuf()->pubseekpos(pos, ios_base::in);

        // output "l'heure est grave !"
       cout	<< in_1.rdbuf()	<< endl	<< endl;
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, basic_string,
      basic_istringstream,	basic_ostringstream,
      basic_stringstream

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.7.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    stringstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_stringstream

    SYNOPSIS

      #include <sstream>
      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_stringstream
      : public basic_iostream<charT, traits>

    DESCRIPTION

      The template class basic_stringstream<charT,traits,Allocator>
      provides functionality	to read	and write to an	array in
      memory. It supports writing and reading objects of class
      basic_string<charT,traits,Alocator>. It uses a basic_stringbuf
      object to control the	associated storage. It inherits	from
      basic_iostream and therefore can use all the formatted and
      unformatted output and input	functions.

    INTERFACE

      template<class charT,	class traits = char_traits<charT>,
    	  class	Allocator = allocator<void> >
      class	basic_stringstream
      : public basic_iostream<charT, traits> {

      public:

       typedef basic_stringbuf<charT, traits, Allocator>  sb_type;
       typedef basic_ios<charT, traits>		      ios_type;

       typedef basic_string<charT, traits, Allocator>     string_type;

       typedef traits			     traits_type;
       typedef charT			     char_type;
       typedef typename traits::int_type	     int_type;
       typedef typename traits::pos_type	     pos_type;
       typedef typename traits::off_type	     off_type;

       explicit basic_stringstream(ios_base::openmode which	=
    			       ios_base::out | ios_base::in);

       explicit basic_stringstream(const string_type& str,
    			       ios_base::openmode which	=
    			       ios_base::out | ios_base::in);

       virtual ~basic_stringstream();

       basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
       string_type str() const;

       void	str(const string_type& str);

      };

    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.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type
         charT.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      sb_type
         The type sb_type is an instantiation of class basic_stringbuf on
         type charT.

      string_type
         The type string_type is an	instantiation of class basic_string on
         type charT.

      stringstream
         The type stringstream is an instantiation of class	basic_stringstream
         on type char:

           typedef basic_stringstream<char>	stringstream;

      traits_type
         The type traits_type is a synonym for the template	parameter traits.

      wstringstream
         The type wstringstream is an instantiation	of class
         basic_stringstream on	type wchar_t:

           typedef basic_stringstream<wchar_t> wstringstream;

    CONSTRUCTORS

      explicit basic_stringstream(ios_base::openmode which =
    		    ios_base::in | ios_base::out);
         Constructs an object of class basic_stringstream, initializing
         the base class	basic_iostream with the	associated string
         buffer. The string	buffer is initialized by calling the
         basic_stringbuf constructor
         basic_stringbuf<charT,traits,Allocator>(which).

      explicit basic_stringstream(const string_type& str,
    		    ios_base::openmode which =
    		    ios_base::in | ios_base::out);
         Constructs an object of class basic_stringstream, initializing
         the base class	basic_iostream with the	associated string
         buffer. The string	buffer is initialized by calling the
         basic_stringbuf constructor
         basic_stringbuf<charT,traits,Allocator>(str,which).

    DESTRUCTOR

      virtual ~basic_stringstream();
         Destroys an object	of class basic_stringstream.

    MEMBER FUNCTIONS

      basic_stringbuf<charT,traits,Allocator>*
      rdbuf() const;
         Returns a pointer to the basic_stringbuf associated with the stream.

      string_type
      str()	const;
         Returns a string object of	type string_type whose contents	is a
         copy of the underlying buffer contents.

      void
      str(const string_type& str);
         Clears the	string buffer and copies the string object str into
         it.	If the opening mode is in, initializes the input
         sequence to point at	the first character of	the buffer. If
         the opening mode	is out,	initializes the output	sequence to
         point at the first	character of the buffer. If the opening mode
         is out | app, initializes	the output sequence to point at	the
         last character of the buffer.

    EXAMPLES

      //
      // stdlib/examples/manual/stringstream.cpp
      //
      #include<iostream>
      #include<sstream>

      void main ( )
      {
       using namespace std;

        // create a	bi-directional wstringstream object
       wstringstream inout;

        // output characters
       inout << L"Das ist die rede von einem man" << endl;
       inout << L"C'est l'histoire d'un home" << endl;
       inout << L"This is the story	of a man" << endl;

       wchar_t p[100];

        // extract the first line
       inout.getline(p,100);

        // output the first	line to	stdout
       wcout << endl << L"Deutch :"	<< endl;
       wcout << p;

        // extract the seconf line
       inout.getline(p,100);

        // output the second line to stdout
       wcout << endl << L"Francais :" << endl;
       wcout << p;

        // extract the third line
       inout.getline(p,100);

        // output the third	line to	stdout
       wcout << endl << L"English :" << endl;
       wcout << p;

        // output the all content of the
        //wstringstream object to stdout
       wcout << endl << endl << inout.str();
      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_stringbuf, basic_string,
      basic_istringstream,	basic_ostringstream(3c++)

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.7.3

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    strstream
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      strstream

      This page describes the ANSI strstream class.	 If you	would like
      information on the pre-ANSI strstream class,	use the
      command:

           help cxxl

    SYNOPSIS

      #include <strstream>
      class	strstream
      : public basic_iostream<char>

    DESCRIPTION

      The class strstream provides functionality to	read and write to an
      array in memory. It uses a private strstreambuf object	to
      control the associated array. It inherits from basic_iostream<char>
      and therefore can use all the formatted and	unformatted output and
      input functions.

    INTERFACE

      class	strstream
      : public basic_iostream<char>	{

      public:

       typedef char_traits<char>	       traits;

       typedef char			      char_type;
       typedef typename traits::int_type  int_type;
       typedef typename traits::pos_type  pos_type;
       typedef typename traits::off_type  off_type;

       strstream();
       strstream(char *s, int n,
    	     ios_base::openmode	= ios_base::out	| ios_base::in);

       void	freeze(int freezefl = 1);

       int pcount()	const;

       virtual ~strstream();

       strstreambuf	*rdbuf() const;

       char	*str();

      };

    TYPES

      char_type
         The type char_type	is a synonym of	type char.

      int_type
         The type int_type is a synonym of type traits::in_type.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits
         The type traits is	a synonym of type char_traits<char>.

    CONSTRUCTORS

      strstream();
         Constructs	an object of class strstream, initializing the base
         class basic_iostream<char> with the associated strstreambuf
         object. The strstreambuf object is initialized	by calling its
         default constructor strstreambuf().

      strstream(char* s,int	n, ios_base::openmode
    	   mode	= ios_base::out	| ios_base::in);
         Constructs an object of class strstream, initializing the	base
         class basic_iostream<char> with the associated strstreambuf
         object. The strstreambuf object is initialized by	calling	one of
         two constructors:

    	      +	      if mode &	app == 0 calls strstreambuf(s,n,s)

    	      +	      Otherwise	calls strstreambuf(s,n,s + ::strlen(s))

    DESTRUCTORS

      virtual ~strstream();
         Destroys an object	of class strstream.

    MEMBER FUNCTIONS

      void
      freeze(int freezefl =	1);
         If	the mode is dynamic, alters the	freeze status of the dynamic
         array object as follows:

         +	     If	freezefl is false, the function	sets the freeze	status to
    	  frozen.

         +	     Otherwise,	it clears the freeze status.

      int
      pcount() const;
         Returns the size of the output sequence.

      strstreambuf*
      rdbuf() const;
         Returns a pointer to the strstreambuf object associated with the
         stream.

      char*
      str();
         Returns a pointer to the underlying array object which may	be null.

    EXAMPLES

      //
      // stdlib/examples/manual/strstream.cpp
      //
      #include<strstream>

      void main ( )
      {
       using namespace std;

        // create a	bi-directional strstream object
       strstream inout;

        // output characters
       inout << "Das ist die rede von einem	man" <<	endl;
       inout << "C'est l'histoire d'un home" << endl;
       inout << "This is the story of a man" << endl;

       char	p[100];

        // extract the first line
       inout.getline(p,100);

        // output the first	line to	stdout
       cout	<< endl	<< "Deutch :" << endl;
       cout	<< p;

        // extract the seconf line
       inout.getline(p,100);

        // output the second line to stdout
       cout	<< endl	<< "Francais :"	<< endl;
       cout	<< p;

        // extract the third line
       inout.getline(p,100);

        // output the third	line to	stdout
       cout	<< endl	<< "English :" << endl;
       cout	<< p;

        // output the all content of the
        // strstream object	to stdout
       cout	<< endl	<< endl	<< inout.str();

      }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      strstreambuf, istrstream, ostrstream(3c++)

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Annex D
      Compatibility features Section D.6.4

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    strstreambuf
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      strstreambuf

      This page describes the ANSI strstreambuf class.  If you would like
      information on the	pre-ANSI strstreambuf class, use the command:

           help cxxl

    SYNOPSIS

      #include <strstream>
      class	strstreambuf
      : public basic_streambuf<char>

    DESCRIPTION

      The class strstreambuf is derived from basic_streambuf specialized
      on	type char to associate possibly the input sequence	and
      possibly the output sequence with	a tiny character array,	whose
      elements store arbitrary values.

      Each object of type strstreambuf controls two	character sequences:

      +	  A character input sequence;

      +	  A character output sequence.

      Note:	see basic_streambuf.

      The two sequences are	related	to each	other, but are manipulated
      separately.  This means that you can read and	write characters at
      different positions in objects of type strstreambuf without any
      conflict (in opposition to the basic_filebuf objects).

      The underlying array has several attributes:

      +	  allocated, set when a	dynamic	array has been allocated, and
           hence should be freed by the destructor of the	strstreambuf
           object.

      +	  constant, set	when the array has const elements, so the output
           sequence	cannot be written.

      +	  dynamic, set when the	array object is	allocated
           (or reallocated) as necessary to hold a character sequence that
           can change in length.

      +	  frozen, set when the program has requested that the array will
           not be altered, reallocated,	or freed.

    INTERFACE

      class	strstreambuf
      : public basic_streambuf<char> {

      public:

       typedef char_traits<char>	      traits;
       typedef basic_ios<char, traits>    ios_type;

       typedef char			      char_type;
       typedef typename traits::int_type  int_type;
       typedef typename traits::pos_type  pos_type;
       typedef typename traits::off_type  off_type;

       explicit strstreambuf(streamsize alsize = 0);
       strstreambuf(void *(*palloc)(size_t), void (*pfree)(void *));
       strstreambuf(char *gnext, streamsize	n, char	*pbeg =	0);

       strstreambuf(unsigned char *gnext, streamsize n,
    		unsigned char *pbeg = 0);
       strstreambuf(signed char *gnext, streamsize n,
    		signed char *pbeg = 0);

       strstreambuf(const char *gnext, streamsize n);
       strstreambuf(const unsigned char *gnext, streamsize n);
       strstreambuf(const signed char *gnext, streamsize n);

       virtual ~strstreambuf();

       void	freeze(bool f =	1);

       char	*str();
       int pcount()	const;

      protected:

       virtual int_type overflow(int_type c	= traits::eof());

       virtual int_type pbackfail(int_type c = traits::eof());

       virtual int_type underflow();

       virtual pos_type seekoff(off_type, ios_type::seekdir	way,
    			    ios_type::openmode which =
    			    ios_type::in | ios_type::out);

       virtual pos_type seekpos(pos_type sp, ios_type::openmode which =
    			    ios_type::in | ios_type::out);

       virtual streambuf* setbuf(char *s, streamsize n);

       virtual streamsize xsputn(const char_type* s, streamsize n);

      };

    TYPES

      char_type
         The type char_type	is a synonym of	type char.

      int_type
         The type int_type is a synonym of type traits::in_type.

      ios_type
         The type ios_type is an instantiation of class basic_ios on type char.

      off_type
         The type off_type is a synonym of type traits::off_type.

      pos_type
         The type pos_type is a synonym of type traits::pos_type.

      traits
         The type traits is	a synonym of type char_traits<char>.

    CONSTRUCTORS

      explicit strstreambuf(streamsize alsize = 0);
         Constructs	an object of class strstreambuf, initializing the base
         class with streambuf(). After initialization the	strstreambuf
         object is in dynamic mode and its array	object has a size of
         alsize.

      strstreambuf(void* (*palloc)(size_t),
    	      void (*pfree)(void*));
         Constructs an object of class strstreambuf, initializing the base
         class with streambuf(). After initialization the strstreambuf
         object is	in dynamic mode. The function used to allocate memory
         is pointed at by void*	(*palloc)(size_t) and the one used to
         free memory is	pointed	at by void (*pfree)(void*).

      strstreambuf(char* gnext, streamsize n,
    	      char* pbeg = 0);
      strstreambuf(signed char* gnext, streamsize n,
    	      signed char* pbeg	= 0);
      strstreambuf(unsigned	char* gnext, streamsize	n,
    	      unsigned char* pbeg = 0);
         Constructs an object of class strstreambuf, initializing the base
         class with streambuf(). The argument gnext point to the first
         element of an array object whose	number of elements is:

    		n, if n	> 0
    		 ::strlen(gnext), if n == 0
    		INT_MAX, if n <	0

    		If pbeg	is a null pointer set only the input sequence
                    to gnext, otherwise set also the output sequence to
                    pbeg.

      strstreambuf(const char* gnext, streamsize n);
      strstreambuf(const signed char* gnext, streamsize n);
      strstreambuf(const unsigned char* gnext, streamsize n);
         Constructs	an object of class strstreambuf, initializing the base
         class with streambuf(). The argument gnext point	to the first
         element of	an array object whose	number of elements is:

        n, if n > 0
         ::strlen(gnext), if n == 0
        INT_MAX, if	n < 0

        Set	the input sequence to gnext and	the mode to constant.

    DESTRUCTORS

      virtual ~strstreambuf();
         Destroys an object	of class strstreambuf. The function frees the
         dynamically allocated array object only if allocated is set and
         frozen is not set.

    MEMBER FUNCTIONS

      void
      freeze(bool freezefl = 1);
         If	the mode is dynamic, alters the	freeze status of the dynamic
         array as follows:

         +	     If	freezefl is false, the function	sets the freeze	status
              to frozen.

         +	     Otherwise,	it clears the freeze status.

      int_type
      overflow( int_type c = traits::eof() );
         If	the output sequence has	a put position available, and c	is not
         traits::eof(), then write c into it. If there is no position
         available, the function grow the size	of the array object by
         allocating more memory and then write c at the new current put
         position. If dynamic is not set or	if frozen is set the operation
         fails. The function returns traits::not_eof(c), except	if it
         fails, in	which case it returns traits::eof().

      int_type
      pbackfail( int_type c	= traits::eof()	);
         Puts back the character designated	by c into the input sequence.
         If traits::eq_int_type(c,traits::eof()) returns true,	move
         the input sequence one position backward. If	the operation
         fails, the function returns traits::eof(). Otherwise it returns
         traits::not_eof(c).

      int
      pcount() const;
         Returns the size of the output sequence.

      pos_type
      seekoff(off_type off,	ios_base::seekdir way,
    	 ios_base::openmode which =
    	 ios_base::in |	ios_base::out);
         If the open mode is	in | out, alters the stream position
         of	both the input and the output sequence. If the open
         mode	is in, alters the	stream position	of only	the
         input sequence, and	if it is out, alters the stream
         position of only the output sequence. The	new position is
         calculated by combining	the two	parameters off (dis-
         placement) and way (reference point). If the current position of
         the sequence is invalid before repositioning, the
         operation	fails and the return value is
         pos_type(off_type(-1)). Otherwise the function returns the
         current new position.

      pos_type
      seekpos(pos_type sp,ios_base::openmode which =
    	 ios_base::in |	ios_base::out);
         If the open	mode is	in | out, alters the stream position
         of	both the	input and the output sequence. If the open
         mode	is in, alters the	stream position	of only	the
         input sequence, and	if it is out, alters the stream
         position of only the output sequence. If the current position of
         the sequence is	invalid	before repositioning, the
         operation fails	and the	return value is	pos_type(off_type(-
         1)). Otherwise the function	returns	the current new
         position.

      strstreambuf*
      setbuf(char* s, streamsize n);
         If	dynamic	is set and freeze is not, proceed as follows:

         If	s is not a null	pointer	and n is greater than the number of
         characters already in  the current array, replaces it (copy its
         contents) by the array of size n pointed at by s.

      char*
      str();
         Calls freeze(), then returns the beginning	pointer	for the	input
         sequence.

      int_type
      underflow();
         If	the input sequence has a read position available, returns the
         content of	this position. Otherwise tries to expand the input
         sequence to match the output	sequence and if	possible
         returns the content of	the new current position. The function
         returns traits::eof() to indicate failure.

         In	the case where s is a null pointer and n is greater than the
         number of	characters already in  the current array, resize it to
         size n.

         If	the function fails, it returns a null pointer.

      streamsize
      xsputn(const char_type* s, streamsize	n);
         Writes up to n characters to the output sequence. The characters
         written are obtained from successive elements of the array	whose
         first element is	designated by s. The function returns the
         number of characters written.

    EXAMPLES

      //
      // stdlib/examples/manual/strstreambuf.cpp
      //
      #include<iostream>
      #include<strstream>
      #include<iomanip>

      void main ( )
      {
       using namespace std;

        // create a	read/write strstream object
        // and attach it to	an ostrstream object
       ostrstream out;

        // tie the istream object to the ostrstream	object
       istream in(out.rdbuf());

        // output to out
       out << "anticonstitutionellement is a big word !!!";

        // create a	NTBS
       char	*p ="Le	rat des	villes et le rat des champs";

        // output the NTBS
       out << p << endl;

        // resize the buffer
       if (	out.rdbuf()->pubsetbuf(0,5000) )
        cout << endl << "Success in	allocating the buffer" << endl;

        // output the all buffer to	stdout
       cout	<< in.rdbuf( );

        // output the decimal conversion of	100 in hex
        // with right padding and a	width field of 200
       out << dec << setfill('!') << setw(200) << 0x100 << endl;

        // output the content of the input sequence	to stdout
       cout	<< in.rdbuf( ) << endl;

        // number of elements in the output	sequence
       cout	<< out.rdbuf()->pcount() << endl;

        // resize the buffer to a minimum size
       if (	out.rdbuf()->pubsetbuf(0,out.rdbuf()->pcount())	)
        cout << endl << "Success in	resizing the buffer" <<	endl;

        // output the content of the all array object
       cout	<< out.rdbuf()->str() << endl;

       }

    SEE ALSO

      char_traits,	ios_base, basic_ios,
      basic_streambuf, istrstream(3c++), ostrstream,
      strstream(3c++)

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Annex D
      Compatibility features Section D.5

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    wcerr
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      wcerr

    SYNOPSIS

      #include <iostream>
      extern wostream wcerr;

    DESCRIPTION

      wostream wcerr;
         The object	wcerr controls output to an unbuffered stream buffer
         associated with the object stderr declared in <cstdio>. By
         default the standard C and	C++ streams are	synchronized,
         but you can improve performance by	using the ios_base member
         function synch_with_stdio to desynchronize them.

         wcerr uses	the locale codecvt facet to convert the	wide
         characters	it receives to the tiny characters it	outputs	to
         stderr.

    FORMATTING

      The formatting is done through member	functions or manipulators. See
      cout, wcout	or basic_ostream for details.

    EXAMPLES

      //
      // wcerr example
      //
      #include<iostream>
      #include<fstream>

      void main ( )
      {
       using namespace std;

        // open the	file "file_name.txt"
        // for reading
       wifstream in("file_name.txt");

        // output the all file to stdout
       if (	in )
         wcout << in.rdbuf();
       else
          // if the	wifstream object is in a bad state
          // output	an error message to stderr
         wcerr << L"Error while opening the	file" << endl;
      }

    SEE ALSO

      basic_ostream, iostream, basic_filebuf,
      cout, cin, cerr, clog, wcin,
      wcout, wclog, iomanip, ios_base,
      basic_ios

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.3.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    wcin
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      wcin

    SYNOPSIS

      #include <iostream>
      extern wistream wcin;

    DESCRIPTION

      wistream wcin;
         The object	wcin controls input from a stream buffer associated
         with the object stdin declared in <cstdio>.	By default the
         standard	C and C++ streams are synchronized, but performance
         improvement can be achieved by using the ios_base	member
         function	synch_with_stdio to desynchronize them.

         After the object wcin is initialized, wcin.tie() returns &wcout,
         which implies that wcin and wcout are synchronized. wcin	uses
         the locale codecvt facet to convert the tiny characters extracted
         from stdin to the wide characters stored in the wcin
         buffer.

    EXAMPLES

      //
      // wcin example one
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       int i;
       float f;
       wchar_t c;

        //read an integer, a float and a wide character from stdin
       wcin	>> i >>	f >> c;

        // output i, f and c to stdout
       wcout << i << endl << f << endl << c	<< endl;
      }

      //
      // wcin example two
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       wchar_t p[50];

        // remove all the white spaces
       wcin	>> ws;

        // read characters from stdin until	a newline
        // or 49 characters	have been read
       wcin.getline(p,50);

        // output the result to stdout
       wcout << p;
      }

         When inputting "  Grendel the monster" (newline) in the previous
         test, the output	will be	"Grendel the monster". The manipulator
         ws removes spaces.

    SEE ALSO

      basic_istream, iostream, basic_filebuf,
      cin,	cout, cerr, clog, wcout,
      wcerr, wclog, ios_base, basic_ios

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.3.2

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    wclog
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      wclog

    SYNOPSIS

      #include <iostream>
      extern wostream wclog;

    DESCRIPTION

      wostream wclog;
         The object	wclog controls output to a stream buffer associated
         with the object stderr declared in <cstdio>. The difference
         between	wclog and wcerr is that wclog is buffered, but wcerr
         isn't .	Therefore, commands like wclog	<< L"ERROR !!";	and
         fprintf(stderr,"ERROR !!");	are not	synchronized.	 wclog
         uses the	locale codecvt facet to	convert	the wide characters
         it receives to the tiny	characters it outputs to stderr.

    FORMATTING

      The formatting is done through member	functions or manipulators. See
      cout, wcout	or basic_ostream for details.

    EXAMPLES

      //
      // wclog example
      //
      #include<iostream>
      #include<fstream>

      void main ( )
      {
       using namespace std;

        // open the	file "file_name.txt"
        // for reading
       wifstream in("file_name.txt");

        // output the all file to stdout
       if (	in )
         wcout << in.rdbuf();
       else
          // if the	wifstream object is in a bad state
          // output	an error message to stderr
         wclog << L"Error while opening the	file" << endl;
      }

    WARNINGS

      wclog	can be used to redirect	some of	the errors to another
      recipient. For example, you might want to redirect them to a	file
      named my_err:

      wofstream out("my_err");

      if ( out )
       wclog.rdbuf(out.rdbuf());
      else
       cerr	<< "Error while	opening	the file" << endl;

      Then when you	are doing something like wclog << L"error number x";
      the error	message	is output to the file my_err.  Obviously, you
      can use the same scheme to redirect wclog	to other devices.

    SEE ALSO

      basic_ostream, iostream, basic_filebuf,
      cout, cin, cerr, clog, wcin,
      wcout, wcerr, iomanip, ios_base,
      basic_ios

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.3.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    wcout
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      wcout

    SYNOPSIS

      #include <iostream>
      extern wostream wcout;

    DESCRIPTION

      wostream wcout;
         The object	wcout controls output to a stream buffer associated
         with the object stdout declared in <cstdio>.  By default the
         standard C and	C++ streams are synchronized, but performance
         can be improved by using	the ios_base member function
         synch_with_stdio to desynchronize	them.

         After the object wcin is initialized, wcin.tie() returns &wcout,
         which implies that wcin and wcout are synchronized.  wcout uses
         the locale codecvt facet to convert the wide characters it
         receives to the tiny characters	it outputs to stdout.

    FORMATTING

      The formatting is done through member	functions or manipulators.

      Manipulators			   Member Functions

      showpos			   setf(ios_base::showpos)
      noshowpos			   unsetf(ios_base::showpos)
      showbase			   setf(ios_base::showbase)
      noshowbase			   unsetf(ios_base::showbase)
      uppercase			   setf(ios_base::uppercase)
      nouppercase			   unsetf(ios_base::uppercase)
      showpoint			   setf(ios_base::showpoint)
      noshowpoint			   unsetf(ios_base::showpoint)
      boolalpha			   setf(ios_base::boolalpha)
      noboolalpha			   unsetf(ios_base::boolalpha)
      unitbuf			   setf(ios_base::unitbuf)
      nounitbuf			   unsetf(ios_base::unitbuf)
      internal			   setf(ios_base::internal,
    				      ios_base::adjustfield)
      left				   setf(ios_base::left,
    				      ios_base::adjustfield)
      right				   setf(ios_base::right,
    				      ios_base::adjustfield)
      dec				   setf(ios_base::dec,
    				      ios_base::basefield)
      hex				   setf(ios_base::hex,
    				      ios_base::basefield)
      oct				   setf(ios_base::oct,
    				      ios_base::basefield)
      fixed				   setf(ios_base::fixed,
    				      ios_base::floatfield)
      scientific			   setf(ios_base::scientific,
    				      ios_base::floatfield)
      resetiosflags
       (ios_base::fmtflags flag)	   setf(0,flag)
      setiosflags
       (ios_base::fmtflags flag)	   setf(flag)
      setbase(int base)		   See above
      setfill(char_type c)		   fill(c)
      setprecision(int n)		   precision(n)
      setw(int n)			   width(n)
      endl
      ends
      flush				   flush( )

    DESCRIPTION

      showpos   Generates a	+ sign in non-negative generated numeric output.

      showbase   Generates a prefix	indicating the numeric base of generated
    	     integer output.

      uppercase   Replaces certain lowercase letters with their uppercase
    	      equivalents in generated output.

      showpoint   Generates	a decimal-point	character unconditionally in
                  generated floating-point output.

      boolalpha   Inserts and extracts bool	type in	alphabetic format.

      unitbuf   Flushes output after each output operation.

      internal   Adds fill characters at a designated internal point in
                 certain generated output, or identical to right if	no such
                 point is designated.

      left	 Adds fill characters on the right (final positions) of	certain
             generated	output.

      right	  Adds fill characters on the left (initial positions) of certain
    	  generated output.

      dec	Converts integer input or generates integer output in decimal
            base.

      hex	Converts integer input or generates integer output in hexadecimal
    	base.

      oct	Converts integer input or generates integer output in octal base.

      fixed	  Generates floating-point output in fixed-point notation.

      scientific   Generates floating-point	output in scientific notation.

      resetiosflagss

      (ios_base::fmtflags flag)   Resets the fmtflags field	flag

      setiosflags

      (ios_base::fmtflags flag)   Sets up the flag flag

      setbase(int base)   Converts integer input or	generates integer output
                          in base base. The parameter base can	be 8,
                          10 or 16.

      setfill(char_type c)	 Sets the character used to pad	(fill) an output
    			 conversion to the specified field width.

      setprecision(int n)	Sets the precision (number of digits after the
    			decimal	point) to generate on certain output
                            conversions.

      setw(int n)	Sets the field with (number of characters) to generate on
    		certain	output conversions.

      endl	 Inserts a newline character into the output sequence and flush
             the output	buffer.

      ends	 Inserts a null	character into the output sequence.

      flush	  Flushes the output buffer.

    DEFAULT	VALUES

      precision()		 6
      width()		 0
      fill()		 the space character
      flags()		 skipws	| dec
      getloc()		 locale::locale()

    EXAMPLES

      //
      // wcout example one
      //
      #include<iostream>
      #include<iomanip>

      void main ( )
      {
       using namespace std;

       int i;
       float f;

        // read an integer and a float from	stdin
       cin >> i >> f;

        // output the integer and goes at the line
       wcout << i << endl;

        // output the float	and goes at the	line
       wcout << f << endl;

        // output i	in hexa
       wcout << hex	<< i <<	endl;

        // output i	in octal and then in decimal
       wcout << oct	<< i <<	dec << i << endl;

        // output i	preceded by its	sign
       wcout << showpos << i << endl;

        // output i	in hexa
       wcout << setbase(16)	<< i <<	endl;

        // output i	in dec and pad to the left with	character
        // @ until a width of 20
        // if you input 45 it outputs 45@@@@@@@@@@@@@@@@@@
       wcout << setfill(L'@') << setw(20) << left << dec <<	i;
       wcout << endl;

        // output the same result as the code just above
        // but uses	member functions rather	than manipulators
       wcout.fill('@');
       wcout.width(20);
       wcout.setf(ios_base::left, ios_base::adjustfield);
       wcout.setf(ios_base::dec, ios_base::basefield);
       wcout << i << endl;

        // outputs f in scientific notation	with
        // a precision of 10 digits
       wcout << scientific << setprecision(10) << f	<< endl;

        // change the precision to 6 digits
        // equivalents to wcout << setprecision(6);
       wcout.precision(6);

        // output f	and goes back to fixed notation
       wcout << f << fixed << endl;

      }

      //
      // wcout example two
      //
      #include <iostream>

      void main ( )
      {
       using namespace std;

       wchar_t p[50];

       wcin.getline(p,50);

       wcout << p;
      }

      //
      // wcout example three
      //
      #include <iostream>
      #include <fstream>

      void main ( )
      {
       using namespace std;

        // open the	file "file_name.txt"
        // for reading
       wifstream in("file_name.txt");

        // output the all file to stdout
       if (	in )
         wcout << in.rdbuf();
       else
          {
           wcout <<	"Error while opening the file";
           wcout <<	endl;
          }
      }

    WARNINGS

      Keep in mind that the	manipulator endl flushes the stream buffer.
      Therefore it is	recommended to use L'0 if your only intent is
      to go at the line. It will greatly improve performance when	C and
      C++ streams are not synchronized.

    SEE ALSO

      basic_ostream, iostream, basic_filebuf,
      cin,	cout, cerr, clog, wcin,
      wcerr, wclog, iomanip, ios_base,
      basic_ios

      Working Paper	for Draft Proposed International Standard for
      Information Systems--Programming Language	C++, Section 27.3.1

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    wstring
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      basic_string,string  - A templated class for handling	sequences of
      character-like entities.  string and wstring are specialized
      versions	of basic_string for chars and wchar_ts, respectively.

      This page describes the ANSI basic_string class.  If you would like
      information on the	pre-ANSI string	class, use the command:

           help cxxl

      typedef basic_string <char> string;
      typedef basic_string <wchar_t> wstring;

    SYNOPSIS

      #include <string>

      template <class charT,
    	   class traits	= char_traits<charT>,
    	   class Allocator = allocator<charT> >

      class	basic_string;

    DESCRIPTION

      basic_string<charT, traits, Allocator> is a homogeneous collection
      of character-like entities.  It provides	general	string
      functionality such as compare, append, assign, insert, remove, and
      replace , along with various searches.  basic_string also functions
      as an STL sequence container, providing random	access
      iterators.  This	allows some of the generic algorithms to apply
      to strings.

      Any underlying character-like	type may be used as long as an
      appropriate string_char_traits class is provided or the default
      traits class is applicable.

    INTERFACE

      template <class charT,
    	   class traits	= char_traits<charT>,
    	   class Allocator = allocator<charT> >
      class	basic_string {

      public:

      // Types

      typedef traits			       traits_type;
      typedef typename traits::char_type	       value_type;
      typedef Allocator			       allocator_type;

      typename size_type;
      typename difference_type;
      typename reference;
      typename const_reference;
      typename pointer;
      typename const_pointer;
      typename iterator;
      typename const_iterator;
      typename const_reverse_iterator;
      typename reverse_iterator;

      static const size_type npos =	-1;

      // Constructors/Destructors

      explicit basic_string(const Allocator& = Allocator());
      basic_string (const basic_string<charT, traits, Allocator>&);
      basic_string(const basic_string&, size_type, size_type = npos);
      basic_string(const charT*, size_type,
    	      const Allocator& = Allocator());
      basic_string(const charT*, Allocator&	= Allocator());
      basic_string(size_type, charT,
    	      const Allocator& = Allocator());
      template <class InputIterator>
      basic_string(InputIterator, InputIterator,
    	      const Allocator& = Allocator());
      ~basic_string();

      // Assignment	operators
      basic_string&	operator=(const	basic_string&);
      basic_string&	operator=(const	charT*);
      basic_string&	operator=(charT);

      // Iterators

      iterator	 begin();
      const_iterator begin() const;
      iterator	 end();
      const_iterator end() const;

      reverse_iterator	 rbegin();
      const_reverse_iterator rbegin() const;
      reverse_iterator	 rend();
      const_reverse_iterator rend()	const;

      // Capacity

        size_type	    size() const;
        size_type	    length() const;
        size_type	    max_size() const;
        void	    resize(size_type, charT);
        void	    resize(size_type);
        size_type	    capacity() const;
        void	    reserve(size_type);
        bool	    empty() const;

      // Element access

        const_reference operator[](size_type) const;
        reference	    operator[](size_type);
        const_reference at(size_type) const;
        reference	    at(size_type);

      // Modifiers

        basic_string& operator+=(const basic_string&);
        basic_string& operator+=(const charT*);
        basic_string& operator+=(charT);

        basic_string& append(const basic_string&);
        basic_string& append(const basic_string&,
    			 size_type, size_type);
        basic_string& append(const charT*, size_type);
        basic_string& append(const charT*);
        basic_string& append(size_type, charT);
        template<class InputIterator>
         basic_string& append(InputIterator, InputIterator);

        basic_string& assign(const basic_string&);
        basic_string& assign(const basic_string&,
    			 size_type, size_type);
        basic_string& assign(const charT*, size_type);
        basic_string& assign(const charT*);
        basic_string& assign(size_type, charT);
        template<class InputIterator>
         basic_string& assign(InputIterator, InputIterator);

        basic_string& insert(size_type, const basic_string&);
        basic_string& insert(size_type, const basic_string&,
    			 size_type, size_type);
        basic_string& insert(size_type, const charT*, size_type);
        basic_string& insert(size_type, const charT*);
        basic_string& insert(size_type, size_type, charT);
        iterator insert(iterator, charT = charT());
        void insert(iterator, size_type, charT);
        template<class InputIterator>
         void insert(iterator, InputIterator,
    		InputIterator);

        basic_string& erase(size_type = 0, size_type= npos);
        iterator erase(iterator);
        iterator erase(iterator, iterator);

        basic_string& replace(size_type, size_type,
    			  const	basic_string&);
        basic_string& replace(size_type, size_type,
    			  const	basic_string&,
    			  size_type, size_type);
        basic_string& replace(size_type, size_type,
    			  const	charT*,	size_type);
        basic_string& replace(size_type, size_type,
    			  const	charT*);
        basic_string& replace(size_type, size_type,
    			  size_type, charT);
        basic_string& replace(iterator, iterator,
    			  const	basic_string&);
        basic_string& replace(iterator, iterator,
    			  const	charT*,	size_type);
        basic_string& replace(iterator, iterator,
    			  const	charT*);
        basic_string& replace(iterator, iterator,
    			  size_type, charT);
        template<class InputIterator>
         basic_string& replace(iterator, iterator,
    			  InputIterator, InputIterator);

        size_type copy(charT*, size_type, size_type	= 0);
        void swap(basic_string<charT, traits, Allocator>&);

      // String operations

        const charT* c_str() const;
        const charT* data()	const;
        const allocator_type& get_allocator() const;

        size_type find(const basic_string&,
    		   size_type = 0) const;
        size_type find(const charT*,
    		   size_type, size_type) const;
        size_type find(const charT*, size_type = 0)	const;
        size_type find(charT, size_type = 0) const;
        size_type rfind(const basic_string&,
    		    size_type =	npos) const;
        size_type rfind(const charT*,
    		    size_type, size_type) const;
        size_type rfind(const charT*,
    		    size_type =	npos) const;
        size_type rfind(charT, size_type = npos) const;

        size_type find_first_of(const basic_string&,
    			    size_type =	0) const;
        size_type find_first_of(const charT*,
    			    size_type, size_type) const;
        size_type find_first_of(const charT*,
    			    size_type =	0) const;
        size_type find_first_of(charT, size_type = 0) const;

        size_type find_last_of(const basic_string&,
    			   size_type = npos) const;
        size_type find_last_of(const charT*,
    			   size_type, size_type) const;
        size_type find_last_of(const charT*, size_type = npos) const;
        size_type find_last_of(charT, size_type = npos) const;

        size_type find_first_not_of(const basic_string&,
    				size_type = 0) const;
        size_type find_first_not_of(const charT*,
    				size_type, size_type) const;
        size_type find_first_not_of(const charT*, size_type	= 0) const;
        size_type find_first_not_of(charT, size_type = 0) const;

        size_type find_last_not_of(const basic_string&,
    			       size_type = npos) const;
        size_type find_last_not_of(const charT*,
    			       size_type, size_type) const;
        size_type find_last_not_of(const charT*,
    			       size_type = npos) const;
        size_type find_last_not_of(charT, size_type	= npos)	const;

        basic_string substr(size_type = 0, size_type = npos) const;
        int	compare(const basic_string&) const;
        int	compare(size_type, size_type, const basic_string&) const;
        int	compare(size_type, size_type, const basic_string&,
    		size_type, size_type) const;
        int	compare(size_type, size_type, charT*) const;
        int	compare(charT*)	const;
        int	compare(size_type, size_type, const charT*, size_type) const;
      };

      // Non-member	Operators

      template <class charT, class traits, class Allocator>
      basic_string operator+ (const	basic_string&,
    			  const	basic_string&);
      template <class charT, class traits, class Allocator>
      basic_string operator+ (const	charT*,	const basic_string&);
      template <class charT, class traits, class Allocator>
      basic_string operator+ (charT, const basic_string&);
      template <class charT, class traits, class Allocator>
      basic_string operator+ (const	basic_string&, const charT*);
      template <class charT, class traits, class Allocator>
      basic_string operator+ (const	basic_string&, charT);

      template <class charT, class traits, class Allocator>
      bool operator== (const basic_string&,	const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator== (const charT*, const basic_string&);
      template <class charT, class traits ,	class Allocator>
      bool operator== (const basic_string&,	const charT*);

      template <class charT, class traits, class Allocator>
      bool operator< (const	basic_string&, const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator< (const	charT*,	const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator< (const	basic_string&, const charT*);

      template <class charT, class traits, class Allocator>
      bool operator!= (const basic_string&,	const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator!= (const charT*, const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator!= (const basic_string&,	const charT*);

      template <class charT, class traits, class Allocator>
      bool operator> (const	basic_&, const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator> (const	charT*,	const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator> (const	basic_string&, const charT*);

      template <class charT, class traits, class Allocator>
      bool operator<= (const basic_string&,	const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator<= (const charT*, const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator<= (const basic_string&,	const charT*);

      template <class charT, class traits, class Allocator>
      bool operator>= (const basic_string&,	const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator>= (const charT*, const basic_string&);
      template <class charT, class traits, class Allocator>
      bool operator>= (const basic_string&,	const charT*);

      template <class charT, class traits, class Allocator>
      void swap(basic_string<charT,traits,Allocator>& a,
    	   basic_string<charT,traits,Allocator>& b);

      template<class charT,	class traits, class Allocator>
      istream& operator>> (istream&, basic_string&);
      template <class charT, class traits, class Allocator>
      ostream& operator<< (ostream&, const basic_string&);
      template <class Stream, class	charT,
    	   class traits, class Allocator>
      Stream& getline (Stream&, basic_string&, charT);

    CONSTRUCTORS AND DESTRUCTORS

      In all cases,	the Allocator parameter	will be	used for storage
      management.

      explicit
      basic_string (const Allocator& a = Allocator());
         The default constructor.  Creates a basic_string with the
         following effects:

         data()   a	non-null pointer that is copyable and can have 0
                  added to it

         size()   0

         capacity()	  an unspecified value

      basic_string (const basic_string<T, traits, Allocator>& str);
         Copy constructor. Creates a string	that is	a copy of str.

      basic_string (const basic_string &str, size_type pos,
    	       size_type n= npos);
         Creates a string if pos<=size() and determines length	rlen
         of initial string value as the smaller of n and str.size() - pos.
         This has the following	effects:

         data()   points at the first element of an allocated copy
    	      of rlen elements of the string controlled by	str
                  beginning at	position pos

         size()   rlen

         capacity()   a value at least	as large as size()

         get_allocator()   str.get_allocator()

         An out_of_range exception will be thrown if pos>str.size().

      basic_string (const charT* s,	size_type n,
    	       const Allocator&	a = Allocator());
         Creates a string that	contains the first n characters	of s.
         s must not be	a NULL pointer.	 The effects of	this con-
         structor are:

         data()   points at the first element of an allocated copy
    	      of the array	whose first element is pointed at by
    	      s

         size()   n

         capacity()   a value at least	as large as size()

         An out_of_range exception will be thrown if n	== npos.

      basic_string (const charT * s,
    	       const Allocator&	a = Allocator());
         Constructs a string containing all characters	in s up	to,
         but not including, a traits::eos() character.	s must not be
         a null pointer. The effects of this constructor are:

         data()   points at the first element of an allocated copy
                  of the array	whose first element is pointed at by
                  s

         size()   traits::length(s)

         capacity()   a value at least	as large as size()

      basic_string (size_type n, charT c,
    	       const Allocator&	a  = Allocator());
         Constructs a string containing n repetitions of c.  A
         length_error exception is thrown if n	== npos.  The effects
         of this constructor are:

         data()   points at the first element of an allocated array
                  of n	elements, each storing the initial value c

         size()   n

         capacity()   a value at least	as large as size()

      template <class InputIterator>
      basic_string	(InputIterator first, InputIterator last,
    		const Allocator& a = Allocator());
         Creates a basic_string of length last - first, filled with all
         values obtained by dereferencing	the InputIterators on the
         range [first, last). The	effects	of this	constructor are:

         data()   points at the first	element	of an allocated	copy
                  of the elements in the range [first,last)

         size()   distance between first and last

         capacity()	a value	at least as large as size()

      ~basic_string	();
         Releases any allocated memory for this basic_string.

    OPERATORS

      basic_string&
      operator= (const basic_string& str);
         Assignment	operator. Sets the contents of this string to be the
         same as str.  The effects of operator= are:

         data()   points at	the first element of an	allocated copy of the array
    	      whose first element is pointed at	by str.size()

         size()   str.size()

         capacity()	  a value at least as large as size()

      basic_string&
      operator= (const charT * s);
         Assignment	operator. Sets the contents of this string to be the
         same as s up to, but not including, the traits::eos() character.

      basic_string&
      operator= (charT c);
         Assignment	operator. Sets the contents of this string to be equal
         to the single charT c.

      const_reference
      operator[] (size_type	pos) const;
      reference
      operator[] (size_type	pos);
         If	pos < size(), returns the element at position pos in this
         string. If	pos == size(),	the const version returns
         traits::eos(), the behavior of	the non-const version is
         undefined.  The reference returned by either version is
         invalidated by any call	to c_str(), data(), or any non-const
         member function for the object.

      basic_string&
      operator+= (const basic_string& s);
      basic_string&
      operator+= (const charT* s);
      basic_string&
      operator+= (charT c);
         Concatenates a string onto	the current contents of	this string.
         The second member operator uses traits::length() to determine the
         number of elements from s to	add.  The third	member
         operator	adds the single	character c.  All return a reference
         to this string after completion.

    ITERATORS

      iterator begin ();
      const_iterator begin () const;
         Return an iterator	initialized to the first element of the
         string.

      iterator end ();
      const_iterator end ()	const;
         Return an iterator	initialized to the position after the last
         element of the string.

      reverse_iterator rbegin ();
      const_reverse_iterator rbegin	() const;
         Returns an	iterator equivalent to reverse_iterator(end()).

      reverse_iterator rend	();
      const_reverse_iterator rend () const;
         Returns an	iterator equivalent to reverse_iterator(begin()).

    ALLOCATOR

      const	allocator_type get_allocator ()	const;
         Returns a copy of the allocator used by self for storage
         management.

    MEMBER FUNCTIONS

      basic_string&
      append (const	basic_string& s, size_type pos,	size_type npos);
      basic_string&
      append (const	basic_string& s);
      basic_string&
      append (const	charT* s, size_type n);
      basic_string&
      append (const	charT* s);
      basic_string&
      append (size_type n, charT c );
      template<class InputIterator>
      basic_string&
      append (InputIterator	first, InputIterator last);
         Append another string to the end of this string.  The first two
         functions append the lesser of n and s.size() - pos characters of
         s, beginning at position pos to this string.	 The second
         member will	throw an	out_of_range exception if pos
         >	str.size().  The third member appends n characters of the
         array pointed to by s.	 The fourth variation appends elements
         from the array pointed to	by s up	to, but	not including, a
         traits::eos() character.  The fifth variation appends n
         repetitions of c.	 The final append function appends the
         elements	specified in the range [first, last).

         All functions will	throw a	length_error exception if the
         resulting length will exceed	max_size().  All return	a
         reference to this string after completion.

      basic_string&
      assign (const	basic_string& s);
      basic_string&
      assign (const	 basic_string& s,
    	size_type pos, size_type n);
      basic_string&
      assign (const	charT* s, size_type n);
      basic_string&
      assign (const	charT* s);
      basic_string&
      assign (size_type n, charT c );
      template<class InputIterator>
      basic_string&
      assign (InputIterator	first, InputIterator last);

         Replace the value of this string with the value of	another.

         All versions of the function assign values	to this	string.	 The
         first two variations assign the lesser of n and s.size()	- pos
         characters of s,	beginning at position pos.  The	second
         variation throws	an out_of_range exception if pos > str.size().
         The third version of the function assigns n	characters of
         the array	pointed	to by s.  The fourth version assigns elements
         from the array pointed to	by s up	to, but	not including,	a
         traits::eos()	character.  The	fifth assigns one or n
         repetitions of c.	The last variation assigns the members
         specified by the range [first, last).

         All functions will	throw a	length_error  exception	if the
         resulting length will exceed	max_size(). All	return a
         reference to this string after completion.

      const_reference
      at (size_type	pos) const;
      reference
      at (size_type	pos);
         If	pos < size(), returns the element at position pos in this
         string. Otherwise,	an out_of_range	exception is thrown.

      size_type
      capacity () const;
         Returns the current storage capacity of the string. This is
         guaranteed to	be at least as large as	size().

      int
      compare (const basic_string& str);
         Returns the result	of a lexicographical comparison	between
         elements of this string and elements of str.  The return value
         is:

         <0	    if size() <	str.size()
         0	    if size() == str.size()
         >0	    if size() >	str.size()

      int
      compare (size_type pos1, size_type n1,
    	  const	basic_string& str) const;
      int
      compare (size_type pos1, size_type n1, const basic_string& str,
    	  size_type pos2, size_type n2)	const;
      int
      compare (charT* s) const;
      int
      compare (size_type pos, size_type n1,	charT* s) const;
      int
      compare (size_type pos, size_type n1,	charT* s,
    	  size_type n2)	const;
         Return the	result of a lexicographical comparison between ele-
         ments of this string and a	given comparison string. The members
         return, respectively:

    	  compare (str)
    	  compare (basic_string	(str, pos2, n2))
    	  compare (basic_string(s))
    	  compare (basic_string(s, npos))
    	  compare (basic_string	(s,n2))

      size_type
      copy (charT* s, size_type n,	size_type pos =	0) const;
         Replaces elements in memory with copies of	elements from this
         string. An	out_of_range exception will be thrown if pos > size().
         The lesser of n and size() - pos	 elements of this string,
         starting at position pos are copied	into the array pointed
         to by s.	 No terminating	null is appended to s.

      const	charT*
      c_str	() const;
      const	charT*
      data () const;
         Return a pointer to the initial element of	an array whose first
         size() elements are copies of the	elements in this string.  A
         traits::eos() element is	appended to the	end.  The elements of
         the array	may not	be altered, and the returned pointer is only
         valid until a non-const member function of this string is
         called.	If size() is zero, the data() function returns a
         NULL pointer.

      bool empty ()	const;
         Returns size() == 0.

      basic_string&
      erase	(size_type pos = 0, size_type n	= npos);
      iterator
      erase	(iterator p);
      iterator
      erase	(iterator first, iterator last);
         This function removes elements from the string, collapsing	the
         remaining elements, as necessary, to	remove any space left
         empty.  The first	version of the function removes the smaller
         of n and size() -	pos  starting at	position pos.  An
         out_of_range exception will be thrown	if  pos	> size().  The
         second version requires  that p is a	valid iterator on this
         string, and removes the character referred to	by p. The last
         version of erase requires that both first and	last are valid
         iterators on this string, and removes the characters defined by
         the range [first, last).  The destructors for all removed
         characters	are called.   All versions of erase return a
         reference to this string after completion.

      size_type
      find (const basic_string& str, size_type pos = 0) const;
         Searches for the first occurrence of the substring	specified by
         str in this string, starting at position pos.  If	found, it
         returns the index of	the first character of the matching
         substring.	If not found, returns npos. Equality is defined by
         traits::eq().

      size_type
      find (const charT* s,	size_type pos, size_type n) const;
      size_type
      find (const charT* s,	size_type pos =	0) const;
      size_type
      find (charT c, size_type pos = 0) const;
         Search for	the first sequence of characters in this string	that
         match a specified string.	The variations of this function
         return,	respectively:

         find(basic_string(s,n), pos)
         find(basic_string(s), pos)
         find(basic_string(1, c), pos)

      size_type
      find_first_not_of (const basic_string& str,
    		    size_type pos = 0) const;
         Searches	for the	first element of this string at	or after
         position pos that is not equal to any element of str.  If	found,
         find_first_not_of returns the index of the non-matching
         character. If all of the characters match, the function returns
         npos.  Equality is defined by traits::eq().

      size_type
      find_first_not_of  (const charT* s,
    		     size_type pos, size_type n) const;
      size_type
      find_first_not_of (const charT* s,
    		    size_type pos = 0) const;
      size_type
      find_first_not_of (charT c, size_type	pos = 0) const;
         Search for	the first element in this string at or after position
         pos that is not equal to any element of a given set of
         characters.  The members return, respectively:

         find_first_not_of(basic_string(s,n), pos)
         find_first_not_of(basic_string(s),	pos)
         find_first_not_of(basic_string(1, c), pos)

      size_type
      find_first_of(const basic_string& str,
    	       size_type pos = 0) const;
         Searches for the first occurrence at or after	position pos
         of any element of str	in this	string.	 If found, the index
         of this matching character is	 returned.  If not found, npos
         is returned.  Equality is defined by traits::eq().

      size_type
      find_first_of(const charT*  s,  size_type  pos,
    	       size_type n) const;
      size_type
      find_first_of(const charT* s,	size_type pos =	0) const;
      size_type
      find_first_of	(charT c, size_type pos	= 0) const;
         Search for	the first occurrence in	this  string of	any element in
         a specified string.	The find_first_of variations return,
         respectively:

         find_first_of(basic_string(s,n), pos)
         find_first_of(basic_string(s), pos)
         find_first_of(basic_string(1, c), pos)

      size_type
      find_last_not_of(const basic_string& str,
    		  size_type pos	= npos)	const;
         Searches for the last element of this string at or before
         position pos that is not equal to any element of str.  If
         find_last_not_of finds a non-matching element, it	returns	the
         index of the character.  If	all the	elements match, the
         function returns npos.  Equality is defined by	traits::eq().

      size_type
      find_last_not_of(const charT*	s,
    		  size_type pos, size_type n) const;
      size_type
      find_last_not_of(const charT*	s, size_type pos = npos) const;
      size_type
      find_last_not_of(charT c, size_type pos = npos) const;
         Search for	the last element in this string	at or  before position pos
         that is not equal to any element of a given set of	characters.  The
         members return, respectively:

         find_last_not_of(basic_string(s,n), pos)
         find_last_not_of(basic_string(s), pos)
         find_last_not_of(basic_string(1, c), pos)

      size_type
      find_last_of(const basic_string& str,
    	      size_type	pos = npos) const;
         Searches for the last occurrence of any element of str	at or
         before	position pos in	this string.  If found,	find_last_of
         returns the index of the matching character.  If not found
         find_last_of returns npos.  Equality is defined by traits::eq().

      size_type
      find_last_of(const charT* s, size_type pos,
    	      size_type	n) const;
      size_type
      find_last_of(const charT* s, size_type pos = npos) const;
      size_type
      find_last_of(charT c,	size_type pos =	npos) const;
         Search for	the last occurrence in this string of any element in a
         specified string.  The members return, respectively:

         find_last_of(basic_string(s,n), pos)
         find_last_of(basic_string(s), pos)
         find_last_of(basic_string(1, c), pos)

      basic_string&
      insert(size_type pos1, const basic_string& s);
      basic_string&
      insert(size_type pos,	const  basic_string& s,
    	size_type pos2 = 0, size_type n	= npos);
      basic_string&
      insert(size_type pos,	const charT* s,	size_type n);
      basic_string&
      insert(size_type pos,	const charT* s);
      basic_string&
      insert(size_type pos,	size_type n, charT c);
         Insert additional elements	at position pos	in this	string.	 All
         of	the variants of this function will throw an out_of_range
         exception if pos > size().  All variants will	also throw a
         length_error if the resulting string will exceed	max_size().
         Elements of this string will be moved apart as necessary	to
         accommodate the inserted elements.  All return a reference to
         this string after completion.

         The second	variation of this function inserts the lesser of n and
         s.size() -	pos2 characters	of s, beginning	at position pos2 in
         this string.  This version will	throw an out_of_range
         exception	if  pos2  > s.size().	The third version inserts n
         characters of the array pointed to	by s.  The fourth inserts
         elements from	the array pointed to by	s up to, but not
         including, a traits::eos()  character.	 Finally, the fifth
         variation inserts n repetitions of	c.

      iterator
      insert(iterator p, charT c = charT());
      void
      insert(iterator p, size_type n, charT	c);
      template<class InputIterator>
      void
      insert(iterator p, InputIterator first, InputIterator	last);
         Insert additional elements	in this	 string	 immediately before
         the	character referred to by p.  All of these versions
         of insert require that p is	a valid	iterator on this
         string.  The first version inserts a copy of c.	 The second
         version inserts n repetitions of c.	 The third version
         inserts characters	in the range [first, last).  The first version
         returns p.

      size_type
      length() const;
         Return the	number of elements contained in	this string.

      size_type
      max_size() const;
         Returns the maximum possible size of the string.

      size_type
      rfind	(const basic_string& str, size_type pos	 = npos) const;
         Searches for the last occurrence of the substring	specified by
         str in this string, starting at position pos. Note that only the
         first character of the	substring must be <= pos; the
         remaining	characters may extend beyond pos. If found, the index
         of	the first character of that matches substring is returned.  If
         not found, npos	is returned.  Equality is defined by
         traits::eq().

      size_type
      rfind(const charT* s,	size_type pos,	size_type n) const;
      size_type
      rfind(const charT* s,	size_type pos =	npos) const;
      size_type
      rfind(charT c, size_type pos = npos) const;
         Searches for the last sequence of characters in this string
         matching a specified string.	The rfind variations return,
         respectively:

         rfind(basic_string(s,n), pos)
         rfind(basic_string(s), pos)
         rfind(basic_string(1, c), pos)

      basic_string&
      replace(size_type pos, size_type n1, const basic_string& s);
      basic_string&
      replace(size_type pos1, size_type n1,	const basic_string& str,
    	 size_type pos2, size_type n2);
      basic_string&
      replace(size_type pos, size_type n1, const charT* s,
    	 size_type n2);
      basic_string&
      replace(size_type pos, size_type n1, const charT* s);
      basic_string&
      replace(size_type pos, size_type n1, size_type n2, charT c);
         The replace function replaces selected elements of	this string
         with an alternate set of elements.	 All of	these versions insert
         the new elements in place of n1 elements in this string,
         starting at position	pos. They each throw an	out_of_range
         exception if pos1 > size()and a length_error exception if the
         resulting string size exceeds max_size().

         The second	version	replaces elements of the original string with
         n2 characters	from string s starting at position pos2.  It
         will throw	the out_of_range exception if pos2 > s.size().	 The
         third variation of	the function replaces elements	in the
         original	string with n2 elements	from the array pointed to by
         s.	 The fourth version replaces elements in the string with
         elements from the array pointed to by s, up to, but not
         including,	a traits::eos()	character.  The	fifth replaces n
         elements with n2 repetitions of character c.

      basic_string&
      replace(iterator i1, iterator	i2,
    	 const basic_string& str);
      basic_string&
      replace(iterator i1, iterator	i2, const charT* s,
    	 size_type n);
      basic_string&
      replace(iterator i1, iterator	i2, const charT* s);
      basic_string&
      replace(iterator i1, iterator	i2, size_type n,
    	 charT c);
      template<class InputIterator>
      basic_string&
      replace(iterator  i1,	 iterator  i2,
    	 InputIterator j1, InputIterator j2);
         Replace selected elements of this string with an alternative set
         of elements.  All of these versions of replace require
         iterators i1 and i2 to be valid iterators on this string.  The
         elements specified by the range [i1,i2) are replaced by
         the new elements.

         The first version shown here replaces with all members in
         str. The	second version starts at position i1, and replaces the
         next n characters with n	characters of the array	pointed	to by
         s.  The third variation replaces string elements with elements
         from the array pointed to by s up to, but not including, a
         traits::eos() character.	The fourth version replaces string
         elements with n repetitions of c.  The last variation
         shown here replaces string elements with the members
         specified	in the range [j1, j2).

      void
      reserve(size_type res_arg);
         Assures that the storage capacity is at least res_arg.

      void
      resize(size_type n, charT c);
      void
      resize(size_type n);
         Changes the capacity of this string to n.	If the new capacity is
         smaller than the current size of the string, then it is
         truncated.	 If the capacity is larger, then the string is	padded
         with c characters. The latter	resize member pads the string
         with default characters specified by  traits::eos().

      size type
      size() const;
         Return the	number of elements contained in	this string.

      basic_string
      substr(size_type pos = 0, size_type n	= npos)	const;
         Returns a string composed of copies of the	lesser of n and	size()
         characters in this string starting at index pos.  Throws an
         out_of_range exception if pos <= size().

      void
      swap(basic_string& s);
         Swaps the contents	of this	string with the	contents of s.

    NON-MEMBER OPERATORS

      template<class charT,	class traits, class Allocator>
      basic_string
      operator+(const basic_string&	lhs, const basic_string& rhs);
         Returns a string of length	lhs.size()  +  rhs.size(), where the
         first lhs.size()	elements are copies of the  elements of	lhs,
         and the next rhs.size()	elements are copies of the elements of
         rhs.

      template<class charT,	class traits, class Allocator>
      basic_string
      operator+(const charT* lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      basic_string
      operator+(charT lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      basic_string
      operator+(const basic_string&	 lhs, const charT* rhs);
      template<class charT,	class traits, class Allocator>
      basic_string
      operator+(const basic_string&	lhs, charT rhs);
         Returns a string that represents the concatenation	of two
         string-like entities.	These functions	return,	respectively:

         basic_string(lhs) + rhs
         basic_string(1, lhs) + rhs
         lhs + basic_string(rhs)
         lhs + basic_string(1, rhs)

      template<class charT,	class traits, class Allocator>
      bool
      operator==(const basic_string& lhs, const basic_string& rhs);
         Returns a boolean value of	true if	lhs and	rhs are	equal, and
         false if they are not. Equality  is	defined	by the
         compare() member	function.

      template<class charT,	class traits, class Allocator>
      bool
      operator==(const charT* lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      bool
      operator==(const basic_string& lhs, const charT* rhs);
         Returns a boolean value indicating	whether	lhs and	rhs are	equal.
         Equality is defined by the	compare()  member function.  These
         functions return, respectively:

         basic_string(lhs) == rhs
         lhs == basic_string(rhs)

      template<class charT,	class traits, class Allocator>
      bool
      operator!=(const basic_string& lhs,
    	    const basic_string&	rhs);
         Returns a boolean value representing the	inequality of lhs and
         rhs.  Inequality	is defined by the compare() member function.

      template<class charT,	class traits, class Allocator>
      bool
      operator!=(const charT* lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      bool
      operator!=(const basic_string& lhs, const charT* rhs);
         Returns a boolean value representing the inequality of  lhs and
         rhs. Inequality	is defined by the compare()  member function.
         The functions return, respectively:

         basic_string(lhs) != rhs
         lhs != basic_string(rhs)

      template<class charT,	class traits, class Allocator>
      bool
      operator<(const basic_string&	lhs, const basic_string& rhs);
         Returns a boolean value representing the lexicographical
         less-than	relationship of lhs and rhs.  Less-than is defined
         by the compare() member.

      template<class charT,	class traits, class Allocator>
      bool
      operator<(const charT* lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      bool
      operator<(const basic_string&	lhs, const charT* rhs);
         Returns a boolean value representing the lexicographical
         less-than	relationship of lhs and rhs.  Less-than is defined
         by the compare() member function.	These functions	return,
         respectively:

         basic_string(lhs) < rhs
         lhs < basic_string(rhs)

      template<class charT,	class traits, class Allocator>
      bool
      operator>(const basic_string&	lhs, const basic_string& rhs);
         Returns a boolean value representing the lexicographical
         greater-than relationship of lhs and rhs.  Greater-than	is
         defined by the compare() member function.

      template<class charT,	class traits, class Allocator>
      bool
      operator>(const charT* lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      bool
      operator>(const basic_string&	lhs, const charT* rhs);
         Returns a boolean value representing the lexicographical
         greater-than relationship of lhs and rhs.  Greater-than	is
         defined by the compare() member.  The functions return,
         respectively:

         basic_string(lhs) > rhs
         lhs > basic_string(rhs)

      template<class charT,	class traits, class Allocator>
      bool
      operator<=(const basic_string& lhs,
    	      const basic_string& rhs);
         Returns a boolean value representing the lexicographical
         less-than-or-equal relationship of lhs	and rhs.  Less-than-
         or-equal is defined by	the compare() member function.

      template<class charT,	class traits, class Allocator>
      bool
      operator<=(const charT* lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      bool
      operator<=(const basic_string& lhs, const charT* rhs);
         Returns a boolean value representing the lexicographical
         less-than-or-equal relationship	of lhs and rhs.
         Less-than-or-equal is defined by the compare() member function.
         These functions return, respectively:

         basic_string(lhs) <= rhs
         lhs <= basic_string(rhs)

      template<class charT,	class traits, class Allocator>
      bool
      operator>=(const basic_string& lhs, const basic_string& rhs);
         Returns a boolean value representing the lexicographical
         greater-than- or-equal relationship of lhs and rhs.
         Greater-than-or-equal is defined by	the compare() member
         function.

      template<class charT,	class traits, class Allocator>
      bool
      operator>=(const charT* lhs, const basic_string& rhs);
      template<class charT,	class traits, class Allocator>
      bool
      operator>=(const basic_string& lhs, const charT* rhs);
         Returns a boolean value representing the lexicographical
         greater-than- or-equal  relationship of lhs and rhs.
         Greater-than-or-equal is defined by	the compare() member.
         The functions return, respectively:

         basic_string(lhs) >= rhs
         lhs >= basic_string(rhs)

      template <class charT, class traits, class Allocator>
      void swap(basic_string<charT,traits,Allocator>& a,
    	   basic_string<charT,traits,Allocator>& b);

         Swaps the	contents of a and b by calling a's swap	function on b.

      template<class charT,	class traits, class Allocator>
      istream&
      operator>>(istream& is, basic_string&	str);
         Reads str	from  is using traits::char_in until a
         traits::is_del()	element  is read.  All elements read,	except
         the delimiter, are placed in str.  After the read, the function
         returns	is.

      template<class charT,	class traits, class Allocator>
      ostream&
      operator<<(ostream& os, const	basic_string& str);
         Writes all	elements of str	to os in order from first to last,
         using traits::char_out().  After	the write, the function
         returns	os.

    NON-MEMBER FUNCTION

      template <class Stream, class	charT, class traits,
    	   class Allocator>
      Stream&
      getline(Stream& is, basic_string& str, charT delim);
         An	unformatted input function that	extracts characters from is
         into str until npos	- 1 characters are read, the end of
         the	input sequence is reached, or the character read is
         delim.  The characters are read using traits::char_in().

    EXAMPLE

      //
      // string.cpp
      //
       #include<string>
       #include <iostream.h>

      int main()
       {
        string test;

         //Type in a string	over five characters long
        while(test.empty() ||  test.size() <= 5)
         {
          cout << "Type a string between 5 and 100 characters long.	"
    	    << endl;
          cin >> test;
         }

         //Test operator[] access
        cout << "Changing the third	character from " << test[2] <<
    	     " to * " << endl;
        test[2] = '*';
        cout << "now its: "	<< test	<< endl	<< endl;

         //Try the insertion member	function
        cout << "Identifying the middle: ";
        test.insert(test.size() / 2, "(the middle is here!)");
        cout << test << endl << endl;

         //Try replacement
        cout << "I didn't like the word 'middle',so	instead,I'll say:"
    		<< endl;
        test.replace(test.find("middle",0),	6, "center");
        cout << test << endl;

        return 0;
       }

      Output :
      Type a string	between	5 and 100 characters long.
      roguewave
      Changing the third character from g to *
      now its: ro*uewave
      Identifying the middle: ro*u(the middle is here!)ewave
      I didn't like	the word 'middle', so instead, I'll say:
      ro*u(the center is here!)ewave

    SEE ALSO

      Allocators, string, wstring

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

|  | privacy statement and legal notices