streambuf layering: give formatted output a different destination

Formatting and the device should not be bound together

If the output destination changes from a file to memory, the rules for converting integers to text should not have to be rewritten. The key boundary shown in the excerpt is that the stream interprets format and state, while streambuf provides the transport interface for character sequences. Plug a custom device into the character layer and you can reuse ostream's formatting capabilities.

The sample device is a fixed-size array. It has no file, network, or dynamic allocation, does not support seeking, and only guarantees sequential writes from the start. Making the promised contract precise is more reliable than appearing to implement a complete device while missing edge cases; a fixed capacity also makes the failure path deterministically reproducible.

What happens after the put area is full

At construction, setp sets the start and one-past-the-end pointers so ordinary characters can go directly into the put area; when space is exhausted, further writes cannot continue. We do not silently grow a full buffer; instead we return traits_type::eof() to indicate that a character cannot be accepted.

overflow receives an int_type and must not convert it to char before testing for EOF, or it will confuse a character with the end-of-file marker. The sample returns not_eof for an EOF request, indicating that a request that needs no new character was handled successfully; for a genuine new character it returns EOF. This derived class has no data pending flush to another device; the character array itself is the final destination.

Check the stream state, and also check writes that already happened

A failed output does not mean previously written characters are automatically undone. The sample first writes three characters successfully, then appends a fourth, asserting that badbit is set and that the original three characters remain; this checks both the upper-layer state and the lower-layer content. A protocol that needs atomic commit of a whole message should add a separate transactional buffer; do not mistake ostream for a database.

The buffer object must outlive the ostream that refers to it. This example destroys in reverse declaration order: the stream first, then the buffer. The book's diagrams of file-buffer pointer arrangement are an explanatory model, not a mandated ABI; the layered interface still applies in C++20, but do not depend on whether a given standard-library implementation uses a single buffer or a double buffer internally.

Pitfalls

• badbit does not undo characters already output; restoring stream state is also not the same as enlarging device capacity.
• ostream does not own a custom streambuf passed to it; destroying the buffer first and then using the stream leaves a dangling pointer.

Minimum C++11 · complete program · Download .cpp

#include <array>
#include <cassert>
#include <cstddef>
#include <locale>
#include <ostream>
#include <streambuf>
#include <string>
class FixedBuffer : public std::streambuf {
    std::array<char, 3> data_{};
protected:
    int_type overflow(int_type c = traits_type::eof()) override {
        if (traits_type::eq_int_type(c, traits_type::eof()))
            return traits_type::not_eof(c);
        return traits_type::eof();
    }
public:
    FixedBuffer() { setp(data_.data(), data_.data() + data_.size()); }
    FixedBuffer(const FixedBuffer&) = delete;
    FixedBuffer& operator=(const FixedBuffer&) = delete;
    std::string text() const { return std::string(pbase(), pptr()); }
};
int main() {
    FixedBuffer buffer;
    std::ostream out(&buffer);
    out.imbue(std::locale::classic());
    out << 42 << '!';
    assert(out.good());
    assert(buffer.text() == "42!");
    out.put('?');
    assert(out.bad());
    assert(buffer.text() == "42!");
}

Compile locally

g++ -std=c++11 -Wall -Wextra -Wpedantic -pthread books-iostreams-locales.cpp -o example && ./example

Expected result

Expected: exit 0, no output; every assert holds.

CHECK YOUR UNDERSTANDING

Close the answer. Explain it.

What happens if you change the capacity from 3 to 4, keep the first two writes, and then append one more character?

Check the sources

• Langer/Kreft 授权书摘 pp.84—109
• N3337 streambuf put area 虚接口

Drafts and official chapters change. The version mark is only the example’s minimum.