The header <streambuf> defines types that control input and output to character sequences.

Overview of Stream Buffers

The sections in this chapter are:

• "Header <streambuf>"
• "27.5.1 Stream buffer requirements"
• "27.5.2 Template class basic_streambuf<charT, traits>"

Header <streambuf>

Prototype:

namespace std {

template <class charT, class traits = 
char_traits<charT> >

	class basic_streambuf;

typedef basic_streambuf<char> streambuf;

typedef basic_streambuf<wchar_t> wstreambuf;

}

27.5.1 Stream buffer requirements

Stream buffers can impose constraints. The constraints include:

• The input sequence can be not readable
• The output sequence can be not writable
• The sequences can be association with other presentations such as external files
• The sequences can support operations to or from associated sequences.
• The sequences can impose limitations on how the program can read and write characters to and from a sequence or alter the stream position.

There are three pointers that control the operations performed on a sequence or associated sequences. These are used for read, writes and stream position alteration. If not null all pointers point to the same charT array object.

The beginning pointer or lowest element in an array. - (beg) The next pointer of next element addressed for read or write. - (next) The end pointer of first element addressed beyond the end of the array. - (end)

27.5.2 Template class basic_streambuf<charT, traits>

The prototype is listed below. Additional topics in this section are:

• "27.5.2.1 basic_streambuf Constructor"
• "27.5.2.2 basic_streambuf Public Member Functions"
• "27.5.2.2.1 Locales"
• "27.5.2.2.2 Buffer Management and Positioning"
• "27.5.2.2.3 Get Area"
• "27.5.2.2.4 Putback"
• "27.5.2.2.5 Put Area"
• "27.5.2.3 basic_streambuf Protected Member Functions"
• "27.5.2.3.1 Get Area Access"
• "27.5.2.3.2 Put Area Access"
• "27.5.2.4 basic_streambuf Virtual Functions"
• "27.5.2.4.1 Locales"
• "27.5.2.4.2 Buffer Management and Positioning"
• "27.5.2.4.3 Get Area"
• "27.5.2.4.4 Putback"
• "27.5.2.4.5 Put Area" Prototype:

  ---

  namespace std {
  template< class charT, class traits = char_traits<charT> >
  class basic_streambuf {
  public:
  	typedef charT char_type;
  	typedef typename traits::int_type int_type;
  	typedef typename traits::pos_type pos__type;
  	typedef typename traits::off_type off_type;
  
  	virtual ~basic_streambuf();
  
  	locale pubimbue(const locale &loc);
  	locale getloc() const;
  
  	basic_streambuf<char_type, traits> * pubsetbuf
  	(char_type* s, streamsize n);
  
  	pos_type pubseekoff
  		(off_type off,
  		ios_base::seekdir way, 
  		ios_base::openmode which = ios_base::in | ios_base::out);
  	pos_type pubseekpos
  		(pos_type sp,
  		ios_base::openmode which = ios::in | ios::out);
  
  	int pubsync();
  
  	streamsize in_avail();
  
  	int_type snextc();
  	int_type sbumpc();
  	int_type sgetc();
  	streamsize sgetn(char_type *s, streamsize n);
  
  	int_type sputback(char_type C);
  	int_type sungetc();
  
  	int_type sputc(char_type c);
  	int_type sputn(char_type *s, streamsize n);
  
  protected:
  	basic_streambuf();
  
  	char_type* eback() const;
  	char_type* gptr() const;
  	char_type* egptr() const;
  	void gbump(int n);
  	void setg
  		(char_type *gbeg, 
  		char_type *gnext,
  		char_type *gend);
  
  	char_type* pbase() const;
  	char_type* pptr() const;
  	char_type* epptr() const;
  
  	void pbump(int n);
  	void setp(char_type *pbeg, char_type *pend);
  
  	virtual void imbue(const locale &loc);
  
  	virtual basic_streambuf<char_type, traits>* setbuf
  		(char_type* s, streamsize n);
  
  	virtual pos_type seekoff
  		(off_type off,
  		ios_base::seekdir way, 
  		ios_base::openmode which = ios::in | ios::out);
  	virtual pos_type seekpos
  		(pos_type sp,
  		ios_base::openmode which = ios::in | ios::out);
  	virtual int sync();
  
  	virtual int showmanyc();
  	virtual streamsize xsgetn(char_type *s, 
  				streamsize n);
  	virtual int_type underflow();
  	virtual int_type uflow();
  
  	virtual int_type 
  			pbackfail(int_type c = traits::eof());
  
  	virtual streamsize xsputn
  		(const char_type *s,streamsize n);
  	virtual int_type overflow
  		(int_type c = traits::eof());
  	};
  }

  ---

  Remarks:

The template class basic_streambuf is an abstract class for deriving various stream buffers whose objects control input and output sequences. The type streambuf is an instantiation of char type. the type wstreambuf is an instantiation of wchar_t type.

27.5.2.1 basic_streambuf Constructor

Default Constructor

Construct and destruct an object of type basic_streambuf.

Prototype:

protected:

	basic_streambuf();

The constructor sets all pointer member objects to null pointers and calls getloc() to copy the global locale at the time of construction.

Destructor

Prototype:

virtual ~basic_streambuf();

Removes the object from memory.

27.5.2.2 basic_streambuf Public Member Functions

The public member functions allow access to member functions from derived classes.

27.5.2.2.1 Locales

Locales are used for encapsulation and manipulation of information to a particular locale.

basic_streambuf::pubimbue

To set the locale.

Prototype:

locale pubimbue(const locale &loc);

The function pubimbue calls imbue(loc).

Return:

The previous value of getloc().

basic_streambuf::getloc

To get the locale.

Prototype:

locale getloc() const;

If pubimbue has already been called one it returns the last value of loc supplied otherwise the current one. If pubimbue has been called but has not returned a value it from imbue, it then returns the previous value.

27.5.2.2.2 Buffer Management and Positioning

Functions used to manipulate the buffer and the input and output positioning pointers.

basic_streambuf::pubsetbuf

To set an allocation after construction.

Prototype:

basic_streambuf<char_type, traits> *pubsetbuf

	(char_type* s, streamsize n);

The first argument is used in an another function by a filebuf derived class. See setbuf(). The second argument is used to set the size of a dynamic allocated buffer.

Return:

A pointer to basic_streambuf<char_type, traits> via setbuf(s, n).

Example of basic_streambuf::pubsetbuf() usage::

#include <iostream>
#include <sstream>
const int size = 100; 
char temp[size] = "\0";

int main()
{
using namespace std;
  
	stringbuf strbuf; 
	strbuf.pubsetbuf('\0', size);
	strbuf.sputn("Metrowerks CodeWarrior",50);
	strbuf.sgetn(temp, 50);
	cout << temp;

	return 0;
}





Result:
Metrowerks CodeWarrior
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::pubseekoff
		
		
		
		
		
 
		
		
		
 Determines the position of the get pointer.
		
		
		
Prototype:		
		
pos_type pubseekoff
		
		
		
 
		
		
		
	(off_type off,
		
		
		
 
		
		
		
	ios_base::seekdir way, ios_base::openmode 
		
		
		
 
		
		
		
	which = ios_base::in | ios_base::out);
		
		
		
Remarks:		
		
 The member function pubseekoff() is used to find the difference in bytes of the get pointer from
		
		a known position (such as the beginning or end of a stream).
		The
		
		function pubseekoff() returns a type pos_type which holds all the necessary information.
		
		
		
Return:		
		
 A pos_type via seekoff(off, way, which)
		
		
		
See Also:		
		
 pubseekpos()
		
		
		
Example of basic_streambuf::pubseekoff() usage::		
		

				

		
The MW Reference file contains originally
Metrowerks CodeWarrior "Software at Work"
		
		
		
 
		
		
		

				#include <iostream>
		
		
		
#include <fstream> 
		
		
		
#include <stdlib.h>
		
		
		
 
		
		
		
char inFile[] = "MW Reference";
		
		
		
 
		
		
		
int main()
		
		
		
{
		
		
		
using namespace std;
		
		
		
 
		
		
		
	ifstream inOut(inFile, ios::in | ios::out);
		
		
		
	if(!inOut.is_open()) 
		
		
		
		{cout << "Could not open file"; exit(1);}
		
		
		
	ostream Out(inOut.rdbuf());
		
		
		
 
		
		
		
	char str[] = "\nRegistered Trademark";
		
		
		
 
		
		
		
	inOut.rdbuf()->pubseekoff(0, ios::end);
		
		
		
 
		
		
		
	Out << str;
		
		
		
 
		
		
		
	inOut.close();
		
		
		
	return 0;
		
		
		
}
		
		
		
		
		

				

		
Result:
The File now reads:
Metrowerks CodeWarrior "Software at Work"
Registered Trademark
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::pubseekpos
		
		
		
		
		
 
		
		
		
 Determine and move to a desired offset.
		
		
		
Prototype:		
		
pos_type pubseekpos
		
		
		
 
		
		
		
	(pos_type sp,
		
		
		
 
		
		
		
	ios_base::openmode which = ios::in 
|ios::out);
		
		
		
Remarks:		
		
 The function pubseekpos() is use to move to a desired offset
		
		using a type pos_type, which holds all necessary information.
		
		
		
Return:		
		
 A pos_type via seekpos(sb, which)
		
		
		
See Also:		
		
 pubseekoff(), seekoff()
		
		
		
Example of streambuf::pubseekpos() usage::		
		

				

		
The file MW Reference contains:
ABCDEFGHIJKLMNOPQRSTUVWXYZ





#include <iostream>
#include <fstream>
#include <cstdlib>
int main()
{
using namespace std;

	ifstream in("MW Reference");
	if(!in.is_open())
		{cout << "could not open file"; exit(1);} 

	streampos spEnd(0), spStart(0), aCheck(0);
	spEnd = spStart = 5;

	aCheck = in.rdbuf()->pubseekpos(spStart,ios::in);
	cout << "The offset at the start of the reading"
			<< " in bytes is " 
			<< static_cast<streamoff>(aCheck) << endl;

	char ch;
	while(spEnd != spStart+10) 
	{
		in.get(ch);
		cout << ch;
		spEnd = in.rdbuf()->pubseekoff(0, ios::cur);
	}

	aCheck = in.rdbuf()->pubseekoff(0,ios::cur);
	cout << "\nThe final position's offset"
			<< " in bytes now is "
			<< static_cast<streamoff>(aCheck) << endl;

	in.close();

	return 0;
}





Result:
The offfset for the start of the reading in bytes is 5
FGHIJKLMNO
The final position's offset in bytes now is 15
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::pubsync
		
		
		
		
		
 
		
		
		
 To synchronize the streambuf object with its input/output.
		
		
		
Prototype:		
		
int pubsync();
		
		
		
Remarks:		
		
 The function pubsync() will attempt to synchronize the streambuf
		
		input and output.
		
		
		
Return:		
		
 Zero if successful or EOF if not via sync().
		
		
		
Example of streambuf::pubsync() usage::		
		

				

		
#include <iostream>
struct address {
	int number;
	char street[40];
}addbook;

int main()
{ 
using namespace std;

	cout << "Enter your street number: ";
	cin >> addbook.number;

	cin.rdbuf()->pubsync(); // buffer flush

	cout << "Enter your street name: "; 
	cin.get(addbook.street, 40);

	cout << "Your address is: "
			<< addbook.number << " " << addbook.street;

	return 0;
}





Result:
Enter your street number: 2201
Enter your street name: Donley Drive
Your address is: 2201 Donley Drive
		
		
		
 
		
		
		

				

				
		
 27.5.2.2.3 Get Area
		
		
		
		
		
 
		
		
		
 Public functions for retrieving input from a buffer.
		
		
		


				
		
 basic_streambuf::in_avail
		
		
		
		
		
 
		
		
		
 To test for availability of input stream.
		
		
		
Prototype:		
		
streamsize in_avail();
		
		
		
Return:		
		
 If a read is permitted returns size of stream as a type streamsize.
		
		
		


				
		
 basic_streambuf::snextc
		
		
		
		
		
 
		
		
		
 To retrieve the next character in a stream.
		
		
		
Prototype:		
		
int_type snextc();
		
		
		
Remarks:		
		
 The function snextc() calls sbumpc() to extract the next character in a stream. After
		
		the operation, the get pointer references the character following
		
		the last character extracted.
		
		
		
Return:		
		
 If sbumpc returns traits::eof returns that, otherwise returns sgetc().
		
		
		
Example of streambuf::snextc() usage::		
		

				

		
#include <iostream>
#include <sstream>
const int size = 100; 

int main()
{
using namespace std;

	stringbuf strbuf; 
	strbuf.pubsetbuf('\0', size);
	strbuf.sputn("ABCDE",50);

	char ch;
					// look ahead at the next character
	ch =strbuf.snextc(); 
	cout << ch;
		// get pointer was not returned after peeking
	ch = strbuf.snextc();
	cout << ch;

	return 0;
}





Result: 
BC
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::sbumpc
		
		
		
		
		
 
		
		
		
 To move the get pointer.
		
		
		
Prototype:		
		
int_type sbumpc();
		
		
		
Remarks:		
		
 The function sbumpc() moves the get pointer one element when called.
		
		
		
Return:		
		
 The value of the character at the get pointer. It returns uflow() if it fails to move the pointer.
		
		
		
See Also:		
		
sgetc()
		
		
		
Example of streambuf::sbumpc() usage::		
		

				
		
#include <iostream>
#include <sstream> 
const int size = 100;
std::string buf = "Metrowerks CodeWarrior --Software at Work--"; 
 
int main()
{   
using namespace std;

	stringbuf strbuf(buf);

	int ch;
	for (int i = 0; i < 23; i++)
	{
		ch = strbuf.sgetc();
		strbuf.sbumpc();
		cout.put(ch);
	}
	cout << endl;
	cout << strbuf.str() << endl;
	return 0;
}





Result:
Metrowerks CodeWarrior 
Metrowerks CodeWarrior --Software at Work--
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::sgetc
		
		
		
		
		
 
		
		
		
 To extract a character from the stream.
		
		
		
Prototype:		
		
int_type sgetc();
		
		
		
Remarks:		
		
 The function sgetc() extracts a single character, without moving the get pointer.
		
		
		
Return:		
		
 A int_type type at the get pointer if available otherwise returns underflow().
		
		
		
Example of streambuf::sgetc() usage::		
		

						

		
See streambuf::sbumpc()
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::sgetn
		
		
		
		
		
 
		
		
		
 To extract a series of characters from the stream. 
		
		
		
Prototype:		
		
streamsize sgetn(char_type *s, streamsize n);
		
		
		
Remarks:		
		
 The public member function sgetn() is used to extract a series of characters from the stream buffer.
		
		After the operation, the get pointer references the character
		
		following the last character extracted.
		
		
		
Return:		
		
 A streamsize type as returned from the function xsgetn(s,n).
		
		
		
Example of streambuf::sgetn() usage::		
		

						

		
See pubsetbuf()
		
		
		
 
		
		
		

				

				
		
 27.5.2.2.4 Putback
		
		
		
		
		
 
		
		
		
 Public functions to return a value to a stream.
		
		
		


				
		
 basic_streambuf::sputback
		
		
		
		
		
 
		
		
		
 To put a character back into the stream.
		
		
		
Prototype:		
		
int_type sputback(char_type c);
		
		
		
Remarks:		
		
 The function sputbackc() will replace a character extracted from the stream with another
		
		character. The results are not assured if the putback is not
		immediately
		
		done or a different character is used.
		
		
		
Return:		
		
 If successful returns a pointer to the get pointer as an int_type otherwise returns pbackfail(c).
		
		
		
Example of streambuf::sputbackc() usage::		
		

				

		
#include <iostream>
#include <sstream>
std::string buffer = "ABCDEF";

int main()
{ 
using namespace std;

	stringbuf strbuf(buffer); 	
	char ch;
	
	ch = strbuf.sgetc(); // extract first character
	cout << ch; 		// show it

		//get the next character 
	ch = strbuf.snextc(); 

	// if second char is B replace first char with x 
	if(ch =='B') strbuf.sputbackc('x'); 

		// read the first character now x
	cout << (char)strbuf.sgetc();   

	strbuf.sbumpc(); 		// increment get pointer
		 // read second character
	cout << (char)strbuf.sgetc();

	strbuf.sbumpc(); 		// increment get pointer
		// read third character
	cout << (char)strbuf.sgetc(); 
		
		// show the new stream after alteration
	strbuf.pubseekoff(0, ios::beg);
	cout << endl;
	
	cout << (char)strbuf.sgetc();
	

	while( (ch = strbuf.snextc()) != EOF) 
		cout << ch;

	
	return 0;
}





Result:
AxBC
xBCDEF
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::sungetc
		
		
		
		
		
 
		
		
		
 To restore a character extracted.
		
		
		
Prototype:		
		
int_type sungetc();
		
		
		
Remarks:		
		
 The function sungetc() restores the previously extracted character. After the operation,
		
		the get pointer references the last character extracted.
		
		
		
Return:		
		
 If successful returns a pointer to the get pointer as an int_type otherwise returns pbackfail(c).
		
		
		
Example of streambuf::sungetc() usage::		
		

						

		
See: streambuf::sputbackc()
		
		
		
 
		
		
		

				

				
		
 27.5.2.2.5 Put Area
		
		
		
		
		
 
		
		
		
 Public functions for inputting characters into a buffer.
		
		
		


				
		
 basic_streambuf::sputc
		
		
		
		
		
 
		
		
		
 To insert a character in the stream.
		
		
		
Prototype:		
		
int_type sputc(char_type c);
		
		
		
Remarks:		
		
 The function sputc() inserts a character into the stream. After the operation, the
		
		get pointer references the character following the last character
		
		extracted.
		
		
		
Return:		
		
 If successful returns c as an int_type otherwise returns -overflow(c).
		
		
		
Example of streambuf::sputc() usage::		
		

				

		
#include <iostream>
#include <sstream>
int main()
{ 
using namespace std;

	stringbuf strbuf; 
	strbuf.sputc('A');

	char ch;
	ch = strbuf.sgetc();
	cout << ch;

	return 0;
}





Result:
A
		
		
		
 
		
		
		

				

				
		
 basic_streambuf::sputn
		
		
		
		
		
 
		
		
		
 To insert a series of characters into a stream.
		
		
		
Prototype:		
		
int_type sputn(char_type *s, streamsize n);
		
		
		
Remarks:		
		
 The function sputn() inserts a series of characters into a stream. After the operation,
		
		the get pointer references the character following the last
		character
		
		extracted.
		
		
		
Return:		
		
 A streamsize type returned from a call to xputn(s,n).
		
		
		


				
		
 27.5.2.3 basic_streambuf Protected Member Functions
		
		
		
		
		
 
		
		
		
 Protected member functions that are used for stream buffer manipulations
		
		by the basic_streambuf class and derived classes from it.
		
		
		


				
		
 27.5.2.3.1 Get Area Access
		
		
		
		
		
 
		
		
		
 Member functions for extracting information from a stream.
		
		
		


				
		
 basic_streambuf::eback
		
		
		
		
		
 
		
		
		
 Retrieve the beginning pointer for stream input.
		
		
		
Prototype:		
		
char_type* eback() const;
		
		
		
Return:		
		
 The beginning pointer.
		
		
		


				
		
 basic_streambuf::gptr
		
		
		
		
		
 
		
		
		
 Retrieve the next pointer for stream input.
		
		
		
Prototype:		
		
char_type* gptr() const;
		
		
		
Return:		
		
 The next pointer.
		
		
		


				
		
 basic_streambuf::egptr
		
		
		
		
		
 
		
		
		
 Retrieve the end pointer for stream input.
		
		
		
Prototype:		
		
char_type* egptr() const;
		
		
		
Return:		
		
 The end pointer.
		
		
		


				
		
 basic_streambuf::gbump
		
		
		
		
		
 
		
		
		
 Advances the next pointer for stream input.
		
		
		
Prototype:		
		
void gbump(int n);
		
		
		
Remarks:		
		
 The function gbump() advances the input pointer by the value of the int n argument.
		
		
		


				
		
 basic_streambuf::setg
		
		
		
		
		
 
		
		
		
 To set the beginning, next and end pointers.
		
		
		
Prototype:		
		
void setg
		
		
		
 
		
		
		
	(char_type *gbeg,
		
		
		
 
		
		
		
	char_type *gnext, 
		
		
		
 
		
		
		
	char_type *gend);
		
		
		
Remarks:		
		
 After the call to setg() the gbeg pointer equals eback(), the gnext pointer equals gptr(), and the gend pointer equals egptr().
		
		
		


				
		
 27.5.2.3.2 Put Area Access
		
		
		
		
		
 
		
		
		
 Protec5ted member functions for stream output sequences.
		
		
		


				
		
 basic_streambuf::pbase
		
		
		
		
		
 
		
		
		
 To retrieve the beginning pointer for stream output.
		
		
		
Prototype:		
		
char_type* pbase() const;
		
		
		
Return:		
		
 The beginning pointer.
		
		
		


				
		
 basic_streambuf::pptr
		
		
		
		
		
 
		
		
		
 To retrieve the next pointer for stream output.
		
		
		
Prototype:		
		
char_type* pptr() const;
		
		
		
Return:		
		
 The next pointer.
		
		
		


				
		
 basic_streambuf::epptr
		
		
		
		
		
 
		
		
		
 To retrieve the end pointer for stream output.
		
		
		
Prototype:		
		
char_type* epptr() const;
		
		
		
Return:		
		
 The end pointer.
		
		
		


				
		
 basic_streambuf::pbump
		
		
		
		
		
 
		
		
		
 To advance the next pointer for stream output.
		
		
		
Prototype:		
		
void pbump(int n);
		
		
		
Remarks:		
		
 The function pbump() advances the next pointer by the value of the int argument n.
		
		
		


				
		
 basic_streambuf::setp
		
		
		
		
		
 
		
		
		
 To set the values for the beginning, next and end pointers.
		
		
		
Prototype:		
		
void setp
		
		
		
 
		
		
		
	(char_type* pbeg, 
		
		
		
 
		
		
		
	char_type* pend);
		
		
		
Remarks:		
		
 After the call to setp(), pbeg equals pbase(), pbeg equals pptr() and pend equals epptr().
		
		
		


				
		
 27.5.2.4 basic_streambuf Virtual Functions
		
		
		
		
		
 
		
		
		
 The virtual functions in basic_streambuf class are to be overloaded in any derived class.
		
		
		


				
		
 27.5.2.4.1 Locales
		
		
		
		
		
 
		
		
		
 To get and set the stream locale. These functions should be overridden
		
		in derived classes.
		
		
		


				
		
 basic_streambuf::imbue
		
		
		
		
		
 
		
		
		
 To change any translations base on locale.
		
		
		
Prototype:		
		
virtual void imbue(const locale &loc);
		
		
		
Remarks:		
		
 The imbue() function allows the derived class to be informed
		
		in changes of locale and to cache results of calls to locale
		functions.
		
		
		


				
		
 27.5.2.4.2 Buffer Management and Positioning
		
		
		
		
		
 
		
		
		
 Virtual functions for positioning and manipulating the stream
		
		buffer. These functions should be overridden in derived classes.
		
		
		


				
		
 basic_streambuf::setbuf
		
		
		
		
		
 
		
		
		
 To set a buffer for stream input and output sequences.
		
		
		
Prototype:		
		
virtual basic_streambuf<char_type, traits> *

setbuf
		
		
		
 
		
		
		
	(char_type* s, streamsize n);
		
		
		
Remarks:		
		
 The function setbuf() is overridden in basic_stringbuf and basic_filebuf classes.
		
		
		
Return:		
		
 The this pointer.
		
		
		


				
		
 basic_streambuf::seekoff
		
		
		
		
		
 
		
		
		
 To return an offset of the current pointer in an input or output
		
		streams.
		
		
		
Prototype:		
		
virtual pos_type seekoff
		
		
		
 
		
		
		
	(off_type off,
		
		
		
 
		
		
		
	ios_base::seekdir way, 
		
		
		
 
		
		
		
	ios_base::openmode which = ios::in 
|ios::out);
		
		
		
Remarks:		
		
 The function seekoff() is overridden in basic_stringbuf and basic_filebuf classes.
		
		
		
Return:		
		
 A pos_type value, which is an invalid stream position.
		
		
		


				
		
 basic_streambuf::seekpos
		
		
		
		
		
 
		
		
		
 To alter an input or output stream position.
		
		
		
Prototype:		
		
virtual pos_type seekpos
		
		
		
 
		
		
		
	(pos_type sp,
		
		
		
 
		
		
		
	ios_base::openmode which = ios::in 
|ios::out);
		
		
		
Remarks:		
		
 The function seekpos() is overridden in basic_stringbuf and basic_filebuf classes.
		
		
		
Return:		
		
 A pos_type value, which is an invalid stream position.
		
		
		


				
		
 basic_streambuf::sync
		
		
		
		
		
 
		
		
		
 To synchronize the controlled sequences in arrays.
		
		
		
Prototype:		
		
virtual int sync();
		
		
		
Remarks:		
		
 If pbase() is non null the characters between pbase() and pptr() are written to the control sequence. The function setbuf() is overridden the basic_filebuf class.
		
		
		
Return:		
		
 Zero if successful and -1 if failure occurs.
		
		
		


				
		
 27.5.2.4.3 Get Area
		
		
		
		
		
 
		
		
		
 Virtual functions for extracting information from an input stream
		
		buffer. These functions should be overridden in derived classes.
		
		
		


				
		
 basic_streambuf::showmanc
		
		
		
		
		
 
		
		
		
 Shows how many characters in an input stream
		
		
		
Prototype:		
		
virtual int showmanyc();
		
		
		
Remarks:		
		
 If the function showmanyc() returns a positive value then calls to underflow() will succeed. If showmanyc() returns a negative number any calls to the functions underflow() and uflow() will fail.
		
		
		
Return:		
		
 Zero for normal behavior and negative or positive one.
		
		
		


				
		
 basic_streambuf::xsgetn
		
		
		
		
		
 
		
		
		
 To read a number of characters from and input stream buffer.
		
		
		
Prototype:		
		
virtual streamsize xsgetn
		
		
		
 
		
		
		
	(char_type *s, streamsize n);
		
		
		
Remarks:		
		
 The characters are read by repeated calls to sbumpc() until either n characters have been assigned or EOF is encountered.
		
		
		
Return:		
		
 The number of characters read.
		
		
		


				
		
 basic_streambuf::underflow
		
		
		
		
		
 
		
		
		
 To show an underflow condition and not increment the get pointer.
		
		
		
Prototype:		
		
virtual int_type underflow();
		
		
		
Remarks:		
		
 The function underflow() is called when a character is not available for sgetc().
		
		
		
 
		
		
		
 There are many constraints for underflow().
		
		
		
 
		
		
		

						
			
The pending sequence of characters is a concatenation of end pointer
			
			minus the get pointer plus some sequence of characters to be
			read
			
			from input.
			
			
			
The result character if the sequence is not empty the first character
			
			in the sequence or the next character in the sequence.
			
			
			
The backup sequence if the beginning pointer is null, the sequence is empty, otherwise the sequence is the get pointer minus the beginning pointer.
			
			
			
Return:		
		
		
		
		
 The first character of the pending sequence and does not increment
		
		the get pointer. If the position is null returns traits::eof() to indicate failure.
		
		
		


				
		
 basic_streambuf::uflow
		
		
		
		
		
 
		
		
		
 To show a underflow condition for a single character and increment
		
		the get pointer.
		
		
		
Prototype:		
		
virtual int_type uflow();
		
		
		
Remarks:		
		
 The function uflow() is called when a character is not available for sbumpc().
		
		
		
 
		
		
		
 The constraints are the same as underflow(), with the exceptions that the resultant character is transferred
		
		from the pending sequence to the back up sequence and the pending
		
		sequence may not be empty.
		
		
		
Return:		
		
 Calls underflow() and if traits::eof is not returned returns the integer value of the get pointer and increments the next pointer for input.
		
		
		


				
		
 27.5.2.4.4 Putback
		
		
		
		
		
 
		
		
		
 Virtual functions for replacing data to a stream. These functions
		
		should be overridden in derived classes.
		
		
		


				
		
 basic_streambuf::pbackfail
		
		
		
		
		
 
		
		
		
 To show a failure in a put back operation.
		
		
		
Prototype:		
		
virtual int_type pbackfail
		
		
		
 
		
		
		
	(int_type c = traits::eof());
		
		
		
Remarks:		
		
 The resulting conditions are the same as the function underflow().
		
		
		
Return:		
		
 The function pbackfail() is only called when a put back operation
		
		really has failed and returns traits::eof. If success occurs
		the
		
		return is undefined.
		
		
		


				
		
 27.5.2.4.5 Put Area
		
		
		
		
		
 
		
		
		
 Virtual function for inserting data into an output stream buffer.
		
		These functions should be overridden in derived classes.
		
		
		


				
		
 basic_streambuf::xsputn
		
		
		
		
		
 
		
		
		
 Write a number of characters to an output buffer.
		
		
		
Prototype:		
		
virtual streamsize xsputn
		
		
		
 
		
		
		
	(const char_type *s,streamsize n);
		
		
		
Remarks:		
		
 The function xsputn() writes to the output character by using repeated calls to sputc(c). Write stops when n characters have been written or EOF is encountered.
		
		
		
Return:		
		
 The number of characters written in a type streamsize.
		
		
		


				
		
 basic_streambuf::overflow
		
		
		
		
		
 
		
		
		
 Consumes the pending characters of an output sequence.
		
		
		
Prototype:		
		
virtual int_type overflow
		
		
		
 
		
		
		
(int_type c = traits::eof());
		
		
		
Remarks:		
		
 The pending sequence is defined as the concatenation of the put pointer minus the beginning pointer plus either the sequence of characters or an empty sequence, unless
		
		the beginning pointer is null in which case the pending sequence
		
		is an empty sequence.
		
		
		
 
		
		
		
 This function is called by sputc() and sputn() when the buffer is not large enough to hold the output sequence.
		
		
		
 
		
		
		
 Overriding this function requires that:
		
		
		
 
		
		
		

						
			
When overridden by a derived class how characters are consumed
			
			must be specified.
			
			
			
After the overflow either the beginning pointer must be null or the beginning and put pointer must both be set to the same non-null value.
			
			
			
The function may fail if appending characters to an output stream
			
			fails or failure to set the previous requirement occurs.
			
			
			
Return:		
		
		
		
		
 The function returns traits::eof() for failure or some unspecified result to indicate success.
		
		
		
 
		
		
		

		
		
		
  
		
		
		
 
		
		
		
 
		
		
		
		
		

				[ First ]  [ Previous ]  [ Next ]  [ Last ]  [ Manuals ]		
		

				

		

		
Visit the Metrowerks website at: http://www.metrowerks.com

				For assistance contact Metrowerks Technical Support at: cw_support@metrowerks.com

				Copyright © 2000, Metrowerks Corp. All rights reserved.
		
 
		
Last updated: July 21, 2000