Name

strstreambuf class — I/O buffer for character array streams

Synopsis

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:

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:

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:

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:

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:

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

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.

See Also virtual basic_streambuf<charT,traits>* setbu f(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.