13.47 <strstream>

The <strstream> header declares several classes for reading from character arrays and writing to character arrays in the same manner as reading from and writing to files.

This header and its classes are deprecated in the standard, meaning they might disappear from a future version of the standard. Instead, you are encouraged to use the <sstream> header and its class templates. Nonetheless, the <strstream> classes have their uses; when you are dealing exclusively with narrow characters, and are using character arrays instead of string objects, these classes sometimes offer better performance than their <sstream> counterparts.

See Chapter 10 for a general discussion of I/O, and the <istream> and <ostream> sections in this chapter for information about the base classes from which the strstream classes derive. Refer to the <streambuf> section in this chapter for information about the streambuf class.

class istrstream: public istream
{
public:
  explicit istrstream(const char* str);
  explicit istrstream(char* str);
  istrstream(const char* str, streamsize n);
  istrstream(char* str, streamsize n);
   
  strstreanbuf* rdbuf(  ) const;
  char* str(  );
};

The istrstream class represents an input string stream. To construct an istrstream, pass a character array (with an optional size). You can then read from the string stream just as you would from any other input stream.

The following are the methods of istrstream:

explicit istrstream(const char* str)

explicit istrstream(char* str)

Initializes an input string stream by constructing an internal stream buffer as strstreambuf(str, 0) and passing the address of the stream buffer to the base-class constructor for istream.

explicit istrstream(const char* str, streamsize n)

explicit istrstream(char* str, streamsize n)

Initializes an input string stream by constructing an internal stream buffer as strstreambuf(str, n) and passing the address of the stream buffer to the base-class constructor for istream.

strstreambuf* rdbuf( ) const

Returns a pointer to the internal strstreambuf object.

char* str( )

Returns the internal string, rdbuf( )->str( ).

See Also

ostrstream class, strstream class, strstreambuf class, istream in <istream>, istringstream in <sstream>

class ostrstream: public ostream
{
public:
  ostrstream(  );
  ostrstream(char* str, int n, ios_base::openmode mode = ios_base::out);
   
  strstreambuf* rdbuf(  ) const;
  void freeze(bool flag = true);
  char* str(  );
  int pcount(  ) const;
};

The ostrstream class represents an output string stream. You can provide a character array, and the stream contents are written to that array. Another typical usage is to construct an ostrstream with no argument and let the string stream allocate the string as you write to the stream. Then call str( ) to obtain the resulting character array. Once you call str( ), the stream is frozen and cannot be modified. The pointer returned from str( ) remains valid until the ostrstream object is destroyed or until you thaw the stream to allow writing again.

The following are the methods of ostrstream:

ostrstream( )

Initializes an empty output string stream by constructing an internal strstreambuf object and passing the address of the string buffer to the base-class constructor for ostream.

ostrstream(char* str, int n, ios_base::openmode mode = ios_base::out)

Initializes a string stream with str as the initial string contents by constructing an internal strstreambuf object and passing the address of the buffer to the base-class constructor for ostream. If the ios_base::app bit is set in mode, the buffer is constructed like this:

strstreambuf(str, n, str + std::strlen(str));

If the ios_base::app bit is clear in mode, the buffer is constructed like this:

strstreambuf(str, n, str);

void freeze(bool flag = true)

Freezes or thaws the buffer by calling rdbuf( )->freeze(flag).

strstreambuf* rdbuf( ) const

Returns a pointer to the internal strstreambuf object.

char* str( )

Returns a pointer to the buffer's character array, that is, rdbuf( )->str( ).

int pcount( ) const

Returns the number of bytes in the output buffer by calling rdbuf( )->pcount( ).

See Also

istrstream class, strstream class, strstreambuf class, ostream in <ostream>, ostringstream in <sstream>

class strstream: public iostream
{
public:
  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;
   
  strstream(  );
  strstream(char* s, int n, 
            ios_base::openmode mode = ios_base::in|ios_base::out);
  virtual ~strstream(  );
   
  strstreambuf* rdbuf(  ) const;
  void freeze(bool freezefl = true);
  int pcount(  ) const;
  char* str(  );
};

The strstream class is a stream class that performs input and output to a character array. You can start with an empty string and write to the stream, or start with a string and read from the stream. You can switch between reading and writing at any time. If you use the default constructor and write to the stream, the stream buffer grows as needed. Then you can call str( ) to obtain the resulting character array. Once you call str( ), the stream is frozen and cannot be modified. The pointer returned from str( ) remains valid until the ostrstream object is destroyed or until you thaw the stream to allow writing again.

The following are the methods of strstream:

strstream( )

Initializes an empty string stream by constructing an internal strstreambuf object and passing the address of the string buffer to the base-class constructor for iostream.

basic_strstream(char* str, int n, ios_base::openmode mode = ios_base::in|ios_base::out)

Initializes a string stream with str as the initial string contents by constructing an internal strstreambuf object and passing the address of the buffer to the base-class constructor for iostream. If the ios_base::app bit is set in mode, the buffer is constructed like this:

strstreambuf(str, n, str + std::strlen(str));

If the ios_base::app bit is clear in mode, the buffer is constructed like this:

strstreambuf(str, n, str);

void freeze(bool flag = true)

Freezes or thaws the buffer by calling rdbuf( )->freeze(flag).

strstreambuf* rdbuf( ) const

Returns a pointer to the internal strstreambuf object.

char* str( )

Returns a pointer to the buffer's character array, that is, rdbuf( )->str( ).

int pcount( ) const

Returns the number of bytes in the output buffer by calling rdbuf( )->pcount( ).

See Also

istrstream class, ostrstream class, strstreambuf class, basic_iostream in <istream>, stringstream in <sstream>

class strstreambuf : public basic_streambuf<char> {
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(  );
   
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);
};

The strstreambuf class implements a stream buffer for character array streams. An internal buffer maintains a single character array with separate positions for reading and writing. That is, the buffer has begin, next, and end pointers for reading and separate begin, next, and end pointers for writing. The begin pointer points to the start of a buffer, and the end pointer points to one past the end of the buffer. The next pointer points to the position where the next character is to be read or written. Refer to basic_streambuf in <streambuf> for details about buffer positions.

A strstreambuf object maintains a set of flags, an allocated buffer size, and two function pointers for an allocation and deallocation function. If the allocation function pointer is null, the new[] operator is used for allocating the character array; if the deallocation function pointer is null, the delete[] operator is used.

The flags are:

allocated

Indicates that the character array has been allocated, so the destructor should delete it

constant

Indicates that the character array is const, so it cannot be used for output

dynamic

Indicates that the character array has been dynamically allocated and can grow as needed to accommodate output

frozen

Indicates that the character array can no longer be modified, extended, or freed

The following are the public member functions of strstreambuf:

explicit strstreambuf(streamsize alloc_size = 0)

Saves alloc_size as the suggested size of the character array, and sets the dynamic flag. The allocation and deallocation functions are set to null pointers.

strstreambuf(void* (*palloc)(size_t), void (*pfree)(void*))

Sets the dynamic flag and saves palloc and pfree as the allocation and deallocation functions.

strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0)

strstreambuf(signed char* gnext_arg, streamsize n, signed char* pbeg_arg = 0)

strstreambuf(unsigned char* gnext_arg, streamsize n, unsigned char* pbeg_arg = 0)

Clears all flags and sets the allocation and deallocation functions to null pointers. If pbeg_arg is null, the output pointers are null and the input buffer is set to n bytes starting at gnext_arg by calling setg(gnext_arg, gnext_arg, gnext_arg + N). If pbeg_arg is not null, the input pointers are set by calling setg(gnext_arg, gnext_arg, pbeg_arg), and the output pointers are set by calling setp(pbeg_arg, pbeg_arg + N). N is determined as follows:

n > 0

N is n.

n == 0

N is strlen(gnext_arg).

n < 0

N is INT_MAX.

strstreambuf(const char* gnext_arg, streamsize n)

strstreambuf(const signed char* gnext_arg, streamsize n)

strstreambuf(const unsigned char* gnext_arg, streamsize n)

Initializes the buffer pointers in the same manner as constructing strstreambuf(const_cast<char*>(gnext_arg), n). The only difference is that the constant flag is set.

virtual ~strstreambuf( )

The destructor frees the character array if the allocated flag is set and the frozen flag is clear.

void freeze(bool freezefl = true)

Freezes or thaws the character buffer. If the dynamic flag is set, the freeze function sets or clears the frozen flag to match the freezefl parameter. If the dynamic flag is clear, freeze( ) does nothing.

char* str( )

Returns the internal character buffer by calling freeze( ) and returning gbase( ).

int pcount( )

Returns the number of output bytes in the buffer. If pptr( ) is null, 0 is returned; otherwise, pptr( ) - pbase( ) is returned.

The overridden virtual functions are:

virtual int_type overflow (int_type c = EOF)

Attempts to append c to the end of the character array as follows:

• If c == EOF, nothing happens and a non-end-of-file character is returned to indicate success.

• If c != EOF, and a write position is available, c is appended to the character array by calling sputc(c).

• If a write position is not available, the dynamic flag is set, and the frozen flag is clear, then the character array is extended and c is appended to the array. The array is extended by allocating a new, larger character array; copying the old contents (if any); updating the read and write pointers. If the array is successfully extended, the allocated flag is set.

• Otherwise, the array cannot be extended, so the function fails.

The return value is c for success or EOF for failure. If c is EOF, a value other than EOF is returned for success.

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

Attempts to push back c onto the input array for reading as follows:

• If c == EOF, and a putback position is available, gptr( ) is set to gptr( ) - 1.

• If c != EOF, a putback position is available, and gptr( )[-1] is equal to c, gptr( ) is set to gptr( ) - 1.

• If c != EOF, the constant flag is clear, and a putback position is available, gptr( ) is set to gptr( ) - 1, and *gptr( ) is assigned c.

• Otherwise, the character cannot be put back, so the function fails.

The return value is c for success or EOF for failure. If c is EOF, a value other than EOF is returned for success.

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

Sets the stream position. The input position, output position, or both can be set, depending on (which & (ios_base::in | ios_base::out)). The following are the possible results of this expression:

os_base::in

Sets the input position

os_base::out

Sets the output position

ios_base::in | ios_base::out, and way is either ios_base::beg or ios_base::end

Sets input and output positions

Otherwise

The function fails and returns pos_type(-1)

The new position is determined by adding the offset off to a base position given by way, which must be one of the following:

ios_base::beg

The base position is the at start of the stream—that is, off is an absolute position.

ios_base::cur

The base position is the current stream position.

ios_base::end

The base position is at the end of the stream.

In all cases, a positive offset is toward the end of the stream, and a negative offset is toward the start of the stream. If the desired position is negative or past the end of the string, the function fails and returns pos_type(-1). If the function succeeds, it returns the new position.

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

Sets the stream position to sp. The input position is set if which & ios_base::in is nonzero. The output position is set if which & ios_base::out is nonzero. If sp is not a valid position, or if neither the input nor the output position is set, seekpos fails and pos_type(-1) is returned. The return value is sp for success. If sp was not returned from a prior call to a positioning function (that is, seekoff, seekpos, tellg, or tellp), the results are undefined.

virtual basic_streambuf<charT,traits>* setbuf(charT*, streamsize)

Calling setbuf(0, 0) has no effect. The result of any other call to setbuf is implementation-defined.

virtual int_type underflow( )

Gets another character from the input range without moving the input pointer. If the stream has a read position, the function returns *gptr( ). If there is no read position, but there is a non-null write pointer past the end of the input range—that is, pptr( ) > gend( )—then the read end pointer (gend( )) is advanced at least one position but still less than or equal to pptr( ). The return value is EOF for failure or *gnext( ) for success.

See Also

stringbuf in <sstream>, basic_streambuf in <streambuf>