strstream(3C++std)

istrstream , ostrstream , strstream , strstreambuf - defines several iostreams classes that manipulate in-memory character sequences

Synopsis

   namespace std {
   class strstreambuf;
   class istrstream;
   class ostrstream;
   class strstream;
       };

Description

Include the iostreams standard header <strstream> to define several classes that support iostreams operations on sequences stored in an allocated array of char object. Such sequences are easily converted to and from C strings.

strstreambuf

freeze , overflow , pbackfail , pcount , seekoff , seekpos , str , strstreambuf , underflow

   class strstreambuf : public streambuf {
   public:
       explicit strstreambuf(streamsize n = 0);
       strstreambuf(void (*palloc)(size_t),
           void (*pfree)(void *));
       strstreambuf(char *gp, streamsize n,
           char *pp = 0);
       strstreambuf(signed char *gp, streamsize n,
           signed char *pp = 0);
       strstreambuf(unsigned char *gp, streamsize n,
           unsigned char *pp = 0);
       strstreambuf(const char *gp, streamsize n);
       strstreambuf(const signed char *gp, streamsize n);
       strstreambuf(const unsigned char *gp, streamsize n);
       void freeze(bool frz = true);
       char *str();
       streamsize pcount();
   protected:
       virtual streampos seekoff(streamoff off,
           ios_base::seekdir way,
           ios_base::openmode which =
               ios_base::in | ios_base::out);
       virtual streampos seekpos(streampos sp,
           ios_base::openmode which =
               ios_base::in | ios_base::out);
       virtual int underflow();
       virtual int pbackfail(int c = EOF);
       virtual int overflow(int c = EOF);
       };

The class describes a stream buffer that controls the transmission of elements to and from a sequence of elements stored in a char array object. Depending on how it is constructed, the object can be allocated, extended, and freed as necessary to accommodate changes in the sequence.

An object of class strstreambuf stores several bits of mode information as its strstreambuf mode. These bits indicate whether the controlled sequence:

has been allocated, and hence needs to be freed eventually
is modifiable
is extendable by reallocating storage
has been frozen and hence needs to be unfrozen before the object is destroyed, or freed (if allocated) by an agency other than the object

A controlled sequence that is frozen cannot be modified or extended, regardless of the state of these separate mode bits.

The object also stores pointers to two functions that control strstreambuf allocation. If these are null pointers, the object devises its own method of allocating and freeing storage for the controlled sequence.

strstreambuf::freeze

   void freeze(bool frz = true);

If frz is true, the function alters the stored strstreambuf mode to make the controlled sequence frozen. Otherwise, it makes the controlled sequence not frozen.

strstreambuf::pcount

   streamsize pcount();

The member function returns a count of the number of elements written to the controlled sequence. Specifically, if pptr() is a null pointer, the function returns zero. Otherwise, it returns pptr() - pbase().

strstreambuf::overflow

   virtual int overflow(int c = EOF);

If c != EOF, the protected virtual member function endeavors to insert the element (char)c into the output buffer. It can do so in various ways:

If a write position is available, it can store the element into the write position and increment the next pointer for the output buffer.
If the stored strstreambuf mode says the controlled sequence is modifiable, extendable, and not frozen, the function can make a write position available by allocating new for the output buffer. (Extending the output buffer this way also extends any associated input buffer.)

If the function cannot succeed, it returns EOF. Otherwise, if c == EOF it returns some value other than EOF. Otherwise, it returns c.

strstreambuf::pbackfail

   virtual int pbackfail(int c = EOF);

The protected virtual member function endeavors to put back an element into the input buffer, then make it the current element (pointed to by the next pointer).

If c == EOF, the element to push back is effectively the one already in the stream before the current element. Otherwise, that element is replaced by x = (char)c. The function can put back an element in various ways:

If a putback position is available, and the element stored there compares equal to x, it can simply decrement the next pointer for the input buffer.
If a putback position is available, and if the strstreambuf mode says the controlled sequence is modifiable, the function can store x into the putback position and decrement the next pointer for the input buffer.

If the function cannot succeed, it returns EOF. Otherwise, if c == EOF it returns some value other than EOF. Otherwise, it returns c.

strstreambuf::seekoff

   virtual streampos seekoff(streamoff off,
       ios_base::seekdir way,
       ios_base::openmode which =
           ios_base::in | ios_base::out);

The protected virtual member function endeavors to alter the current positions for the controlled streams. For an object of class strstreambuf, a stream position consists purely of a stream offset. Offset zero designates the first element of the controlled sequence.

The new position is determined as follows:

If way == ios_base::beg, the new position is the beginning of the stream plus off.
If way == ios_base::cur, the new position is the current stream position plus off.
If way == ios_base::end, the new position is the end of the stream plus off.

If which & ios_base::in is nonzero and the input buffer exist, the function alters the next position to read in the input buffer. If which & ios_base::out is also nonzero, way != ios_base::cur, and the output buffer exists, the function also sets the next position to write to match the next position to read.

Otherwise, if which & ios_base::out is nonzero and the output buffer exists, the function alters the next position to write in the output buffer. Otherwise, the positioning operation fails. For a positioning operation to succeed, the resulting stream position must lie within the controlled sequence.

If the function succeeds in altering the stream position(s), it returns the resultant stream position. Otherwise, it fails and returns an invalid stream position.

strstreambuf::seekpos

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

If which & ios_base::in is nonzero and the input buffer exists, the function alters the next position to read in the input buffer. (If which & ios_base::out is nonzero and the output buffer exists, the function also sets the next position to write to match the next position to read.) Otherwise, if which & ios_base::out is nonzero and the output buffer exists, the function alters the next position to write in the output buffer. Otherwise, the positioning operation fails. For a positioning operation to succeed, the resulting stream position must lie within the controlled sequence.

If the function succeeds in altering the stream position(s), it returns the resultant stream position. Otherwise, it fails and returns an invalid stream position.

strstreambuf::str

   char *str();

The member function calls freeze(), then returns a pointer to the beginning of the controlled sequence. (Note that no terminating null element exists, unless you insert one explicitly.)

strstreambuf::strstreambuf

   explicit strstreambuf(streamsize n = 0);
   strstreambuf(void (*palloc)(size_t),
       void (*pfree)(void *));
   strstreambuf(char *gp, streamsize n,
       char *pp = 0);
   strstreambuf(signed char *gp, streamsize n,
       signed char *pp = 0);
   strstreambuf(unsigned char *gp, streamsize n,
       unsigned char *pp = 0);
   strstreambuf(const char *gp, streamsize n);
   strstreambuf(const signed char *gp, streamsize n);
   strstreambuf(const unsigned char *gp, streamsize n);

The first constructor stores a null pointer in all the pointers controlling the input buffer, the output buffer, and strstreambuf allocation. It sets the stored strstreambuf mode to make the controlled sequence modifiable and extendable. And it accepts n as a suggested initial allocation size.

The second constructor behaves much as the first, except that it stores palloc as the pointer to the function to call to allocate storage, and pfree as the pointer to the function to call to free that storage.

The three constructors:

   strstreambuf(char *gp, streamsize n,
       char *pp = 0);
   strstreambuf(signed char *gp, streamsize n,
       signed char *pp = 0);
   strstreambuf(unsigned char *gp, streamsize n,
       unsigned char *pp = 0);

also behave much as the first, except that gp designates the array object used to hold the controlled sequence. (Hence, it must not be a null pointer.) The number of elements N in the array is determined as follows:

If (n > 0), then N is n.
If (n == 0), then N is strlen((const char *)gp).
If (n < 0), then N is INT_MAX.

If pp is a null pointer, the function establishes just an input buffer, by executing:

   setg(gp, gp, gp + N);

Otherwise, it establishes both input and output buffers, by executing:

   setg(gp, gp, pp);
   setp(pp, gp + N);

In this case, pp must be in the interval [gp, gp + N].

Finally, the three constructors:

   strstreambuf(const char *gp, streamsize n);
   strstreambuf(const signed char *gp, streamsize n);
   strstreambuf(const unsigned char *gp, streamsize n);

all behave the same as:

   streambuf((char *)gp, n);

except that the stored mode makes the controlled sequence neither modifiable not extendable.

strstreambuf::underflow

   virtual int underflow();

The protected virtual member function endeavors to extract the current element c from the input buffer, then advance the current stream position, and return the element as (int)(unsigned char)c. It can do so in only one way: If a read position is available, it takes c as the element stored in the read position and advances the next pointer for the input buffer.

If the function cannot succeed, it returns EOF. Otherwise, it returns the current element in the input stream, converted as described above.

istrstream

istrstream , rdbuf , str

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

The class describes an object that controls extraction of elements and encoded objects from a stream buffer of class strstreambuf. The object stores an ojbect of class strstreambuf.

istrstream::istrstream

   explicit istrstream(const char *s);
   explicit istrstream(char *s);
   istrstream(const char *s, streamsize n);
   istrstream(char *s, streamsize n);

All the constructors initialize the base class by calling istream(sb), where sb is the stored object of class strstreambuf. The first two constructors also initialize sb by calling strstreambuf((const char *)s, 0). The remaining two constructors instead call strstreambuf((const char *)s, n).

istrstream::rdbuf

   strstreambuf *rdbuf() const

The member function returns the address of the stored stream buffer, of type pointer to strstreambuf.

istrstream::str

   char *str();

The member function returns rdbuf()-> str().

ostrstream

freeze , ostrstream , pcount , rdbuf , str

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

The class describes an object that controls insertion of elements and encoded objects into a stream buffer of class strstreambuf. The object stores an ojbect of class strstreambuf.

ostrstream::freeze

   void freeze(bool frz = true)

The member function calls rdbuf()-> freeze(frz).

ostrstream::ostrstream

   ostrstream();
   ostrstream(char *s, streamsize n,
       ios_base::openmode mode = ios_base::out);

Both constructors initialize the base class by calling ostream(sb), where sb is the stored object of class strstreambuf. The first constructor also initializes sb by calling strstreambuf(). The second constructor initializes the base class one of two ways:

If mode & ios_base::app == 0, then s must designate the first element of an array of n elements, and the constructor calls strstreambuf(s, n, s).
Otherwise, s must designate the first element of an array of n elements that contains a C string whose first element is designated by s, and the constructor calls strstreambuf(s, n, s + strlen(s).

ostrstream::pcount

   streamsize pcount() const;

The member function returns rdbuf()-> pcount().

ostrstream::rdbuf

   strstreambuf *rdbuf() const

The member function returns the address of the stored stream buffer, of type pointer to strstreambuf.

ostrstream::str

   char *str();

The member function returns rdbuf()-> str().

strstream

freeze , pcount , rdbuf , str , strstream

   class strstream : public iostream {
   public:
       strstream();
       strstream(char *s, streamsize n,
           ios_base::openmode mode =
               ios_base::in | ios_base::out);
       strstreambuf *rdbuf() const;
       void freeze(bool frz = true);
       char *str();
       streamsize pcount() const;
       };

The class describes an object that controls insertion and extraction of elements and encoded objects using a stream buffer of class strstreambuf. The object stores an ojbect of class strstreambuf.

strstream::freeze

   void freeze(bool frz = true)

The member function calls rdbuf()-> freeze(zfrz).

strstream::pcount

   streamsize pcount() const;

The member function returns rdbuf()-> pcount().

strstream::strstream

   strstream();
   strstream(char *s, streamsize n,
       ios_base::openmode mode =
           ios_base::in | ios_base::out);

Both constructors initialize the base class by calling streambuf(sb), where sb is the stored object of class strstreambuf. The first constructor also initializes sb by calling strstreambuf(). The second constructor initializes the base class one of two ways:

If mode & ios_base::app == 0, then s must designate the first element of an array of n elements, and the constructor calls strstreambuf(s, n, s).
Otherwise, s must designate the first element of an array of n elements that contains a C string whose first element is designated by s, and the constructor calls strstreambuf(s, n, s + strlen(s).

strstream::rdbuf

   strstreambuf *rdbuf() const

The member function returns the address of the stored stream buffer, of type pointer to strstreambuf.

strstream::str

   char *str();

The member function returns rdbuf()-> str().

References

ios(3C++std) , istream(3C++std) , limits(5) , ostream(3C++std) , stdio(5) , streambuf(3C++std) , string(5)