Index/include / boost / capy / buffers / buffer_slice.hpp

include/boost/capy/buffers/buffer_slice.hpp

100.0% Lines (2/2) 100.0% List of functions (2/3)
[ ] prev/next file
buffer_slice.hpp
f(x) Functions (3)
Function Calls Lines Blocks
<unknown function 87> :87 – – – auto boost::capy::buffer_slice<boost::capy::const_buffer>(boost::capy::const_buffer const&, unsigned long, unsigned long) :87 1584x 100.0% 100.0% auto boost::capy::buffer_slice<boost::capy::mutable_buffer>(boost::capy::mutable_buffer const&, unsigned long, unsigned long) :87 38x 100.0% 100.0%
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)`.
28
29 @par Return Value
30 An object of unspecified type satisfying the @ref Slice concept.
31 Bind with `auto` and operate through the concept's members. When
32 `seq` models @ref MutableBufferSequence, the returned object
33 additionally models @ref MutableSlice.
34
35 @par Lifetime
36 The returned slice is associated with `seq` as its underlying
37 buffer sequence. `seq` — and the memory referenced by its buffer
38 descriptors — must remain valid for as long as the slice, or
39 any buffer sequence obtained from its `data()`, is in use.
40 Passing a temporary buffer sequence to `buffer_slice` produces
41 a dangling slice.
42
43 The buffer sequence returned by `data()` is independent of the
44 slice object: subsequent operations on the slice (mutation,
45 copy, move, destruction) do not invalidate an already-obtained
46 `data()` view. It remains valid for as long as `seq` is valid.
47
48 Iterators and buffer descriptors obtained through `data()`
49 follow the same invalidation rules as those of `seq`.
50
51 @par Parameters
52 @li `seq` The underlying buffer sequence. Must outlive the
53 returned slice and any `data()` view obtained from it.
54 @li `offset` Number of bytes to skip from the start of `seq`.
55 Clamped to `buffer_size(seq)`.
56 @li `length` Maximum number of bytes the slice will expose,
57 starting at `offset`. Clamped to `buffer_size(seq) - offset`.
58 Defaults to the maximum value of `std::size_t`, i.e. "to end".
59
60 @par Example
61 @code
62 template< ReadStream Stream, MutableBufferSequence MB >
63 task< io_result< std::size_t > >
64 read_all( Stream& stream, MB buffers )
65 {
66 auto s = buffer_slice( buffers );
67 std::size_t const total_size = buffer_size( buffers );
68 std::size_t total = 0;
69 while( total < total_size )
70 {
71 auto [ec, n] = co_await stream.read_some( s.data() );
72 s.remove_prefix( n );
73 total += n;
74 if( ec )
75 co_return {ec, total};
76 }
77 co_return {{}, total};
78 }
79 @endcode
80
81 @see Slice, MutableSlice
82 */
83 template<class BufferSequence>
84 requires MutableBufferSequence<BufferSequence>
85 || ConstBufferSequence<BufferSequence>
86 auto
87 4369x buffer_slice(
88 BufferSequence const& seq,
89 std::size_t offset = 0,
90 std::size_t length =
91 (std::numeric_limits<std::size_t>::max)()) noexcept
92 {
93 4369x return detail::slice_impl<BufferSequence>(seq, offset, length);
94 }
95
96 /** Deleted overload that rejects rvalue arguments at compile time.
97
98 Because the returned slice's validity depends on the underlying
99 buffer sequence remaining alive, calling `buffer_slice` with a
100 temporary buffer sequence would produce an immediately dangling
101 slice. This overload makes such calls ill-formed, surfacing the
102 lifetime error at compile time rather than as runtime UB.
103
104 To slice a buffer sequence produced as a temporary, hoist it
105 into a named variable first:
106
107 @code
108 auto bufs = some_dynamic_buffer.data(); // named, lives in scope
109 auto s = buffer_slice( bufs ); // OK
110 @endcode
111 */
112 template<class BufferSequence>
113 requires MutableBufferSequence<BufferSequence>
114 || ConstBufferSequence<BufferSequence>
115 auto
116 buffer_slice(
117 BufferSequence const&& seq,
118 std::size_t offset = 0,
119 std::size_t length =
120 (std::numeric_limits<std::size_t>::max)()) = delete;
121
122 } // namespace capy
123 } // namespace boost
124
125 #endif
126