bslstl_stringbuf

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Memory Allocation
    • bslma-Style Allocators
  • Usage
    • Example 1: Basic Operations

Purpose

Provide a C++03-compatible stringbuf class.

Classes

• bsl::stringbuf: C++03-compatible stringbuf class
• bsl::StringBufContainer: wrapper for basic_stringbuf

Canonical header: bsl_sstream.h

See also

bslstl_stringstream, bslstl_ostringstream, bslstl_istringstream

Description

This component is for internal use only. Please include <bsl_sstream.h> instead.

This component defines a class template, bsl::basic_stringbuf, that implements a standard string buffer, providing an unformatted character input sequence and an unformatted character output sequence that may be initialized or accessed using a string value (see 27.8.2 [stringbuf] of the C++11 standard). This component also defines two standard aliases, bsl::stringbuf and bsl::wstringbuf, that refer to specializations of the bsl::basic_stringbuf template for char and wchar_t types, respectively. As with any stream buffer class, bsl::basic_stringbuf is rarely used directly. Stream buffers provide low-level unformatted input/output. They are usually plugged into std::basic_stream classes to provide higher-level formatted input and output via operator>> and operator<<. bsl::basic_stringbuf is used in the bsl::basic_stringstream family of classes and users should prefer those classes over direct use of bsl::basic_stringbuf.

bsl::basic_stringbuf derives from std::basic_streambuf and implements the necessary protected virtual methods. In this way bsl::basic_stringbuf customizes the behavior of std::basic_streambuf to redirect the reading and writing of characters to an internally-maintained sequence of characters that can be initialized or accessed using a bsl::basic_string. Note that although the standard mandates functions that access and modify the buffered sequence using a basic_string , it does not mandate that a basic_stringbuf internally store this buffer in a basic_string ; this implementation currently uses a basic_string as its internal buffer, but that is subject to change without warning.

The bsl::stringbuf template has three parameters, CHAR_TYPE, CHAR_TRAITS, and ALLOCATOR. The CHAR_TYPE and CHAR_TRAITS parameters respectively define the character type for the stream buffer and a type providing a set of operations the stream buffer will use to manipulate characters of that type, which must meet the character traits requirements defined by the C++11 standard, 21.2 [char.traits]. The ALLOCATOR template parameter is described in the "Memory Allocation" section below.

Memory Allocation

The type supplied as a stream buffer's ALLOCATOR template parameter determines how that stream buffer will allocate memory. The basic_stringbuf template supports allocators meeting the requirements of the C++11 standard, 17.6.3.5 [allocator.requirements]; in addition, it supports scoped-allocators derived from the bslma::Allocator memory allocation protocol. Clients intending to use bslma-style allocators should use bsl::allocator, which provides a C++11 standard-compatible adapter for a bslma::Allocator object. Note that the standard aliases bsl::stringbuf and bsl::wstringbuf both use bsl::allocator.

bslma-Style Allocators

If the type supplied for the ALLOCATOR template parameter of a stringbuf instantiation is bsl::allocator, then objects of that stream buffer type will conform to the standard behavior of a bslma-allocator-enabled type. Such a stream buffer accepts an optional bslma::Allocator argument at construction. If the address of a bslma::Allocator object is explicitly supplied at construction, it will be used to supply memory for the stream buffer throughout its lifetime; otherwise, the stream buffer will use the default allocator installed at the time of the stream buffer's construction (see bslma_default ).

Usage

This section illustrates intended use of this component.

Example 1: Basic Operations

The following example demonstrates the use of bsl::stringbuf to read and write character data from and to a bsl::string object.

Suppose we want to implement a simplified converter from unsigned int to bsl::string and back. First, we define the prototypes of two conversion functions:

bsl::string  toString(unsigned int from);
unsigned int fromString(const bsl::string& from);

Then, we use bsl::stringbuf to implement the toString function. We write all digits into bsl::stringbuf individually using sputc methods and then return the resulting bsl::string object:

#include <algorithm>
 
bsl::string toString(unsigned int from)
{
    bsl::stringbuf out;
 
    for (; from != 0; from /= 10) {
        out.sputc('0' + from % 10);
    }
 
    bsl::string result(out.str());
    std::reverse(result.begin(), result.end());
    return result;
}

Now, we implement the fromString function that converts from bsl::string to unsigned int by using bsl::stringbuf to read individual digits from the string object:

unsigned int fromString(const bsl::string& from)
{
    unsigned int result = 0;
 
    for (bsl::stringbuf in(from); in.in_avail(); ) {
        result = result * 10 + (in.sbumpc() - '0');
    }
 
    return result;
}

Finally, we verify that the result of the round-trip conversion is identical to the original value:

unsigned int orig   = 92872498;
unsigned int result = fromString(toString(orig));
 
assert(orig == result);