bslstl_stringstream

Detailed Description

Outline

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

Purpose

Provide a C++03-compatible stringstream class.

Classes

• bsl::stringstream: C++03-compatible stringstream class

Canonical header: bsl_sstream.h

See also

Description

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

This component defines a class template, bsl::basic_stringstream, implementing a standard stream that provides a constructor and manipulator (str) that allow clients to directly set the internal sequence of characters that is accessed (or modified) by the stream, as well as an accessor (str) for obtaining a string having the same sequence of characters to which the stream currently refers (see 27.8.5 [stringstream] of the C++11 standard). This component also defines two standard aliases, bsl::stringstream and bsl::wstringstream, that refer to specializations of the bsl::basic_stringstream template for char and wchar_t types, respectively. The bsl::basic_stringstream template has three parameters, CHAR_TYPE, CHAR_TRAITS, and ALLOCATOR. The CHAR_TYPE and CHAR_TRAITS parameters respectively define the character type for the string-stream and a type providing a set of operations the string-stream 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 string-stream's ALLOCATOR template parameter determines how that string-stream will allocate memory. The basic_stringstream 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::stringstream and bsl::wstringstream both use bsl::allocator.

bslma-Style Allocators

If the type supplied for the ALLOCATOR template parameter of an stringstream instantiation is bsl::allocator, then objects of that string-stream type will conform to the standard behavior of a bslma-allocator-enabled type. Such a string-stream 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 string-stream throughout its lifetime; otherwise, the string-stream will use the default allocator installed at the time of the string-stream's construction (see bslma_default ).

Usage

This section illustrates intended use of this component.

Example 1: Basic Input and Output Operations

The following example demonstrates the use of bsl::stringstream to read and write data of various types to a bsl::string object.

Suppose we want to implement a simplified converter between a pair of generic types, TYPE1 and TYPE2. We use bsl::stringstream to implement the lexicalCast function. We write the data of type TYPE1 into the stream with operator<< and then read it back as the data of TYPE2 with operator>>:

template <class TYPE2, class TYPE1>
TYPE2 lexicalCast(const TYPE1& what)
{
    bsl::stringstream converter;
    converter << what;
 
    TYPE2 val;
    converter >> val;
    return val;
}

Finally, we verify that the lexicalCast function works on some simple test cases:

assert(lexicalCast<int>("1234") == 1234);
 
assert(lexicalCast<short>("-5") == -5);
 
assert(lexicalCast<bsl::string>("abc") == "abc");
 
assert(lexicalCast<bsl::string>(1234) == "1234");
 
assert(lexicalCast<short>(-5) == -5);