include/boost/capy/buffers.hpp

96.9% Lines (63/65) 100.0% List of functions (127/127)

[ ] prev/next file n p prev/next uncovered line

buffers.hpp

f(x) Functions (127)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
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_HPP
11		#define BOOST_CAPY_BUFFERS_HPP
12
13		#include <boost/capy/detail/config.hpp>
14		#include <concepts>
15		#include <cstddef>
16		#include <iterator>
17		#include <memory>
18		#include <ranges>
19		#include <type_traits>
20
21		// https://www.boost.org/doc/libs/1_65_0/doc/html/boost_asio/reference/ConstBufferSequence.html
22
23		namespace boost {
24
25		namespace asio {
26		class const_buffer;
27		class mutable_buffer;
28		} // asio
29
30		namespace capy {
31
32		class const_buffer;
33		class mutable_buffer;
34
35		/** A reference to a contiguous region of writable memory.
36
37		Represents a pointer and size pair for a modifiable byte range.
38		Does not own the memory. Satisfies `MutableBufferSequence` (as a
39		single-element sequence) and is implicitly convertible to
40		`const_buffer`.
41
42		@see const_buffer, MutableBufferSequence
43		*/
44		class mutable_buffer
45		{
46		unsigned char* p_ = nullptr;
47		std::size_t n_ = 0;
48
49		public:
50		/// Construct an empty buffer.
51	29x	mutable_buffer() = default;
52
53		/// Construct a copy.
54		mutable_buffer(
55		mutable_buffer const&) = default;
56
57		/// Assign by copying.
58		mutable_buffer& operator=(
59		mutable_buffer const&) = default;
60
61		/// Construct from pointer and size.
62	42543x	constexpr mutable_buffer(
63		void* data, std::size_t size) noexcept
64	42543x	: p_(static_cast<unsigned char*>(data))
65	42543x	, n_(size)
66		{
67	42543x	}
68
69		/// Return a pointer to the memory region.
70	62282x	constexpr void* data() const noexcept
71		{
72	62282x	return p_;
73		}
74
75		/// Return the size in bytes.
76	97921x	constexpr std::size_t size() const noexcept
77		{
78	97921x	return n_;
79		}
80
81		/** Advance the buffer start, shrinking the region.
82
83		@param n Bytes to skip. Clamped to `size()`.
84		*/
85		mutable_buffer&
86	19795x	operator+=(std::size_t n) noexcept
87		{
88	19795x	if( n > n_)
89	✗	n = n_;
90	19795x	p_ += n;
91	19795x	n_ -= n;
92	19795x	return *this;
93		}
94		};
95
96		/** A reference to a contiguous region of read-only memory.
97
98		Represents a pointer and size pair for a non-modifiable byte range.
99		Does not own the memory. Satisfies `ConstBufferSequence` (as a
100		single-element sequence). Implicitly constructible from
101		`mutable_buffer`.
102
103		@see mutable_buffer, ConstBufferSequence
104		*/
105		class const_buffer
106		{
107		unsigned char const* p_ = nullptr;
108		std::size_t n_ = 0;
109
110		public:
111		/// Construct an empty buffer.
112	57x	const_buffer() = default;
113
114		/// Construct a copy.
115		const_buffer(const_buffer const&) = default;
116
117		/// Assign by copying.
118		const_buffer& operator=(
119		const_buffer const& other) = default;
120
121		/// Construct from pointer and size.
122	43395x	constexpr const_buffer(
123		void const* data, std::size_t size) noexcept
124	43395x	: p_(static_cast<unsigned char const*>(data))
125	43395x	, n_(size)
126		{
127	43395x	}
128
129		/// Construct from mutable_buffer.
130	11963x	constexpr const_buffer(
131		mutable_buffer const& b) noexcept
132	11963x	: p_(static_cast<unsigned char const*>(b.data()))
133	11963x	, n_(b.size())
134		{
135	11963x	}
136
137		/// Return a pointer to the memory region.
138	59932x	constexpr void const* data() const noexcept
139		{
140	59932x	return p_;
141		}
142
143		/// Return the size in bytes.
144	112803x	constexpr std::size_t size() const noexcept
145		{
146	112803x	return n_;
147		}
148
149		/** Advance the buffer start, shrinking the region.
150
151		@param n Bytes to skip. Clamped to `size()`.
152		*/
153		const_buffer&
154	19796x	operator+=(std::size_t n) noexcept
155		{
156	19796x	if( n > n_)
157	✗	n = n_;
158	19796x	p_ += n;
159	19796x	n_ -= n;
160	19796x	return *this;
161		}
162		};
163
164		/** Concept for sequences of read-only buffer regions.
165
166		A type satisfies `ConstBufferSequence` if it represents one or more
167		contiguous memory regions that can be read. This includes single
168		buffers (convertible to `const_buffer`) and ranges of buffers.
169
170		@par Syntactic Requirements
171		@li Convertible to `const_buffer`, OR
172		@li A bidirectional range with value type convertible to `const_buffer`
173
174		@see const_buffer, MutableBufferSequence
175		*/
176		template<typename T>
177		concept ConstBufferSequence =
178		std::is_convertible_v<T, const_buffer> \|\| (
179		std::ranges::bidirectional_range<T> &&
180		std::is_convertible_v<std::ranges::range_value_t<T>, const_buffer>);
181
182		/** Concept for sequences of writable buffer regions.
183
184		A type satisfies `MutableBufferSequence` if it represents one or more
185		contiguous memory regions that can be written. This includes single
186		buffers (convertible to `mutable_buffer`) and ranges of buffers.
187		Every `MutableBufferSequence` also satisfies `ConstBufferSequence`.
188
189		@par Syntactic Requirements
190		@li Convertible to `mutable_buffer`, OR
191		@li A bidirectional range with value type convertible to `mutable_buffer`
192
193		@see mutable_buffer, ConstBufferSequence
194		*/
195		template<typename T>
196		concept MutableBufferSequence =
197		std::is_convertible_v<T, mutable_buffer> \|\| (
198		std::ranges::bidirectional_range<T> &&
199		std::is_convertible_v<std::ranges::range_value_t<T>, mutable_buffer>);
200
201		/** Return an iterator to the first buffer in a sequence.
202
203		Handles single buffers and ranges uniformly. For a single buffer,
204		returns a pointer to it (forming a one-element range).
205		*/
206		constexpr struct begin_mrdocs_workaround_t
207		{
208		template<std::convertible_to<const_buffer> ConvertibleToBuffer>
209	13111x	auto operator()(ConvertibleToBuffer const& b) const noexcept -> ConvertibleToBuffer const*
210		{
211	13111x	return std::addressof(b);
212		}
213
214		template<ConstBufferSequence BS>
215		requires (!std::convertible_to<BS, const_buffer>)
216	46366x	auto operator()(BS const& bs) const noexcept
217		{
218	46366x	return std::ranges::begin(bs);
219		}
220
221		template<ConstBufferSequence BS>
222		requires (!std::convertible_to<BS, const_buffer>)
223	9192x	auto operator()(BS& bs) const noexcept
224		{
225	9192x	return std::ranges::begin(bs);
226		}
227		} begin {};
228
229		/** Return an iterator past the last buffer in a sequence.
230
231		Handles single buffers and ranges uniformly. For a single buffer,
232		returns a pointer one past it.
233		*/
234		constexpr struct end_mrdocs_workaround_t
235		{
236		template<std::convertible_to<const_buffer> ConvertibleToBuffer>
237	12871x	auto operator()(ConvertibleToBuffer const& b) const noexcept -> ConvertibleToBuffer const*
238		{
239	12871x	return std::addressof(b) + 1;
240		}
241
242		template<ConstBufferSequence BS>
243		requires (!std::convertible_to<BS, const_buffer>)
244	46366x	auto operator()(BS const& bs) const noexcept
245		{
246	46366x	return std::ranges::end(bs);
247		}
248
249		template<ConstBufferSequence BS>
250		requires (!std::convertible_to<BS, const_buffer>)
251	9192x	auto operator()(BS& bs) const noexcept
252		{
253	9192x	return std::ranges::end(bs);
254		}
255		} end {};
256
257		/** Return the total byte count across all buffers in a sequence.
258
259		Sums the `size()` of each buffer in the sequence. This differs
260		from `buffer_length` which counts the number of buffer elements.
261
262		@par Example
263		@code
264		std::array<mutable_buffer, 2> bufs = { ... };
265		std::size_t total = buffer_size( bufs ); // sum of both sizes
266		@endcode
267		*/
268		constexpr struct buffer_size_mrdocs_workaround_t
269		{
270		// GCC 13 falsely flags reads of arr_[i].n_ in detail::buffer_array
271		// when iterating here. The class uses union storage with placement
272		// new for slots 0..n_-1, so reads inside this bounded loop are
273		// well-defined, but the optimizer can't prove the loop bound and
274		// warns. The runtime cost of value-initializing all N slots is
275		// non-trivial for non-trivial value types, so we suppress instead.
276		#if defined(__GNUC__) && !defined(__clang__)
277		#pragma GCC diagnostic push
278		#pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
279		#endif
280		template<ConstBufferSequence CB>
281	12812x	constexpr std::size_t operator()(
282		CB const& bs) const noexcept
283		{
284	12812x	std::size_t n = 0;
285	12812x	auto const e = capy::end(bs);
286	27149x	for(auto it = capy::begin(bs); it != e; ++it)
287	14337x	n += const_buffer(*it).size();
288	12812x	return n;
289		}
290		#if defined(__GNUC__) && !defined(__clang__)
291		#pragma GCC diagnostic pop
292		#endif
293		} buffer_size {};
294
295		/** Check if a buffer sequence contains no data.
296
297		@return `true` if all buffers have size zero or the sequence
298		is empty.
299		*/
300		constexpr struct buffer_empty_mrdocs_workaround_t
301		{
302		// See note on buffer_size above — same union-storage false positive.
303		#if defined(__GNUC__) && !defined(__clang__)
304		#pragma GCC diagnostic push
305		#pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
306		#endif
307		template<ConstBufferSequence CB>
308	4243x	constexpr bool operator()(
309		CB const& bs) const noexcept
310		{
311	4243x	auto it = begin(bs);
312	4243x	auto const end_ = end(bs);
313	4284x	while(it != end_)
314		{
315	4244x	const_buffer b(*it++);
316	4244x	if(b.size() != 0)
317	4203x	return false;
318		}
319	40x	return true;
320		}
321		#if defined(__GNUC__) && !defined(__clang__)
322		#pragma GCC diagnostic pop
323		#endif
324		} buffer_empty {};
325
326		namespace detail {
327
328		template<class It>
329		auto
330	240x	length_impl(It first, It last, int)
331		-> decltype(static_cast<std::size_t>(last - first))
332		{
333	240x	return static_cast<std::size_t>(last - first);
334		}
335
336		template<class It>
337		std::size_t
338		length_impl(It first, It last, long)
339		{
340		std::size_t n = 0;
341		while(first != last)
342		{
343		++first;
344		++n;
345		}
346		return n;
347		}
348
349		} // detail
350
351		/** Return the number of buffer elements in a sequence.
352
353		Counts the number of individual buffer objects, not bytes.
354		For a single buffer, returns 1. For a range, returns the
355		distance from `begin` to `end`.
356
357		@see buffer_size
358		*/
359		template<ConstBufferSequence CB>
360		std::size_t
361	240x	buffer_length(CB const& bs)
362		{
363	240x	return detail::length_impl(
364	240x	begin(bs), end(bs), 0);
365		}
366
367		/// Alias for `mutable_buffer` or `const_buffer` based on sequence type.
368		template<typename BS>
369		using buffer_type = std::conditional_t<
370		MutableBufferSequence<BS>,
371		mutable_buffer, const_buffer>;
372
373		} // capy
374		} // boost
375
376		#endif
377