streamb_.gml

开放源码的编译器open watcom 1.6.0版的源代码

:CLFNM.streambuf
:CMT.========================================================================
:LIBF fmt='hdr'.streambuf
:HFILE.streambu.h
:DVBYL.
:DVBY.filebuf
:DVBY.stdiobuf
:DVBY.strstreambuf
:eDVBYL.
:CLSS.
The &cls. is responsible for maintaining the buffer used to create an
efficient implementation of the stream classes. Through its pure virtual
functions, it is also responsible for the actual communication with the
device associated with the stream.
:P.
The &cls. is abstract, due to the presence of pure virtual member functions.
Abstract classes may not be instantiated, only inherited.
Hence, &obj.s will not be created by user programs.
:P.
Stream objects maintain a pointer to an associated &obj. and present the
interface that the user deals with most often. Whenever a stream member
function wishes to read or write characters, it uses the
:MONO.rdbuf
member function to access the associated &obj. and its member functions.
Through judicious use of inline functions, most reads and writes of
characters access the buffer directly without even doing a function call.
Whenever the buffer gets filled (writing) or exhausted (reading), these
inline functions invoke the function required to rectify the situation
so that the proper action can take place.
:P.
:I1.reserve area
:I1.get area
:I1.put area
A &obj. can be unbuffered, but most often has one buffer which can be used
for both input and output operations. The buffer (called the &rsvarea.)
is divided into two areas, called the &getarea. and the &putarea.:PERIOD.
For a &obj. being used exclusively to write, the &getarea. is empty or not
present. Likewise, a &obj. being used exclusively for reading has an empty or
non-existent &putarea.:PERIOD.
:P.
The use of the &getarea. and &putarea. differs among the various classes
derived from the &cls.:PERIOD.
:INCLUDE file='flb_desc'.
:INCLUDE file='std_desc'.
:INCLUDE file='ssb_desc'.
:P.
The &rsvarea. is marked by two pointer values. The
:MONO.base
member function returns the pointer to the start of the buffer. The
:MONO.ebuf
member function returns the pointer to the end of the buffer
(last character + 1). The
:MONO.setb
protected member function is used to set both pointers.
:P.
Within the &rsvarea., the &getarea. is marked by three pointer values. The
:MONO.eback
member function returns a pointer to the start of the &getarea.:PERIOD.
The
:MONO.egptr
member function returns a pointer to the end of the &getarea.
(last character + 1). The
:MONO.gptr
member function returns the &getptr.:PERIOD.
The &getptr. is a pointer to the next character to be extracted from the
&getarea.:PERIOD.
Characters before the &getptr.
have already been consumed by the program, while characters at and after the
&getptr. have been read from their source and are buffered and waiting to be
read by the program. The
:MONO.setg
member function is used to set all three pointer values. If any of these
pointers are &null., there is no &getarea.:PERIOD.
:P.
Also within the &rsvarea., the &putarea. is marked by three pointer values.
The
:MONO.pbase
member function returns a pointer to the start of the &putarea.:PERIOD.
The
:MONO.epptr
member function returns a pointer to the end of the &putarea. (last
character + 1 ).
The
:MONO.pptr
member function returns the &putptr.:PERIOD.
The &putptr. is a pointer to the next available position into which a
character may be stored.
Characters before the &putptr. are buffered and waiting to be written to their
final destination, while character positions at and after the &putptr. have
yet to be written by the program. The
:MONO.setp
member function is used to set all three pointer values. If any of these
pointers are &null., there is no &putarea.:PERIOD.
:P.
Unbuffered I/O is also possible. If unbuffered, the
:MONO.overflow
virtual member function is used to write single characters directly to their
final destination without using the &putarea.:PERIOD.
Similarly, the
:MONO.underflow
virtual member function is used to read single characters directly from their
source without using the &getarea.:PERIOD.
:HDG.Protected Member Functions
The following member functions are declared in the protected interface:
:MFNL.
:MFCD cd_idx='c'.streambuf();
:MFCD cd_idx='c'.streambuf( char *, int );
:MFCD cd_idx='d' .virtual ~~streambuf();
:MFN index='allocate'     .int allocate();
:MFN index='base'         .char *base() const;
:MFN index='ebuf'         .char *ebuf() const;
:MFN index='blen'         .int blen() const;
:MFN index='setb'         .void setb( char *, char *, int );
:MFN index='eback'        .char *eback() const;
:MFN index='gptr'         .char *gptr() const;
:MFN index='egptr'        .char *egptr() const;
:MFN index='gbump'        .void gbump( streamoff );
:MFN index='setg'         .void setg( char *, char *, char *);
:MFN index='pbase'        .char *pbase() const;
:MFN index='pptr'         .char *pptr() const;
:MFN index='epptr'        .char *epptr() const;
:MFN index='pbump'        .void pbump( streamoff );
:MFN index='setp'         .void setp( char *, char *);
:MFN index='unbuffered'   .int unbuffered( int );
:MFN index='unbuffered'   .int unbuffered() const;
:MFN index='doallocate'   .virtual int doallocate();
:eMFNL.
:HDG.Public Member Functions
The following member functions are declared in the public interface:
:MFNL.
:MFN index='in_avail'   .int in_avail() const;
:MFN index='out_waiting'.int out_waiting() const;
:MFN index='snextc'     .int snextc();
:MFN index='sgetn'      .int sgetn( char *, int );
:MFN index='speekc'     .int speekc();
:MFN index='sgetc'      .int sgetc();
:MFN index='sgetchar'   .int sgetchar();
:MFN index='sbumpc'     .int sbumpc();
:MFN index='stossc'     .void stossc();
:MFN index='sputbackc'  .int sputbackc( char );
:MFN index='sputc'      .int sputc( int );
:MFN index='sputn'      .int sputn( char const *, int );
:MFN index='dbp'        .void dbp();
:eMFNL.
:MFNL.
:MFN index='do_sgetn'   .virtual int do_sgetn( char *, int );
:MFN index='do_sputn'   .virtual int do_sputn( char const *, int );
:MFN index='pbackfail'  .virtual int pbackfail( int );
:MFN index='overflow'   .virtual int overflow( int = EOF ) = 0;
:MFN index='underflow'  .virtual int underflow() = 0;
:MFN index='setbuf'     .virtual streambuf *setbuf( char *, int );
:MFN index='seekoff'    .virtual streampos seekoff( streamoff, ios::seekdir,
:MFNFLF                 .                           ios::openmode = ios::in|ios::out );
:MFN index='seekpos'    .virtual streampos seekpos( streampos,
:MFNFLF                 .                           ios::openmode = ios::in|ios::out );
:MFN index='sync'       .virtual int sync();
:eMFNL.
:eCLSS.
:SALSO.
:SAL typ='cls'.filebuf
:SAL typ='cls'.stdiobuf
:SAL typ='cls'.strstreambuf
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected'.allocate
:SNPL.
:SNPFLF               .#include <streambu.h>
:SNPFLF               .protected:
:SNPF index='allocate'.int streambuf::allocate();
:eSNPL.
:SMTICS.
The &fn. works in tandem with the
:MONO.doallocate
protected virtual member function to manage allocation of the &obj.
&rsvarea.:PERIOD.
Classes derived from the &cls. should call the &fn., rather than the
:MONO.doallocate
protected virtual member function. The &fn. determines whether or not the &obj.
is allowed to allocate a buffer for use as the &rsvarea.:PERIOD.
If a &rsvarea.
already exists or if the &obj. unbuffering state is non-zero, the &fn.
fails. Otherwise, it calls the
:MONO.doallocate
protected virtual member function.
:RSLTS.
The &fn. returns &noteof. on success, otherwise &eof. is returned.
:SALSO.
:SAL typ='mfun'.doallocate
:SAL typ='mfun'.underflow
:SAL typ='mfun'.overflow
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected'.base
:SNPL.
:SNPFLF           .#include <streambu.h>
:SNPFLF           .protected:
:SNPF index='base'.char *streambuf::base() const;
:eSNPL.
:SMTICS.
The &fn. returns a pointer to the start of the &rsvarea. that the &obj.
is using.
:INCLUDE file='sb_rgp'.
:RSLTS.
The &fn. returns a pointer to the start of the &rsvarea. that the &obj.
is using. If the &obj. currently does not have a &rsvarea., &null. is
returned.
:SALSO.
:SAL typ='mfun'.blen
:SAL typ='mfun'.ebuf
:SAL typ='mfun'.setb
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected'.blen
:SNPL.
:SNPFLF           .#include <streambu.h>
:SNPFLF           .protected:
:SNPF index='blen'.int streambuf::blen() const;
:eSNPL.
:SMTICS.
The &fn. reports the length of the &rsvarea. that the &obj. is using.
:INCLUDE file='sb_rgp'.
:RSLTS.
The &fn. returns the length of the &rsvarea. that the &obj. is using.
If the &obj. currently does not have a &rsvarea., zero is returned.
:SALSO.
:SAL typ='mfun'.base
:SAL typ='mfun'.ebuf
:SAL typ='mfun'.setb
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.dbp
:SNPL.
:SNPFLF          .#include <streambu.h>
:SNPFLF          .public:
:SNPF index='dbp'.void streambuf::dbp();
:eSNPL.
:SMTICS.
The &fn. dumps information about the &obj. directly to
:MONO.stdout
:CONT., and is used for
debugging classes derived from the &cls.:PERIOD.
:P.
The following is an example of what the &fn. dumps:
:eLIBF.
:XMP.
STREAMBUF Debug Info:
this  = 00030679, unbuffered = 0, delete_reserve = 1
base  = 00070010, ebuf = 00070094
eback = 00000000, gptr = 00000000, egptr = 00000000
pbase = 00070010, pptr = 00070010, epptr = 00070094
:eXMP.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public virtual'.do_sgetn
:SNPL.
:SNPFLF               .#include <streambu.h>
:SNPFLF               .public:
:SNPF index='do_sgetn'.virtual int do_sgetn( char *buf, int len );
:eSNPL.
:SMTICS.
The &fn. works in tandem with the
:MONO.sgetn
member function to transfer
:ARG.len
characters from the &getarea. into
:ARG.buf
:PERIOD.
:P.
Classes derived from the &cls. should call the
:MONO.sgetn
member function, rather than the &fn.:PERIOD.
:PRTCL.
Classes derived from the &cls. that implement the &fn. should support copying
up to
:ARG.len
characters from the source through the &getarea. and into
:ARG.buf
:PERIOD.
:DEFIMPL.
The default &fn. provided with the &cls. calls the
:MONO.underflow
virtual member function to fetch more characters and then copies
the characters from the &getarea. into
:ARG.buf
:PERIOD.
:RSLTS.
The &fn. returns the number of characters successfully transferred.
:SALSO.
:SAL typ='mfun'.sgetn
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public virtual'.do_sputn
:SNPL.
:SNPFLF               .#include <streambu.h>
:SNPFLF               .public:
:SNPF index='do_sputn'.virtual int do_sputn( char const *buf, int len );
:eSNPL.
:SMTICS.
The &fn. works in tandem with the
:MONO.sputn
member function to transfer
:ARG.len
characters from
:ARG.buf
to the end of the &putarea. and advances the &putptr.:PERIOD.
:P.
Classes derived from the &cls. should call the
:MONO.sputn
member function, rather than the &fn.:PERIOD.
:PRTCL.
Classes derived from the &cls. that implement the &fn. should support copying
up to
:ARG.len
characters from
:ARG.buf
through the &putarea. and out to the destination device.
:DEFIMPL.
The default &fn. provided with the &cls. calls the
:MONO.overflow
virtual member function to flush the &putarea. and then copies the rest of
the characters from
:ARG.buf
into the &putarea.:PERIOD.
:RSLTS.
The &fn. returns the number of characters successfully written.
If an error occurs, this number may be less than
:ARG.len
:PERIOD.
:SALSO.
:SAL typ='mfun'.sputn
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected virtual'.doallocate
:SNPL.
:SNPFLF                 .#include <streambu.h>
:SNPFLF                 .protected:
:SNPF index='doallocate'.virtual int streambuf::doallocate();
:eSNPL.
:SMTICS.
The &fn. manages allocation of the &obj.'s &rsvarea. in tandem with the
:MONO.allocate
protected member function.
:P.
Classes derived from the &cls. should call the
:MONO.allocate
protected member function rather than the &fn.:PERIOD.
:P.
The &fn. does the actual memory allocation, and can be defined for each
class derived from the &cls.:PERIOD.
:PRTCL.
Classes derived from the &cls. should implement the &fn. such that it does
the following:
:OL.
:LI.attempts to allocate an area of memory,
:LI.calls the
:MONO.setb
protected member function to initialize the &rsvarea. pointers,
:LI.performs any class specific operations required.
:eOL.
:DEFIMPL.
The default &fn. provided with the &cls. attempts to allocate a buffer area
with the
:MONO.operator~bnew
intrinsic function. It then calls the
:MONO.setb
protected member function to set up the pointers to the &rsvarea.:PERIOD.
:RSLTS.
The &fn. returns &noteof. on success, otherwise &eof. is returned.
:SALSO.
:SAL typ='mfun'.allocate
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected'.eback
:SNPL.
:SNPFLF            .#include <streambu.h>
:SNPFLF            .protected:
:SNPF index='eback'.char *streambuf::eback() const;
:eSNPL.
:SMTICS.
The &fn. returns a pointer to the start of the &getarea. within the &rsvarea.
used by the &obj.:PERIOD.
:INCLUDE file='sb_rgp'.
:RSLTS.
The &fn. returns a pointer to the start of the &getarea.:PERIOD.
If the &obj.
currently does not have a &getarea., &null. is returned.
:SALSO.
:SAL typ='mfun'.egptr
:SAL typ='mfun'.gptr
:SAL typ='mfun'.setg
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected'.ebuf
:SNPL.
:SNPFLF           .#include <streambu.h>
:SNPFLF           .protected:
:SNPF index='ebuf'.char *streambuf::ebuf() const;
:eSNPL.
:SMTICS.
The &fn. returns a pointer to the end of the &rsvarea. that the &obj.
is using.  The character pointed at is actually the first character past
the end of the &rsvarea.:PERIOD.
:INCLUDE file='sb_rgp'.
:RSLTS.
The &fn. returns a pointer to the end of the &rsvarea.:PERIOD.
If the &obj. currently does not have a &rsvarea., &null. is returned.
:SALSO.
:SAL typ='mfun'.base
:SAL typ='mfun'.blen
:SAL typ='mfun'.setb
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected'.egptr
:SNPL.
:SNPFLF            .#include <streambu.h>
:SNPFLF            .protected:
:SNPF index='egptr'.char *streambuf::egptr() const;
:eSNPL.
:SMTICS.
The &fn. returns a pointer to the end of the &getarea. within the &rsvarea.
used by the &obj.:PERIOD.
The character pointed at is actually the first character
past the end of the &getarea.:PERIOD.
:INCLUDE file='sb_rgp'.
:RSLTS.
The &fn. returns a pointer to the end of the &getarea.:PERIOD.
If the &obj.
currently does not have a &getarea., &null. is returned.
:SALSO.
:SAL typ='mfun'.eback
:SAL typ='mfun'.gptr
:SAL typ='mfun'.setg
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected'.epptr
:SNPL.
:SNPFLF            .#include <streambu.h>
:SNPFLF            .protected:
:SNPF index='epptr'.char *streambuf::epptr() const;
:eSNPL.
:SMTICS.
The &fn. returns a pointer to the end of the &putarea. within the &rsvarea.
used by the &obj.:PERIOD.