streambuf_pub(C++)

Synopsis

   #include <iostream.h>
   

   typedef long streamoff, streampos;
   class ios {
   public:
   	enum	seek_dir { beg, cur, end };
   	enum	open_mode { in, out, ate, app, trunc, nocreate, noreplace } ;
   	// and lots of other stuff ... See ios(3C++)
   } ;
   

   class streambuf {
   public :
   

   	int		in_avail();
   	int		out_waiting();
   	int		sbumpc();
   	streambuf*	setbuf(char* ptr, int len);
   	streampos	seekpos(streampos, int =ios::in|ios::out);
   	streampos	seekoff(streamoff, seek_dir, int =ios::in|ios::out);
   	int		sgetc();
   	int		sgetn(char* ptr, int n);
   	int		snextc();
   	int		sputbackc(char);
   	int		sputc(int c);
   	int		sputn(const char* s, int n);
   	void		stossc();
   	virtual int	sync();
   };

Description

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. Queuelike buffers (e.g., see strstream(C++) and strstreambuf(C++)) 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, see filebuf(C++)) 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 streambuf_prot(C++), which describes the protected interface.

The public member functions of the streambuf class are described below. In the following descriptions assume:
-- i, n, and len are ints.
-- c is an int. It always holds a ``character'' value or EOF. A ``character'' value is always positive even when char is normally sign extended.
-- sb and sb1 are streambuf*s.
-- ptr is a char*.
-- off is a streamoff.
-- pos is a streampos.
-- dir is a seek_dir.
-- mode is an int representing an open_mode.

Public member functions:

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 will be reported.

i=sb->out_waiting()

Returns the number of characters in the put area that have not been consumed (by the ultimate consumer).

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.

pos=sb->seekoff(off, dir, mode)

Repositions the get and/or put pointers. 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.)

Not all classes derived from streambuf support repositioning. seekoff() will return EOF if the class does not support repositioning. If the class does support repositioning, seekoff() will return the new position or EOF on error.

pos=sb->seekpos(pos, 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 streampos should be treated as a ``magic cookie'' and no arithmetic should be performed on it. Two particular values have special meaning:

streampos(0)

The beginning of the file.

streampos(EOF)

Used as an error indication.

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.

sb1=sb->setbuf(ptr, len, 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 honored depends on details of the derived class. setbuf() normally returns sb, but if it does not accept the offer or honor the request, it returns 0.

i=sb->sgetn(ptr, 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.

c=sb->snextc()

Moves the get pointer forward one character and returns the character following the new position. It returns EOF if the pointer is currently at the end of the sequence or is at the end of the sequence after moving forward.

i=sb->sputbackc(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. sputbackc() returns EOF when it fails. The conditions under which it can fail depend on the details of the derived class.

i=sb->sputc(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.

i=sb->sputn(ptr, 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 i is n, but it may be less when errors occur.

sb->stossc()

Moves the get pointer forward one character. If the pointer started at the end of the sequence this function has no effect.

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. Usually this ``flushes'' any characters that have been stored but not yet consumed, and ``gives back'' any characters that may have been produced but not yet fetched. sync() returns EOF to indicate errors.

Notices

Requiring the program to provide the previously fetched character to sputback is probably a botch.

References