The header <strstream> defines streambuf derived classes that allow for the formatting
and storage of character array based buffers, as well as their
input and output.
The sections in this chapter are:
¯ "Strstreambuf constructors and Destructors"
¯ "Strstreambuf Public Member Functions"
¯ "Protected Virtual Member Functions"
"Istrstream Class," a strstrean class for input
¯ "Constructors and Destructor"
"Ostrstream Class," a strstream class for output
¯ "Constructors and Destructor"
"Strstream Class," a class for input and output
¯ "Constructors and Destructor"
The include file strstream includes three classes, for in memory character array based stream input and output.
Class declarations for header <strstream>:
class strstreambuf
: public streambuf
{
public:
explicit strstreambuf(streamsize alsize_arg = 0);
strstreambuf(void* (*palloc_arg)(size_t),
void (*pfree_arg)(void*));
strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0);
strstreambuf(const char* gnext_arg, streamsize n);
strstreambuf(signed char* gnext_arg, streamsize n,
signed char* pbeg_arg = 0);
strstreambuf(const signed char* gnext_arg, streamsize n);
strstreambuf(unsigned char* gnext_arg, streamsize n,
unsigned char* pbeg_arg = 0);
strstreambuf(const unsigned char* gnext_arg, streamsize n);
virtual ~strstreambuf();
void freeze(bool freezefl = true);
char* str();
int pcount() const;
protected:
virtual int_type overflow (int_type c = EOF);
virtual int_type pbackfail(int_type c = EOF);
virtual int_type underflow();
virtual pos_type seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which = ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type sp,
ios_base::openmode which = ios_base::in | ios_base::out);
virtual streambuf* setbuf(char* s, streamsize n);
private:
typedef unsigned char strstate;
static const strstate allocated = 1 << 0;
static const strstate constant = 1 << 1;
static const strstate dynamic = 1 << 2;
static const strstate frozen = 1 << 3;
static const streamsize default_alsize = 128;
streamsize alsize_;
void* (*palloc_)(size_t);
void (*pfree_)(void*);
strstate strmode_;
void init(char* gnext_arg, streamsize n, char* pbeg_arg = 0);
};
The class strstreambuf is derived from streambuf to associate a stream with an in memory character array.
The strstreambuf class includes virtual protected and public member functions
class strstreambuf
: public streambuf
{
public:
explicit strstreambuf(streamsize alsize_arg = 0);
strstreambuf(void* (*palloc_arg)(size_t),
void (*pfree_arg)(void*));
strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0);
strstreambuf(const char* gnext_arg, streamsize n);
strstreambuf(signed char* gnext_arg, streamsize n,
signed char* pbeg_arg = 0);
strstreambuf(const signed char* gnext_arg, streamsize n);
strstreambuf(unsigned char* gnext_arg, streamsize n,
unsigned char* pbeg_arg = 0);
strstreambuf(const unsigned char* gnext_arg, streamsize n);
virtual ~strstreambuf();
void freeze(bool freezefl = true);
char* str();
int pcount() const;
protected:
virtual int_type overflow (int_type c = EOF);
virtual int_type pbackfail(int_type c = EOF);
virtual int_type underflow();
virtual pos_type seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which = ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type sp,
ios_base::openmode which = ios_base::in | ios_base::out);
virtual streambuf* setbuf(char* s, streamsize n);
private:
typedef unsigned char strstate;
static const strstate allocated = 1 << 0;
static const strstate constant = 1 << 1;
static const strstate dynamic = 1 << 2;
static const strstate frozen = 1 << 3;
static const streamsize default_alsize = 128;
streamsize alsize_;
void* (*palloc_)(size_t);
void (*pfree_)(void*);
strstate strmode_;
void init(char* gnext_arg, streamsize n, char* pbeg_arg = 0);
};
The template class streambuf is an abstract class for deriving various stream buffers whose
objects control input and output sequences.
Construct and destruct an object of type streambuf.
Dynamic Prototypes:
explicit strstreambuf(streamsize alsize_arg = 0);
strstreambuf(void* (*palloc_arg)(size_t),
void (*pfree_arg)(void*)); strstreambuf(char* gnext_arg, streamsize n,
char* pbeg_arg = 0); strstreambuf(const char* gnext_arg, streamsize n);
strstreambuf(signed char* gnext_arg,
streamsize n, signed char* pbeg_arg = 0); strstreambuf(const signed char* gnext_arg,
streamsize n); strstreambuf(unsigned char* gnext_arg,
streamsize n, unsigned char* pbeg_arg = 0); strstreambuf(const unsigned char* gnext_arg,
streamsize n); The constructor sets all pointer member objects to null pointers.
The strstreambuf object is used usually for a intermediate storage object for input and output. The overloaded constructor that is used determines the attributes of the arry object when it is created. These might be allocated, or dynamic and are stored in a bitmask type. The first two constructors listed allow for dynamic allocation. The constructors with character array arguments will use that character array for a buffer.
To destroy a strstreambuf object.
Prototype:
virtual ~~strstreambuf();Remarks:
Removes the object from memory.
The public member functions allow access to member functions from derived classes.
To freeze the allocation of strstreambuf.
Prototype:
void freeze(bool freezefl = true);
Remarks:
The function freeze() stops allocation if the strstreambuf object is using dynamic allocation and prevents the destructor from freeing the allocation. The function freeze(0) when used with zero as an argument releases the freeze to allow for destruction.
Return:
Example of strstreambuf::freeze() usage::
#include <iostream>
#include <strstream>
#include <string.h>
const int size = 100;
int main()
{
// dynamic allocation minimum allocation 100
strstreambuf strbuf(size);
// add a string and get size
strbuf.sputn( "Metrowerks ", strlen("Metrowerks "));
cout << "The size of the stream is: "
<< strbuf.pcount() << endl;
// add a string and get size
strbuf.sputn( "CodeWarrior", strlen("CodeWarrior"));
cout << "The size of the stream is: "
<< strbuf.pcount() << endl;
strbuf.sputc('\0'); // null terminate for output
// now freeze for no more growth
strbuf.freeze();
// try to add more
strbuf.sputn( " -- Software at Work --",
strlen(" -- Software at Work --"));
cout << "The size of the stream is: "
<< strbuf.pcount() << endl;
cout << "The buffer contains:\n"
<< strbuf.str() << endl;
return 0;
}
To determine the effective length of the buffer,
Prototype:
Remarks:
The function pcount() is used to determine the offset of the next character position from the beginning of the buffer.
Return:
A null terminated character array.
Example of strstreambuf::pcount() usage.:
See: strstreambuf::freeze
To return the char array stored in the buffer.
Prototype:
Remarks:
The function str() freezes the buffer and appends a null character then returns the array. The user is responsible for destruction of any dynamically allocated buffer.
Return:
A null terminated character array.
Example of strstreambuf::str() usage:
#include <iostream>
#include <strstream>
const int size = 100;
char buf[size];
char arr[size] = "Metrowerks CodeWarrior - Software at Work";
int main()
{
ostrstream ostr(buf, size);
ostr << arr;
// associate buffer
strstreambuf *strbuf(ostr.rdbuf());
// do some manipulations
strbuf->pubseekoff(10,ios::beg);
strbuf->sputc('\0');
strbuf->pubseekoff(0, ios::beg);
cout << "The original array was\n" << arr << "\n\n";
cout << "The strstreambuf array is\n"
<< strbuf->str() << "\n\n";
cout << "The ostrstream array is now\n" << buf;
return 0;
}
Result:
The original array was
Metrowerks CodeWarrior - Software at Work
The strstreambuf array is
Metrowerks
The ostrstream array is now
Metrowerks
Protected Virtual Member Functions
Protected member functions that are overridden for stream buffer
manipulations by the strstream class and derived classes from it.
setbuf
To set a buffer for stream input and output sequences.
Prototype:
virtual streambuf* setbuf(char* s, streamsize n);
Remarks:
The function setbuf() is overridden in strstream classes.
Return:
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_base::in | ios_base::out);
Remarks:
The function seekoff() is overridden in strstream classes.
Return:
A pos_type value, which is an invalid stream position.
seekpos
To alter an input or output stream position.
Prototype:
virtual pos_type seekpos(
pos_type sp,
ios_base::openmode
which = ios_base::in | ios_base::out);
Remarks:
The function seekpos() is overridden in strstream classes.
Return:
A pos_type value, which is an invalid stream position.
underflow
To show an underflow condition and not increment the get pointer.
Prototype:
vvirtual int_type underflow();
Remarks:
The virtual function underflow() is called when a character is not available for input.
There are many constraints for underflow().
minus the get pointer plus some sequence of characters to be read
from input.
in the sequence or the next character in the sequence.
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.
To show a failure in a put back operation.
Prototype:
virtual int_type pbackfail(int_type c = 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.
Consumes the pending characters of an output sequence.
Prototype:
virtual int_type overflow (int_type c = 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:
must be specified.
beginning pointer must be null or the beginning and put pointer must both be set to the same non-null value.
fails or failure to set the previous requirement occurs.
Return:
The function returns traits::eof() for failure or some unspecified result to indicate success.
The class istrstream is used to create and associate a stream with an array for input.
The istrstream class includes the following facilities
The istrstream class declaration:
class istrstream : public basic_istream<char>
{
public:
explicit istrstream(const char* s);
explicit istrstream(char* s);
istrstream(const char* s, streamsize n);
istrstream(char* s, streamsize n);
virtual ~istrstream();
strstreambuf* rdbuf() const;
char* str();
private:
strstreambuf strbuf_;
};
The istrstream class has an overloaded constructor.
Create an array based stream for input
Prototype:
explicit istrstream(const char* s);
explicit istrstream(char* s);
istrstream(const char* s, streamsize n);
istrstream(char* s, streamsize n);
Remarks:
The istrstream constructor is overloaded to accept a dynamic or pre-allocated character based
array for input. It is also overloaded to limit the size of the
allocation to prevent accidental overflow
#include <iostream>
#include <strstream>
char buf[100] ="double 3.21 string array int 321";
int main()
{
char arr[4][20];
double d;
long i;
istrstream istr(buf);
istr >> arr[0] >> d >> arr[1] >> arr[2] >> arr[3] >> i;
cout << arr[0] << " is " << d << "\n"
<< arr[1] << " is " << arr[2] << "\n"
<< arr[3] << " is " << i << endl;
return 0;
}
Result:
double is 3.21
string is array
int is 321
Destructor
To destroy an istrstream object.
Prototype:
Remarks:
The istrstream desctructor removes the istrstream object from memory.
Public Member Functions
There are two public member functions.
rdbuf
Returns a pointer to the strsteambuf
Prototype:
Remarks:
To manipulate a stream for random access or sychronization it
is necessary to retrieve a pointer to the streams buffer. The
function rdbuf() allows you to retrieve this pointer.
Return:
Example of istrstream::rdbuf() usage.:
See: strstreambuf::str()
str
Return a pointer to the stored array.
Prototype:
Remarks:
The function str() freezes and terminates the character array
stored in the buffer with a null character. It then returns
the
null terminated character array.
Return:
Example of istrstream::str() usage.:
#include <iostream>
#include <strstream>
const int size = 100;
char buf[size] = "Metrowerks CodeWarrior - Software at Work";
int main()
{
istrstream istr(buf, size);
cout << istr.str();
return 0;
}
Result:
Metrowerks CodeWarrior - Software at Work
Ostrstream Class
The class strstreambuf is derived from streambuf to associate a stream with an array buffer for output.
The ostrstream class includes the following facilities
class ostrstream : public basic_ostream<char>
{
public:
ostrstream();
ostrstream(char* s, int n, ios_base::openmode mode = ios_base::out);
virtual ~ostrstream();
strstreambuf* rdbuf() const;
void freeze(bool freezefl = true);
char* str();
int pcount() const;
private:
strstreambuf strbuf_;
};
The ostrstream class has an overloaded constructor.
Creates a stream and associates it with a char array for output.
Prototype:
ostrstream();
ostrstream(char* s, int n,
ios_base::openmode mode = ios_base::out);
Remarks:
The ostrstream array is overloaded for association a pre allocated array or for
dynamic allocation.
NOTE
When using an ostrstream object the user must supply a null character
for termination. When storing a string which is already null terminated
that null terminator is stripped off to allow for appending.
#include <iostream>
#include <strstream>
int main()
{
ostrstream out;
out << "Ask the teacher anything you want to know" << ends;
istream inOut(out.rdbuf() );
har c;
while( inOut.get(c) ) cout.put(c);
return 0;
}
Result:
Ask the teacher anything you want to know
Destructor
Prototype:
virtual ~ostrstream();
Remarks:
A ostrstream destructor removes the ostrstream object from memory.
Public Member Functions
The oststream class has four public member functions.
freeze
Freezes the dynamic allocation or destruction of a buffer.
Prototype:
void freeze(bool freezefl = true);
Remarks:
To manipulate a stream for random access or sychronization it
is necessary to retrieve a pointer to the streams buffer. The
function rdbuf() allows you to retrieve this pointer.
Return:
Example of ostrstream freeze() usage.:
#include <iostream>
#include <strstream>
int main()
{
ostrstream out;
out << "Metowerks " << 1234;
out << "the size of the array so far is "
<< out.pcount() << " characters \n";
out << " Software" << '\0';
out.freeze(); // freezes so no more growth can occur
out << " at work" << ends;
out << "the final size of the array is "
<<out.pcount() << " characters \n";
cout << out.str() << endl;
return 0;
}
Result:
the size of the array so far is 14 characters
he final size of the array is 24 characters
Metowerks 1234 Software
pcount
Determines the number of bytes offset of the current stream position
to the beginning of the array.
Prototype:
int pcount() const;
Remarks:
The function pcount() is used to determine the offset of the
array. This may not equal to the number of characters inserted
due to possible positioning operations.
Return:
An int_type, the length of the array.
Example of ostrstream pcount() usage.:
#include <iostream>
#include <strstream>
int main()
{
ostrstream out;
out << "Metowerks " << 1234 << ends;
out << "the size of the array so far is "
<< out.pcount() << " characters \n";
out << " Software at work" << ends;
out << "the final size of the array is "
<<out.pcount() << " characters \n";
cout << out.str() << endl;
return 0;
}
Result:
the size of the array so far is 15 characters
the final size of the array is 33 characters
Metowerks 1234
rdbuf
To retrieve a pointer to the streams buffer.
Prototype:
strstreambuf* rdbuf() const;
Remarks:
To manipulate a stream for random access or sychronization it
is necessary to retrieve a pointer to the streams buffer. The
function rdbuf() allows you to retrieve this pointer.
Return:
Example of ostrstream rdbuf() usage.:
See: streambuf::pubseekoff()
str
Returns a pointer to a character array.
Prototype:
char* str();
Remarks:
The function str() freezes any dynamic allocation.
Return:
A null terminated character array.
Example of ostrstream str() usage.:
See ostrstream::freeze(),
Strstream Class
The class strstream is derived from streambuf to associate a stream with an array buffer for output
The strstream class includes the following facilities
class strstream : public basic_iostream<char>
{
public:
// Types
typedef char char_type;
typedef typename char_traits<char>::int_type int_type;
typedef typename char_traits<char>::pos_type pos_type;
typedef typename char_traits<char>::off_type off_type;
// consturctors/destructor
strstream();
strstream(char* s, int n, ios_base::openmode mode = ios_base::in|ios_base::out);
virtual ~strstream();
// Members:
strstreambuf* rdbuf() const;
void freeze(bool freezefl = true);
int pcount() const;
char* str();
private:
strstreambuf strbuf_;
};
The strstream class typedefines a char_type, int_type, pos_type and off_type, for stream positioning and storage.
Creates a stream and associates it with a char array for input
and output.
Prototype:
strstream();
strstream(char* s, int n, ios_base::openmode mode =
ios_base::in|ios_base::out);
Remarks:
The strstream array is overloaded for association a pre allocated array or for
dynamic allocation
Prototype:
virtual ~strstream();
Remarks:
Removes the strstream object from memory.
The class strstream has four public member functions.
Freezes the dynamic allocation or destruction of a buffer.
Prototype:
void freeze(bool freezefl = true);
Remarks:
The function freeze stops dynamic allocation of a buffer.
Determines the number of bytes offset of the current stream position
to the beginning of the array.
Prototype:
int pcount() const;
Remarks:
The function pcount() is used to determine the offset of the
array. This may not equal to the number of characters inserted
due to possible positioning operations.
Return:
An int_type, the length of the array.
Retrieves a pointer to the streams buffer
Prototype:
strstreambuf* rdbuf() const;
Remarks:
To manipulate a stream for random access or sychronization it
is necessary to retrieve a pointer to the streams buffer. The
function rdbuf() allows you to retrieve this pointer.
Return:
Returns a pointer to a character array.
Prototype:
char* str();
Remarks:
The function str() freezes any dynamic allocation.
Return:
A null terminated character array.
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