5 // Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com)
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
11 #ifndef BOOST_ASIO_BUFFER_HPP
12 #define BOOST_ASIO_BUFFER_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
25 #include <boost/asio/detail/array_fwd.hpp>
26 #include <boost/asio/detail/is_buffer_sequence.hpp>
27 #include <boost/asio/detail/string_view.hpp>
28 #include <boost/asio/detail/throw_exception.hpp>
29 #include <boost/asio/detail/type_traits.hpp>
31 #if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1700)
32 # if defined(_HAS_ITERATOR_DEBUGGING) && (_HAS_ITERATOR_DEBUGGING != 0)
33 # if !defined(BOOST_ASIO_DISABLE_BUFFER_DEBUGGING)
34 # define BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
35 # endif // !defined(BOOST_ASIO_DISABLE_BUFFER_DEBUGGING)
36 # endif // defined(_HAS_ITERATOR_DEBUGGING)
37 #endif // defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1700)
40 # if defined(_GLIBCXX_DEBUG)
41 # if !defined(BOOST_ASIO_DISABLE_BUFFER_DEBUGGING)
42 # define BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
43 # endif // !defined(BOOST_ASIO_DISABLE_BUFFER_DEBUGGING)
44 # endif // defined(_GLIBCXX_DEBUG)
45 #endif // defined(__GNUC__)
47 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
48 # include <boost/asio/detail/functional.hpp>
49 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
51 #if defined(BOOST_ASIO_HAS_BOOST_WORKAROUND)
52 # include <boost/detail/workaround.hpp>
53 # if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x582)) \
54 || BOOST_WORKAROUND(__SUNPRO_CC, BOOST_TESTED_AT(0x590))
55 # define BOOST_ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND
56 # endif // BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x582))
57 // || BOOST_WORKAROUND(__SUNPRO_CC, BOOST_TESTED_AT(0x590))
58 #endif // defined(BOOST_ASIO_HAS_BOOST_WORKAROUND)
60 #if defined(BOOST_ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND)
61 # include <boost/asio/detail/type_traits.hpp>
62 #endif // defined(BOOST_ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND)
64 #include <boost/asio/detail/push_options.hpp>
72 /// Holds a buffer that can be modified.
74 * The mutable_buffer class provides a safe representation of a buffer that can
75 * be modified. It does not own the underlying data, and so is cheap to copy or
78 * @par Accessing Buffer Contents
80 * The contents of a buffer may be accessed using the @c data() and @c size()
83 * @code boost::asio::mutable_buffer b1 = ...;
84 * std::size_t s1 = b1.size();
85 * unsigned char* p1 = static_cast<unsigned char*>(b1.data());
88 * The @c data() member function permits violations of type safety, so uses of
89 * it in application code should be carefully considered.
94 /// Construct an empty buffer.
95 mutable_buffer() BOOST_ASIO_NOEXCEPT
101 /// Construct a buffer to represent a given memory range.
102 mutable_buffer(void* data, std::size_t size) BOOST_ASIO_NOEXCEPT
108 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
109 mutable_buffer(void* data, std::size_t size,
110 boost::asio::detail::function<void()> debug_check)
113 debug_check_(debug_check)
117 const boost::asio::detail::function<void()>& get_debug_check() const
121 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
123 /// Get a pointer to the beginning of the memory range.
124 void* data() const BOOST_ASIO_NOEXCEPT
126 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
127 if (size_ && debug_check_)
129 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
133 /// Get the size of the memory range.
134 std::size_t size() const BOOST_ASIO_NOEXCEPT
139 /// Move the start of the buffer by the specified number of bytes.
140 mutable_buffer& operator+=(std::size_t n) BOOST_ASIO_NOEXCEPT
142 std::size_t offset = n < size_ ? n : size_;
143 data_ = static_cast<char*>(data_) + offset;
152 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
153 boost::asio::detail::function<void()> debug_check_;
154 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
157 #if !defined(BOOST_ASIO_NO_DEPRECATED)
159 /// (Deprecated: Use mutable_buffer.) Adapts a single modifiable buffer so that
160 /// it meets the requirements of the MutableBufferSequence concept.
161 class mutable_buffers_1
162 : public mutable_buffer
165 /// The type for each element in the list of buffers.
166 typedef mutable_buffer value_type;
168 /// A random-access iterator type that may be used to read elements.
169 typedef const mutable_buffer* const_iterator;
171 /// Construct to represent a given memory range.
172 mutable_buffers_1(void* data, std::size_t size) BOOST_ASIO_NOEXCEPT
173 : mutable_buffer(data, size)
177 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
178 mutable_buffers_1(void* data, std::size_t size,
179 boost::asio::detail::function<void()> debug_check)
180 : mutable_buffer(data, size, debug_check)
183 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
185 /// Construct to represent a single modifiable buffer.
186 explicit mutable_buffers_1(const mutable_buffer& b) BOOST_ASIO_NOEXCEPT
191 /// Get a random-access iterator to the first element.
192 const_iterator begin() const BOOST_ASIO_NOEXCEPT
197 /// Get a random-access iterator for one past the last element.
198 const_iterator end() const BOOST_ASIO_NOEXCEPT
204 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
206 /// Holds a buffer that cannot be modified.
208 * The const_buffer class provides a safe representation of a buffer that cannot
209 * be modified. It does not own the underlying data, and so is cheap to copy or
212 * @par Accessing Buffer Contents
214 * The contents of a buffer may be accessed using the @c data() and @c size()
217 * @code boost::asio::const_buffer b1 = ...;
218 * std::size_t s1 = b1.size();
219 * const unsigned char* p1 = static_cast<const unsigned char*>(b1.data());
222 * The @c data() member function permits violations of type safety, so uses of
223 * it in application code should be carefully considered.
228 /// Construct an empty buffer.
229 const_buffer() BOOST_ASIO_NOEXCEPT
235 /// Construct a buffer to represent a given memory range.
236 const_buffer(const void* data, std::size_t size) BOOST_ASIO_NOEXCEPT
242 /// Construct a non-modifiable buffer from a modifiable one.
243 const_buffer(const mutable_buffer& b) BOOST_ASIO_NOEXCEPT
246 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
247 , debug_check_(b.get_debug_check())
248 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
252 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
253 const_buffer(const void* data, std::size_t size,
254 boost::asio::detail::function<void()> debug_check)
257 debug_check_(debug_check)
261 const boost::asio::detail::function<void()>& get_debug_check() const
265 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
267 /// Get a pointer to the beginning of the memory range.
268 const void* data() const BOOST_ASIO_NOEXCEPT
270 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
271 if (size_ && debug_check_)
273 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
277 /// Get the size of the memory range.
278 std::size_t size() const BOOST_ASIO_NOEXCEPT
283 /// Move the start of the buffer by the specified number of bytes.
284 const_buffer& operator+=(std::size_t n) BOOST_ASIO_NOEXCEPT
286 std::size_t offset = n < size_ ? n : size_;
287 data_ = static_cast<const char*>(data_) + offset;
296 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
297 boost::asio::detail::function<void()> debug_check_;
298 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
301 #if !defined(BOOST_ASIO_NO_DEPRECATED)
303 /// (Deprecated: Use const_buffer.) Adapts a single non-modifiable buffer so
304 /// that it meets the requirements of the ConstBufferSequence concept.
305 class const_buffers_1
306 : public const_buffer
309 /// The type for each element in the list of buffers.
310 typedef const_buffer value_type;
312 /// A random-access iterator type that may be used to read elements.
313 typedef const const_buffer* const_iterator;
315 /// Construct to represent a given memory range.
316 const_buffers_1(const void* data, std::size_t size) BOOST_ASIO_NOEXCEPT
317 : const_buffer(data, size)
321 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
322 const_buffers_1(const void* data, std::size_t size,
323 boost::asio::detail::function<void()> debug_check)
324 : const_buffer(data, size, debug_check)
327 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
329 /// Construct to represent a single non-modifiable buffer.
330 explicit const_buffers_1(const const_buffer& b) BOOST_ASIO_NOEXCEPT
335 /// Get a random-access iterator to the first element.
336 const_iterator begin() const BOOST_ASIO_NOEXCEPT
341 /// Get a random-access iterator for one past the last element.
342 const_iterator end() const BOOST_ASIO_NOEXCEPT
348 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
350 /// Trait to determine whether a type satisfies the MutableBufferSequence
352 template <typename T>
353 struct is_mutable_buffer_sequence
354 #if defined(GENERATING_DOCUMENTATION)
355 : integral_constant<bool, automatically_determined>
356 #else // defined(GENERATING_DOCUMENTATION)
357 : boost::asio::detail::is_buffer_sequence<T, mutable_buffer>
358 #endif // defined(GENERATING_DOCUMENTATION)
362 /// Trait to determine whether a type satisfies the ConstBufferSequence
364 template <typename T>
365 struct is_const_buffer_sequence
366 #if defined(GENERATING_DOCUMENTATION)
367 : integral_constant<bool, automatically_determined>
368 #else // defined(GENERATING_DOCUMENTATION)
369 : boost::asio::detail::is_buffer_sequence<T, const_buffer>
370 #endif // defined(GENERATING_DOCUMENTATION)
374 /// Trait to determine whether a type satisfies the DynamicBuffer requirements.
375 template <typename T>
376 struct is_dynamic_buffer
377 #if defined(GENERATING_DOCUMENTATION)
378 : integral_constant<bool, automatically_determined>
379 #else // defined(GENERATING_DOCUMENTATION)
380 : boost::asio::detail::is_dynamic_buffer<T>
381 #endif // defined(GENERATING_DOCUMENTATION)
385 /// (Deprecated: Use the socket/descriptor wait() and async_wait() member
386 /// functions.) An implementation of both the ConstBufferSequence and
387 /// MutableBufferSequence concepts to represent a null buffer sequence.
391 /// The type for each element in the list of buffers.
392 typedef mutable_buffer value_type;
394 /// A random-access iterator type that may be used to read elements.
395 typedef const mutable_buffer* const_iterator;
397 /// Get a random-access iterator to the first element.
398 const_iterator begin() const BOOST_ASIO_NOEXCEPT
403 /// Get a random-access iterator for one past the last element.
404 const_iterator end() const BOOST_ASIO_NOEXCEPT
413 /** @defgroup buffer_sequence_begin boost::asio::buffer_sequence_begin
415 * @brief The boost::asio::buffer_sequence_begin function returns an iterator
416 * pointing to the first element in a buffer sequence.
420 /// Get an iterator to the first element in a buffer sequence.
421 inline const mutable_buffer* buffer_sequence_begin(const mutable_buffer& b)
426 /// Get an iterator to the first element in a buffer sequence.
427 inline const const_buffer* buffer_sequence_begin(const const_buffer& b)
432 #if defined(BOOST_ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)
434 /// Get an iterator to the first element in a buffer sequence.
435 template <typename C>
436 inline auto buffer_sequence_begin(C& c) -> decltype(c.begin())
441 /// Get an iterator to the first element in a buffer sequence.
442 template <typename C>
443 inline auto buffer_sequence_begin(const C& c) -> decltype(c.begin())
448 #else // defined(BOOST_ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)
450 template <typename C>
451 inline typename C::iterator buffer_sequence_begin(C& c)
456 template <typename C>
457 inline typename C::const_iterator buffer_sequence_begin(const C& c)
462 #endif // defined(BOOST_ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)
466 /** @defgroup buffer_sequence_end boost::asio::buffer_sequence_end
468 * @brief The boost::asio::buffer_sequence_end function returns an iterator
469 * pointing to one past the end element in a buffer sequence.
473 /// Get an iterator to one past the end element in a buffer sequence.
474 inline const mutable_buffer* buffer_sequence_end(const mutable_buffer& b)
479 /// Get an iterator to one past the end element in a buffer sequence.
480 inline const const_buffer* buffer_sequence_end(const const_buffer& b)
485 #if defined(BOOST_ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)
487 /// Get an iterator to one past the end element in a buffer sequence.
488 template <typename C>
489 inline auto buffer_sequence_end(C& c) -> decltype(c.end())
494 /// Get an iterator to one past the end element in a buffer sequence.
495 template <typename C>
496 inline auto buffer_sequence_end(const C& c) -> decltype(c.end())
501 #else // defined(BOOST_ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)
503 template <typename C>
504 inline typename C::iterator buffer_sequence_end(C& c)
509 template <typename C>
510 inline typename C::const_iterator buffer_sequence_end(const C& c)
515 #endif // defined(BOOST_ASIO_HAS_DECLTYPE) || defined(GENERATING_DOCUMENTATION)
521 // Tag types used to select appropriately optimised overloads.
522 struct one_buffer {};
523 struct multiple_buffers {};
525 // Helper trait to detect single buffers.
526 template <typename BufferSequence>
527 struct buffer_sequence_cardinality :
529 is_same<BufferSequence, mutable_buffer>::value
530 #if !defined(BOOST_ASIO_NO_DEPRECATED)
531 || is_same<BufferSequence, mutable_buffers_1>::value
532 || is_same<BufferSequence, const_buffers_1>::value
533 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
534 || is_same<BufferSequence, const_buffer>::value,
535 one_buffer, multiple_buffers>::type {};
537 template <typename Iterator>
538 inline std::size_t buffer_size(one_buffer,
539 Iterator begin, Iterator) BOOST_ASIO_NOEXCEPT
541 return const_buffer(*begin).size();
544 template <typename Iterator>
545 inline std::size_t buffer_size(multiple_buffers,
546 Iterator begin, Iterator end) BOOST_ASIO_NOEXCEPT
548 std::size_t total_buffer_size = 0;
550 Iterator iter = begin;
551 for (; iter != end; ++iter)
553 const_buffer b(*iter);
554 total_buffer_size += b.size();
557 return total_buffer_size;
560 } // namespace detail
562 /// Get the total number of bytes in a buffer sequence.
564 * The @c buffer_size function determines the total size of all buffers in the
565 * buffer sequence, as if computed as follows:
567 * @code size_t total_size = 0;
568 * auto i = boost::asio::buffer_sequence_begin(buffers);
569 * auto end = boost::asio::buffer_sequence_end(buffers);
570 * for (; i != end; ++i)
572 * const_buffer b(*i);
573 * total_size += b.size();
575 * return total_size; @endcode
577 * The @c BufferSequence template parameter may meet either of the @c
578 * ConstBufferSequence or @c MutableBufferSequence type requirements.
580 template <typename BufferSequence>
581 inline std::size_t buffer_size(const BufferSequence& b) BOOST_ASIO_NOEXCEPT
583 return detail::buffer_size(
584 detail::buffer_sequence_cardinality<BufferSequence>(),
585 boost::asio::buffer_sequence_begin(b),
586 boost::asio::buffer_sequence_end(b));
589 #if !defined(BOOST_ASIO_NO_DEPRECATED)
591 /** @defgroup buffer_cast boost::asio::buffer_cast
593 * @brief (Deprecated: Use the @c data() member function.) The
594 * boost::asio::buffer_cast function is used to obtain a pointer to the
595 * underlying memory region associated with a buffer.
599 * To access the memory of a non-modifiable buffer, use:
600 * @code boost::asio::const_buffer b1 = ...;
601 * const unsigned char* p1 = boost::asio::buffer_cast<const unsigned char*>(b1);
604 * To access the memory of a modifiable buffer, use:
605 * @code boost::asio::mutable_buffer b2 = ...;
606 * unsigned char* p2 = boost::asio::buffer_cast<unsigned char*>(b2);
609 * The boost::asio::buffer_cast function permits violations of type safety, so
610 * uses of it in application code should be carefully considered.
614 /// Cast a non-modifiable buffer to a specified pointer to POD type.
615 template <typename PointerToPodType>
616 inline PointerToPodType buffer_cast(const mutable_buffer& b) BOOST_ASIO_NOEXCEPT
618 return static_cast<PointerToPodType>(b.data());
621 /// Cast a non-modifiable buffer to a specified pointer to POD type.
622 template <typename PointerToPodType>
623 inline PointerToPodType buffer_cast(const const_buffer& b) BOOST_ASIO_NOEXCEPT
625 return static_cast<PointerToPodType>(b.data());
630 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
632 /// Create a new modifiable buffer that is offset from the start of another.
634 * @relates mutable_buffer
636 inline mutable_buffer operator+(const mutable_buffer& b,
637 std::size_t n) BOOST_ASIO_NOEXCEPT
639 std::size_t offset = n < b.size() ? n : b.size();
640 char* new_data = static_cast<char*>(b.data()) + offset;
641 std::size_t new_size = b.size() - offset;
642 return mutable_buffer(new_data, new_size
643 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
644 , b.get_debug_check()
645 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
649 /// Create a new modifiable buffer that is offset from the start of another.
651 * @relates mutable_buffer
653 inline mutable_buffer operator+(std::size_t n,
654 const mutable_buffer& b) BOOST_ASIO_NOEXCEPT
659 /// Create a new non-modifiable buffer that is offset from the start of another.
661 * @relates const_buffer
663 inline const_buffer operator+(const const_buffer& b,
664 std::size_t n) BOOST_ASIO_NOEXCEPT
666 std::size_t offset = n < b.size() ? n : b.size();
667 const char* new_data = static_cast<const char*>(b.data()) + offset;
668 std::size_t new_size = b.size() - offset;
669 return const_buffer(new_data, new_size
670 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
671 , b.get_debug_check()
672 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
676 /// Create a new non-modifiable buffer that is offset from the start of another.
678 * @relates const_buffer
680 inline const_buffer operator+(std::size_t n,
681 const const_buffer& b) BOOST_ASIO_NOEXCEPT
686 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
689 template <typename Iterator>
690 class buffer_debug_check
693 buffer_debug_check(Iterator iter)
698 ~buffer_debug_check()
700 #if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC == 1400)
701 // MSVC 8's string iterator checking may crash in a std::string::iterator
702 // object's destructor when the iterator points to an already-destroyed
703 // std::string object, unless the iterator is cleared first.
705 #endif // defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC == 1400)
717 } // namespace detail
718 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
720 /** @defgroup buffer boost::asio::buffer
722 * @brief The boost::asio::buffer function is used to create a buffer object to
723 * represent raw memory, an array of POD elements, a vector of POD elements,
726 * A buffer object represents a contiguous region of memory as a 2-tuple
727 * consisting of a pointer and size in bytes. A tuple of the form <tt>{void*,
728 * size_t}</tt> specifies a mutable (modifiable) region of memory. Similarly, a
729 * tuple of the form <tt>{const void*, size_t}</tt> specifies a const
730 * (non-modifiable) region of memory. These two forms correspond to the classes
731 * mutable_buffer and const_buffer, respectively. To mirror C++'s conversion
732 * rules, a mutable_buffer is implicitly convertible to a const_buffer, and the
733 * opposite conversion is not permitted.
735 * The simplest use case involves reading or writing a single buffer of a
738 * @code sock.send(boost::asio::buffer(data, size)); @endcode
740 * In the above example, the return value of boost::asio::buffer meets the
741 * requirements of the ConstBufferSequence concept so that it may be directly
742 * passed to the socket's write function. A buffer created for modifiable
743 * memory also meets the requirements of the MutableBufferSequence concept.
745 * An individual buffer may be created from a builtin array, std::vector,
746 * std::array or boost::array of POD elements. This helps prevent buffer
747 * overruns by automatically determining the size of the buffer:
749 * @code char d1[128];
750 * size_t bytes_transferred = sock.receive(boost::asio::buffer(d1));
752 * std::vector<char> d2(128);
753 * bytes_transferred = sock.receive(boost::asio::buffer(d2));
755 * std::array<char, 128> d3;
756 * bytes_transferred = sock.receive(boost::asio::buffer(d3));
758 * boost::array<char, 128> d4;
759 * bytes_transferred = sock.receive(boost::asio::buffer(d4)); @endcode
761 * In all three cases above, the buffers created are exactly 128 bytes long.
762 * Note that a vector is @e never automatically resized when creating or using
763 * a buffer. The buffer size is determined using the vector's <tt>size()</tt>
764 * member function, and not its capacity.
766 * @par Accessing Buffer Contents
768 * The contents of a buffer may be accessed using the @c data() and @c size()
771 * @code boost::asio::mutable_buffer b1 = ...;
772 * std::size_t s1 = b1.size();
773 * unsigned char* p1 = static_cast<unsigned char*>(b1.data());
775 * boost::asio::const_buffer b2 = ...;
776 * std::size_t s2 = b2.size();
777 * const void* p2 = b2.data(); @endcode
779 * The @c data() member function permits violations of type safety, so
780 * uses of it in application code should be carefully considered.
782 * For convenience, a @ref buffer_size function is provided that works with
783 * both buffers and buffer sequences (that is, types meeting the
784 * ConstBufferSequence or MutableBufferSequence type requirements). In this
785 * case, the function returns the total size of all buffers in the sequence.
787 * @par Buffer Copying
789 * The @ref buffer_copy function may be used to copy raw bytes between
790 * individual buffers and buffer sequences.
792 * In particular, when used with the @ref buffer_size function, the @ref
793 * buffer_copy function can be used to linearise a sequence of buffers. For
796 * @code vector<const_buffer> buffers = ...;
798 * vector<unsigned char> data(boost::asio::buffer_size(buffers));
799 * boost::asio::buffer_copy(boost::asio::buffer(data), buffers); @endcode
801 * Note that @ref buffer_copy is implemented in terms of @c memcpy, and
802 * consequently it cannot be used to copy between overlapping memory regions.
804 * @par Buffer Invalidation
806 * A buffer object does not have any ownership of the memory it refers to. It
807 * is the responsibility of the application to ensure the memory region remains
808 * valid until it is no longer required for an I/O operation. When the memory
809 * is no longer available, the buffer is said to have been invalidated.
811 * For the boost::asio::buffer overloads that accept an argument of type
812 * std::vector, the buffer objects returned are invalidated by any vector
813 * operation that also invalidates all references, pointers and iterators
814 * referring to the elements in the sequence (C++ Std, 23.2.4)
816 * For the boost::asio::buffer overloads that accept an argument of type
817 * std::basic_string, the buffer objects returned are invalidated according to
818 * the rules defined for invalidation of references, pointers and iterators
819 * referring to elements of the sequence (C++ Std, 21.3).
821 * @par Buffer Arithmetic
823 * Buffer objects may be manipulated using simple arithmetic in a safe way
824 * which helps prevent buffer overruns. Consider an array initialised as
827 * @code boost::array<char, 6> a = { 'a', 'b', 'c', 'd', 'e' }; @endcode
829 * A buffer object @c b1 created using:
831 * @code b1 = boost::asio::buffer(a); @endcode
833 * represents the entire array, <tt>{ 'a', 'b', 'c', 'd', 'e' }</tt>. An
834 * optional second argument to the boost::asio::buffer function may be used to
835 * limit the size, in bytes, of the buffer:
837 * @code b2 = boost::asio::buffer(a, 3); @endcode
839 * such that @c b2 represents the data <tt>{ 'a', 'b', 'c' }</tt>. Even if the
840 * size argument exceeds the actual size of the array, the size of the buffer
841 * object created will be limited to the array size.
843 * An offset may be applied to an existing buffer to create a new one:
845 * @code b3 = b1 + 2; @endcode
847 * where @c b3 will set to represent <tt>{ 'c', 'd', 'e' }</tt>. If the offset
848 * exceeds the size of the existing buffer, the newly created buffer will be
851 * Both an offset and size may be specified to create a buffer that corresponds
852 * to a specific range of bytes within an existing buffer:
854 * @code b4 = boost::asio::buffer(b1 + 1, 3); @endcode
856 * so that @c b4 will refer to the bytes <tt>{ 'b', 'c', 'd' }</tt>.
858 * @par Buffers and Scatter-Gather I/O
860 * To read or write using multiple buffers (i.e. scatter-gather I/O), multiple
861 * buffer objects may be assigned into a container that supports the
862 * MutableBufferSequence (for read) or ConstBufferSequence (for write) concepts:
866 * std::vector<char> d2(128);
867 * boost::array<char, 128> d3;
869 * boost::array<mutable_buffer, 3> bufs1 = {
870 * boost::asio::buffer(d1),
871 * boost::asio::buffer(d2),
872 * boost::asio::buffer(d3) };
873 * bytes_transferred = sock.receive(bufs1);
875 * std::vector<const_buffer> bufs2;
876 * bufs2.push_back(boost::asio::buffer(d1));
877 * bufs2.push_back(boost::asio::buffer(d2));
878 * bufs2.push_back(boost::asio::buffer(d3));
879 * bytes_transferred = sock.send(bufs2); @endcode
883 #if defined(BOOST_ASIO_NO_DEPRECATED) || defined(GENERATING_DOCUMENTATION)
884 # define BOOST_ASIO_MUTABLE_BUFFER mutable_buffer
885 # define BOOST_ASIO_CONST_BUFFER const_buffer
886 #else // defined(BOOST_ASIO_NO_DEPRECATED) || defined(GENERATING_DOCUMENTATION)
887 # define BOOST_ASIO_MUTABLE_BUFFER mutable_buffers_1
888 # define BOOST_ASIO_CONST_BUFFER const_buffers_1
889 #endif // defined(BOOST_ASIO_NO_DEPRECATED) || defined(GENERATING_DOCUMENTATION)
891 /// Create a new modifiable buffer from an existing buffer.
893 * @returns <tt>mutable_buffer(b)</tt>.
895 inline BOOST_ASIO_MUTABLE_BUFFER buffer(
896 const mutable_buffer& b) BOOST_ASIO_NOEXCEPT
898 return BOOST_ASIO_MUTABLE_BUFFER(b);
901 /// Create a new modifiable buffer from an existing buffer.
903 * @returns A mutable_buffer value equivalent to:
904 * @code mutable_buffer(
906 * min(b.size(), max_size_in_bytes)); @endcode
908 inline BOOST_ASIO_MUTABLE_BUFFER buffer(const mutable_buffer& b,
909 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
911 return BOOST_ASIO_MUTABLE_BUFFER(
912 mutable_buffer(b.data(),
913 b.size() < max_size_in_bytes
914 ? b.size() : max_size_in_bytes
915 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
916 , b.get_debug_check()
917 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
921 /// Create a new non-modifiable buffer from an existing buffer.
923 * @returns <tt>const_buffer(b)</tt>.
925 inline BOOST_ASIO_CONST_BUFFER buffer(
926 const const_buffer& b) BOOST_ASIO_NOEXCEPT
928 return BOOST_ASIO_CONST_BUFFER(b);
931 /// Create a new non-modifiable buffer from an existing buffer.
933 * @returns A const_buffer value equivalent to:
934 * @code const_buffer(
936 * min(b.size(), max_size_in_bytes)); @endcode
938 inline BOOST_ASIO_CONST_BUFFER buffer(const const_buffer& b,
939 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
941 return BOOST_ASIO_CONST_BUFFER(b.data(),
942 b.size() < max_size_in_bytes
943 ? b.size() : max_size_in_bytes
944 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
945 , b.get_debug_check()
946 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
950 /// Create a new modifiable buffer that represents the given memory range.
952 * @returns <tt>mutable_buffer(data, size_in_bytes)</tt>.
954 inline BOOST_ASIO_MUTABLE_BUFFER buffer(void* data,
955 std::size_t size_in_bytes) BOOST_ASIO_NOEXCEPT
957 return BOOST_ASIO_MUTABLE_BUFFER(data, size_in_bytes);
960 /// Create a new non-modifiable buffer that represents the given memory range.
962 * @returns <tt>const_buffer(data, size_in_bytes)</tt>.
964 inline BOOST_ASIO_CONST_BUFFER buffer(const void* data,
965 std::size_t size_in_bytes) BOOST_ASIO_NOEXCEPT
967 return BOOST_ASIO_CONST_BUFFER(data, size_in_bytes);
970 /// Create a new modifiable buffer that represents the given POD array.
972 * @returns A mutable_buffer value equivalent to:
973 * @code mutable_buffer(
974 * static_cast<void*>(data),
975 * N * sizeof(PodType)); @endcode
977 template <typename PodType, std::size_t N>
978 inline BOOST_ASIO_MUTABLE_BUFFER buffer(PodType (&data)[N]) BOOST_ASIO_NOEXCEPT
980 return BOOST_ASIO_MUTABLE_BUFFER(data, N * sizeof(PodType));
983 /// Create a new modifiable buffer that represents the given POD array.
985 * @returns A mutable_buffer value equivalent to:
986 * @code mutable_buffer(
987 * static_cast<void*>(data),
988 * min(N * sizeof(PodType), max_size_in_bytes)); @endcode
990 template <typename PodType, std::size_t N>
991 inline BOOST_ASIO_MUTABLE_BUFFER buffer(PodType (&data)[N],
992 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
994 return BOOST_ASIO_MUTABLE_BUFFER(data,
995 N * sizeof(PodType) < max_size_in_bytes
996 ? N * sizeof(PodType) : max_size_in_bytes);
999 /// Create a new non-modifiable buffer that represents the given POD array.
1001 * @returns A const_buffer value equivalent to:
1002 * @code const_buffer(
1003 * static_cast<const void*>(data),
1004 * N * sizeof(PodType)); @endcode
1006 template <typename PodType, std::size_t N>
1007 inline BOOST_ASIO_CONST_BUFFER buffer(
1008 const PodType (&data)[N]) BOOST_ASIO_NOEXCEPT
1010 return BOOST_ASIO_CONST_BUFFER(data, N * sizeof(PodType));
1013 /// Create a new non-modifiable buffer that represents the given POD array.
1015 * @returns A const_buffer value equivalent to:
1016 * @code const_buffer(
1017 * static_cast<const void*>(data),
1018 * min(N * sizeof(PodType), max_size_in_bytes)); @endcode
1020 template <typename PodType, std::size_t N>
1021 inline BOOST_ASIO_CONST_BUFFER buffer(const PodType (&data)[N],
1022 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1024 return BOOST_ASIO_CONST_BUFFER(data,
1025 N * sizeof(PodType) < max_size_in_bytes
1026 ? N * sizeof(PodType) : max_size_in_bytes);
1029 #if defined(BOOST_ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND)
1031 // Borland C++ and Sun Studio think the overloads:
1033 // unspecified buffer(boost::array<PodType, N>& array ...);
1037 // unspecified buffer(boost::array<const PodType, N>& array ...);
1039 // are ambiguous. This will be worked around by using a buffer_types traits
1040 // class that contains typedefs for the appropriate buffer and container
1041 // classes, based on whether PodType is const or non-const.
1045 template <bool IsConst>
1046 struct buffer_types_base;
1049 struct buffer_types_base<false>
1051 typedef mutable_buffer buffer_type;
1052 typedef BOOST_ASIO_MUTABLE_BUFFER container_type;
1056 struct buffer_types_base<true>
1058 typedef const_buffer buffer_type;
1059 typedef BOOST_ASIO_CONST_BUFFER container_type;
1062 template <typename PodType>
1064 : public buffer_types_base<is_const<PodType>::value>
1068 } // namespace detail
1070 template <typename PodType, std::size_t N>
1071 inline typename detail::buffer_types<PodType>::container_type
1072 buffer(boost::array<PodType, N>& data) BOOST_ASIO_NOEXCEPT
1074 typedef typename boost::asio::detail::buffer_types<PodType>::buffer_type
1076 typedef typename boost::asio::detail::buffer_types<PodType>::container_type
1078 return container_type(
1079 buffer_type(data.c_array(), data.size() * sizeof(PodType)));
1082 template <typename PodType, std::size_t N>
1083 inline typename detail::buffer_types<PodType>::container_type
1084 buffer(boost::array<PodType, N>& data,
1085 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1087 typedef typename boost::asio::detail::buffer_types<PodType>::buffer_type
1089 typedef typename boost::asio::detail::buffer_types<PodType>::container_type
1091 return container_type(
1092 buffer_type(data.c_array(),
1093 data.size() * sizeof(PodType) < max_size_in_bytes
1094 ? data.size() * sizeof(PodType) : max_size_in_bytes));
1097 #else // defined(BOOST_ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND)
1099 /// Create a new modifiable buffer that represents the given POD array.
1101 * @returns A mutable_buffer value equivalent to:
1102 * @code mutable_buffer(
1104 * data.size() * sizeof(PodType)); @endcode
1106 template <typename PodType, std::size_t N>
1107 inline BOOST_ASIO_MUTABLE_BUFFER buffer(
1108 boost::array<PodType, N>& data) BOOST_ASIO_NOEXCEPT
1110 return BOOST_ASIO_MUTABLE_BUFFER(
1111 data.c_array(), data.size() * sizeof(PodType));
1114 /// Create a new modifiable buffer that represents the given POD array.
1116 * @returns A mutable_buffer value equivalent to:
1117 * @code mutable_buffer(
1119 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1121 template <typename PodType, std::size_t N>
1122 inline BOOST_ASIO_MUTABLE_BUFFER buffer(boost::array<PodType, N>& data,
1123 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1125 return BOOST_ASIO_MUTABLE_BUFFER(data.c_array(),
1126 data.size() * sizeof(PodType) < max_size_in_bytes
1127 ? data.size() * sizeof(PodType) : max_size_in_bytes);
1130 /// Create a new non-modifiable buffer that represents the given POD array.
1132 * @returns A const_buffer value equivalent to:
1133 * @code const_buffer(
1135 * data.size() * sizeof(PodType)); @endcode
1137 template <typename PodType, std::size_t N>
1138 inline BOOST_ASIO_CONST_BUFFER buffer(
1139 boost::array<const PodType, N>& data) BOOST_ASIO_NOEXCEPT
1141 return BOOST_ASIO_CONST_BUFFER(data.data(), data.size() * sizeof(PodType));
1144 /// Create a new non-modifiable buffer that represents the given POD array.
1146 * @returns A const_buffer value equivalent to:
1147 * @code const_buffer(
1149 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1151 template <typename PodType, std::size_t N>
1152 inline BOOST_ASIO_CONST_BUFFER buffer(boost::array<const PodType, N>& data,
1153 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1155 return BOOST_ASIO_CONST_BUFFER(data.data(),
1156 data.size() * sizeof(PodType) < max_size_in_bytes
1157 ? data.size() * sizeof(PodType) : max_size_in_bytes);
1160 #endif // defined(BOOST_ASIO_ENABLE_ARRAY_BUFFER_WORKAROUND)
1162 /// Create a new non-modifiable buffer that represents the given POD array.
1164 * @returns A const_buffer value equivalent to:
1165 * @code const_buffer(
1167 * data.size() * sizeof(PodType)); @endcode
1169 template <typename PodType, std::size_t N>
1170 inline BOOST_ASIO_CONST_BUFFER buffer(
1171 const boost::array<PodType, N>& data) BOOST_ASIO_NOEXCEPT
1173 return BOOST_ASIO_CONST_BUFFER(data.data(), data.size() * sizeof(PodType));
1176 /// Create a new non-modifiable buffer that represents the given POD array.
1178 * @returns A const_buffer value equivalent to:
1179 * @code const_buffer(
1181 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1183 template <typename PodType, std::size_t N>
1184 inline BOOST_ASIO_CONST_BUFFER buffer(const boost::array<PodType, N>& data,
1185 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1187 return BOOST_ASIO_CONST_BUFFER(data.data(),
1188 data.size() * sizeof(PodType) < max_size_in_bytes
1189 ? data.size() * sizeof(PodType) : max_size_in_bytes);
1192 #if defined(BOOST_ASIO_HAS_STD_ARRAY) || defined(GENERATING_DOCUMENTATION)
1194 /// Create a new modifiable buffer that represents the given POD array.
1196 * @returns A mutable_buffer value equivalent to:
1197 * @code mutable_buffer(
1199 * data.size() * sizeof(PodType)); @endcode
1201 template <typename PodType, std::size_t N>
1202 inline BOOST_ASIO_MUTABLE_BUFFER buffer(
1203 std::array<PodType, N>& data) BOOST_ASIO_NOEXCEPT
1205 return BOOST_ASIO_MUTABLE_BUFFER(data.data(), data.size() * sizeof(PodType));
1208 /// Create a new modifiable buffer that represents the given POD array.
1210 * @returns A mutable_buffer value equivalent to:
1211 * @code mutable_buffer(
1213 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1215 template <typename PodType, std::size_t N>
1216 inline BOOST_ASIO_MUTABLE_BUFFER buffer(std::array<PodType, N>& data,
1217 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1219 return BOOST_ASIO_MUTABLE_BUFFER(data.data(),
1220 data.size() * sizeof(PodType) < max_size_in_bytes
1221 ? data.size() * sizeof(PodType) : max_size_in_bytes);
1224 /// Create a new non-modifiable buffer that represents the given POD array.
1226 * @returns A const_buffer value equivalent to:
1227 * @code const_buffer(
1229 * data.size() * sizeof(PodType)); @endcode
1231 template <typename PodType, std::size_t N>
1232 inline BOOST_ASIO_CONST_BUFFER buffer(
1233 std::array<const PodType, N>& data) BOOST_ASIO_NOEXCEPT
1235 return BOOST_ASIO_CONST_BUFFER(data.data(), data.size() * sizeof(PodType));
1238 /// Create a new non-modifiable buffer that represents the given POD array.
1240 * @returns A const_buffer value equivalent to:
1241 * @code const_buffer(
1243 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1245 template <typename PodType, std::size_t N>
1246 inline BOOST_ASIO_CONST_BUFFER buffer(std::array<const PodType, N>& data,
1247 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1249 return BOOST_ASIO_CONST_BUFFER(data.data(),
1250 data.size() * sizeof(PodType) < max_size_in_bytes
1251 ? data.size() * sizeof(PodType) : max_size_in_bytes);
1254 /// Create a new non-modifiable buffer that represents the given POD array.
1256 * @returns A const_buffer value equivalent to:
1257 * @code const_buffer(
1259 * data.size() * sizeof(PodType)); @endcode
1261 template <typename PodType, std::size_t N>
1262 inline BOOST_ASIO_CONST_BUFFER buffer(
1263 const std::array<PodType, N>& data) BOOST_ASIO_NOEXCEPT
1265 return BOOST_ASIO_CONST_BUFFER(data.data(), data.size() * sizeof(PodType));
1268 /// Create a new non-modifiable buffer that represents the given POD array.
1270 * @returns A const_buffer value equivalent to:
1271 * @code const_buffer(
1273 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1275 template <typename PodType, std::size_t N>
1276 inline BOOST_ASIO_CONST_BUFFER buffer(const std::array<PodType, N>& data,
1277 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1279 return BOOST_ASIO_CONST_BUFFER(data.data(),
1280 data.size() * sizeof(PodType) < max_size_in_bytes
1281 ? data.size() * sizeof(PodType) : max_size_in_bytes);
1284 #endif // defined(BOOST_ASIO_HAS_STD_ARRAY) || defined(GENERATING_DOCUMENTATION)
1286 /// Create a new modifiable buffer that represents the given POD vector.
1288 * @returns A mutable_buffer value equivalent to:
1289 * @code mutable_buffer(
1290 * data.size() ? &data[0] : 0,
1291 * data.size() * sizeof(PodType)); @endcode
1293 * @note The buffer is invalidated by any vector operation that would also
1294 * invalidate iterators.
1296 template <typename PodType, typename Allocator>
1297 inline BOOST_ASIO_MUTABLE_BUFFER buffer(
1298 std::vector<PodType, Allocator>& data) BOOST_ASIO_NOEXCEPT
1300 return BOOST_ASIO_MUTABLE_BUFFER(
1301 data.size() ? &data[0] : 0, data.size() * sizeof(PodType)
1302 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1303 , detail::buffer_debug_check<
1304 typename std::vector<PodType, Allocator>::iterator
1306 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1310 /// Create a new modifiable buffer that represents the given POD vector.
1312 * @returns A mutable_buffer value equivalent to:
1313 * @code mutable_buffer(
1314 * data.size() ? &data[0] : 0,
1315 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1317 * @note The buffer is invalidated by any vector operation that would also
1318 * invalidate iterators.
1320 template <typename PodType, typename Allocator>
1321 inline BOOST_ASIO_MUTABLE_BUFFER buffer(std::vector<PodType, Allocator>& data,
1322 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1324 return BOOST_ASIO_MUTABLE_BUFFER(data.size() ? &data[0] : 0,
1325 data.size() * sizeof(PodType) < max_size_in_bytes
1326 ? data.size() * sizeof(PodType) : max_size_in_bytes
1327 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1328 , detail::buffer_debug_check<
1329 typename std::vector<PodType, Allocator>::iterator
1331 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1335 /// Create a new non-modifiable buffer that represents the given POD vector.
1337 * @returns A const_buffer value equivalent to:
1338 * @code const_buffer(
1339 * data.size() ? &data[0] : 0,
1340 * data.size() * sizeof(PodType)); @endcode
1342 * @note The buffer is invalidated by any vector operation that would also
1343 * invalidate iterators.
1345 template <typename PodType, typename Allocator>
1346 inline BOOST_ASIO_CONST_BUFFER buffer(
1347 const std::vector<PodType, Allocator>& data) BOOST_ASIO_NOEXCEPT
1349 return BOOST_ASIO_CONST_BUFFER(
1350 data.size() ? &data[0] : 0, data.size() * sizeof(PodType)
1351 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1352 , detail::buffer_debug_check<
1353 typename std::vector<PodType, Allocator>::const_iterator
1355 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1359 /// Create a new non-modifiable buffer that represents the given POD vector.
1361 * @returns A const_buffer value equivalent to:
1362 * @code const_buffer(
1363 * data.size() ? &data[0] : 0,
1364 * min(data.size() * sizeof(PodType), max_size_in_bytes)); @endcode
1366 * @note The buffer is invalidated by any vector operation that would also
1367 * invalidate iterators.
1369 template <typename PodType, typename Allocator>
1370 inline BOOST_ASIO_CONST_BUFFER buffer(
1371 const std::vector<PodType, Allocator>& data,
1372 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1374 return BOOST_ASIO_CONST_BUFFER(data.size() ? &data[0] : 0,
1375 data.size() * sizeof(PodType) < max_size_in_bytes
1376 ? data.size() * sizeof(PodType) : max_size_in_bytes
1377 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1378 , detail::buffer_debug_check<
1379 typename std::vector<PodType, Allocator>::const_iterator
1381 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1385 /// Create a new modifiable buffer that represents the given string.
1387 * @returns <tt>mutable_buffer(data.size() ? &data[0] : 0,
1388 * data.size() * sizeof(Elem))</tt>.
1390 * @note The buffer is invalidated by any non-const operation called on the
1391 * given string object.
1393 template <typename Elem, typename Traits, typename Allocator>
1394 inline BOOST_ASIO_MUTABLE_BUFFER buffer(
1395 std::basic_string<Elem, Traits, Allocator>& data) BOOST_ASIO_NOEXCEPT
1397 return BOOST_ASIO_MUTABLE_BUFFER(data.size() ? &data[0] : 0,
1398 data.size() * sizeof(Elem)
1399 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1400 , detail::buffer_debug_check<
1401 typename std::basic_string<Elem, Traits, Allocator>::iterator
1403 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1407 /// Create a new non-modifiable buffer that represents the given string.
1409 * @returns A mutable_buffer value equivalent to:
1410 * @code mutable_buffer(
1411 * data.size() ? &data[0] : 0,
1412 * min(data.size() * sizeof(Elem), max_size_in_bytes)); @endcode
1414 * @note The buffer is invalidated by any non-const operation called on the
1415 * given string object.
1417 template <typename Elem, typename Traits, typename Allocator>
1418 inline BOOST_ASIO_MUTABLE_BUFFER buffer(
1419 std::basic_string<Elem, Traits, Allocator>& data,
1420 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1422 return BOOST_ASIO_MUTABLE_BUFFER(data.size() ? &data[0] : 0,
1423 data.size() * sizeof(Elem) < max_size_in_bytes
1424 ? data.size() * sizeof(Elem) : max_size_in_bytes
1425 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1426 , detail::buffer_debug_check<
1427 typename std::basic_string<Elem, Traits, Allocator>::iterator
1429 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1433 /// Create a new non-modifiable buffer that represents the given string.
1435 * @returns <tt>const_buffer(data.data(), data.size() * sizeof(Elem))</tt>.
1437 * @note The buffer is invalidated by any non-const operation called on the
1438 * given string object.
1440 template <typename Elem, typename Traits, typename Allocator>
1441 inline BOOST_ASIO_CONST_BUFFER buffer(
1442 const std::basic_string<Elem, Traits, Allocator>& data) BOOST_ASIO_NOEXCEPT
1444 return BOOST_ASIO_CONST_BUFFER(data.data(), data.size() * sizeof(Elem)
1445 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1446 , detail::buffer_debug_check<
1447 typename std::basic_string<Elem, Traits, Allocator>::const_iterator
1449 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1453 /// Create a new non-modifiable buffer that represents the given string.
1455 * @returns A const_buffer value equivalent to:
1456 * @code const_buffer(
1458 * min(data.size() * sizeof(Elem), max_size_in_bytes)); @endcode
1460 * @note The buffer is invalidated by any non-const operation called on the
1461 * given string object.
1463 template <typename Elem, typename Traits, typename Allocator>
1464 inline BOOST_ASIO_CONST_BUFFER buffer(
1465 const std::basic_string<Elem, Traits, Allocator>& data,
1466 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1468 return BOOST_ASIO_CONST_BUFFER(data.data(),
1469 data.size() * sizeof(Elem) < max_size_in_bytes
1470 ? data.size() * sizeof(Elem) : max_size_in_bytes
1471 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1472 , detail::buffer_debug_check<
1473 typename std::basic_string<Elem, Traits, Allocator>::const_iterator
1475 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1479 #if defined(BOOST_ASIO_HAS_STD_STRING_VIEW) \
1480 || defined(GENERATING_DOCUMENTATION)
1482 /// Create a new modifiable buffer that represents the given string_view.
1484 * @returns <tt>mutable_buffer(data.size() ? &data[0] : 0,
1485 * data.size() * sizeof(Elem))</tt>.
1487 template <typename Elem, typename Traits>
1488 inline BOOST_ASIO_CONST_BUFFER buffer(
1489 basic_string_view<Elem, Traits> data) BOOST_ASIO_NOEXCEPT
1491 return BOOST_ASIO_CONST_BUFFER(data.size() ? &data[0] : 0,
1492 data.size() * sizeof(Elem)
1493 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1494 , detail::buffer_debug_check<
1495 typename basic_string_view<Elem, Traits>::iterator
1497 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1501 /// Create a new non-modifiable buffer that represents the given string.
1503 * @returns A mutable_buffer value equivalent to:
1504 * @code mutable_buffer(
1505 * data.size() ? &data[0] : 0,
1506 * min(data.size() * sizeof(Elem), max_size_in_bytes)); @endcode
1508 template <typename Elem, typename Traits>
1509 inline BOOST_ASIO_CONST_BUFFER buffer(
1510 basic_string_view<Elem, Traits> data,
1511 std::size_t max_size_in_bytes) BOOST_ASIO_NOEXCEPT
1513 return BOOST_ASIO_CONST_BUFFER(data.size() ? &data[0] : 0,
1514 data.size() * sizeof(Elem) < max_size_in_bytes
1515 ? data.size() * sizeof(Elem) : max_size_in_bytes
1516 #if defined(BOOST_ASIO_ENABLE_BUFFER_DEBUGGING)
1517 , detail::buffer_debug_check<
1518 typename basic_string_view<Elem, Traits>::iterator
1520 #endif // BOOST_ASIO_ENABLE_BUFFER_DEBUGGING
1524 #endif // defined(BOOST_ASIO_HAS_STD_STRING_VIEW)
1525 // || defined(GENERATING_DOCUMENTATION)
1529 /// Adapt a basic_string to the DynamicBuffer requirements.
1531 * Requires that <tt>sizeof(Elem) == 1</tt>.
1533 template <typename Elem, typename Traits, typename Allocator>
1534 class dynamic_string_buffer
1537 /// The type used to represent the input sequence as a list of buffers.
1538 typedef BOOST_ASIO_CONST_BUFFER const_buffers_type;
1540 /// The type used to represent the output sequence as a list of buffers.
1541 typedef BOOST_ASIO_MUTABLE_BUFFER mutable_buffers_type;
1543 /// Construct a dynamic buffer from a string.
1545 * @param s The string to be used as backing storage for the dynamic buffer.
1546 * Any existing data in the string is treated as the dynamic buffer's input
1547 * sequence. The object stores a reference to the string and the user is
1548 * responsible for ensuring that the string object remains valid until the
1549 * dynamic_string_buffer object is destroyed.
1551 * @param maximum_size Specifies a maximum size for the buffer, in bytes.
1553 explicit dynamic_string_buffer(std::basic_string<Elem, Traits, Allocator>& s,
1554 std::size_t maximum_size =
1555 (std::numeric_limits<std::size_t>::max)()) BOOST_ASIO_NOEXCEPT
1557 size_(string_.size()),
1558 max_size_(maximum_size)
1562 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
1563 /// Move construct a dynamic buffer.
1564 dynamic_string_buffer(dynamic_string_buffer&& other) BOOST_ASIO_NOEXCEPT
1565 : string_(other.string_),
1567 max_size_(other.max_size_)
1570 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
1572 /// Get the size of the input sequence.
1573 std::size_t size() const BOOST_ASIO_NOEXCEPT
1578 /// Get the maximum size of the dynamic buffer.
1580 * @returns The allowed maximum of the sum of the sizes of the input sequence
1581 * and output sequence.
1583 std::size_t max_size() const BOOST_ASIO_NOEXCEPT
1588 /// Get the current capacity of the dynamic buffer.
1590 * @returns The current total capacity of the buffer, i.e. for both the input
1591 * sequence and output sequence.
1593 std::size_t capacity() const BOOST_ASIO_NOEXCEPT
1595 return string_.capacity();
1598 /// Get a list of buffers that represents the input sequence.
1600 * @returns An object of type @c const_buffers_type that satisfies
1601 * ConstBufferSequence requirements, representing the basic_string memory in
1604 * @note The returned object is invalidated by any @c dynamic_string_buffer
1605 * or @c basic_string member function that modifies the input sequence or
1608 const_buffers_type data() const BOOST_ASIO_NOEXCEPT
1610 return const_buffers_type(boost::asio::buffer(string_, size_));
1613 /// Get a list of buffers that represents the output sequence, with the given
1616 * Ensures that the output sequence can accommodate @c n bytes, resizing the
1617 * basic_string object as necessary.
1619 * @returns An object of type @c mutable_buffers_type that satisfies
1620 * MutableBufferSequence requirements, representing basic_string memory
1621 * at the start of the output sequence of size @c n.
1623 * @throws std::length_error If <tt>size() + n > max_size()</tt>.
1625 * @note The returned object is invalidated by any @c dynamic_string_buffer
1626 * or @c basic_string member function that modifies the input sequence or
1629 mutable_buffers_type prepare(std::size_t n)
1631 if (size () > max_size() || max_size() - size() < n)
1633 std::length_error ex("dynamic_string_buffer too long");
1634 boost::asio::detail::throw_exception(ex);
1637 string_.resize(size_ + n);
1639 return boost::asio::buffer(boost::asio::buffer(string_) + size_, n);
1642 /// Move bytes from the output sequence to the input sequence.
1644 * @param n The number of bytes to append from the start of the output
1645 * sequence to the end of the input sequence. The remainder of the output
1646 * sequence is discarded.
1648 * Requires a preceding call <tt>prepare(x)</tt> where <tt>x >= n</tt>, and
1649 * no intervening operations that modify the input or output sequence.
1651 * @note If @c n is greater than the size of the output sequence, the entire
1652 * output sequence is moved to the input sequence and no error is issued.
1654 void commit(std::size_t n)
1656 size_ += (std::min)(n, string_.size() - size_);
1657 string_.resize(size_);
1660 /// Remove characters from the input sequence.
1662 * Removes @c n characters from the beginning of the input sequence.
1664 * @note If @c n is greater than the size of the input sequence, the entire
1665 * input sequence is consumed and no error is issued.
1667 void consume(std::size_t n)
1669 std::size_t consume_length = (std::min)(n, size_);
1670 string_.erase(0, consume_length);
1671 size_ -= consume_length;
1675 std::basic_string<Elem, Traits, Allocator>& string_;
1677 const std::size_t max_size_;
1680 /// Adapt a vector to the DynamicBuffer requirements.
1682 * Requires that <tt>sizeof(Elem) == 1</tt>.
1684 template <typename Elem, typename Allocator>
1685 class dynamic_vector_buffer
1688 /// The type used to represent the input sequence as a list of buffers.
1689 typedef BOOST_ASIO_CONST_BUFFER const_buffers_type;
1691 /// The type used to represent the output sequence as a list of buffers.
1692 typedef BOOST_ASIO_MUTABLE_BUFFER mutable_buffers_type;
1694 /// Construct a dynamic buffer from a string.
1696 * @param v The vector to be used as backing storage for the dynamic buffer.
1697 * Any existing data in the vector is treated as the dynamic buffer's input
1698 * sequence. The object stores a reference to the vector and the user is
1699 * responsible for ensuring that the vector object remains valid until the
1700 * dynamic_vector_buffer object is destroyed.
1702 * @param maximum_size Specifies a maximum size for the buffer, in bytes.
1704 explicit dynamic_vector_buffer(std::vector<Elem, Allocator>& v,
1705 std::size_t maximum_size =
1706 (std::numeric_limits<std::size_t>::max)()) BOOST_ASIO_NOEXCEPT
1708 size_(vector_.size()),
1709 max_size_(maximum_size)
1713 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
1714 /// Move construct a dynamic buffer.
1715 dynamic_vector_buffer(dynamic_vector_buffer&& other) BOOST_ASIO_NOEXCEPT
1716 : vector_(other.vector_),
1718 max_size_(other.max_size_)
1721 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
1723 /// Get the size of the input sequence.
1724 std::size_t size() const BOOST_ASIO_NOEXCEPT
1729 /// Get the maximum size of the dynamic buffer.
1731 * @returns The allowed maximum of the sum of the sizes of the input sequence
1732 * and output sequence.
1734 std::size_t max_size() const BOOST_ASIO_NOEXCEPT
1739 /// Get the current capacity of the dynamic buffer.
1741 * @returns The current total capacity of the buffer, i.e. for both the input
1742 * sequence and output sequence.
1744 std::size_t capacity() const BOOST_ASIO_NOEXCEPT
1746 return vector_.capacity();
1749 /// Get a list of buffers that represents the input sequence.
1751 * @returns An object of type @c const_buffers_type that satisfies
1752 * ConstBufferSequence requirements, representing the basic_string memory in
1755 * @note The returned object is invalidated by any @c dynamic_vector_buffer
1756 * or @c basic_string member function that modifies the input sequence or
1759 const_buffers_type data() const BOOST_ASIO_NOEXCEPT
1761 return const_buffers_type(boost::asio::buffer(vector_, size_));
1764 /// Get a list of buffers that represents the output sequence, with the given
1767 * Ensures that the output sequence can accommodate @c n bytes, resizing the
1768 * basic_string object as necessary.
1770 * @returns An object of type @c mutable_buffers_type that satisfies
1771 * MutableBufferSequence requirements, representing basic_string memory
1772 * at the start of the output sequence of size @c n.
1774 * @throws std::length_error If <tt>size() + n > max_size()</tt>.
1776 * @note The returned object is invalidated by any @c dynamic_vector_buffer
1777 * or @c basic_string member function that modifies the input sequence or
1780 mutable_buffers_type prepare(std::size_t n)
1782 if (size () > max_size() || max_size() - size() < n)
1784 std::length_error ex("dynamic_vector_buffer too long");
1785 boost::asio::detail::throw_exception(ex);
1788 vector_.resize(size_ + n);
1790 return boost::asio::buffer(boost::asio::buffer(vector_) + size_, n);
1793 /// Move bytes from the output sequence to the input sequence.
1795 * @param n The number of bytes to append from the start of the output
1796 * sequence to the end of the input sequence. The remainder of the output
1797 * sequence is discarded.
1799 * Requires a preceding call <tt>prepare(x)</tt> where <tt>x >= n</tt>, and
1800 * no intervening operations that modify the input or output sequence.
1802 * @note If @c n is greater than the size of the output sequence, the entire
1803 * output sequence is moved to the input sequence and no error is issued.
1805 void commit(std::size_t n)
1807 size_ += (std::min)(n, vector_.size() - size_);
1808 vector_.resize(size_);
1811 /// Remove characters from the input sequence.
1813 * Removes @c n characters from the beginning of the input sequence.
1815 * @note If @c n is greater than the size of the input sequence, the entire
1816 * input sequence is consumed and no error is issued.
1818 void consume(std::size_t n)
1820 std::size_t consume_length = (std::min)(n, size_);
1821 vector_.erase(vector_.begin(), vector_.begin() + consume_length);
1822 size_ -= consume_length;
1826 std::vector<Elem, Allocator>& vector_;
1828 const std::size_t max_size_;
1831 /** @defgroup dynamic_buffer boost::asio::dynamic_buffer
1833 * @brief The boost::asio::dynamic_buffer function is used to create a
1834 * dynamically resized buffer from a @c std::basic_string or @c std::vector.
1838 /// Create a new dynamic buffer that represents the given string.
1840 * @returns <tt>dynamic_string_buffer<Elem, Traits, Allocator>(data)</tt>.
1842 template <typename Elem, typename Traits, typename Allocator>
1843 inline dynamic_string_buffer<Elem, Traits, Allocator> dynamic_buffer(
1844 std::basic_string<Elem, Traits, Allocator>& data) BOOST_ASIO_NOEXCEPT
1846 return dynamic_string_buffer<Elem, Traits, Allocator>(data);
1849 /// Create a new dynamic buffer that represents the given string.
1851 * @returns <tt>dynamic_string_buffer<Elem, Traits, Allocator>(data,
1854 template <typename Elem, typename Traits, typename Allocator>
1855 inline dynamic_string_buffer<Elem, Traits, Allocator> dynamic_buffer(
1856 std::basic_string<Elem, Traits, Allocator>& data,
1857 std::size_t max_size) BOOST_ASIO_NOEXCEPT
1859 return dynamic_string_buffer<Elem, Traits, Allocator>(data, max_size);
1862 /// Create a new dynamic buffer that represents the given vector.
1864 * @returns <tt>dynamic_vector_buffer<Elem, Allocator>(data)</tt>.
1866 template <typename Elem, typename Allocator>
1867 inline dynamic_vector_buffer<Elem, Allocator> dynamic_buffer(
1868 std::vector<Elem, Allocator>& data) BOOST_ASIO_NOEXCEPT
1870 return dynamic_vector_buffer<Elem, Allocator>(data);
1873 /// Create a new dynamic buffer that represents the given vector.
1875 * @returns <tt>dynamic_vector_buffer<Elem, Allocator>(data, max_size)</tt>.
1877 template <typename Elem, typename Allocator>
1878 inline dynamic_vector_buffer<Elem, Allocator> dynamic_buffer(
1879 std::vector<Elem, Allocator>& data,
1880 std::size_t max_size) BOOST_ASIO_NOEXCEPT
1882 return dynamic_vector_buffer<Elem, Allocator>(data, max_size);
1887 /** @defgroup buffer_copy boost::asio::buffer_copy
1889 * @brief The boost::asio::buffer_copy function is used to copy bytes from a
1890 * source buffer (or buffer sequence) to a target buffer (or buffer sequence).
1892 * The @c buffer_copy function is available in two forms:
1894 * @li A 2-argument form: @c buffer_copy(target, source)
1896 * @li A 3-argument form: @c buffer_copy(target, source, max_bytes_to_copy)
1898 * Both forms return the number of bytes actually copied. The number of bytes
1899 * copied is the lesser of:
1901 * @li @c buffer_size(target)
1903 * @li @c buffer_size(source)
1905 * @li @c If specified, @c max_bytes_to_copy.
1907 * This prevents buffer overflow, regardless of the buffer sizes used in the
1910 * Note that @ref buffer_copy is implemented in terms of @c memcpy, and
1911 * consequently it cannot be used to copy between overlapping memory regions.
1917 inline std::size_t buffer_copy_1(const mutable_buffer& target,
1918 const const_buffer& source)
1920 using namespace std; // For memcpy.
1921 std::size_t target_size = target.size();
1922 std::size_t source_size = source.size();
1923 std::size_t n = target_size < source_size ? target_size : source_size;
1925 memcpy(target.data(), source.data(), n);
1929 template <typename TargetIterator, typename SourceIterator>
1930 inline std::size_t buffer_copy(one_buffer, one_buffer,
1931 TargetIterator target_begin, TargetIterator,
1932 SourceIterator source_begin, SourceIterator) BOOST_ASIO_NOEXCEPT
1934 return (buffer_copy_1)(*target_begin, *source_begin);
1937 template <typename TargetIterator, typename SourceIterator>
1938 inline std::size_t buffer_copy(one_buffer, one_buffer,
1939 TargetIterator target_begin, TargetIterator,
1940 SourceIterator source_begin, SourceIterator,
1941 std::size_t max_bytes_to_copy) BOOST_ASIO_NOEXCEPT
1943 return (buffer_copy_1)(*target_begin,
1944 boost::asio::buffer(*source_begin, max_bytes_to_copy));
1947 template <typename TargetIterator, typename SourceIterator>
1948 std::size_t buffer_copy(one_buffer, multiple_buffers,
1949 TargetIterator target_begin, TargetIterator,
1950 SourceIterator source_begin, SourceIterator source_end,
1951 std::size_t max_bytes_to_copy
1952 = (std::numeric_limits<std::size_t>::max)()) BOOST_ASIO_NOEXCEPT
1954 std::size_t total_bytes_copied = 0;
1955 SourceIterator source_iter = source_begin;
1957 for (mutable_buffer target_buffer(
1958 boost::asio::buffer(*target_begin, max_bytes_to_copy));
1959 target_buffer.size() && source_iter != source_end; ++source_iter)
1961 const_buffer source_buffer(*source_iter);
1962 std::size_t bytes_copied = (buffer_copy_1)(target_buffer, source_buffer);
1963 total_bytes_copied += bytes_copied;
1964 target_buffer += bytes_copied;
1967 return total_bytes_copied;
1970 template <typename TargetIterator, typename SourceIterator>
1971 std::size_t buffer_copy(multiple_buffers, one_buffer,
1972 TargetIterator target_begin, TargetIterator target_end,
1973 SourceIterator source_begin, SourceIterator,
1974 std::size_t max_bytes_to_copy
1975 = (std::numeric_limits<std::size_t>::max)()) BOOST_ASIO_NOEXCEPT
1977 std::size_t total_bytes_copied = 0;
1978 TargetIterator target_iter = target_begin;
1980 for (const_buffer source_buffer(
1981 boost::asio::buffer(*source_begin, max_bytes_to_copy));
1982 source_buffer.size() && target_iter != target_end; ++target_iter)
1984 mutable_buffer target_buffer(*target_iter);
1985 std::size_t bytes_copied = (buffer_copy_1)(target_buffer, source_buffer);
1986 total_bytes_copied += bytes_copied;
1987 source_buffer += bytes_copied;
1990 return total_bytes_copied;
1993 template <typename TargetIterator, typename SourceIterator>
1994 std::size_t buffer_copy(multiple_buffers, multiple_buffers,
1995 TargetIterator target_begin, TargetIterator target_end,
1996 SourceIterator source_begin, SourceIterator source_end) BOOST_ASIO_NOEXCEPT
1998 std::size_t total_bytes_copied = 0;
2000 TargetIterator target_iter = target_begin;
2001 std::size_t target_buffer_offset = 0;
2003 SourceIterator source_iter = source_begin;
2004 std::size_t source_buffer_offset = 0;
2006 while (target_iter != target_end && source_iter != source_end)
2008 mutable_buffer target_buffer =
2009 mutable_buffer(*target_iter) + target_buffer_offset;
2011 const_buffer source_buffer =
2012 const_buffer(*source_iter) + source_buffer_offset;
2014 std::size_t bytes_copied = (buffer_copy_1)(target_buffer, source_buffer);
2015 total_bytes_copied += bytes_copied;
2017 if (bytes_copied == target_buffer.size())
2020 target_buffer_offset = 0;
2023 target_buffer_offset += bytes_copied;
2025 if (bytes_copied == source_buffer.size())
2028 source_buffer_offset = 0;
2031 source_buffer_offset += bytes_copied;
2034 return total_bytes_copied;
2037 template <typename TargetIterator, typename SourceIterator>
2038 std::size_t buffer_copy(multiple_buffers, multiple_buffers,
2039 TargetIterator target_begin, TargetIterator target_end,
2040 SourceIterator source_begin, SourceIterator source_end,
2041 std::size_t max_bytes_to_copy) BOOST_ASIO_NOEXCEPT
2043 std::size_t total_bytes_copied = 0;
2045 TargetIterator target_iter = target_begin;
2046 std::size_t target_buffer_offset = 0;
2048 SourceIterator source_iter = source_begin;
2049 std::size_t source_buffer_offset = 0;
2051 while (total_bytes_copied != max_bytes_to_copy
2052 && target_iter != target_end && source_iter != source_end)
2054 mutable_buffer target_buffer =
2055 mutable_buffer(*target_iter) + target_buffer_offset;
2057 const_buffer source_buffer =
2058 const_buffer(*source_iter) + source_buffer_offset;
2060 std::size_t bytes_copied = (buffer_copy_1)(
2061 target_buffer, boost::asio::buffer(source_buffer,
2062 max_bytes_to_copy - total_bytes_copied));
2063 total_bytes_copied += bytes_copied;
2065 if (bytes_copied == target_buffer.size())
2068 target_buffer_offset = 0;
2071 target_buffer_offset += bytes_copied;
2073 if (bytes_copied == source_buffer.size())
2076 source_buffer_offset = 0;
2079 source_buffer_offset += bytes_copied;
2082 return total_bytes_copied;
2085 } // namespace detail
2087 /// Copies bytes from a source buffer sequence to a target buffer sequence.
2089 * @param target A modifiable buffer sequence representing the memory regions to
2090 * which the bytes will be copied.
2092 * @param source A non-modifiable buffer sequence representing the memory
2093 * regions from which the bytes will be copied.
2095 * @returns The number of bytes copied.
2097 * @note The number of bytes copied is the lesser of:
2099 * @li @c buffer_size(target)
2101 * @li @c buffer_size(source)
2103 * This function is implemented in terms of @c memcpy, and consequently it
2104 * cannot be used to copy between overlapping memory regions.
2106 template <typename MutableBufferSequence, typename ConstBufferSequence>
2107 inline std::size_t buffer_copy(const MutableBufferSequence& target,
2108 const ConstBufferSequence& source) BOOST_ASIO_NOEXCEPT
2110 return detail::buffer_copy(
2111 detail::buffer_sequence_cardinality<MutableBufferSequence>(),
2112 detail::buffer_sequence_cardinality<ConstBufferSequence>(),
2113 boost::asio::buffer_sequence_begin(target),
2114 boost::asio::buffer_sequence_end(target),
2115 boost::asio::buffer_sequence_begin(source),
2116 boost::asio::buffer_sequence_end(source));
2119 /// Copies a limited number of bytes from a source buffer sequence to a target
2120 /// buffer sequence.
2122 * @param target A modifiable buffer sequence representing the memory regions to
2123 * which the bytes will be copied.
2125 * @param source A non-modifiable buffer sequence representing the memory
2126 * regions from which the bytes will be copied.
2128 * @param max_bytes_to_copy The maximum number of bytes to be copied.
2130 * @returns The number of bytes copied.
2132 * @note The number of bytes copied is the lesser of:
2134 * @li @c buffer_size(target)
2136 * @li @c buffer_size(source)
2138 * @li @c max_bytes_to_copy
2140 * This function is implemented in terms of @c memcpy, and consequently it
2141 * cannot be used to copy between overlapping memory regions.
2143 template <typename MutableBufferSequence, typename ConstBufferSequence>
2144 inline std::size_t buffer_copy(const MutableBufferSequence& target,
2145 const ConstBufferSequence& source,
2146 std::size_t max_bytes_to_copy) BOOST_ASIO_NOEXCEPT
2148 return detail::buffer_copy(
2149 detail::buffer_sequence_cardinality<MutableBufferSequence>(),
2150 detail::buffer_sequence_cardinality<ConstBufferSequence>(),
2151 boost::asio::buffer_sequence_begin(target),
2152 boost::asio::buffer_sequence_end(target),
2153 boost::asio::buffer_sequence_begin(source),
2154 boost::asio::buffer_sequence_end(source), max_bytes_to_copy);
2160 } // namespace boost
2162 #include <boost/asio/detail/pop_options.hpp>
2164 #endif // BOOST_ASIO_BUFFER_HPP