1 // 2 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 // 4 // Distributed under the Boost Software License, Version 1.0. (See accompanying 5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 // 7 // Official repository: https://github.com/boostorg/beast 8 // 9 10 #ifndef BOOST_BEAST_BUFFERS_RANGE_HPP 11 #define BOOST_BEAST_BUFFERS_RANGE_HPP 12 13 #include <boost/beast/core/detail/config.hpp> 14 #include <boost/beast/core/buffer_traits.hpp> 15 #include <boost/beast/core/detail/buffers_range_adaptor.hpp> 16 17 namespace boost { 18 namespace beast { 19 20 /** Returns an iterable range representing a buffer sequence. 21 22 This function returns an iterable range representing the 23 passed buffer sequence. The values obtained when iterating 24 the range will be `net::const_buffer`, unless the underlying 25 buffer sequence is a <em>MutableBufferSequence</em>, in which case 26 the value obtained when iterating will be a `net::mutable_buffer`. 27 28 @par Example 29 30 The following function returns the total number of bytes in 31 the specified buffer sequence. A copy of the buffer sequence 32 is maintained for the lifetime of the range object: 33 34 @code 35 template <class BufferSequence> 36 std::size_t buffer_sequence_size (BufferSequence const& buffers) 37 { 38 std::size_t size = 0; 39 for (auto const buffer : buffers_range (buffers)) 40 size += buffer.size(); 41 return size; 42 } 43 @endcode 44 45 @param buffers The buffer sequence to adapt into a range. The 46 range object returned from this function will contain a copy 47 of the passed buffer sequence. 48 49 @return An object of unspecified type which meets the requirements 50 of <em>ConstBufferSequence</em>. If `buffers` is a mutable buffer 51 sequence, the returned object will also meet the requirements of 52 <em>MutableBufferSequence</em>. 53 54 @see buffers_range_ref 55 */ 56 template<class BufferSequence> 57 #if BOOST_BEAST_DOXYGEN 58 __implementation_defined__ 59 #else 60 detail::buffers_range_adaptor<BufferSequence> 61 #endif buffers_range(BufferSequence const & buffers)62buffers_range(BufferSequence const& buffers) 63 { 64 static_assert( 65 is_const_buffer_sequence<BufferSequence>::value, 66 "BufferSequence type requirements not met"); 67 return detail::buffers_range_adaptor< 68 BufferSequence>(buffers); 69 } 70 71 /** Returns an iterable range representing a buffer sequence. 72 73 This function returns an iterable range representing the 74 passed buffer sequence. The values obtained when iterating 75 the range will be `net::const_buffer`, unless the underlying 76 buffer sequence is a <em>MutableBufferSequence</em>, in which case 77 the value obtained when iterating will be a `net::mutable_buffer`. 78 79 @par Example 80 81 The following function returns the total number of bytes in 82 the specified buffer sequence. A reference to the original 83 buffers is maintained for the lifetime of the range object: 84 85 @code 86 template <class BufferSequence> 87 std::size_t buffer_sequence_size_ref (BufferSequence const& buffers) 88 { 89 std::size_t size = 0; 90 for (auto const buffer : buffers_range_ref (buffers)) 91 size += buffer.size(); 92 return size; 93 } 94 @endcode 95 96 @param buffers The buffer sequence to adapt into a range. The 97 range returned from this function will maintain a reference to 98 these buffers. The application is responsible for ensuring that 99 the lifetime of the referenced buffers extends until the range 100 object is destroyed. 101 102 @return An object of unspecified type which meets the requirements 103 of <em>ConstBufferSequence</em>. If `buffers` is a mutable buffer 104 sequence, the returned object will also meet the requirements of 105 <em>MutableBufferSequence</em>. 106 107 @see buffers_range 108 */ 109 template<class BufferSequence> 110 #if BOOST_BEAST_DOXYGEN 111 __implementation_defined__ 112 #else 113 detail::buffers_range_adaptor<BufferSequence const&> 114 #endif buffers_range_ref(BufferSequence const & buffers)115buffers_range_ref(BufferSequence const& buffers) 116 { 117 static_assert( 118 is_const_buffer_sequence<BufferSequence>::value, 119 "BufferSequence type requirements not met"); 120 return detail::buffers_range_adaptor< 121 BufferSequence const&>(buffers); 122 } 123 /** @} */ 124 125 } // beast 126 } // boost 127 128 #endif 129