TLA  Line data    Source code

       1                 : //
       2                 : // Copyright (c) 2026 Michael Vandeberg
       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/cppalliance/capy
       8                 : //
       9                 : 
      10                 : #ifndef BOOST_CAPY_BUFFERS_BUFFER_SLICE_HPP
      11                 : #define BOOST_CAPY_BUFFERS_BUFFER_SLICE_HPP
      12                 : 
      13                 : #include <boost/capy/detail/config.hpp>
      14                 : #include <boost/capy/buffers.hpp>
      15                 : #include <boost/capy/detail/slice_impl.hpp>
      16                 : 
      17                 : #include <cstddef>
      18                 : #include <limits>
      19                 : 
      20                 : namespace boost {
      21                 : namespace capy {
      22                 : 
      23                 : /** Return a byte-range slice of a buffer sequence.
      24                 : 
      25                 :     Constructs a view over a contiguous byte range of `seq`. The
      26                 :     slice exposes its current bytes via `data()` (a buffer sequence)
      27                 :     and supports incremental consumption via `remove_prefix(n)` and
      28                 :     `remove_suffix(n)`.
      29                 : 
      30                 :     @par Return Value
      31                 :     An object of unspecified type satisfying the @ref Slice concept.
      32                 :     Bind with `auto` and operate through the concept's members. When
      33                 :     `seq` models @ref MutableBufferSequence, the returned object
      34                 :     additionally models @ref MutableSlice.
      35                 : 
      36                 :     @par Lifetime
      37                 :     The returned object holds a non-owning reference to data within
      38                 :     `seq`. `seq` must remain valid until the returned object is
      39                 :     destroyed. Iterators and buffer descriptors obtained through
      40                 :     `data()` follow the same invalidation rules as those of `seq`.
      41                 : 
      42                 :     @par Parameters
      43                 :     @li `seq` The underlying buffer sequence.
      44                 :     @li `offset` Number of bytes to skip from the start of `seq`.
      45                 :         Clamped to `buffer_size(seq)`.
      46                 :     @li `length` Maximum number of bytes the slice will expose,
      47                 :         starting at `offset`. Clamped to `buffer_size(seq) - offset`.
      48                 :         Defaults to the maximum value of `std::size_t`, i.e. "to end".
      49                 : 
      50                 :     @par Example
      51                 :     @code
      52                 :     template< ReadStream Stream, MutableBufferSequence MB >
      53                 :     task< io_result< std::size_t > >
      54                 :     read_all( Stream& stream, MB buffers )
      55                 :     {
      56                 :         auto s = buffer_slice( buffers );
      57                 :         std::size_t const total_size = buffer_size( buffers );
      58                 :         std::size_t total = 0;
      59                 :         while( total < total_size )
      60                 :         {
      61                 :             auto [ec, n] = co_await stream.read_some( s.data() );
      62                 :             s.remove_prefix( n );
      63                 :             total += n;
      64                 :             if( ec )
      65                 :                 co_return {ec, total};
      66                 :         }
      67                 :         co_return {{}, total};
      68                 :     }
      69                 :     @endcode
      70                 : 
      71                 :     @see Slice, MutableSlice
      72                 : */
      73                 : template<class BufferSequence>
      74                 :     requires MutableBufferSequence<BufferSequence>
      75                 :           || ConstBufferSequence<BufferSequence>
      76                 : auto
      77 HIT         205 : buffer_slice(
      78                 :     BufferSequence const& seq,
      79                 :     std::size_t offset = 0,
      80                 :     std::size_t length =
      81                 :         (std::numeric_limits<std::size_t>::max)()) noexcept
      82                 : {
      83             205 :     return detail::slice_impl<BufferSequence>(seq, offset, length);
      84                 : }
      85                 : 
      86                 : } // namespace capy
      87                 : } // namespace boost
      88                 : 
      89                 : #endif