Annex D (normative) Compatibility features [depr]

D.6 char* streams [depr.str.strstreams]

D.6.1 Class strstreambuf [depr.strstreambuf]

namespace std {
  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:
    int_type overflow (int_type c = EOF) override;
    int_type pbackfail(int_type c = EOF) override;
    int_type underflow() override;
    pos_type seekoff(off_type off, ios_base::seekdir way,
                     ios_base::openmode which
                      = ios_base::in | ios_base::out) override;
    pos_type seekpos(pos_type sp,
                     ios_base::openmode which
                      = ios_base::in | ios_base::out) override;
    streambuf* setbuf(char* s, streamsize n) override;

  private:
    using strstate = T1;              // exposition only
    static const strstate allocated;  // exposition only
    static const strstate constant;   // exposition only
    static const strstate dynamic;    // exposition only
    static const strstate frozen;     // exposition only
    strstate strmode;                 // exposition only
    streamsize alsize;                // exposition only
    void* (*palloc)(size_t);          // exposition only
    void (*pfree)(void*);             // exposition only
  };
}

The class strstreambuf associates the input sequence, and possibly the output sequence, with an object of some character array type, whose elements store arbitrary values. The array object has several attributes.

[ Note: For the sake of exposition, these are represented as elements of a bitmask type (indicated here as T1) called strstate. The elements are:

(2.1)
allocated, set when a dynamic array object has been allocated, and hence should be freed by the destructor for the strstreambuf object;
(2.2)
constant, set when the array object has const elements, so the output sequence cannot be written;
(2.3)
dynamic, set when the array object is allocated (or reallocated) as necessary to hold a character sequence that can change in length;
(2.4)
frozen, set when the program has requested that the array object not be altered, reallocated, or freed.

— end note ]

[ Note: For the sake of exposition, the maintained data is presented here as:

(3.1)
strstate strmode, the attributes of the array object associated with the strstreambuf object;
(3.2)
int alsize, the suggested minimum size for a dynamic array object;
(3.3)
void* (*palloc)(size_t), points to the function to call to allocate a dynamic array object;
(3.4)
void (*pfree)(void*), points to the function to call to free a dynamic array object.

— end note ]

Each object of class strstreambuf has a seekable area, delimited by the pointers seeklow and seekhigh. If gnext is a null pointer, the seekable area is undefined. Otherwise, seeklow equals gbeg and seekhigh is either pend, if pend is not a null pointer, or gend.

D.6.1.1 strstreambuf constructors [depr.strstreambuf.cons]

explicit strstreambuf(streamsize alsize_arg = 0);

Effects: Constructs an object of class strstreambuf, initializing the base class with streambuf(). The postconditions of this function are indicated in Table 142.

Table 142 — strstreambuf(streamsize) effects

Element	Value
strmode	dynamic
alsize	alsize_arg
palloc	a null pointer
pfree	a null pointer

strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));

Effects: Constructs an object of class strstreambuf, initializing the base class with streambuf(). The postconditions of this function are indicated in Table 143.

Table 143 — strstreambuf(void* (*)(size_t), void (*)(void*)) effects

Element	Value
strmode	dynamic
alsize	an unspecified value
palloc	palloc_arg
pfree	pfree_arg

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);

Effects: Constructs an object of class strstreambuf, initializing the base class with streambuf(). The postconditions of this function are indicated in Table 144.

Table 144 — strstreambuf(charT*, streamsize, charT*) effects

Element	Value
strmode	0
alsize	an unspecified value
palloc	a null pointer
pfree	a null pointer

gnext_arg shall point to the first element of an array object whose number of elements N is determined as follows:

(4.1)
If n > 0, N is n.
(4.2)
If n == 0, N is std::strlen(gnext_arg).
(4.3)
If n < 0, N is INT_MAX.331

If pbeg_arg is a null pointer, the function executes:

setg(gnext_arg, gnext_arg, gnext_arg + N);

Otherwise, the function executes:

setg(gnext_arg, gnext_arg, pbeg_arg);
setp(pbeg_arg,  pbeg_arg + N);

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

Effects: Behaves the same as strstreambuf((char*)gnext_arg,n), except that the constructor also sets constant in strmode.

virtual ~strstreambuf();

Effects: Destroys an object of class strstreambuf. The function frees the dynamically allocated array object only if (strmode & allocated) != 0 and (strmode & frozen) == 0. ([depr.strstreambuf.virtuals] describes how a dynamically allocated array object is freed.)

331)

The function signature strlen(const char*) is declared in <cstring>. The macro INT_MAX is defined in <climits>.

D.6.1.2 Member functions [depr.strstreambuf.members]

void freeze(bool freezefl = true);

Effects: If strmode & dynamic is nonzero, alters the freeze status of the dynamic array object as follows:

(1.1)
If freezefl is true, the function sets frozen in strmode.
(1.2)
Otherwise, it clears frozen in strmode.

char* str();

Effects: Calls freeze(), then returns the beginning pointer for the input sequence, gbeg.

Remarks: The return value can be a null pointer.

int pcount() const;

Effects: If the next pointer for the output sequence, pnext, is a null pointer, returns zero. Otherwise, returns the current effective length of the array object as the next pointer minus the beginning pointer for the output sequence, pnext - pbeg.

D.6.1.3 strstreambuf overridden virtual functions [depr.strstreambuf.virtuals]

int_type overflow(int_type c = EOF) override;

Effects: Appends the character designated by c to the output sequence, if possible, in one of two ways:

(1.1)
If c != EOF and if either the output sequence has a write position available or the function makes a write position available (as described below), assigns c to *pnext++.
Returns (unsigned char)c.
(1.2)
If c == EOF, there is no character to append.
Returns a value other than EOF.

Returns EOF to indicate failure.

Remarks: The function can alter the number of write positions available as a result of any call.

To make a write position available, the function reallocates (or initially allocates) an array object with a sufficient number of elements n to hold the current array object (if any), plus at least one additional write position. How many additional write positions are made available is otherwise unspecified.332 If palloc is not a null pointer, the function calls (*palloc)(n) to allocate the new dynamic array object. Otherwise, it evaluates the expression new charT[n]. In either case, if the allocation fails, the function returns EOF. Otherwise, it sets allocated in strmode.

To free a previously existing dynamic array object whose first element address is p: If pfree is not a null pointer, the function calls (*pfree)(p). Otherwise, it evaluates the expression delete[]p.

If (strmode & dynamic) == 0, or if (strmode & frozen) != 0, the function cannot extend the array (reallocate it with greater length) to make a write position available.

int_type pbackfail(int_type c = EOF) override;

Puts back the character designated by c to the input sequence, if possible, in one of three ways:

(7.1)
If c != EOF, if the input sequence has a putback position available, and if (char)c == gnext[-1], assigns gnext - 1 to gnext.
Returns c.
(7.2)
If c != EOF, if the input sequence has a putback position available, and if strmode & constant is zero, assigns c to *--gnext.
Returns c.
(7.3)
If c == EOF and if the input sequence has a putback position available, assigns gnext - 1 to gnext.
Returns a value other than EOF.

Returns EOF to indicate failure.

Remarks: If the function can succeed in more than one of these ways, it is unspecified which way is chosen. The function can alter the number of putback positions available as a result of any call.

int_type underflow() override;

Effects: Reads a character from the input sequence, if possible, without moving the stream position past it, as follows:

(10.1)
If the input sequence has a read position available, the function signals success by returning (unsigned char)*gnext.
(10.2)
Otherwise, if the current write next pointer pnext is not a null pointer and is greater than the current read end pointer gend, makes a read position available by assigning to gend a value greater than gnext and no greater than pnext.
Returns (unsigned char)*gnext.

Returns EOF to indicate failure.

Remarks: The function can alter the number of read positions available as a result of any call.

pos_type seekoff(off_type off, seekdir way, openmode which = in | out) override;

Effects: Alters the stream position within one of the controlled sequences, if possible, as indicated in Table 145.

Table 145 — seekoff positioning

Conditions	Result
(which & ios::in) != 0	positions the input sequence
(which & ios::out) != 0	positions the output sequence
(which & (ios::in \| ios::out)) == (ios::in \| ios::out)) and way == either ios::beg or ios::end	positions both the input and the output sequences
Otherwise	the positioning operation fails.

For a sequence to be positioned, if its next pointer is a null pointer, the positioning operation fails. Otherwise, the function determines newoff as indicated in Table 146.

Table 146 — newoff values

Condition	newoff Value
way == ios::beg	0
way == ios::cur	the next pointer minus the beginning pointer (xnext - xbeg).
way == ios::end	seekhigh minus the beginning pointer (seekhigh - xbeg).

If (newoff + off) < (seeklow - xbeg) or (seekhigh - xbeg) < (newoff + off), the positioning operation fails. Otherwise, the function assigns xbeg + newoff + off to the next pointer xnext.

Returns: pos_type(newoff), constructed from the resultant offset newoff (of type off_type), that stores the resultant stream position, if possible. If the positioning operation fails, or if the constructed object cannot represent the resultant stream position, the return value is pos_type(off_type(-1)).

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

Effects: Alters the stream position within one of the controlled sequences, if possible, to correspond to the stream position stored in sp (as described below).

(17.1)
If (which & ios::in) != 0, positions the input sequence.
(17.2)
If (which & ios::out) != 0, positions the output sequence.
(17.3)
If the function positions neither sequence, the positioning operation fails.

For a sequence to be positioned, if its next pointer is a null pointer, the positioning operation fails. Otherwise, the function determines newoff from sp.offset():

(18.1)
If newoff is an invalid stream position, has a negative value, or has a value greater than (seekhigh - seeklow), the positioning operation fails
(18.2)
Otherwise, the function adds newoff to the beginning pointer xbeg and stores the result in the next pointer xnext.

streambuf<char>* setbuf(char* s, streamsize n) override;

Effects: Implementation defined, except that setbuf(0, 0) has no effect.

332)

An implementation should consider alsize in making this decision.