Class basic_streambuf

  virtual ~basic_streambuf();
  

Removes the object from memory.

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

To set the locale.

  locale pubimbue(const locale &loc);
  

The function pubimbue calls imbue(loc).

Returns the previous value of getloc().

To get the locale.

  locale getloc() const;
  

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

To set an allocation after construction.

  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.

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

#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("CodeWarrior",50);

   strbuf.sgetn(temp, 50);

   cout << temp;

   return 0;

}

Result:

  CodeWarrior
  

Determines the position of the get pointer.

  pos_type pubseekoff

     (off_type off,

     ios_base::seekdir way, ios_base::openmode 

     which = ios_base::in | ios_base::out);  

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.

Returns a pos_type via seekoff(off, way, which)

pubseekpos()

// The ewl-test file contains originally
// CodeWarrior "Software at Work"

#include <iostream>
#include <fstream> 
#include <stdlib.h>
char inFile[] = "ewl-test";

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:
  CodeWarrior "Software at Work"
  Registered Trademark

Determine and move to a desired offset.

  pos_type pubseekpos

     (pos_type sp,

     ios_base::openmode which = ios::in |ios::out);  

The function pubseekpos() is use to move to a desired offset using a type pos_type, which holds all necessary information.

Returns a pos_type via seekpos(sb, which)

pubseekoff(), seekoff()

// The file ewl-test contains:
// ABCDEFGHIJKLMNOPQRSTUVWXYZ

#include <iostream>
#include <fstream>
#include <cstdlib>

int main()
{
using namespace std;
   ifstream in("ewl-test");
   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  

To synchronize the streambuf object with its input/output.

  int pubsync();
  

The function pubsync() will attempt to synchronize the streambuf input and output.

Returns zero if successful or EOF if not via sync().

#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
  

To test for availability of input stream.

  streamsize in_avail();
  

If a read is permitted returns size of stream as a type streamsize.

To retrieve the next character in a stream.

  int_type snextc();
  

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.

If sbumpc returns traits::eof, otherwise returns sgetc().

#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
  

To move the get pointer.

int_type sbumpc();

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.

sgetc()

#include <iostream>
#include <sstream> 

const int size = 100;
std::string buf = "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:

  CodeWarrior 
  CodeWarrior --Software at Work-- 

To extract a character from the stream.

  int_type sgetc();
  

The function sgetc() extracts a single character, without moving the get pointer.

A int_type type at the get pointer if available, otherwise returns underflow().

For an example of streambuf::sgetc() usage refer to streambuf::sbumpc()

To extract a series of characters from the stream.

  streamsize sgetn(char_type *s, streamsize n);
  

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.

Returns a streamsize type as returned from the function xsgetn(s,n).

For an example of streambuf::sgetn() usage refer to pubsetbuf()

To put a character back into the stream.

  int_type sputbackc(char_type c);

  

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.

If successful, returns a pointer to the get pointer as an int_type otherwise returns pbackfail(c).

#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

  

To restore a character extracted.

  int_type sungetc();

  

The function sungetc() restores the previously extracted character. After the operation, the get pointer references the last character extracted.

If successful, returns a pointer to the get pointer as an int_type otherwise returns pbackfail(c).

For an example of streambuf::sungetc() usage refer to streambuf::sputbackc()

To insert a character in the stream.

  int_type sputc(char_type c);
  

The function sputc() inserts a character into the stream. After the operation, the get pointer references the character following the last character inserted.

If successful, returns c as an int_type otherwise returns overflow(c).

#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
  

To insert a series of characters into a stream.

  int_type sputn(char_type *s, streamsize n);
  

The function sputn() inserts a series of characters into a stream. After the operation, the get pointer references the character following the last character inserted.

Returns a streamsize type returned from a call to xputn(s,n).

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

Retrieve the beginning pointer for stream input.

  char_type* eback() const;
  

Returns the beginning pointer.

Retrieve the next pointer for stream input.

  char_type* gptr() const;
  

Returns the next pointer.

Retrieve the end pointer for stream input.

  char_type* egptr() const;
  

Returns the end pointer.

Advances the next pointer for stream input.

  void gbump(int n);
  

The function gbump() advances the input pointer by the value of the int n argument.

To set the beginning, next and end pointers.

  void setg
     (char_type *gbeg,
     char_type *gnext, 
     char_type *gend);
  

After the call to setg() the gbeg pointer equals eback(), the gnext pointer equals gptr(), and the gend pointer equals egptr().

To retrieve the beginning pointer for stream output.

  char_type* pbase() const;
  

Returns the beginning pointer.

To retrieve the next pointer for stream output.

  char_type* pptr() const;
  

Returns the next pointer.

To retrieve the end pointer for stream output.

  char_type* epptr() const;
  

Returns the end pointer.

To advance the next pointer for stream output.

  void pbump(int n);
  

The function pbump() advances the next pointer by the value of the int argument n.

To set the values for the beginning, next and end pointers.

  void setp
     (char_type* pbeg, 
     char_type* pend);
  

After the call to setp(), pbeg equals pbase(), pbeg equals pptr() and pend equals epptr().

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

To change any translations base on locale.

  virtual void imbue(const locale &loc);
  

The imbue() function allows the derived class to be informed in changes of locale and to cache results of calls to locale functions.

To set a buffer for stream input and output sequences.

  virtual basic_streambuf<char_type, traits> *setbuf
     (char_type* s, streamsize n);
  

The function setbuf() is overridden in basic_stringbuf and basic_filebuf classes.

Returns the this pointer.

To return an offset of the current pointer in an input or output stream.

  virtual pos_type seekoff
     (off_type off,
     ios_base::seekdir way, 
     ios_base::openmode which = ios::in |ios::out);
  

The function seekoff() is overridden in basic_stringbuf and basic_filebuf classes.

Returns a pos_type value, which is an invalid stream position.

To alter an input or output stream position.

  virtual pos_type seekpos
     (pos_type sp,
     ios_base::openmode which = ios::in |ios::out);
  

The function seekpos() is overridden in basic_stringbuf and basic_filebuf classes.

Returns a pos_type value, which is an invalid stream position.

To synchronize the controlled sequences in arrays.

  virtual int sync();
  

If pbase() is non null the characters between pbase() and pptr() are written to the control sequence. The function setbuf() overrides the basic_filebuf class.

Returns zero if successful and -1 if failure occurs.

Shows how many characters in an input stream

  virtual int showmanyc();
  

The function returns zero for the default behavior. Derived classes may return a negative one or a non-negative value. A positive value estimates the number of characters available in the sequence. If a positive value is returned, then successive calls to underflow() will not return traits::eof() until at least that number of characters have been extracted from the stream. If showmanyc() returns -1, then calls to underflow() or uflow() will fail.

Note that underflow or uflow might fail by throwing an exception prematurely. The intention is that the calls will not return eof() and will return immediately.

To read a number of characters from an input stream buffer.

  virtual streamsize xsgetn
     (char_type *s, streamsize n);
  

The characters are read by repeated calls to sbumpc() until either n characters have been assigned or EOF is encountered.

Returns the number of characters read.

To show an underflow condition and not increment the get pointer.

  virtual int_type underflow();
  

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.

Returns 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.

To show a underflow condition for a single character and increment the get pointer.

  virtual int_type uflow();
  

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.

Calls underflow() and if traits::eof is not returned returns the integer value of the get pointer and increments the next pointer for input.

To show a failure in a put back operation.

  virtual int_type pbackfail
     (int_type c = traits::eof());
  

The resulting conditions are the same as the function underflow().

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.

Write a number of characters to an output buffer.

  virtual streamsize xsputn
     (const char_type *s,streamsize n);
  

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.

Returns the number of characters written in a type streamsize.

Consumes the pending characters of an output sequence.

  virtual int_type overflow
  (int_type c = traits::eof());
  

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.

The function returns traits::eof() for failure or some unspecified result to indicate success.