beast/core/buffers_range.hpp

0001 //
0002 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/beast
0008 //
0009
0010 #ifndef BOOST_BEAST_BUFFERS_RANGE_HPP
0011 #define BOOST_BEAST_BUFFERS_RANGE_HPP
0012
0013 #include <boost/beast/core/detail/config.hpp>
0014 #include <boost/beast/core/buffer_traits.hpp>
0015 #include <boost/beast/core/detail/buffers_range_adaptor.hpp>
0016
0017 namespace boost {
0018 namespace beast {
0019
0020 /** Returns an iterable range representing a buffer sequence.
0021
0022     This function returns an iterable range representing the
0023     passed buffer sequence. The values obtained when iterating
0024     the range will be `net::const_buffer`, unless the underlying
0025     buffer sequence is a <em>MutableBufferSequence</em>, in which case
0026     the value obtained when iterating will be a `net::mutable_buffer`.
0027
0028     @par Example
0029
0030     The following function returns the total number of bytes in
0031     the specified buffer sequence. A copy of the buffer sequence
0032     is maintained for the lifetime of the range object:
0033
0034     @code
0035     template <class BufferSequence>
0036     std::size_t buffer_sequence_size (BufferSequence const& buffers)
0037     {
0038         std::size_t size = 0;
0039         for (auto const buffer : buffers_range (buffers))
0040             size += buffer.size();
0041         return size;
0042     }
0043     @endcode
0044
0045     @param buffers The buffer sequence to adapt into a range. The
0046     range object returned from this function will contain a copy
0047     of the passed buffer sequence.
0048
0049     @return An object of unspecified type which meets the requirements
0050     of <em>ConstBufferSequence</em>. If `buffers` is a mutable buffer
0051     sequence, the returned object will also meet the requirements of
0052     <em>MutableBufferSequence</em>.
0053
0054     @see buffers_range_ref
0055 */
0056 template<class BufferSequence>
0057 #if BOOST_BEAST_DOXYGEN
0058 __implementation_defined__
0059 #else
0060 detail::buffers_range_adaptor<BufferSequence>
0061 #endif
0062 buffers_range(BufferSequence const& buffers)
0063 {
0064     static_assert(
0065         is_const_buffer_sequence<BufferSequence>::value,
0066         "BufferSequence type requirements not met");
0067     return detail::buffers_range_adaptor<
0068         BufferSequence>(buffers);
0069 }
0070
0071 /** Returns an iterable range representing a buffer sequence.
0072
0073     This function returns an iterable range representing the
0074     passed buffer sequence. The values obtained when iterating
0075     the range will be `net::const_buffer`, unless the underlying
0076     buffer sequence is a <em>MutableBufferSequence</em>, in which case
0077     the value obtained when iterating will be a `net::mutable_buffer`.
0078
0079     @par Example
0080
0081     The following function returns the total number of bytes in
0082     the specified buffer sequence. A reference to the original
0083     buffers is maintained for the lifetime of the range object:
0084
0085     @code
0086     template <class BufferSequence>
0087     std::size_t buffer_sequence_size_ref (BufferSequence const& buffers)
0088     {
0089         std::size_t size = 0;
0090         for (auto const buffer : buffers_range_ref (buffers))
0091             size += buffer.size();
0092         return size;
0093     }
0094     @endcode
0095
0096     @param buffers The buffer sequence to adapt into a range. The
0097     range returned from this function will maintain a reference to
0098     these buffers. The application is responsible for ensuring that
0099     the lifetime of the referenced buffers extends until the range
0100     object is destroyed.
0101
0102     @return An object of unspecified type which meets the requirements
0103     of <em>ConstBufferSequence</em>. If `buffers` is a mutable buffer
0104     sequence, the returned object will also meet the requirements of
0105     <em>MutableBufferSequence</em>.
0106
0107     @see buffers_range
0108 */
0109 template<class BufferSequence>
0110 #if BOOST_BEAST_DOXYGEN
0111 __implementation_defined__
0112 #else
0113 detail::buffers_range_adaptor<BufferSequence const&>
0114 #endif
0115 buffers_range_ref(BufferSequence const& buffers)
0116 {
0117     static_assert(
0118         is_const_buffer_sequence<BufferSequence>::value,
0119         "BufferSequence type requirements not met");
0120     return detail::buffers_range_adaptor<
0121         BufferSequence const&>(buffers);
0122 }
0123
0124 } // beast
0125 } // boost
0126
0127 #endif