include/boost/capy/buffers/buffer_slice.hpp
100.0% Lines (2/2)
100.0% List of functions (1/2)
Functions (2)
| Line | TLA | Hits | 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 | 205x | 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 | 205x | return detail::slice_impl<BufferSequence>(seq, offset, length); | |
| 84 | } | ||
| 85 | |||
| 86 | } // namespace capy | ||
| 87 | } // namespace boost | ||
| 88 | |||
| 89 | #endif | ||
| 90 |