Component bslstl_stringbuf [Package bslstl]

Provide a C++03-compatible stringbuf class. More...

Namespaces
namespace	bsl
namespace	bslma

---

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:

Component bslstl_stringstream, Component bslstl_ostringstream, Component 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);