[ новости /+++ | форум | теги | ]

                       Standard C++ Library
             Copyright 1998, Rogue Wave Software, Inc.


NAME
     basic_streambuf

      - Abstract base class for deriving various  stream  buffers
     to facilitate control of character sequences.



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
     to facilitate control of character sequences such as:



     o    A character input sequence;

     o    A character output sequence.


     Each  sequence  is  associated  with  three   pointers   (as
     described  below),  which,  if  non-null, all point into the
     same charT array object. The array object represents, at any
     moment,  a  segment  of characters from the sequence. Opera-
     tions performed on a sequence alter the values pointed to by
     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 segment to
     sequence relationship. The three pointers are:



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

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


     o    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:



     o    The controlled input sequence may be unreadable;

     o    The controlled output sequence may be unwriteable;

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

     o    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 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 showmanyc();
     virtual streamsize xsgetn(char_type *s, streamsize n);

     virtual int_type underflow();
     virtual int_type uflow();

     virtual int_type pbackfail(int_type c = traits::eof());
     virtual streamsize xsputn(const char_type *s,
                               streamsize n);
     virtual int_type overflow(int_type c = traits::eof());

     virtual int sync();

     };



TYPES
     char_type


        The type char_type is a synonym for the template  parame-
        ter 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 param-
        eter traits.



     wstreambuf


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

        typedef basic_streambuf<wchar_t> wstreambuf;



PUBLIC CONSTRUCTORS
     basic_streambuf();


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



PUBLIC DESTRUCTORS
     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, it returns the default
        (global) locale locale::locale() in effect at the time of
        construction.



     streamsize
     in_avail();


        If a read position is available, returns  the  number  of
        available  characters  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 it 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 it
        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 it 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 it  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, it  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 it
        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 over-
        loaded 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  func-
        tion  when not enough room can be found in the put buffer
        to accommodate the argument character sequence. The func-
        tion  returns traits::eof() if it fails to make more room
        available or if it fails 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 a 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 a 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  inter-
        nal buffer, or returns -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 func-
        tion returns the  character  pointed  to  by  gptr(),  if
        gptr() is not null and if gptr() < egptr(). Otherwise the
        function tries to read character into the buffer.  If  it
        fails, it returns 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 charac-
        ters 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++),                      basic_filebuf(3C++),
     basic_stringbuf(3C++), strstreambuf(3C++)

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



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

Партнёры:

Хостинг: