Clarify that buffer_copy does not support overlapping memory regions.

Fixes boost trac ticket #8295.

asio/include/asio/buffer.hpp

diff --git a/asio/include/asio/buffer.hpp b/asio/include/asio/buffer.hpp
index db271bd..afd5d04 100644
--- a/asio/include/asio/buffer.hpp
+++ b/asio/include/asio/buffer.hpp
@@ -617,6 +617,9 @@
  * 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
@@ -1264,6 +1267,9 @@
  *
  * This prevents buffer overflow, regardless of the buffer sizes used in the
  * copy operation.
+ *
+ * Note that @ref buffer_copy is implemented in terms of @c memcpy, and
+ * consequently it cannot be used to copy between overlapping memory regions.
  */
 /*@{*/
 
@@ -1282,6 +1288,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const const_buffer& source)
@@ -1309,6 +1318,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const const_buffers_1& source)
@@ -1332,6 +1344,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const mutable_buffer& source)
@@ -1355,6 +1370,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const mutable_buffers_1& source)
@@ -1377,6 +1395,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename ConstBufferSequence>
 std::size_t buffer_copy(const mutable_buffer& target,
@@ -1414,6 +1435,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const const_buffer& source)
@@ -1436,6 +1460,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const const_buffers_1& source)
@@ -1460,6 +1487,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const mutable_buffer& source)
@@ -1484,6 +1514,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const mutable_buffers_1& source)
@@ -1507,6 +1540,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename ConstBufferSequence>
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
@@ -1530,6 +1566,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -1567,6 +1606,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 inline std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -1591,6 +1633,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 inline std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -1615,6 +1660,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 inline std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -1638,6 +1686,9 @@
  * @li @c buffer_size(target)
  *
  * @li @c buffer_size(source)
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence, typename ConstBufferSequence>
 std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -1703,6 +1754,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const const_buffer& source, std::size_t max_bytes_to_copy)
@@ -1729,6 +1783,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const const_buffers_1& source, std::size_t max_bytes_to_copy)
@@ -1756,6 +1813,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const mutable_buffer& source, std::size_t max_bytes_to_copy)
@@ -1783,6 +1843,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffer& target,
     const mutable_buffers_1& source, std::size_t max_bytes_to_copy)
@@ -1810,6 +1873,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename ConstBufferSequence>
 inline std::size_t buffer_copy(const mutable_buffer& target,
@@ -1837,6 +1903,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const const_buffer& source, std::size_t max_bytes_to_copy)
@@ -1863,6 +1932,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const const_buffers_1& source, std::size_t max_bytes_to_copy)
@@ -1890,6 +1962,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const mutable_buffer& source, std::size_t max_bytes_to_copy)
@@ -1917,6 +1992,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
     const mutable_buffers_1& source, std::size_t max_bytes_to_copy)
@@ -1944,6 +2022,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename ConstBufferSequence>
 inline std::size_t buffer_copy(const mutable_buffers_1& target,
@@ -1972,6 +2053,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 inline std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -2000,6 +2084,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 inline std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -2029,6 +2116,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 inline std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -2058,6 +2148,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence>
 inline std::size_t buffer_copy(const MutableBufferSequence& target,
@@ -2086,6 +2179,9 @@
  * @li @c buffer_size(source)
  *
  * @li @c max_bytes_to_copy
+ *
+ * This function is implemented in terms of @c memcpy, and consequently it
+ * cannot be used to copy between overlapping memory regions.
  */
 template <typename MutableBufferSequence, typename ConstBufferSequence>
 std::size_t buffer_copy(const MutableBufferSequence& target,