...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1 buffer( const mutable_buffer & b); mutable_buffers_1 buffer( const mutable_buffer & b, std::size_t max_size_in_bytes); const_buffers_1 buffer( const const_buffer & b); const_buffers_1 buffer( const const_buffer & b, std::size_t max_size_in_bytes); mutable_buffers_1 buffer( void * data, std::size_t size_in_bytes); const_buffers_1 buffer( const void * data, std::size_t size_in_bytes); template< typename PodType, std::size_t N> mutable_buffers_1 buffer( PodType & data); template< typename PodType, std::size_t N> mutable_buffers_1 buffer( PodType & data, std::size_t max_size_in_bytes); template< typename PodType, std::size_t N> const_buffers_1 buffer( const PodType & data); template< typename PodType, std::size_t N> const_buffers_1 buffer( const PodType & data, std::size_t max_size_in_bytes); template< typename PodType, std::size_t N> mutable_buffers_1 buffer( boost::array< PodType, N > & data); template< typename PodType, std::size_t N> mutable_buffers_1 buffer( boost::array< PodType, N > & data, std::size_t max_size_in_bytes); template< typename PodType, std::size_t N> const_buffers_1 buffer( boost::array< const PodType, N > & data); template< typename PodType, std::size_t N> const_buffers_1 buffer( boost::array< const PodType, N > & data, std::size_t max_size_in_bytes); template< typename PodType, std::size_t N> const_buffers_1 buffer( const boost::array< PodType, N > & data); template< typename PodType, std::size_t N> const_buffers_1 buffer( const boost::array< PodType, N > & data, std::size_t max_size_in_bytes); template< typename PodType, typename Allocator> mutable_buffers_1 buffer( std::vector< PodType, Allocator > & data); template< typename PodType, typename Allocator> mutable_buffers_1 buffer( std::vector< PodType, Allocator > & data, std::size_t max_size_in_bytes); template< typename PodType, typename Allocator> const_buffers_1 buffer( const std::vector< PodType, Allocator > & data); template< typename PodType, typename Allocator> const_buffers_1 buffer( const std::vector< PodType, Allocator > & data, std::size_t max_size_in_bytes); const_buffers_1 buffer( const std::string & data); const_buffers_1 buffer( const std::string & data, std::size_t max_size_in_bytes);
The simplest use case involves reading or writing a single buffer of a specified size:
sock.write(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 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.read(boost::asio::buffer(d1)); std::vector<char> d2(128); bytes_transferred = sock.read(boost::asio::buffer(d2)); boost::array<char, 128> d3; bytes_transferred = sock.read(boost::asio::buffer(d3));
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.read(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.write(bufs2);