| Home | Libraries | People | FAQ | More

### buffer

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);