. /include/boost/capy /buffers /buffer_slice.hpp
100.00% Lines (2/2) 100.00% Functions (1/1)
[ ] prev/next file n p prev/next uncovered line
TLA Baseline Branch
Line Hits Code Line Hits 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
HITGNC   77 + 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 + {
HITGNC   83 + 205 return detail::slice_impl<BufferSequence>(seq, offset, length);
  84 + }
  85 +
  86 + } // namespace capy
  87 + } // namespace boost
  88 +
  89 + #endif