//

// buffer.hpp

// ~~~~~~~~~~

//

// Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

#ifndef ASIO_BUFFER_HPP

#define ASIO_BUFFER_HPP

#if defined(_MSC_VER) && (_MSC_VER >= 1200)

# pragma once

#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)

#include "asio/detail/config.hpp"

#include <cstddef>

#include <cstring>

#include <limits>

#include <stdexcept>

#include <string>

#include <vector>

#include "asio/detail/array_fwd.hpp"

#include "asio/detail/memory.hpp"

#include "asio/detail/string_view.hpp"

#include "asio/detail/throw_exception.hpp"

#include "asio/detail/type_traits.hpp"

#if defined(ASIO_MSVC) && (ASIO_MSVC >= 1700)

# if defined(_HAS_ITERATOR_DEBUGGING) && (_HAS_ITERATOR_DEBUGGING != 0)

# if !defined(ASIO_DISABLE_BUFFER_DEBUGGING)

# define ASIO_ENABLE_BUFFER_DEBUGGING

# endif // !defined(ASIO_DISABLE_BUFFER_DEBUGGING)

# endif // defined(_HAS_ITERATOR_DEBUGGING)

#endif // defined(ASIO_MSVC) && (ASIO_MSVC >= 1700)

#if defined(__GNUC__)

# if defined(_GLIBCXX_DEBUG)

# if !defined(ASIO_DISABLE_BUFFER_DEBUGGING)

# define ASIO_ENABLE_BUFFER_DEBUGGING

# endif // !defined(ASIO_DISABLE_BUFFER_DEBUGGING)

# endif // defined(_GLIBCXX_DEBUG)

#endif // defined(__GNUC__)

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

# include "asio/detail/functional.hpp"

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

#if defined(ASIO_HAS_BOOST_WORKAROUND)

# include <boost/detail/workaround.hpp>

# if !defined(__clang__)

# if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x582))

# define ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND

# endif // BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x582))

# elif BOOST_WORKAROUND(__SUNPRO_CC, BOOST_TESTED_AT(0x590))

# define ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND

# endif // BOOST_WORKAROUND(__SUNPRO_CC, BOOST_TESTED_AT(0x590))

#endif // defined(ASIO_HAS_BOOST_WORKAROUND)

#if defined(ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND)

# include "asio/detail/type_traits.hpp"

#endif // defined(ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND)

#include "asio/detail/push_options.hpp"

namespace asio {

class mutable_buffer;

class const_buffer;

/// Holds a buffer that can be modified.

/**

* The mutable_buffer class provides a safe representation of a buffer that can

* be modified. It does not own the underlying data, and so is cheap to copy or

* assign.

*

* @par Accessing Buffer Contents

*

* The contents of a buffer may be accessed using the @c data() and @c size()

* member functions:

*

* @code asio::mutable_buffer b1 = ...;

* std::size_t s1 = b1.size();

* unsigned char* p1 = static_cast<unsigned char*>(b1.data());

* @endcode

*

* The @c data() member function permits violations of type safety, so uses of

* it in application code should be carefully considered.

*/

class mutable_buffer

{

public:

/// Construct an empty buffer.

mutable_buffer() ASIO_NOEXCEPT

: data_(0),

size_(0)

{

}

/// Construct a buffer to represent a given memory range.

mutable_buffer(void* data, std::size_t size) ASIO_NOEXCEPT

: data_(data),

size_(size)

{

}

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

mutable_buffer(void* data, std::size_t size,

asio::detail::function<void()> debug_check)

: data_(data),

size_(size),

debug_check_(debug_check)

{

}

const asio::detail::function<void()>& get_debug_check() const

{

return debug_check_;

}

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

/// Get a pointer to the beginning of the memory range.

void* data() const ASIO_NOEXCEPT

{

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

if (size_ && debug_check_)

debug_check_();

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

return data_;

}

/// Get the size of the memory range.

std::size_t size() const ASIO_NOEXCEPT

{

return size_;

}

/// Move the start of the buffer by the specified number of bytes.

mutable_buffer& operator+=(std::size_t n) ASIO_NOEXCEPT

{

std::size_t offset = n < size_ ? n : size_;

data_ = static_cast<char*>(data_) + offset;

size_ -= offset;

return *this;

}

private:

void* data_;

std::size_t size_;

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

asio::detail::function<void()> debug_check_;

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

};

#if !defined(ASIO_NO_DEPRECATED)

/// (Deprecated: Use mutable_buffer.) Adapts a single modifiable buffer so that

/// it meets the requirements of the MutableBufferSequence concept.

class mutable_buffers_1

: public mutable_buffer

{

public:

/// The type for each element in the list of buffers.

typedef mutable_buffer value_type;

/// A random-access iterator type that may be used to read elements.

typedef const mutable_buffer* const_iterator;

/// Construct to represent a given memory range.

mutable_buffers_1(void* data, std::size_t size) ASIO_NOEXCEPT

: mutable_buffer(data, size)

{

}

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

mutable_buffers_1(void* data, std::size_t size,

asio::detail::function<void()> debug_check)

: mutable_buffer(data, size, debug_check)

{

}

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

/// Construct to represent a single modifiable buffer.

explicit mutable_buffers_1(const mutable_buffer& b) ASIO_NOEXCEPT

: mutable_buffer(b)

{

}

/// Get a random-access iterator to the first element.

const_iterator begin() const ASIO_NOEXCEPT

{

return this;

}

/// Get a random-access iterator for one past the last element.

const_iterator end() const ASIO_NOEXCEPT

{

return begin() + 1;

}

};

#endif // !defined(ASIO_NO_DEPRECATED)

/// Holds a buffer that cannot be modified.

/**

* The const_buffer class provides a safe representation of a buffer that cannot

* be modified. It does not own the underlying data, and so is cheap to copy or

* assign.

*

* @par Accessing Buffer Contents

*

* The contents of a buffer may be accessed using the @c data() and @c size()

* member functions:

*

* @code asio::const_buffer b1 = ...;

* std::size_t s1 = b1.size();

* const unsigned char* p1 = static_cast<const unsigned char*>(b1.data());

* @endcode

*

* The @c data() member function permits violations of type safety, so uses of

* it in application code should be carefully considered.

*/

class const_buffer

{

public:

/// Construct an empty buffer.

const_buffer() ASIO_NOEXCEPT

: data_(0),

size_(0)

{

}

/// Construct a buffer to represent a given memory range.

const_buffer(const void* data, std::size_t size) ASIO_NOEXCEPT

: data_(data),

size_(size)

{

}

/// Construct a non-modifiable buffer from a modifiable one.

const_buffer(const mutable_buffer& b) ASIO_NOEXCEPT

: data_(b.data()),

size_(b.size())

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

, debug_check_(b.get_debug_check())

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

{

}

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

const_buffer(const void* data, std::size_t size,

asio::detail::function<void()> debug_check)

: data_(data),

size_(size),

debug_check_(debug_check)

{

}

const asio::detail::function<void()>& get_debug_check() const

{

return debug_check_;

}

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

/// Get a pointer to the beginning of the memory range.

const void* data() const ASIO_NOEXCEPT

{

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

if (size_ && debug_check_)

debug_check_();

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

return data_;

}

/// Get the size of the memory range.

std::size_t size() const ASIO_NOEXCEPT

{

return size_;

}

/// Move the start of the buffer by the specified number of bytes.

const_buffer& operator+=(std::size_t n) ASIO_NOEXCEPT

{

std::size_t offset = n < size_ ? n : size_;

data_ = static_cast<const char*>(data_) + offset;

size_ -= offset;

return *this;

}

private:

const void* data_;

std::size_t size_;

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

asio::detail::function<void()> debug_check_;

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

};

#if !defined(ASIO_NO_DEPRECATED)

/// (Deprecated: Use const_buffer.) Adapts a single non-modifiable buffer so

/// that it meets the requirements of the ConstBufferSequence concept.

class const_buffers_1

: public const_buffer

{

public:

/// The type for each element in the list of buffers.

typedef const_buffer value_type;

/// A random-access iterator type that may be used to read elements.

typedef const const_buffer* const_iterator;

/// Construct to represent a given memory range.

const_buffers_1(const void* data, std::size_t size) ASIO_NOEXCEPT

: const_buffer(data, size)

{

}

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

const_buffers_1(const void* data, std::size_t size,

asio::detail::function<void()> debug_check)

: const_buffer(data, size, debug_check)

{

}

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

/// Construct to represent a single non-modifiable buffer.

explicit const_buffers_1(const const_buffer& b) ASIO_NOEXCEPT

: const_buffer(b)

{

}

/// Get a random-access iterator to the first element.

const_iterator begin() const ASIO_NOEXCEPT

{

return this;

}

/// Get a random-access iterator for one past the last element.

const_iterator end() const ASIO_NOEXCEPT

{

return begin() + 1;

}

};

#endif // !defined(ASIO_NO_DEPRECATED)

/// (Deprecated: Use the socket/descriptor wait() and async_wait() member

/// functions.) An implementation of both the ConstBufferSequence and

/// MutableBufferSequence concepts to represent a null buffer sequence.

class null_buffers

{

public:

/// The type for each element in the list of buffers.

typedef mutable_buffer value_type;

/// A random-access iterator type that may be used to read elements.

typedef const mutable_buffer* const_iterator;

/// Get a random-access iterator to the first element.

const_iterator begin() const ASIO_NOEXCEPT

{

return &buf_;

}

/// Get a random-access iterator for one past the last element.

const_iterator end() const ASIO_NOEXCEPT

{

return &buf_;

}

private:

mutable_buffer buf_;

};

/** @defgroup buffer_sequence_begin asio::buffer_sequence_begin

*

* @brief The asio::buffer_sequence_begin function returns an iterator

* pointing to the first element in a buffer sequence.

*/

/*@{*/

/// Get an iterator to the first element in a buffer sequence.

template <typename MutableBuffer>

inline const mutable_buffer* buffer_sequence_begin(const MutableBuffer& b,

typename constraint<

is_convertible<const MutableBuffer*, const mutable_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return static_cast<const mutable_buffer*>(detail::addressof(b));

}

/// Get an iterator to the first element in a buffer sequence.

template <typename ConstBuffer>

inline const const_buffer* buffer_sequence_begin(const ConstBuffer& b,

typename constraint<

is_convertible<const ConstBuffer*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return static_cast<const const_buffer*>(detail::addressof(b));

}

#if defined(ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)

/// Get an iterator to the first element in a buffer sequence.

template <typename C>

inline auto buffer_sequence_begin(C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT -> decltype(c.begin())

{

return c.begin();

}

/// Get an iterator to the first element in a buffer sequence.

template <typename C>

inline auto buffer_sequence_begin(const C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT -> decltype(c.begin())

{

return c.begin();

}

#else // defined(ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)

template <typename C>

inline typename C::iterator buffer_sequence_begin(C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return c.begin();

}

template <typename C>

inline typename C::const_iterator buffer_sequence_begin(const C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return c.begin();

}

#endif // defined(ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)

/*@}*/

/** @defgroup buffer_sequence_end asio::buffer_sequence_end

*

* @brief The asio::buffer_sequence_end function returns an iterator

* pointing to one past the end element in a buffer sequence.

*/

/*@{*/

/// Get an iterator to one past the end element in a buffer sequence.

template <typename MutableBuffer>

inline const mutable_buffer* buffer_sequence_end(const MutableBuffer& b,

typename constraint<

is_convertible<const MutableBuffer*, const mutable_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return static_cast<const mutable_buffer*>(detail::addressof(b)) + 1;

}

/// Get an iterator to one past the end element in a buffer sequence.

template <typename ConstBuffer>

inline const const_buffer* buffer_sequence_end(const ConstBuffer& b,

typename constraint<

is_convertible<const ConstBuffer*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return static_cast<const const_buffer*>(detail::addressof(b)) + 1;

}

#if defined(ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)

/// Get an iterator to one past the end element in a buffer sequence.

template <typename C>

inline auto buffer_sequence_end(C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT -> decltype(c.end())

{

return c.end();

}

/// Get an iterator to one past the end element in a buffer sequence.

template <typename C>

inline auto buffer_sequence_end(const C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT -> decltype(c.end())

{

return c.end();

}

#else // defined(ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)

template <typename C>

inline typename C::iterator buffer_sequence_end(C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return c.end();

}

template <typename C>

inline typename C::const_iterator buffer_sequence_end(const C& c,

typename constraint<

!is_convertible<const C*, const mutable_buffer*>::value

&& !is_convertible<const C*, const const_buffer*>::value

>::type = 0) ASIO_NOEXCEPT

{

return c.end();

}

#endif // defined(ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)

/*@}*/

namespace detail {

// Tag types used to select appropriately optimised overloads.

struct one_buffer {};

struct multiple_buffers {};

// Helper trait to detect single buffers.

template <typename BufferSequence>

struct buffer_sequence_cardinality :

conditional<

is_same<BufferSequence, mutable_buffer>::value

#if !defined(ASIO_NO_DEPRECATED)

|| is_same<BufferSequence, mutable_buffers_1>::value

|| is_same<BufferSequence, const_buffers_1>::value

#endif // !defined(ASIO_NO_DEPRECATED)

|| is_same<BufferSequence, const_buffer>::value,

one_buffer, multiple_buffers>::type {};

template <typename Iterator>

inline std::size_t buffer_size(one_buffer,

Iterator begin, Iterator) ASIO_NOEXCEPT

{

return const_buffer(*begin).size();

}

template <typename Iterator>

inline std::size_t buffer_size(multiple_buffers,

Iterator begin, Iterator end) ASIO_NOEXCEPT

{

std::size_t total_buffer_size = 0;

Iterator iter = begin;

for (; iter != end; ++iter)

{

const_buffer b(*iter);

total_buffer_size += b.size();

}

return total_buffer_size;

}

} // namespace detail

/// Get the total number of bytes in a buffer sequence.

/**

* The @c buffer_size function determines the total size of all buffers in the

* buffer sequence, as if computed as follows:

*

* @code size_t total_size = 0;

* auto i = asio::buffer_sequence_begin(buffers);

* auto end = asio::buffer_sequence_end(buffers);

* for (; i != end; ++i)

* {

* const_buffer b(*i);

* total_size += b.size();

* }

* return total_size; @endcode

*

* The @c BufferSequence template parameter may meet either of the @c

* ConstBufferSequence or @c MutableBufferSequence type requirements.

*/

template <typename BufferSequence>

inline std::size_t buffer_size(const BufferSequence& b) ASIO_NOEXCEPT

{

return detail::buffer_size(

detail::buffer_sequence_cardinality<BufferSequence>(),

asio::buffer_sequence_begin(b),

asio::buffer_sequence_end(b));

}

#if !defined(ASIO_NO_DEPRECATED)

/** @defgroup buffer_cast asio::buffer_cast

*

* @brief (Deprecated: Use the @c data() member function.) The

* asio::buffer_cast function is used to obtain a pointer to the

* underlying memory region associated with a buffer.

*

* @par Examples:

*

* To access the memory of a non-modifiable buffer, use:

* @code asio::const_buffer b1 = ...;

* const unsigned char* p1 = asio::buffer_cast<const unsigned char*>(b1);

* @endcode

*

* To access the memory of a modifiable buffer, use:

* @code asio::mutable_buffer b2 = ...;

* unsigned char* p2 = asio::buffer_cast<unsigned char*>(b2);

* @endcode

*

* The asio::buffer_cast function permits violations of type safety, so

* uses of it in application code should be carefully considered.

*/

/*@{*/

/// Cast a non-modifiable buffer to a specified pointer to POD type.

template <typename PointerToPodType>

inline PointerToPodType buffer_cast(const mutable_buffer& b) ASIO_NOEXCEPT

{

return static_cast<PointerToPodType>(b.data());

}

/// Cast a non-modifiable buffer to a specified pointer to POD type.

template <typename PointerToPodType>

inline PointerToPodType buffer_cast(const const_buffer& b) ASIO_NOEXCEPT

{

return static_cast<PointerToPodType>(b.data());

}

/*@}*/

#endif // !defined(ASIO_NO_DEPRECATED)

/// Create a new modifiable buffer that is offset from the start of another.

/**

* @relates mutable_buffer

*/

inline mutable_buffer operator+(const mutable_buffer& b,

std::size_t n) ASIO_NOEXCEPT

{

std::size_t offset = n < b.size() ? n : b.size();

char* new_data = static_cast<char*>(b.data()) + offset;

std::size_t new_size = b.size() - offset;

return mutable_buffer(new_data, new_size

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

, b.get_debug_check()

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

);

}

/// Create a new modifiable buffer that is offset from the start of another.

/**

* @relates mutable_buffer

*/

inline mutable_buffer operator+(std::size_t n,

const mutable_buffer& b) ASIO_NOEXCEPT

{

return b + n;

}

/// Create a new non-modifiable buffer that is offset from the start of another.

/**

* @relates const_buffer

*/

inline const_buffer operator+(const const_buffer& b,

std::size_t n) ASIO_NOEXCEPT

{

std::size_t offset = n < b.size() ? n : b.size();

const char* new_data = static_cast<const char*>(b.data()) + offset;

std::size_t new_size = b.size() - offset;

return const_buffer(new_data, new_size

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

, b.get_debug_check()

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

);

}

/// Create a new non-modifiable buffer that is offset from the start of another.

/**

* @relates const_buffer

*/

inline const_buffer operator+(std::size_t n,

const const_buffer& b) ASIO_NOEXCEPT

{

return b + n;

}

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

namespace detail {

template <typename Iterator>

class buffer_debug_check

{

public:

buffer_debug_check(Iterator iter)

: iter_(iter)

{

}

~buffer_debug_check()

{

#if defined(ASIO_MSVC) && (ASIO_MSVC == 1400)

// MSVC 8's string iterator checking may crash in a std::string::iterator

// object's destructor when the iterator points to an already-destroyed

// std::string object, unless the iterator is cleared first.

iter_ = Iterator();

#endif // defined(ASIO_MSVC) && (ASIO_MSVC == 1400)

}

void operator()()

{

(void)*iter_;

}

private:

Iterator iter_;

};

} // namespace detail

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

/** @defgroup buffer asio::buffer

*

* @brief The 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 <tt>{void*,

* size_t}</tt> specifies a mutable (modifiable) region of memory. Similarly, a

* tuple of the form <tt>{const void*, size_t}</tt> 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:

*

* @code sock.send(asio::buffer(data, size)); @endcode

*

* In the above example, the return value of 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:

*

* @code char d1[128];

* size_t bytes_transferred = sock.receive(asio::buffer(d1));

*

* std::vector<char> d2(128);

* bytes_transferred = sock.receive(asio::buffer(d2));

*

* std::array<char, 128> d3;

* bytes_transferred = sock.receive(asio::buffer(d3));

*

* boost::array<char, 128> d4;

* bytes_transferred = sock.receive(asio::buffer(d4)); @endcode

*

* In all three cases above, the buffers created are exactly 128 bytes long.

* Note that a vector is @e never automatically resized when creating or using

* a buffer. The buffer size is determined using the vector's <tt>size()</tt>

* member function, and not its capacity.

*

* @par Accessing Buffer Contents

*

* The contents of a buffer may be accessed using the @c data() and @c size()

* member functions:

*

* @code asio::mutable_buffer b1 = ...;

* std::size_t s1 = b1.size();

* unsigned char* p1 = static_cast<unsigned char*>(b1.data());

*

* asio::const_buffer b2 = ...;

* std::size_t s2 = b2.size();

* const void* p2 = b2.data(); @endcode

*

* The @c data() member function permits violations of type safety, so

* uses of it in application code should be carefully considered.

*

* For convenience, a @ref buffer_size function is provided that works with

* both buffers and 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.

*

* @par Buffer Copying

*

* The @ref buffer_copy function may be used to copy raw bytes between

* individual buffers and buffer sequences.

*

* In particular, when used with the @ref buffer_size function, the @ref

* buffer_copy function can be used to linearise a sequence of buffers. For

* example:

*

* @code vector<const_buffer> buffers = ...;

*

* vector<unsigned char> data(asio::buffer_size(buffers));

* asio::buffer_copy(asio::buffer(data), buffers); @endcode

*

* Note that @ref buffer_copy is implemented in terms of @c memcpy, and

* consequently it cannot be used to copy between overlapping memory regions.

*

* @par 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 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 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).

*

* @par 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:

*

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

*

* A buffer object @c b1 created using:

*

* @code b1 = asio::buffer(a); @endcode

*

* represents the entire array, <tt>{ 'a', 'b', 'c', 'd', 'e' }</tt>. An

* optional second argument to the asio::buffer function may be used to

* limit the size, in bytes, of the buffer:

*

* @code b2 = asio::buffer(a, 3); @endcode

*

* such that @c b2 represents the data <tt>{ 'a', 'b', 'c' }</tt>. 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:

*

* @code b3 = b1 + 2; @endcode

*

* where @c b3 will set to represent <tt>{ 'c', 'd', 'e' }</tt>. 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:

*

* @code b4 = asio::buffer(b1 + 1, 3); @endcode

*

* so that @c b4 will refer to the bytes <tt>{ 'b', 'c', 'd' }</tt>.

*

* @par 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:

*

* @code

* char d1[128];

* std::vector<char> d2(128);

* boost::array<char, 128> d3;

*

* boost::array<mutable_buffer, 3> bufs1 = {

* asio::buffer(d1),

* asio::buffer(d2),

* asio::buffer(d3) };

* bytes_transferred = sock.receive(bufs1);

*

* std::vector<const_buffer> bufs2;

* bufs2.push_back(asio::buffer(d1));

* bufs2.push_back(asio::buffer(d2));

* bufs2.push_back(asio::buffer(d3));

* bytes_transferred = sock.send(bufs2); @endcode

*/

/*@{*/

#if defined(ASIO_NO_DEPRECATED) || defined(GENERATING_DOCUMENTATION)

# define ASIO_MUTABLE_BUFFER mutable_buffer

# define ASIO_CONST_BUFFER const_buffer

#else // defined(ASIO_NO_DEPRECATED) || defined(GENERATING_DOCUMENTATION)

# define ASIO_MUTABLE_BUFFER mutable_buffers_1

# define ASIO_CONST_BUFFER const_buffers_1

#endif // defined(ASIO_NO_DEPRECATED) || defined(GENERATING_DOCUMENTATION)

/// Create a new modifiable buffer from an existing buffer.

/**

* @returns <tt>mutable_buffer(b)</tt>.

*/

inline ASIO_MUTABLE_BUFFER buffer(

const mutable_buffer& b) ASIO_NOEXCEPT

{

return ASIO_MUTABLE_BUFFER(b);

}

/// Create a new modifiable buffer from an existing buffer.

/**

* @returns A mutable_buffer value equivalent to:

* @code mutable_buffer(

* b.data(),

* min(b.size(), max_size_in_bytes)); @endcode

*/

inline ASIO_MUTABLE_BUFFER buffer(const mutable_buffer& b,

std::size_t max_size_in_bytes) ASIO_NOEXCEPT

{

return ASIO_MUTABLE_BUFFER(

mutable_buffer(b.data(),

b.size() < max_size_in_bytes

? b.size() : max_size_in_bytes

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

, b.get_debug_check()

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

));

}

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

/**

* @returns <tt>const_buffer(b)</tt>.

*/

inline ASIO_CONST_BUFFER buffer(

const const_buffer& b) ASIO_NOEXCEPT

{

return ASIO_CONST_BUFFER(b);

}

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

/**

* @returns A const_buffer value equivalent to:

* @code const_buffer(

* b.data(),

* min(b.size(), max_size_in_bytes)); @endcode

*/

inline ASIO_CONST_BUFFER buffer(const const_buffer& b,

std::size_t max_size_in_bytes) ASIO_NOEXCEPT

{

return ASIO_CONST_BUFFER(b.data(),

b.size() < max_size_in_bytes

? b.size() : max_size_in_bytes

#if defined(ASIO_ENABLE_BUFFER_DEBUGGING)

, b.get_debug_check()

#endif // ASIO_ENABLE_BUFFER_DEBUGGING

);

}

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

/**

* @returns <tt>mutable_buffer(data, size_in_bytes)</tt>.

*/

inline ASIO_MUTABLE_BUFFER buffer(void* data,

std::size_t size_in_bytes) ASIO_NOEXCEPT

{

return ASIO_MUTABLE_BUFFER(data, size_in_bytes);

}

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

/**

* @returns <tt>const_buffer(data, size_in_bytes)</tt>.

*/

inline ASIO_CONST_BUFFER buffer(const void* data,

std::size_t size_in_bytes) ASIO_NOEXCEPT

{

return ASIO_CONST_BUFFER(data, size_in_bytes);

}

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

/**

* @returns A mutable_buffer value equivalent to:

* @code mutable_buffer(

* static_cast<void*>(data),

* N * sizeof(PodType)); @endcode

*/

template <typename PodType, std::size_t N>

inline ASIO_MUTABLE_BUFFER buffer(PodType (&data)[N]) ASIO_NOEXCEPT

{

return ASIO_MUTABLE_BUFFER(data, N * sizeof(PodType));

}

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

/**

* @returns A mutable_buffer value equivalent to:

* @code mutable_buffer(