|
Compaq C++
Compaq C++ Class Library Reference Manual
SAPP(TYPE) class
Defines parameterized applicators for an
ios
object.
Header File
#include <iomanip.hxx>
Alternative Header
#include <iomanip.h>
Compile-Time Parameter
TYPE---The type of the
ios
object. It must be an identifier.
Declaration
class SAPP(TYPE)
{
public:
SAPP(TYPE)(ios &(*f)(ios &, TYPE));
SMANIP(TYPE) operator()(TYPE a);
};
|
Constructor
SAPP(TYPE)(ios &(*f)(ios &, TYPE))
Creates an applicator.
Operator
SMANIP(TYPE) operator () (TYPE a)
Casts an object of type a into a manipulator function for an
istream
or
ostream
object.
See Also
SMANIP(TYPE)
class
SMANIP(TYPE) class
Defines parameterized manipulators for an
ios
object.
Header File
#include <iomanip.hxx>
Alternative Header
#include <iomanip.h>
Compile-Time Parameter
TYPE---The type of the
ios
object. It must be an identifier.
Declaration
class SMANIP(TYPE)
{
public:
SMANIP(TYPE)(ios &(*f)(ios &, TYPE), TYPE a);
friend istream &operator>>(istream &i, SMANIP(TYPE) &m);
friend ostream &operator<<(ostream &o, SMANIP(TYPE) &m);
};
|
Description
These manipulators serve the
ios
class by producing some useful effect, such as embedding a function
call in an expression containing a series of insertions and
extractions. You also can use manipulators to shorten the long names
and sequences of operations required by the
ios
class.
In its simplest form, a manipulator takes an
ios&
argument, operates on it in some way, and returns it.
Constructor
SMANIP(TYPE)(ios &(*f)(ios &, TYPE), TYPE a)
Creates a manipulator.
Operators
ostream &operator << (ostream &o, SMANIP(TYPE)
&m)
Sends data to an
ostream
object.
istream &operator >> (istream &i, SMANIP(TYPE)
&m)
Takes data from an
istream
object.
stdiobuf class
Provides input/output facilities through
stdio FILE
.
Header File
#include <stdiostream.hxx>
Alternative Header
#include <stdiostream.h>
Declaration
class stdiobuf: public streambuf
{
public:
stdiobuf(FILE *f);
virtual int overflow(int = );
virtual streampos seekoff(streamoff, seek_dir, int mode);
FILE *stdiofile();
virtual int sync();
virtual int underflow();
};
|
Description
This class specializes the
streambuf
class for
stdio FILE
. It uses unbuffered mode causing all operations to be reflected
immediately in the
stdio FILE
.
Constructor
stdiobuf(FILE *f)
Constructs an empty
stdiobuf
object and connects it to the
stdio FILE
that the argument f points to.
Member Functions
virtual int overflow(int c)
Called to consume characters. If c is not
EOF
, this function must also either save c or consume it.
Although it can be called at other times, this function is usually
called when the put area is full and an attempt is being made to store
a new character. The normal action is to consume the characters between
pbase()
and
pptr()
, call
setp()
to establish a new put area, and (if c
!= EOF
) store c using
sputc()
. The
overflow(c)
function should return
EOF
to indicate an error; otherwise, it should return something else.
virtual streampos seekoff(streamoff off, seek_dir dir, int
mode)
Repositions the abstract get and put pointers (not
pptr()
and
gptr()
). mode specifies whether to modify the put pointer (
ios::out
bit set), the get pointer, or both (
ios::in
bit set). off is interpreted as a byte offset. For the
meanings of dir, see the explanation of the enumerated type
seek_dir
in class
ios
.
A class derived from
streambuf
is not required to support repositioning. If the derived class does
not, then
seekoff()
should return
EOF
. If the derived class does support repositioning,
seekoff()
should return the new position or
EOF
on error.
FILE *stdiofile()
Returns a pointer to the
stdio FILE
associated with the
stdiobuf
object.
virtual int sync()
Should consume any characters stored into the put area and, if
possible, give back to the source any characters in the get area that
have not been fetched. When
sync()
returns, there should be no unconsumed characters and the get area
should be empty. If some kind of failure occurs, the function should
return
EOF
.
virtual int underflow()
Called to supply characters for fetching; that is, to create a
condition in which the get area is not empty. If this function is
called when characters are in the get area, it should return the first
character. If the get area is empty, it should create a nonempty get
area and return the next character (which it should also leave in the
get area). If no more characters are available,
underflow()
should return
EOF
and leave an empty get area.
stdiostream class
Specializes the
iostream
class for
stdio FILE
.
Header File
#include <stdiostream.hxx>
Alternative Header
#include <stdiostream.h>
Declaration
class stdiostream: public iostream
{
public:
stdiostream(FILE *f);
~stdiostream();
stdiobuf *rdbuf();
};
|
Description
This class specializes the
iostream
class for
stdio FILE
, and causes that class to use a
stdiobuf
object as its associated
streambuf
object.
In most other existing implementations, the
stdiostream
class is derived directly from the
ios
class rather than from the
iostream
class. Deriving the
stdiostream
class from the
ios
class limits its usefulness and, therefore, can be considered a
historical mistake. Nevertheless, for maximum portability, you should
use only those
stdiostream
features that originate from the
ios
class and avoid the features supplied by the
iostream
class.
Constructors and Destructors
stdiostream(FILE *f)
Constructs a
stdiostream
object whose
stdiobuf
object is associated with the
FILE
parameter that the f argument points to.
~stdiostream()
Deletes a
stdiostream
object and closes the associated
stdiobuf
object.
Member Function
stdiobuf *rdbuf()
Returns a pointer to the
stdiobuf
object associated with the
stdiostream
object.
streambuf class
Provides the buffer mechanism for streams.
Header File
#include <iostream.hxx>
Alternative Header
#include <iostream.h>
Declaration
class streambuf
{
public:
streambuf();
streambuf(char *p, int len);
virtual ~streambuf();
void dbp();
protected:
int allocate();
char *base();
int blen();
virtual int doallocate();
char *eback();
char *ebuf();
char *egptr();
char *epptr();
void gbump(int n);
char *gptr();
char *pbase();
void pbump(int n);
char *pptr();
void setb(char *b, char *eb, int a = 0);
void setg(char *eb, char *g, char *eg);
void setp(char *p, char *ep);
int unbuffered();
void unbuffered(int n);
public:
int fd();
void fd(int);
FILE *fp();
void fp(FILE *);
int in_avail();
int out_waiting();
virtual int overflow(int c = EOF);
virtual int pbackfail(int c);
int sbumpc();
virtual streampos seekpos(streampos, int = ios::in
| ios::out);
virtual streampos seekoff(streamoff, seek_dir,
int = ios::in | ios::out);
virtual streambuf *setbuf(char *ptr, int len);
streambuf *setbuf(unsigned char *ptr, int len);
streambuf *setbuf(char *ptr, int len, int i);
int sgetc();
int sgetn(char *ptr, int n);
int snextc();
int sputbackc(char c);
int sputc(int c = EOF);
int sputn(const char *s, int n);
void stossc();
virtual int sync();
virtual int underflow();
};
|
Description
This class supports buffers into which you can insert (put) or extract
(get) characters. It contains only the basic members for manipulating
the characters. Also, several of its member functions are virtual; to
implement virtual functions, you typically use a class derived from the
streambuf
class.
The protected members of the
streambuf
class present an interface to derived classes organized around the get,
put, and reserve areas (arrays of bytes), which are managed
cooperatively by the base and derived classes.
The reserve area is a sequence of characters with an associated get
pointer, put pointer, or both. This area serves mainly as a resource in
which to allocate space for the put and get areas. As characters enter
and exit the reserve area, the put and get areas change but the reserve
area remains fixed. A collection of character pointer values defines
the three areas. These pointers infer a boundary condition; therefore,
it may be helpful to consider such pointers as pointing just before the
byte, even though they point directly at it.
Classes derived from
streambuf
vary in their handling of the get and put pointers. The simplest are
unidirectional buffers that permit only get and put operations. Such
classes serve as producers and consumers of characters. Queue-like
buffers (such as
strstream
and
strstreambuf
) have a put and a get pointer that move independently of each other.
In such buffers, stored characters are queued until later fetched.
File-like buffers (such as
filebuf
) allow both get and put operations but have their get and put pointers
linked together, so that when one pointer moves so does the other.
You can call virtual functions to manage the collections of characters
in the get and put areas. Services supplied by virtual functions
include fetching more characters from an ultimate producer and flushing
a collection of characters to an ultimate consumer.
If your program expects a buffer to be allocated when none was
allocated, then the iostream package allocates a default buffer.
Data Member
void dbp()
Writes directly on file descriptor 1 information in ASCII about the
state of the buffer. It is intended for debugging and nothing is
specified about the form of the output. What it prints out can be
understood only in relation to the protected interface, but
dbp()
is a public domain function so that it can be called anywhere during
debugging.
Constructors and Destructors
streambuf()
Constructs an empty buffer corresponding to an empty sequence.
streambuf(char* base, int length)
Constructs an empty buffer and then sets up the reserve area to be
length bytes long starting at base.
virtual ~streambuf()
Deletes the reserve area if one is allocated.
Member Functions
int allocate()
Tries to set up a reserve area. If a reserve area already exists or is
unbuffered, it returns 0 without doing anything. If the attempt to
allocate space succeeds,
allocate()
returns 1; otherwise, it returns
EOF
. No nonvirtual member functions of
streambuf
call
allocate()
.
char *base()
Returns a pointer to the first byte of the reserve area. The space
between
base()
and
ebuf()
is the reserve area.
int blen()
Returns the size, in type
char
, of the current reserve area.
virtual int doallocate()
In
streambuf
, it tries to allocate a reserve area using the
new
operator.
In classes derived from
streambuf
, this function is called when
allocate()
determines that space is needed.
doallocate()
is required to call
setb()
, to provide a reserve area, or to return
EOF
if it cannot. It is called only if both
unbuffered()
and
base()
are 0.
char *eback()
Returns a pointer to a lower bound on
gptr()
. The space between
eback()
and
gptr()
is available for putback operations.
char *ebuf()
Returns a pointer to the byte after the last byte of the reserve area.
char *egptr()
Returns a pointer to the byte after the last byte of the get area.
char *epptr()
Returns a pointer to the byte after the last byte of the put area.
int fd()
Returns the file descriptor associated with the
streambuf
object, if any; otherwise, it returns --1.
void fd(int f)
Sets the file descriptor associated with the
streambuf
object to f.
FILE *fp()
Returns the file pointer associated with the
streambuf
object, if any; otherwise, it returns 0.
void fp(FILE *f)
Sets the file pointer associated with the
streambuf
object to f.
void gbump(int n)
Increments
gptr()
by n, which can be a positive or a negative number. No checks
are made on whether the new value of
gptr()
is in bounds.
char *gptr()
Returns a pointer to the first byte of the get area. The characters
available are those between
gptr()
and
egptr()
. The next character fetched will be
*gptr()
unless
egptr()
is less than or equal to
gptr()
.
int in_avail()
Returns the number of characters immediately available in the get area
for fetching. This number is the number of characters that can be
fetched with confidence that an error will not be reported.
int out_waiting()
Returns the number of characters in the put area that have not been
consumed (by the ultimate consumer).
virtual int overflow(int c)
In
streambuf
, this function should be treated as if its behavior is undefined;
classes derived from
streambuf
should always define it.
In classes derived from
streambuf
, it is called to consume characters. If c is not
EOF
,
overflow(c)
also must either save c or consume it. Although it can be
called at other times, this function is usually called when the put
area is full and an attempt is being made to store a new character. The
normal action is to consume the characters between
pbase()
and
pptr()
, call
setp()
to establish a new put area, and (if c
!= EOF
) store c using
sputc()
.
overflow(c)
should return
EOF
to indicate an error; otherwise, it should return something else.
virtual int pbackfail(int c)
In
streambuf
, this function always returns
EOF
.
In classes derived from
streambuf
, this function is called when
eback()
equals
gptr()
and an attempt has been made to put c back. If this situation
can be managed (for example, by repositioning an external file),
pbackfail(c)
should return c; otherwise, it should return
EOF
.
char *pbase()
Returns a pointer to the put area base. Characters between
pbase()
and
pptr()
are stored into the buffer but are not yet consumed.
void pbump(int n)
Increments
pptr()
by n, which can be positive or negative. No checks are made on
whether the new value of
pptr()
is in bounds.
char *pptr()
Returns a pointer to the first byte of the put area. The space between
pptr()
and
epptr()
is the put area.
int sbumpc()
Moves the get pointer forward one character and returns the character
it moved past. The function returns
EOF
if the get pointer is currently at the end of the sequence.
virtual streampos seekoff(streamoff off, (ios::)seek_dir dir, int
mode)
In
streambuf
, this function returns
EOF
.
In classes derived from
streambuf
, it repositions the abstract get and put pointers (not
pptr()
and
gptr()
). mode specifies whether to modify the put pointer (
ios::out
bit set) or the get pointer (
ios::in
bit set) or both pointers. off is interpreted as a byte offset
(it is a signed value). For the meanings of dir, see the
explanation of the enumerated type
seek_dir
in class
ios
.
A class derived from
streambuf
is not required to support repositioning. If the derived class does
not, then
seekoff()
should return
EOF
. If the derived class does support repositioning,
seekoff()
should return the new position or
EOF
on error.
virtual streampos seekpos(streampos pos, int mode)
In
streambuf
, this function returns
seekoff(streamoff(pos), ios::beg, mode)
. To define seeking in a derived class, you can often define
seekoff()
and use the inherited
streambuf::seekpos
.
In classes derived from
streambuf
, this function repositions the
streambuf
get pointer, put pointer, or both, to pos. mode
specifies the affected pointers.
seekpos()
returns the argument pos or
EOF
if the class does not support repositioning or if an error occurs.
streampos(0)
signifies the beginning of the file;
streampos(EOF)
indicates an error.
void setb(char *b, char *eb, int a)
Sets
base()
to b and
ebuf()
to eb. The a argument
controls whether the reserve area will be subject to automatic deletion.
If a is nonzero, then b will be deleted when
base()
is changed by another call to
setb()
, or
when the destructor is called for the
streambuf
object.
If b and eb are both null, then the reserve area
effectively does not exist. If b is nonnull, a reserve area
exists even if eb is less than b (in which case the
reserve area has 0 length).
virtual streambuf *setbuf(char *ptr, int len)
streambuf *setbuf(unsigned char *ptr, int len)
In
streambuf
, this function honors the
request for a reserve area if there is none.
In classes derived from
streambuf
, this function offers for use
as a reserve area the array at ptr with len bytes.
Normally, if ptr or len is 0, the action is
interpreted as a request to make the
streambuf
object
unbuffered. The derived class has the choice of using or not using this area by
accepting or ignoring the request.
setbuf()
should return a
reference to the
streambuf
object if the derived class honors
the request; otherwise, it should return 0.
streambuf *setbuf(char *ptr, int len, int i)
Offers the len bytes starting at ptr as
the reserve area. If ptr is null, or len is 0 or
negative, then the function requests an unbuffered state.
Whether the offered area is used or a request for an unbuffered state is
honored depends on details of the derived class.
setbuf()
normally returns a reference to the
streambuf
object, but if the
derived class does not accept the offer or honor the request,
setbuf()
returns 0.
void setg(char *eb, char *g, char *eg)
Sets
eback()
to eb,
gptr()
to g, and
egptr()
to
eg.
void setp(char *p, char *ep)
Sets
base()
and
pptr()
to p and
epptr()
to ep.
int sgetc()
Returns the character after the get pointer; it does
not move the get pointer. It returns
EOF
if no
character is available.
int sgetn(char *ptr, int n)
Fetches n characters following the get pointer and
copies them to the area starting at ptr. If fewer than n
characters occur before the end of the sequence,
sgetn()
fetches
the characters that remain. It repositions the get pointer after the fetched
characters and returns the number of characters fetched.
int snextc()
Moves the get pointer forward one character and returns the
character after the new position. If the pointer is at the end of the
sequence, either before or after moving forward, the function returns
EOF
.
int sputbackc(char c)
Moves the get pointer back one character. c must be the
current content of the sequence just before the get pointer. The underlying
mechanism may back up the get pointer or may rearrange its internal data
structures so that c is saved. The effect is undefined if
c is not the character before the get pointer. The function
returns
EOF
, by calling
pbackfail()
, when it fails. The
conditions under which it can fail depend on the details of the derived class.
int sputc(int c)
Stores c after the put pointer and moves the put
pointer past the stored character (usually this extends the sequence). The
function returns
EOF
when an error occurs. Conditions that can cause
errors depend on the derived class.
int sputn(const char *s, int n)
Stores after the put pointer the n characters
starting at s, and moves the put pointer past them. It returns the
number of characters successfully stored. Normally n characters are
successfully stored, but fewer characters may be stored when errors occur.
void stossc()
Moves the get pointer ahead one character. If the pointer
started at the end of the sequence,
stossc()
has no effect.
virtual int sync()
In
streambuf
this function returns 0 if the get
area is empty and no unconsumed characters are present; otherwise, it returns
EOF
.
|
|
|