| Previous | Contents | Index |
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.
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.
stdiobuf *rdbuf()
Returns a pointer to the stdiobuf object associated with the stdiostream object.
Provides the buffer mechanism for streams.
#include <iostream.hxx>Alternative Header
#include <iostream.h>
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(); };
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.
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.
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.
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.In classes derived from streambuf, this function is called to let derived classes examine the state of the put, get, and reserve areas, and to synchronize these areas with any external representation. Normally 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, no unconsumed characters should remain and the get area should be empty. If some kind of failure occurs, sync() should return EOF.
int unbuffered()
Returns the current buffering state flag, which is independent of the actual allocation of a reserve area. This function's primary purpose is to find out if a reserve area is being allocated automatically by allocate().void unbuffered(int n)
Sets the value of the current buffering state flag. If n equals 0, then the streambuf object is buffered; otherwise it is unbuffered. This function's primary purpose is to control whether a reserve area is allocated automatically by allocate().virtual int underflow()
In streambuf, this function should be treated as if its behavior is undefined; classes derived from streambuf must define it.In classes derived from streambuf, it is 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.
static const int bufsize = 1024;
char buf[bufsize] ;
int p, g ;
do {
in->sgetc() ; (1)
g = in->in_avail() ; (2)
if (g > bufsize) g = bufsize ; (3)
g = in->sgetn(buf,g) ;
p = out->sput(buf,g) ;
out->sync() ; (4)
if (p!=g) error("output error");
} while (g > 0)
|
Provides a way to pass characters into the in and out arrays as soon as the characters become available (as when someone types them from a terminal) as follows:
- Ensures at least one character is immediately available in the in array (unless the get pointer is at the end of the sequence).
- Returns the number of characters immediately available.
- Checks that chunks in which the characters become available are less than bufsize, and that they fit into the arrays.
- Sends characters put into the out array to the ultimate consumer.
Specializes the iostream class for storing in and fetching from arrays of bytes.
#include <strstream.hxx>Alternative Header
#include <strstream.h>
class strstream: public iostream { public: strstream(); strstream(char *, int, int); strstreambuf *rdbuf(); char *str(); };
This class specializes the iostream class for storing in and fetching from arrays of bytes. It handles all predefined data types, and provides an extensive set of options for performing input and output on these data types.
strstream()
Constructs an strstream object and dynamically allocates space to hold stored characters.strstream(char *cp, int n, int mode)
Constructs an strstream object. It stores characters into the array starting at cp and continuing for n bytes. If ios::ate or ios::app is set in mode, cp is presumed to be a null-terminated string and storing begins at the null character; otherwise, storing begins at cp. Seeks are permitted anywhere in the array.
strstreambuf *rdbuf()
Returns a pointer to the strstreambuf object associated with a strstream object.char *str()
Returns a pointer to an explicit array, to be used as the associated strstreambuf object, if the strstream object was constructed with such an array; otherwise, it returns a pointer to a dynamically allocated area. Until str() is called, deleting the dynamically allocated area is the responsibility of the strstream object. After str() returns, dynamic allocation becomes the responsibility of the user program. After str() has been called, the effect of storing more characters into the strstream object is undefined.
Specializes the streambuf class for input and output performed on arrays of bytes in memory.
#include <strstream.hxx>Alternative Header
#include <strstream.h>
class strstreambuf: public streambuf { public: strstreambuf(); strstreambuf(char *, int, char *); strstreambuf(int); strstreambuf(unsigned char *, int, unsigned char *); strstreambuf(void *(*a)(long), void (*f)(void *)); void freeze(int n = 1); virtual int overflow(int); virtual streambuf *setbuf(char *, int); char *str(); virtual int underflow(); };
Objects of this class let you use an array of bytes (a string of characters) in memory as a streambuf object for stream input/output operations on various kinds of data. Mapping between abstract get and put pointers and char* pointers is direct in the sense that a char* is interpreted as logically pointing immediately ahead of the char it actually points to. Moving the pointers corresponds to incrementing and decrementing the char* values.
Previous Next Contents Index