United States    
COMPAQ STORE | PRODUCTS | SERVICES | SUPPORT
| CONTACT US | SEARCH
C++
streambuf (3C++std) - Tru64 UNIX
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:

       man 3C++ streambuf or man streambuf.3C++

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
  relationship. 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

  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

  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(3C++std), basic_filebuf(3C++std), basic_stringbuf(3C++std),
  strstreambuf(3C++std)

  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
  

1.800.AT.COMPAQ

privacy and legal statement