cpp/io/basic stringbuf/str

Gets and sets the underlying string.

For the purpose of explanation, let denote the open mode of the stream and  denote the internal std object holding the underlying character sequence. Define buffer pointer initialization as follows:
 * For input streams, makes eback point at the first character, , and : the subsequent input will read the first character of the string.
 * For output streams, makes pbase points at the first character and (epptr is allowed to point farther so that the following sputc would not immediately call overflow).


 * For non-appending output streams, makes, so that subsequent output will overwrite the characters of the string.

@1@ Creates and returns a std object containing a copy of this 's underlying character sequence. For input-only streams, the returned string contains the characters from the range. For input/output or output-only streams, contains the characters from pbase to the last character in the sequence regardless of egptr and epptr.


 * The member character sequence in a buffer open for writing can be over-allocated for efficiency purposes. In that case, only the initialized characters are returned: these characters are the ones that were obtained from the string argument of the constructor, the string argument of the most recent call to a setter overload of, or from a write operation. A typical implementation that uses over-allocation maintains a high-watermark pointer to track the end of the initialized part of the buffer and this overload returns the characters from pbase to the high-watermark pointer.

@2@ Same as, except that is used to construct the returned std. Equivalent to. .

@3@ Creates std object as if initialized with. may need to be adjusted to contain the same content as in at first. After construction of the std object, sets to empty and performs buffer pointer initialization, then returns the std object.

@4@ Replaces the underlying character sequence as if by, then performs buffer pointer initialization.

@5@ Same as, except the type of 's allocator is not. .

@6@ Replaces the underlying character sequence as if by, then performs buffer pointer initialization.

Return value
@1-3@ A std object holding this buffer's underlying character sequence. @4-6@ (none)