Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

basic_streambuf

Automatically resizable buffer class based on std::streambuf.

template<
    typename Allocator = std::allocator<char>>
class basic_streambuf :
  noncopyable
Types

Name

Description

const_buffers_type

The type used to represent the input sequence as a list of buffers.

mutable_buffers_type

The type used to represent the output sequence as a list of buffers.

Member Functions

Name

Description

basic_streambuf

Construct a basic_streambuf object.

commit

Move characters from the output sequence to the input sequence.

consume

Remove characters from the input sequence.

data

Get a list of buffers that represents the input sequence.

max_size

Get the maximum size of the basic_streambuf.

prepare

Get a list of buffers that represents the output sequence, with the given size.

size

Get the size of the input sequence.

Protected Member Functions

Name

Description

overflow

Override std::streambuf behaviour.

reserve

underflow

Override std::streambuf behaviour.

The basic_streambuf class is derived from std::streambuf to associate the streambuf's input and output sequences with one or more character arrays. These character arrays are internal to the basic_streambuf object, but direct access to the array elements is provided to permit them to be used efficiently with I/O operations. Characters written to the output sequence of a basic_streambuf object are appended to the input sequence of the same object.

The basic_streambuf class's public interface is intended to permit the following implementation strategies:

The constructor for basic_streambuf accepts a size_t argument specifying the maximum of the sum of the sizes of the input sequence and output sequence. During the lifetime of the basic_streambuf object, the following invariant holds:

size() <= max_size()

Any member function that would, if successful, cause the invariant to be violated shall throw an exception of class std::length_error.

The constructor for basic_streambuf takes an Allocator argument. A copy of this argument is used for any memory allocation performed, by the constructor and by all member functions, during the lifetime of each basic_streambuf object.

Examples

Writing directly from an streambuf to a socket:

boost::asio::streambuf b;
std::ostream os(&b);
os << "Hello, World!\n";

// try sending some data in input sequence
size_t n = sock.send(b.data());

b.consume(n); // sent data is removed from input sequence

Reading from a socket directly into a streambuf:

boost::asio::streambuf b;

// reserve 512 bytes in output sequence
boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512);

size_t n = sock.receive(bufs);

// received data is "committed" from output sequence to input sequence
b.commit(n);

std::istream is(&b);
std::string s;
is >> s;
Requirements

Header: boost/asio/basic_streambuf.hpp

Convenience header: boost/asio.hpp


PrevUpHomeNext