This section describes the public member functions of streambuf. Only objects derived from streambuf (e.g. filebuf, strstreambuf, stdiobuf) are to be used in a program rather than plain streambufs! #include <iostream.h> typedef long streamoff, streampos; class ios enum bin, tabexp}; // and lots of other classes, see ios. }; class streambuf { public:
virtual int sync(); }; | |||||||||||
The streambuf class supports buffers into which characters can be inserted (put) or from which characters can be fetched (get). Such a buffer is a sequence of characters,together with one or two pointers (a get and/or a put pointer) that define the location at which characters are to be inserted or fetched. The pointers should be thought of as pointing between characters rather than at them. This makes it easier to understand the boundary conditions (a pointer before the first character or after the last). Some of the effects of getting and putting are defined by this class but most of the details are left to specialized classes derived from streambuf (see also filebuf, sstreambuf and stdiobuf). Classes derived from streambuf vary in their treatments of the get and put pointers. The simplest are unidirectional buffers which permit only gets or only puts. Such classes serve as pure sources (producers) or sinks (consumers) of characters. Queue-like buffers (see strstream and sstreambuf ) have a put and a get pointer which move independently of each other. In such buffers characters that are stored are held (i.e., queued) until they are later fetched. Filelike buffers (e.g., filebuf) permit both gets and puts but have only a single pointer. (An alternative description is that the get and put pointers are tied together so that when one moves so does the other.) Most streambuf member functions are organized into two phases. As far as possible,operations are performed inline by storing into or fetching from arrays (the get area and the put area, which together form the reserve area, or buffer). From time to time, virtual functions are called to deal with collections of characters in the get and put areas. That is, the virtual functions are called to fetch more characters from the ultimate producer or to flush a collection of characters to the ultimate consumer. Generally the user of a streambuf does not have to know anything about these details, but some of the public members pass back information about the state of the areas. Further detail about these areas is provided in sbufprot, which describes the protected interface. The public member functions of the streambuf class are described below. In the following descriptions, assume that:
Public member functionsint i=sb→in_avail() Returns the number of characters that are immediately available in the get area for fetching. i characters may be fetched with a guarantee that no errors are reported. int i=sb→out_waiting() Returns the number of characters in the put area that have not been consumed (by the ultimate consumer). int c=sb→sbumpc() Moves the get pointer forward one character and returns the character it moved past.Returns EOF if the get pointer is currently at the end of the sequence. int c=sb→sgetc() Returns the character after the get pointer. Contrary to what most people expect from the name it does not move the get pointer. Returns EOF if there is no character available. streambuf* sb1=sb->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 zero or less, then an unbuffered state is requested. Whether the offered area is used, or a request for unbuffered state is honoured depends on details of the derived class. int i=sb->sgetn(char * ptr, int n) Fetches the n characters following the get pointer and copies them to the area starting at ptr. When there are fewer than n characters left before the end of the sequence sgetn() fetches whatever characters remain. sgetn() repositions the get pointer following the fetched characters and returns the number of characters fetched. int c=sb→snextc() Moves the get pointer forward one character and returns the character following the new position. If the pointer is currently at the end of the sequence or is at the end of the sequence after moving forward, EOF is returned. int i=sb->sputbackc(int 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 simply back up the get pointer or may rearrange its internal data structures so the c is saved. Thus the effect of sputbackc() is undefined if c is not the character before the get pointer. int i=sb->sputc(int c) Stores c after the put pointer, and moves the put pointer past the stored character; usually this extends the sequence. It returns EOF when an error occurs. The conditions that can cause errors depend on the derived class. int i=sb->sputn(const char * ptr, int n) Stores the n characters starting at ptr after the put pointer and moves the put pointer past them. sputn() returns i, the number of characters stored successfully. Normally iis n, but it may be less when errors occur. void sb →stossc() Moves the get pointer forward one character. If the pointer started at the end of the sequence this function has no effect. streampos pos=sb->seekoff(streamoff off, ios::seek_dir dir, int mode) Repositions the get and/or put pointers (i.e. the abstract get and put pointers, not pptr() and gptr()). mode specifies whether the put pointer (ios::out bit set) or the get pointer (ios::in bit set) is to be modified. Both bits may be set in which case both pointers should be affected. off is interpreted as a byte offset. (Notice that it is a signed quantity.) The meanings of possible values of dir are ios::beg The beginning of the stream. ios::cur The current position. ios::end The end of the stream (end of file.) A class derived from streambuf is not required to support repositioning. seekoff() returns EOF if the class does not support repositioning. If the class does support repositioning, seekoff() returns the new position or EOF on error. streampos pos=sb->seekpos(streampos pos, int mode) Repositions the streambuf get and/or put pointer to pos. mode specifies which pointers are affected as for seekoff(). Returns pos (the argument) or EOF if the class does not support repositioning or an error occurs. In general, a variable of type streampos should not have arithmetic performed upon it. Two particular values have special meaning: streampos(0) The beginning of the file. streampos(EOF) Used as an error indication. int i=sb→sync() Establishes consistency between the internal data structures and the external source or sink. The details of this function depend on the derived class. sync() is called to give the derived class a chance to look at the state of the areas, and synchronize them with any external representation. Normally sync() should consume any characters that have been 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 not be any unconsumed characters, and the get area should be empty. sync() should return EOF if some kind of failure occurs. In other words, sync() "flushes" any characters that have been stored but not yet consumed, and | |||||||||||
EXAMPLE | The following program defines a variable of type filebuf attached to cin and reads in blocks of characters from that filebuf until end of file is reached. Then the program determines the number of characters read in. Each newline character (\n) represents one character: #include <iostream.h>
#include <fstream.h>
int main()
{
filebuf in_file(0);
/* in_file is connected to cin */
const int N = 10;
int k;
char text_b[N+1];
/* text buffer */
cout << "Please enter " << N << " characters :\n";
cout.flush();
k = in_file.sgetn(&text_b[0],N);
cout << " " << (k+in_file.in_avail()) ;
cout << " characters have been entered.\n";
/* Each \n represents one character. */
return 0;
}
The result of executing the program is: Please enter 10 characters : 0123456789 11 characters have been entered. % CCM0998 CPU time used: 0.0040 seconds The user may change the buffer size by calling the setbuf() member function. Any buffer size may be set with setbuf(). | ||||||||||
BUGS | setbuf does not really belong in the public interface. It is there for compatibility with the stream package. | ||||||||||
SEE ALSO | |||||||||||