bdlsb_fixedmeminstreambuf

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Streaming Architecture
  • Usage
    • Example 1: Basic Use of the bdlsb::FixedMemInStreamBuf
    • Example 2: Scanning Input Data

Purpose

Provide an input basic_streambuf using a client buffer.

Classes

• bdlsb::FixedMemInStreamBuf: input stream buffer using client memory

See also

bdlsb_fixedmemoutstreambuf, bdlsb_memoutstreambuf

Description

This component defines a class, bdlsb::FixedMemInStreamBuf, that implements the input portion of the bsl::basic_streambuf protocol using a client-supplied memory buffer. Method names necessarily correspond to the protocol-specified method names. Clients supply the character buffer at stream buffer construction, and can later reinitialize the stream buffer with a different character buffer by calling the pubsetbuf method.

This component provides none of the output-related functionality of basic_streambuf (see Streaming Architecture, below), nor does it use locales in any way.

Streaming Architecture

Stream buffers are designed to decouple device handling from content formatting, providing the requisite device handling and possible buffering services, and leaving the formatting to the client stream. The standard C++ IOStreams library further partitions streaming into input streaming and output streaming, separating responsibilities for each at both the stream layer and the stream buffer layer. The BDE streaming library for bdex, including all of bdlsb, follows this model.

Usage

This section illustrates intended use of this component.

Example 1: Basic Use of the bdlsb::FixedMemInStreamBuf

bdlsb::FixedMemInStreamBuf can be used in situations when you already have an array of bytes in memory and you'd like to wrap it in an input stream to extract data in a formatted manner. A bdlsb::FixedMemInStreamBuf object refers to an externally managed buffer that is supplied either at construction, or using the pubsetbuf method of the bsl::streambuf base-class.

First, we create an array of characters to provide data that needs to be parsed, and construct bdlsb::FixedMemInStreamBuf on that array:

{
    const char *inputText = "1 1 2 3 5 8 13 21";
    bdlsb::FixedMemInStreamBuf buffer(inputText, strlen(inputText));

Notice that bdlsb::FixedMemInStreamBuf can be used with buffers referring to stack memory or to heap memory.

Then, we use buffer to construct a bsl::istream:

    bsl::istream stream(&buffer);

Finally, we can input the data from the stream in a formatted manner:

    int value;
    while (stream >> value) {
        cout << "Value is: " << value << endl;
    }
}

Example 2: Scanning Input Data

This example illustrates scanning of the input stream buffer for particular pattern ( digits, in our case ) and then using stream to read out found number.

First, we create an array of characters to provide data that needs to be parsed, and construct bdlsb::FixedMemInStreamBuf on that array:

{
    const char *inputText = "The answer is: 42.";
    bdlsb::FixedMemInStreamBuf buffer(inputText, strlen(inputText));

Then, we use buffer to construct a bsl::istream that will be used later to read found number:

    bsl::istream stream(&buffer);

Next, we scan input buffer one character at a time searching for the first digit:

    char ch;
    do {
        ch = static_cast<char>(buffer.sbumpc());
 
        if ( (ch >= '0') && (ch <= '9') ) {

Now, when the digit character is found, we return the first digit into the input stream buffer for subsequent read:

            buffer.sputbackc(ch);
            int n;

Finally, we read out the whole number:

            stream >> n;
            assert( 42 == n );
            cout << "The answer is " << n << " indeed..." << endl;
            break;
        }
    } while ( ch != EOF );
}