sstrbuf_.gml

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

:CLFNM.strstreambuf
:CMT.========================================================================
:LIBF fmt='hdr'.strstreambuf
:HFILE.strstrea.h
:DVFML.
:DVFM.streambuf
:eDVFML.
:CLSS.
The &cls. is derived from the
:MONO.streambuf
class and provides additional functionality required to write characters to
and read characters from a string buffer. Read and write operations can occur
at different positions in the string buffer, since the &getptr. and &putptr.
are not necessarily connected. Seek operations are also supported.
:P.
The &rsvarea. used by the &obj. may be either fixed in size or dynamic.
Generally, input strings are of a fixed size, while output streams are
dynamic, since the final size may not be predictable. For dynamic buffers,
the &obj. automatically grows the buffer when necessary.
:INCLUDE file='ssb_desc'.
:P.
C++ programmers who wish to use string streams without deriving new
objects will probably never explicitly create or use a &obj.:PERIOD.
:HDG.Protected Member Functions
The following member function is declared in the protected interface:
:MFNL.
:MFN index='doallocate'.virtual int doallocate();
:eMFNL.
:HDG.Public Member Functions
The following member functions are declared in the public interface:
:MFNL.
:MFCD cd_idx='c'                 .strstreambuf();
:MFCD cd_idx='c'                 .strstreambuf( int );
:MFCD cd_idx='c'                 .strstreambuf( void *(*)( long ), void (*)( void * ) );
:MFCD cd_idx='c'                 .strstreambuf( char *, int, char * = 0 );
:MFCD cd_idx='d'                 .~~strstreambuf();
:MFN index='alloc_size_increment'.int alloc_size_increment( int );
:MFN index='freeze'              .void freeze( int = 1 );
:MFN index='str'                 .char *str();
:MFN index='overflow'            .virtual int overflow( int = EOF );
:MFN index='underflow'           .virtual int underflow();
:MFN index='setbuf'              .virtual streambuf *setbuf( char *, int );
:MFN index='seekoff'             .virtual streampos seekoff( streamoff,
:MFNFLF                          .                           ios::seekdir,
:MFNFLF                          .                           ios::openmode );
:MFN index='sync'                .virtual int sync();
:eMFNL.
:eCLSS.
:SALSO.
:SAL typ='cls'.streambuf
:SAL typ='cls'.strstreambase
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.alloc_size_increment
:SNPL.
:SNPFLF                           .#include <strstrea.h>
:SNPFLF                           .public:
:SNPF index='alloc_size_increment'.int strstreambuf::alloc_size_increment( int increment );
:eSNPL.
:SMTICS.
The &fn. modifies the allocation size used when the buffer is first allocated
or reallocated by dynamic allocation.
The
:ARG.increment
parameter is added to the previous allocation size for future use.
:P.
This function is a WATCOM extension.
:RSLTS.
The &fn. returns the previous value of the allocation size.
:SALSO.
:SAL typ='mfun'.doallocate
:SAL typ='mfun'.setbuf
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='protected virtual'.doallocate
:SNPL.
:SNPFLF                 .#include <strstrea.h>
:SNPFLF                 .protected:
:SNPF index='doallocate'.virtual int strstreambuf::doallocate();
:eSNPL.
:SMTICS.
The &fn. is called by the
:MONO.allocate
member function when it is determined that the &putarea. is full and needs to
be extended.
:P.
The &fn. performs the following steps:
:OL.
:LI.If dynamic allocation is not being used, the &fn. fails.
:LI.A new size for the buffer is determined.
If the allocation size is bigger than the current size, the allocation
size is used. Otherwise, the buffer size is increased by
:MONO.DEFAULT_MAINBUF_SIZE
:CONT., which is 512.
:LI.A new buffer is allocated.
If an allocation function was specified in the constructor for the
&obj., that allocation function is used, otherwise the
:MONO.operator~bnew
intrinsic function is used. If the allocation fails, the &fn. fails.
:LI.If necessary, the contents of the &getarea. are copied to the newly
allocated buffer and the &getarea. pointers are adjusted accordingly.
:LI.The contents of the &putarea. are copied to the newly allocated buffer
and the &putarea. pointers are adjusted accordingly, extending the &putarea.
to the end of the new buffer.
:LI.The old buffer is freed.
If a free function was specified in the constructor for the
&obj., that free function is used, otherwise the
:MONO.operator~bdelete
intrinsic function is used.
:eOL.
:RSLTS.
The &fn. returns &noteof. on success, otherwise &eof. is returned.
:SALSO.
:SAL typ='mfun'.alloc_size_increment
:SAL typ='mfun'.setbuf
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.freeze
:SNPL.
:SNPFLF             .#include <strstrea.h>
:SNPFLF             .public:
:SNPF index='freeze'.void strstreambuf::freeze( int frozen = 1 );
:eSNPL.
:SMTICS.
The &fn. enables and disables automatic deletion of the &rsvarea.:PERIOD.
If the &fn. is called with no parameter or a non-zero parameter, the
&obj. is frozen.
If the &fn. is called with a zero parameter, the &obj. is unfrozen.
:P.
A frozen &obj. does not free the &rsvarea. in the destructor. If the &obj. is
destroyed while it is frozen, it is the program's responsibility to also
free the &rsvarea.:PERIOD.
:P.
If characters are written to the &obj. while it is frozen, the
effect is undefined since the &rsvarea. may be reallocated and therefore
may move. However, if the &obj. is frozen and then unfrozen, characters
may be written to it.
:RSLTS.
The &fn. returns the previous frozen state.
:SALSO.
:SAL typ='mfun'.str
:SAL typ='dtor'.
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public virtual'.overflow
:SNPL.
:SNPFLF               .#include <strstrea.h>
:SNPFLF               .public:
:SNPF index='overflow'.virtual int strstreambuf::overflow( int ch = EOF );
:eSNPL.
:SMTICS.
The &fn. provides the output communication between the
:MONO.streambuf
member functions and the &obj.:PERIOD.
Member functions in the
:MONO.streambuf
class call the &fn. when the &putarea. is full. The &fn. attempts to grow
the &putarea. so that writing may continue.
:P.
The &fn. performs the following steps:
:OL.
:LI.If dynamic allocation is not being used, the &putarea. cannot be
extended, so the &fn. fails.
:LI.If dynamic allocation is being used, a new buffer is allocated using the
:MONO.doallocate
member function. It handles copying the contents of the old buffer
to the new buffer and discarding the old buffer.
:LI.If the
:ARG.ch
parameter is not &eof., it is added to the end of the extended &putarea. and
the &putptr. is advanced.
:eOL.
:RSLTS.
The &fn. returns &noteof. when it successfully extends the &putarea., otherwise
&eof. is returned.
:SALSO.
:SAL typ='ofun' ocls='streambuf'.overflow
:SAL typ='mfun'.underflow
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public virtual'.seekoff
:SNPL.
:SNPFLF              .#include <strstrea.h>
:SNPFLF              .public:
:SNPF index='seekoff'.virtual streampos strstreambuf::seekoff( streamoff offset,
:SNPFLF              .                                         ios::seekdir dir,
:SNPFLF              .                                         ios::openmode mode );
:eSNPL.
:SMTICS.
The &fn. positions the &getptr. and/or &putptr. to the specified position
in the &rsvarea.:PERIOD.
If the &getptr. is moved, it is moved to a position
relative to the start of the &rsvarea. (which is also the start of the
&getarea.). If a position is specified that is beyond the end of the
&getarea. but is in the &putarea., the &getarea. is extended to include
the &putarea.:PERIOD.
If the &putptr. is moved, it is moved to a position
relative to the start of the &putarea.,
:HILITE.not
relative to the start of the
&rsvarea.:PERIOD.
:P.
The &fn. seeks
:ARG.offset
bytes from the position specified by the
:ARG.dir
parameter.
:INCLUDE file='seekmode'.
:MONO.ios::in|ios::out
is not valid if the
:ARG.dir
parameter is
:MONO.ios::cur
:PERIOD.
:INCLUDE file='seekdir'.
:RSLTS.
The &fn. returns the new position in the file on success, otherwise &eof. is
returned.
If both or
:MONO.ios::in|ios::out
are specified and the
:ARG.dir
parameter is
:MONO.ios::cur
the returned position refers to the &putptr.:PERIOD.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public virtual'.setbuf
:SNPL.
:SNPFLF             .#include <strstrea.h>
:SNPFLF             .public:
:SNPF index='setbuf'.virtual streambuf *strstreambuf::setbuf( char *, int size );
:eSNPL.
:SMTICS.
The &fn. is used to control the size of the allocations when the &obj. is using
dynamic allocation. The first parameter is ignored. The next time an
allocation is required, at least the number of characters specified in the
:ARG.size
parameter is allocated. If the specified size is not sufficient,
the allocation reverts to its default behavior, which is to extend the
buffer by
:MONO.DEFAULT_MAINBUF_SIZE
:CONT., which is 512 characters.
:P.
If a program is going to write a large number of characters to the &obj., it
should call the &fn. to indicate the size of the next allocation, to prevent
multiple allocations as the buffer gets larger.
:RSLTS.
The &fn. returns a pointer to the &obj.:PERIOD.
:SALSO.
:SAL typ='mfun'.alloc_size_increment
:SAL typ='mfun'.doallocate
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.str