Rationale:

The current basic_stringbuf description is over-constrained in such a way as to prohibit vendors from making this the high-performance in-memory stream it was meant to be. The fundamental problem is that the pointers: eback(), gptr(), egptr(), pbase(), pptr(), epptr() are observable from a derived client, and the current description restricts the range [pbase(), epptr()) from being grown geometrically. This change allows, but does not require, geometric growth of this range.

Backwards compatibility issues: These changes will break code that derives from basic_stringbuf, observes epptr(), and depends upon [pbase(), epptr()) growing by one character on each call to overflow() (i.e. test suites). Otherwise there are no backwards compatibility issues.

27.7.1.1/2: The non-normative note is non-binding, and if it were binding, would be over specification. The recommended change focuses on the important observable fact.

27.7.1.1/3: This change does two things: 1. It describes exactly what must happen in terms of the sequences. The terms "input sequence" and "output sequence" are not well defined. 2. It introduces a common extension: open with app or ate mode. I concur with issue 238 that paragraph 4 is both wrong and unnecessary.

27.7.1.2/1: This change is the crux of the efficiency issue. The resultant basic_string is not dependent upon epptr(), and thus implementors are free to grow the underlying buffer geometrically during overflow() *and* place epptr() at the end of that buffer.

27.7.1.2/2: Made consistent with the proposed 27.7.1.1/3.

27.7.1.3/1: Clarifies that characters written to the stream beyond the initially specified string are available for reading in an i/o basic_streambuf.

27.7.1.3/9: Made normative by removing "Notes:", and removed the trailing parenthetical comment concerning epptr().

27.7.1.3/12: Restricting the positioning to [xbeg, xend) is no longer allowable since [pbase(), epptr()) may now contain uninitialized characters. Positioning is only allowable over the initialized range.

[ post-Kona: Howard provided wording. At Kona the LWG agreed that something along these lines was a good idea, but the original proposed resolution didn't say enough about the effect of various member functions on the underlying character sequences. ]

Proposed resolution:

27.7.1.1/2 Change:

2- Notes: The function allocates no array object.

to:

2- Postcondition: str() == "".

27.7.1.1/3 Change:

-3- Effects: Constructs an object of class basic_stringbuf, initializing the base class with basic_streambuf() (lib.streambuf.cons), and initializing mode with which . Then copies the content of str into the basic_stringbuf underlying character sequence and initializes the input and output sequences according to which. If which & ios_base::out is true, initializes the output sequence with the underlying sequence. If which & ios_base::in is true, initializes the input sequence with the underlying sequence.

to:

-3- Effects: Constructs an object of class basic_stringbuf, initializing the base class with basic_streambuf() (lib.streambuf.cons), and initializing mode with which. Then copies the content of str into the basic_stringbuf underlying character sequence. If which & ios_base::out is true, initializes the output sequence such that pbase() points to the first underlying character, epptr() points one past the last underlying character, and if (which & ios_base::ate) is true, pptr() is set equal to epptr() else pptr() is set equal to pbase(). If which & ios_base::in is true, initializes the input sequence such that eback() and gptr() point to the first underlying character and egptr() points one past the last underlying character.

27.7.1.2/1 Change:

-1- Returns: A basic_string object whose content is equal to the basic_stringbuf underlying character sequence. If the buffer is only created in input mode, the underlying character sequence is equal to the input sequence; otherwise, it is equal to the output sequence. In case of an empty underlying character sequence, the function returns basic_string<charT,traits,Allocator>().

to:

-1- Returns: A basic_string object whose content is equal to the basic_stringbuf underlying character sequence. If the basic_stringbuf was created only in input mode, the resultant basic_string contains the character sequence in the range [eback(), egptr()). If the basic_stringbuf was created with (which & ios_base::out) being true then the resultant basic_string contains the character sequence in the range [pbase(), high_mark) where high_mark represents the position one past the highest initialized character in the buffer. Characters can be initialized either through writing to the stream, or by constructing the basic_stringbuf with a basic_string, or by calling the str(basic_string) member function. In the case of calling the str(basic_string) member function, all characters initialized prior to the call are now considered uninitialized (except for those characters re-initialized by the new basic_string). Otherwise the basic_stringbuf has been created in neither input nor output mode and a zero length basic_string is returned.

27.7.1.2/2 Change:

-2- Effects: If the basic_stringbuf's underlying character sequence is not empty, deallocates it. Then copies the content of s into the basic_stringbuf underlying character sequence and initializes the input and output sequences according to the mode stored when creating the basic_stringbuf object. If (mode&ios_base::out) is true, then initializes the output sequence with the underlying sequence. If (mode&ios_base::in) is true, then initializes the input sequence with the underlying sequence.

to:

-2- Effects: Copies the content of s into the basic_stringbuf underlying character sequence. If mode & ios_base::out is true, initializes the output sequence such that pbase() points to the first underlying character, epptr() points one past the last underlying character, and if (mode & ios_base::ate) is true, pptr() is set equal to epptr() else pptr() is set equal to pbase(). If mode & ios_base::in is true, initializes the input sequence such that eback() and gptr() point to the first underlying character and egptr() points one past the last underlying character.

Remove 27.2.1.2/3. (Same rationale as issue 238: incorrect and unnecessary.)

27.7.1.3/1 Change:

1- Returns: If the input sequence has a read position available, returns traits::to_int_type(*gptr()). Otherwise, returns traits::eof().

to:

1- Returns: If the input sequence has a read position available, returns traits::to_int_type(*gptr()). Otherwise, returns traits::eof(). Any character in the underlying buffer which has been initialized is considered to be part of the input sequence.

27.7.1.3/9 Change:

-9- Notes: The function can make a write position available only if ( mode & ios_base::out) != 0. To make a write position available, the function reallocates (or initially allocates) an array object with a sufficient number of elements to hold the current array object (if any), plus one additional write position. If ( mode & ios_base::in) != 0, the function alters the read end pointer egptr() to point just past the new write position (as does the write end pointer epptr()).

to:

-9- The function can make a write position available only if ( mode & ios_base::out) != 0. To make a write position available, the function reallocates (or initially allocates) an array object with a sufficient number of elements to hold the current array object (if any), plus one additional write position. If ( mode & ios_base::in) != 0, the function alters the read end pointer egptr() to point just past the new write position.

27.7.1.3/12 Change:

-12- _ If (newoff + off) < 0, or (xend - xbeg) < (newoff + off), the positioning operation fails. Otherwise, the function assigns xbeg + newoff + off to the next pointer xnext .

to:

-12- _ If (newoff + off) < 0, or if (newoff + off) refers to an uninitialized character (as defined in [stringbuf.members] paragraph 1), the positioning operation fails. Otherwise, the function assigns xbeg + newoff + off to the next pointer xnext .

27.7.1.3 par 8 says:

Notes: The function can make a write position available only if ( mode & ios_base::out) != 0. To make a write position available, the function reallocates (or initially allocates) an array object with a sufficient number of elements to hold the current array object (if any), plus one additional write position. If ( mode & ios_base::in) != 0, the function alters the read end pointer egptr() to point just past the new write position (as does the write end pointer epptr()).

The sentences "plus one additional write position." and especially "(as does the write end pointer epptr())" COULD by interpreted (and is interpreted by at least my library vendor) as:

post-condition: epptr() == pptr()+1

This WOULD force sputc() to call the virtual overflow() each time.

The proposed change also affects Defect Report 169.