boost::asio::basic_streambuf< Allocator > Singleton Reference

Automatically resizable buffer class based on std::streambuf. More...

#include <basic_streambuf_fwd.hpp>

Inheritance diagram for boost::asio::basic_streambuf< Allocator >:

Collaboration diagram for boost::asio::basic_streambuf< Allocator >:

Public Types
typedef boost::asio::const_buffers_1	const_buffers_type
typedef boost::asio::mutable_buffers_1	mutable_buffers_type

Public Member Functions
	basic_streambuf (std::size_t maximum_size=(std::numeric_limits< std::size_t >::max)(), const Allocator &allocator=Allocator())
	Construct a basic_streambuf object. More...
std::size_t	size () const
	Get the size of the input sequence. More...
std::size_t	max_size () const
	Get the maximum size of the basic_streambuf. More...
const_buffers_type	data () const
	Get a list of buffers that represents the input sequence. More...
mutable_buffers_type	prepare (std::size_t n)
	Get a list of buffers that represents the output sequence, with the given size. More...
void	commit (std::size_t n)
	Move characters from the output sequence to the input sequence. More...
void	consume (std::size_t n)
	Remove characters from the input sequence. More...

Protected Types
enum	{ buffer_delta = 128 }

Protected Member Functions
int_type	underflow ()
	Override std::streambuf behaviour. More...
int_type	overflow (int_type c)
	Override std::streambuf behaviour. More...
void	reserve (std::size_t n)

Friends
std::size_t	read_size_helper (basic_streambuf &sb, std::size_t max_size)

Detailed Description

template<typename Allocator>
singleton boost::asio::basic_streambuf< Allocator >

Automatically resizable buffer class based on std::streambuf.

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:

• A single contiguous character array, which is reallocated as necessary to accommodate changes in the size of the character sequence. This is the implementation approach currently used in Asio.

• A sequence of one or more character arrays, where each array is of the same size. Additional character array objects are appended to the sequence to accommodate changes in the size of the character sequence.

• A sequence of one or more character arrays of varying sizes. Additional character array objects are appended to the sequence to accommodate changes in the size of the character sequence.

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;

Member Typedef Documentation

template<typename Allocator>

typedef boost::asio::const_buffers_1 boost::asio::basic_streambuf< Allocator >::const_buffers_type

template<typename Allocator>

typedef boost::asio::mutable_buffers_1 boost::asio::basic_streambuf< Allocator >::mutable_buffers_type

Member Enumeration Documentation

template<typename Allocator>

anonymous enum

protected

Enumerator
buffer_delta

Constructor & Destructor Documentation

template<typename Allocator>

boost::asio::basic_streambuf< Allocator >::basic_streambuf ( std::size_t  maximum_size = (std::numeric_limits<std::size_t>::max)(), const Allocator &  allocator = Allocator()  )

inlineexplicit

Construct a basic_streambuf object.

Constructs a streambuf with the specified maximum size. The initial size of the streambuf's input sequence is 0.

References boost::asio::basic_streambuf< Allocator >::buffer_delta.

Member Function Documentation

template<typename Allocator>

void boost::asio::basic_streambuf< Allocator >::commit ( std::size_t  n )

inline

Move characters from the output sequence to the input sequence.

Appends n characters from the start of the output sequence to the input sequence. The beginning of the output sequence is advanced by n characters.

Requires a preceding call prepare(x) where x >= n, and no intervening operations that modify the input or output sequence.

Note

If n is greater than the size of the output sequence, the entire output sequence is moved to the input sequence and no error is issued.

template<typename Allocator>

void boost::asio::basic_streambuf< Allocator >::consume ( std::size_t  n )

inline

Remove characters from the input sequence.

Removes n characters from the beginning of the input sequence.

Note

If n is greater than the size of the input sequence, the entire input sequence is consumed and no error is issued.

template<typename Allocator>

const_buffers_type boost::asio::basic_streambuf< Allocator >::data ( ) const

inline

Get a list of buffers that represents the input sequence.

Returns

An object of type const_buffers_type that satisfies ConstBufferSequence requirements, representing all character arrays in the input sequence.

Note

The returned object is invalidated by any basic_streambuf member function that modifies the input sequence or output sequence.

References boost::asio::buffer().

template<typename Allocator>

std::size_t boost::asio::basic_streambuf< Allocator >::max_size ( ) const

inline

Get the maximum size of the basic_streambuf.

Returns

The allowed maximum of the sum of the sizes of the input sequence and output sequence.

Referenced by boost::asio::read_size_helper().

template<typename Allocator>

int_type boost::asio::basic_streambuf< Allocator >::overflow ( int_type  c )

inlineprotected

Override std::streambuf behaviour.

Behaves according to the specification of std::streambuf::overflow(), with the specialisation that std::length_error is thrown if appending the character to the input sequence would require the condition size() > max_size() to be true.

References boost::asio::basic_streambuf< Allocator >::buffer_delta, boost::asio::buffer_size(), boost::multiprecision::backends::c, boost::asio::error::eof, and boost::asio::basic_streambuf< Allocator >::reserve().

template<typename Allocator>

mutable_buffers_type boost::asio::basic_streambuf< Allocator >::prepare ( std::size_t  n )

inline

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

Ensures that the output sequence can accommodate n characters, reallocating character array objects as necessary.

Returns

An object of type mutable_buffers_type that satisfies MutableBufferSequence requirements, representing character array objects at the start of the output sequence such that the sum of the buffer sizes is n.

Exceptions

std::length_error

If size() + n > max_size().

Note

The returned object is invalidated by any basic_streambuf member function that modifies the input sequence or output sequence.

References boost::asio::buffer(), and boost::asio::basic_streambuf< Allocator >::reserve().

template<typename Allocator>

void boost::asio::basic_streambuf< Allocator >::reserve ( std::size_t  n )

inlineprotected

References boost::n, and boost::lambda::throw_exception().

Referenced by boost::asio::basic_streambuf< Allocator >::overflow(), and boost::asio::basic_streambuf< Allocator >::prepare().

template<typename Allocator>

std::size_t boost::asio::basic_streambuf< Allocator >::size ( ) const

inline

Get the size of the input sequence.

Returns

The size of the input sequence. The value is equal to that calculated for s in the following code:

size_t s = 0;
const_buffers_type bufs = data();
const_buffers_type::const_iterator i = bufs.begin();
while (i != bufs.end())
{
  const_buffer buf(*i++);
  s += buffer_size(buf);
}

Referenced by boost::asio::read_size_helper().

template<typename Allocator>

int_type boost::asio::basic_streambuf< Allocator >::underflow ( )

inlineprotected

Override std::streambuf behaviour.

Behaves according to the specification of std::streambuf::underflow().

References boost::asio::error::eof.

Friends And Related Function Documentation

template<typename Allocator>

std::size_t read_size_helper ( basic_streambuf< Allocator > &  sb, std::size_t  max_size  )

friend

---

The documentation for this singleton was generated from the following file:

• boost_1_57_0/boost/asio/basic_streambuf.hpp