The boost::asio::buffer function is used to create a buffer object to represent raw memory, an array of POD elements, a vector of POD elements, or a std::string. More...

Functions
mutable_buffers_1	boost::asio::buffer (const mutable_buffer &b)
	Create a new modifiable buffer from an existing buffer. More...

mutable_buffers_1	boost::asio::buffer (const mutable_buffer &b, std::size_t max_size_in_bytes)
	Create a new modifiable buffer from an existing buffer. More...

const_buffers_1	boost::asio::buffer (const const_buffer &b)
	Create a new non-modifiable buffer from an existing buffer. More...

const_buffers_1	boost::asio::buffer (const const_buffer &b, std::size_t max_size_in_bytes)
	Create a new non-modifiable buffer from an existing buffer. More...

mutable_buffers_1	boost::asio::buffer (void *data, std::size_t size_in_bytes)
	Create a new modifiable buffer that represents the given memory range. More...

const_buffers_1	boost::asio::buffer (const void *data, std::size_t size_in_bytes)
	Create a new non-modifiable buffer that represents the given memory range. More...

template<typename PodType , std::size_t N>
mutable_buffers_1	boost::asio::buffer (PodType(&data)[N])
	Create a new modifiable buffer that represents the given POD array. More...

template<typename PodType , std::size_t N>
mutable_buffers_1	boost::asio::buffer (PodType(&data)[N], std::size_t max_size_in_bytes)
	Create a new modifiable buffer that represents the given POD array. More...

template<typename PodType , std::size_t N>
const_buffers_1	boost::asio::buffer (const PodType(&data)[N])
	Create a new non-modifiable buffer that represents the given POD array. More...

template<typename PodType , std::size_t N>
const_buffers_1	boost::asio::buffer (const PodType(&data)[N], std::size_t max_size_in_bytes)
	Create a new non-modifiable buffer that represents the given POD array. More...

template<typename PodType , std::size_t N>
mutable_buffers_1	boost::asio::buffer (boost::array< PodType, N > &data)
	Create a new modifiable buffer that represents the given POD array. More...

template<typename PodType , std::size_t N>
mutable_buffers_1	boost::asio::buffer (boost::array< PodType, N > &data, std::size_t max_size_in_bytes)
	Create a new modifiable buffer that represents the given POD array. More...

template<typename PodType , std::size_t N>
const_buffers_1	boost::asio::buffer (boost::array< const PodType, N > &data)
	Create a new non-modifiable buffer that represents the given POD array. More...

template<typename PodType , std::size_t N>
const_buffers_1	boost::asio::buffer (boost::array< const PodType, N > &data, std::size_t max_size_in_bytes)
	Create a new non-modifiable buffer that represents the given POD array. More...

template<typename PodType , typename Allocator >
mutable_buffers_1	boost::asio::buffer (std::vector< PodType, Allocator > &data)
	Create a new modifiable buffer that represents the given POD vector. More...

template<typename PodType , typename Allocator >
mutable_buffers_1	boost::asio::buffer (std::vector< PodType, Allocator > &data, std::size_t max_size_in_bytes)
	Create a new modifiable buffer that represents the given POD vector. More...

template<typename PodType , typename Allocator >
const_buffers_1	boost::asio::buffer (const std::vector< PodType, Allocator > &data)
	Create a new non-modifiable buffer that represents the given POD vector. More...

template<typename PodType , typename Allocator >
const_buffers_1	boost::asio::buffer (const std::vector< PodType, Allocator > &data, std::size_t max_size_in_bytes)
	Create a new non-modifiable buffer that represents the given POD vector. More...

template<typename Elem , typename Traits , typename Allocator >
const_buffers_1	boost::asio::buffer (const std::basic_string< Elem, Traits, Allocator > &data)
	Create a new non-modifiable buffer that represents the given string. More...

template<typename Elem , typename Traits , typename Allocator >
const_buffers_1	boost::asio::buffer (const std::basic_string< Elem, Traits, Allocator > &data, std::size_t max_size_in_bytes)
	Create a new non-modifiable buffer that represents the given string. More...

template<typename Input , typename Output , typename Distance >
void	boost::geometry::buffer (Input const &geometry_in, Output &geometry_out, Distance const &distance, Distance const &chord_length=-1)
	{buffer} More...

template<typename Output , typename Input , typename Distance >
Output	boost::geometry::return_buffer (Input const &geometry, Distance const &distance, Distance const &chord_length=-1)
	{buffer} More...

template<typename GeometryIn , typename MultiPolygon , typename DistanceStrategy , typename SideStrategy , typename JoinStrategy , typename EndStrategy , typename PointStrategy >
void	boost::geometry::buffer (GeometryIn const &geometry_in, MultiPolygon &geometry_out, DistanceStrategy const &distance_strategy, SideStrategy const &side_strategy, JoinStrategy const &join_strategy, EndStrategy const &end_strategy, PointStrategy const &point_strategy)
	{buffer} More...

Detailed Description

The boost::asio::buffer function is used to create a buffer object to represent raw memory, an array of POD elements, a vector of POD elements, or a std::string.

A buffer object represents a contiguous region of memory as a 2-tuple consisting of a pointer and size in bytes. A tuple of the form {void*, size_t} specifies a mutable (modifiable) region of memory. Similarly, a tuple of the form {const void*, size_t} specifies a const (non-modifiable) region of memory. These two forms correspond to the classes mutable_buffer and const_buffer, respectively. To mirror C++'s conversion rules, a mutable_buffer is implicitly convertible to a const_buffer, and the opposite conversion is not permitted.

The simplest use case involves reading or writing a single buffer of a specified size:

sock.send(boost::asio::buffer(data, size));

In the above example, the return value of boost::asio::buffer meets the requirements of the ConstBufferSequence concept so that it may be directly passed to the socket's write function. A buffer created for modifiable memory also meets the requirements of the MutableBufferSequence concept.

An individual buffer may be created from a builtin array, std::vector, std::array or boost::array of POD elements. This helps prevent buffer overruns by automatically determining the size of the buffer:

 char d1[128];
size_t bytes_transferred = sock.receive(boost::asio::buffer(d1));
std::vector<char> d2(128);
bytes_transferred = sock.receive(boost::asio::buffer(d2));
std::array<char, 128> d3;
bytes_transferred = sock.receive(boost::asio::buffer(d3));
boost::array<char, 128> d4;
bytes_transferred = sock.receive(boost::asio::buffer(d4)); 

In all three cases above, the buffers created are exactly 128 bytes long. Note that a vector is never automatically resized when creating or using a buffer. The buffer size is determined using the vector's size() member function, and not its capacity.

Accessing Buffer Contents

The contents of a buffer may be accessed using the boost::asio::buffer_size and boost::asio::buffer_cast functions:

 boost::asio::mutable_buffer b1 = ...;
std::size_t s1 = boost::asio::buffer_size(b1);
unsigned char* p1 = boost::asio::buffer_cast<unsigned char*>(b1);
boost::asio::const_buffer b2 = ...;
std::size_t s2 = boost::asio::buffer_size(b2);
const void* p2 = boost::asio::buffer_cast<const void*>(b2); 

The boost::asio::buffer_cast function permits violations of type safety, so uses of it in application code should be carefully considered.

For convenience, the boost::asio::buffer_size function also works on buffer sequences (that is, types meeting the ConstBufferSequence or MutableBufferSequence type requirements). In this case, the function returns the total size of all buffers in the sequence.

Buffer Copying

The boost::asio::buffer_copy function may be used to copy raw bytes between individual buffers and buffer sequences.

In particular, when used with the boost::asio::buffer_size, the boost::asio::buffer_copy function can be used to linearise a sequence of buffers. For example:

 vector<const_buffer> buffers = ...;
vector<unsigned char> data(boost::asio::buffer_size(buffers));
boost::asio::buffer_copy(boost::asio::buffer(data), buffers); 

Note that boost::asio::buffer_copy is implemented in terms of memcpy, and consequently it cannot be used to copy between overlapping memory regions.

Buffer Invalidation

A buffer object does not have any ownership of the memory it refers to. It is the responsibility of the application to ensure the memory region remains valid until it is no longer required for an I/O operation. When the memory is no longer available, the buffer is said to have been invalidated.

For the boost::asio::buffer overloads that accept an argument of type std::vector, the buffer objects returned are invalidated by any vector operation that also invalidates all references, pointers and iterators referring to the elements in the sequence (C++ Std, 23.2.4)

For the boost::asio::buffer overloads that accept an argument of type std::basic_string, the buffer objects returned are invalidated according to the rules defined for invalidation of references, pointers and iterators referring to elements of the sequence (C++ Std, 21.3).

Buffer Arithmetic

Buffer objects may be manipulated using simple arithmetic in a safe way which helps prevent buffer overruns. Consider an array initialised as follows:

boost::array<char, 6> a = { 'a', 'b', 'c', 'd', 'e' };

A buffer object b1 created using:

b1 = boost::asio::buffer(a);

represents the entire array, { 'a', 'b', 'c', 'd', 'e' }. An optional second argument to the boost::asio::buffer function may be used to limit the size, in bytes, of the buffer:

b2 = boost::asio::buffer(a, 3);

such that b2 represents the data { 'a', 'b', 'c' }. Even if the size argument exceeds the actual size of the array, the size of the buffer object created will be limited to the array size.

An offset may be applied to an existing buffer to create a new one:

b3 = b1 + 2;

where b3 will set to represent { 'c', 'd', 'e' }. If the offset exceeds the size of the existing buffer, the newly created buffer will be empty.

Both an offset and size may be specified to create a buffer that corresponds to a specific range of bytes within an existing buffer:

b4 = boost::asio::buffer(b1 + 1, 3);

so that b4 will refer to the bytes { 'b', 'c', 'd' }.

Buffers and Scatter-Gather I/O

To read or write using multiple buffers (i.e. scatter-gather I/O), multiple buffer objects may be assigned into a container that supports the MutableBufferSequence (for read) or ConstBufferSequence (for write) concepts:

char d1[128];
std::vector<char> d2(128);
boost::array<char, 128> d3;
boost::array<mutable_buffer, 3> bufs1 = {
  boost::asio::buffer(d1),
  boost::asio::buffer(d2),
  boost::asio::buffer(d3) };
bytes_transferred = sock.receive(bufs1);
std::vector<const_buffer> bufs2;
bufs2.push_back(boost::asio::buffer(d1));
bufs2.push_back(boost::asio::buffer(d2));
bufs2.push_back(boost::asio::buffer(d3));
bytes_transferred = sock.send(bufs2); 

Function Documentation

template<typename Input , typename Output , typename Distance >

void boost::geometry::buffer	(	Input const &	geometry_in,
		Output &	geometry_out,
		Distance const &	distance,
		Distance const &	chord_length = `-1`
	)

inline

#include <boost_1_57_0/boost/geometry/algorithms/buffer.hpp>

{buffer}

{buffer, }.

Template Parameters

Input
Output
Distance

Parameters

geometry_in
geometry_out
distance	The distance to be used for the buffer
chord_length	(optional) The length of the chord's in the generated arcs around points or bends

{[include reference/algorithms/buffer.qbk]}

References boost::geometry::resolve_variant::buffer< Geometry >::apply().

Referenced by boost::geometry::buffer().

template<typename GeometryIn , typename MultiPolygon , typename DistanceStrategy , typename SideStrategy , typename JoinStrategy , typename EndStrategy , typename PointStrategy >

void boost::geometry::buffer	(	GeometryIn const &	geometry_in,
		MultiPolygon &	geometry_out,
		DistanceStrategy const &	distance_strategy,
		SideStrategy const &	side_strategy,
		JoinStrategy const &	join_strategy,
		EndStrategy const &	end_strategy,
		PointStrategy const &	point_strategy
	)

inline

#include <boost_1_57_0/boost/geometry/algorithms/buffer.hpp>

{buffer}

{buffer, }.

Template Parameters

GeometryIn
MultiPolygon	{MultiPolygon}
DistanceStrategy	A strategy defining distance (or radius)
SideStrategy	A strategy defining creation along sides
JoinStrategy	A strategy defining creation around convex corners
EndStrategy	A strategy defining creation at linestring ends
PointStrategy	A strategy defining creation around points

Parameters

geometry_in
geometry_out	output multi polygon (or std:: collection of polygons), will contain a buffered version of the input geometry
distance_strategy	The distance strategy to be used
side_strategy	The side strategy to be used
join_strategy	The join strategy to be used
end_strategy	The end strategy to be used
point_strategy	The point strategy to be used

{distinguish,with strategies} {[include reference/algorithms/buffer_with_strategies.qbk]}

References boost::geometry::buffer(), and boost::geometry::envelope().

mutable_buffers_1 boost::asio::buffer ( const mutable_buffer & b )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer from an existing buffer.

Returns: mutable_buffers_1(b).

Referenced by boost::asio::buffer_copy(), boost::asio::basic_streambuf< Allocator >::data(), boost::asio::buffers_iterator< BufferSequence, ByteType >::end(), boost::asio::basic_socket_streambuf< Protocol, StreamSocketService, Time, TimeTraits, TimerService >::overflow(), boost::asio::basic_streambuf< Allocator >::prepare(), and boost::asio::basic_socket_streambuf< Protocol, StreamSocketService, Time, TimeTraits, TimerService >::underflow().

mutable_buffers_1 boost::asio::buffer	(	const mutable_buffer &	b,
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer from an existing buffer.

Returns: A mutable_buffers_1 value equivalent to:
mutable_buffers_1(

buffer_cast<void*>(b),

min(buffer_size(b), max_size_in_bytes));

References boost::asio::buffer_size().

const_buffers_1 boost::asio::buffer ( const const_buffer & b )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer from an existing buffer.

Returns: const_buffers_1(b).

const_buffers_1 boost::asio::buffer	(	const const_buffer &	b,
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer from an existing buffer.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

buffer_cast<const void*>(b),

min(buffer_size(b), max_size_in_bytes));

References boost::asio::buffer_size().

mutable_buffers_1 boost::asio::buffer	(	void *	data,
		std::size_t	size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer that represents the given memory range.

Returns: mutable_buffers_1(data, size_in_bytes).

const_buffers_1 boost::asio::buffer	(	const void *	data,
		std::size_t	size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given memory range.

Returns: const_buffers_1(data, size_in_bytes).

template<typename PodType , std::size_t N>

mutable_buffers_1 boost::asio::buffer ( PodType(&) data[N] )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer that represents the given POD array.

Returns: A mutable_buffers_1 value equivalent to:
mutable_buffers_1(

static_cast<void*>(data),

N * sizeof(PodType));

References boost::proto::envns_::data.

template<typename PodType , std::size_t N>

mutable_buffers_1 boost::asio::buffer	(	PodType(&)	data[N],
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer that represents the given POD array.

Returns: A mutable_buffers_1 value equivalent to:
mutable_buffers_1(

static_cast<void*>(data),

min(N * sizeof(PodType), max_size_in_bytes));

References boost::proto::envns_::data.

template<typename PodType , std::size_t N>

const_buffers_1 boost::asio::buffer ( const PodType(&) data[N] )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given POD array.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

static_cast<const void*>(data),

N * sizeof(PodType));

References boost::proto::envns_::data.

template<typename PodType , std::size_t N>

const_buffers_1 boost::asio::buffer	(	const PodType(&)	data[N],
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given POD array.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

static_cast<const void*>(data),

min(N * sizeof(PodType), max_size_in_bytes));

References boost::proto::envns_::data.

template<typename PodType , std::size_t N>

mutable_buffers_1 boost::asio::buffer ( boost::array< PodType, N > & data )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer that represents the given POD array.

Returns: A mutable_buffers_1 value equivalent to:
mutable_buffers_1(

data.data(),

data.size() * sizeof(PodType));

References boost::array< T, N >::c_array(), and boost::array< T, N >::size().

template<typename PodType , std::size_t N>

mutable_buffers_1 boost::asio::buffer	(	boost::array< PodType, N > &	data,
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer that represents the given POD array.

Returns: A mutable_buffers_1 value equivalent to:
mutable_buffers_1(

data.data(),

min(data.size() * sizeof(PodType), max_size_in_bytes));

References boost::array< T, N >::c_array(), and boost::array< T, N >::size().

template<typename PodType , std::size_t N>

const_buffers_1 boost::asio::buffer ( boost::array< const PodType, N > & data )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given POD array.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

data.data(),

data.size() * sizeof(PodType));

References boost::array< T, N >::data(), and boost::array< T, N >::size().

template<typename PodType , std::size_t N>

const_buffers_1 boost::asio::buffer	(	boost::array< const PodType, N > &	data,
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given POD array.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

data.data(),

min(data.size() * sizeof(PodType), max_size_in_bytes));

References boost::array< T, N >::data(), and boost::array< T, N >::size().

template<typename PodType , typename Allocator >

mutable_buffers_1 boost::asio::buffer ( std::vector< PodType, Allocator > & data )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer that represents the given POD vector.

Returns: A mutable_buffers_1 value equivalent to:
mutable_buffers_1(

data.size() ? &data[0] : 0,

data.size() * sizeof(PodType));

Note: The buffer is invalidated by any vector operation that would also invalidate iterators.

template<typename PodType , typename Allocator >

mutable_buffers_1 boost::asio::buffer	(	std::vector< PodType, Allocator > &	data,
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new modifiable buffer that represents the given POD vector.

Returns: A mutable_buffers_1 value equivalent to:
mutable_buffers_1(

data.size() ? &data[0] : 0,

min(data.size() * sizeof(PodType), max_size_in_bytes));

Note: The buffer is invalidated by any vector operation that would also invalidate iterators.

template<typename PodType , typename Allocator >

const_buffers_1 boost::asio::buffer ( const std::vector< PodType, Allocator > & data )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given POD vector.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

data.size() ? &data[0] : 0,

data.size() * sizeof(PodType));

Note: The buffer is invalidated by any vector operation that would also invalidate iterators.

template<typename PodType , typename Allocator >

const_buffers_1 boost::asio::buffer	(	const std::vector< PodType, Allocator > &	data,
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given POD vector.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

data.size() ? &data[0] : 0,

min(data.size() * sizeof(PodType), max_size_in_bytes));

Note: The buffer is invalidated by any vector operation that would also invalidate iterators.

template<typename Elem , typename Traits , typename Allocator >

const_buffers_1 boost::asio::buffer ( const std::basic_string< Elem, Traits, Allocator > & data )

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given string.

Returns: const_buffers_1(data.data(), data.size() * sizeof(Elem)).

Note: The buffer is invalidated by any non-const operation called on the given string object.

template<typename Elem , typename Traits , typename Allocator >

const_buffers_1 boost::asio::buffer	(	const std::basic_string< Elem, Traits, Allocator > &	data,
		std::size_t	max_size_in_bytes
	)

inline

#include <boost_1_57_0/boost/asio/buffer.hpp>

Create a new non-modifiable buffer that represents the given string.

Returns: A const_buffers_1 value equivalent to:
const_buffers_1(

data.data(),

min(data.size() * sizeof(Elem), max_size_in_bytes));

Note: The buffer is invalidated by any non-const operation called on the given string object.

template<typename Output , typename Input , typename Distance >

Output boost::geometry::return_buffer	(	Input const &	geometry,
		Distance const &	distance,
		Distance const &	chord_length = `-1`
	)

#include <boost_1_57_0/boost/geometry/algorithms/buffer.hpp>

{buffer}

{return_buffer, }. {buffer}.

Template Parameters

Input
Output
Distance

Parameters

geometry
distance	The distance to be used for the buffer
chord_length	(optional) The length of the chord's in the generated arcs around points or bends (RESERVED, NOT YET USED)

Returns: {buffer}

References boost::geometry::resolve_variant::buffer< Geometry >::apply().

Functions

Detailed Description

Function Documentation