include/boost/capy/buffers.hpp

100.0% Lines (65/0/65) 88.3% List of functions (197/0/223)

[ ] prev/next file

buffers.hpp

f(x) Functions (223)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3		// Copyright (c) 2026 Michael Vandeberg
4		//
5		// Distributed under the Boost Software License, Version 1.0. (See accompanying
6		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7		//
8		// Official repository: https://github.com/cppalliance/capy
9		//
10
11		#ifndef BOOST_CAPY_BUFFERS_HPP
12		#define BOOST_CAPY_BUFFERS_HPP
13
14		#include <boost/capy/detail/config.hpp>
15		#include <concepts>
16		#include <cstddef>
17		#include <iterator>
18		#include <memory>
19		#include <ranges>
20		#include <type_traits>
21
22		// https://www.boost.org/doc/libs/1_65_0/doc/html/boost_asio/reference/ConstBufferSequence.html
23
24		namespace boost {
25
26		namespace asio {
27		class const_buffer;
28		class mutable_buffer;
29		} // asio
30
31		namespace capy {
32
33		class const_buffer;
34		class mutable_buffer;
35
36		/** A reference to a contiguous region of writable memory.
37
38		Represents a pointer and size pair for a modifiable byte range.
39		Does not own the memory. Satisfies `MutableBufferSequence` (as a
40		single-element sequence) and is implicitly convertible to
41		`const_buffer`.
42
43		@see const_buffer, MutableBufferSequence
44		*/
45		class mutable_buffer
46		{
47		unsigned char* p_ = nullptr;
48		std::size_t n_ = 0;
49
50		public:
51		/// Construct an empty buffer.
52	19x	mutable_buffer() = default;
53
54		/** Construct a copy.
55
56		@param other The buffer to copy.
57		*/
58		mutable_buffer(
59		mutable_buffer const& other) = default;
60
61		/** Assign by copying.
62
63		@param other The buffer to copy.
64
65		@return A reference to `*this`.
66		*/
67		mutable_buffer& operator=(
68		mutable_buffer const& other) = default;
69
70		/** Construct from a pointer and size.
71
72		Takes `void*` so a pointer to any object type binds without a
73		cast, since the buffer represents a raw, untyped writable
74		region. Stored internally as `unsigned char*` for byte-wise
75		pointer arithmetic (see `operator+=`).
76
77		@param data A pointer to the first byte of the region.
78
79		@param size The size of the region, in bytes.
80		*/
81	35281x	constexpr mutable_buffer(
82		void* data, std::size_t size) noexcept
83	35281x	: p_(static_cast<unsigned char*>(data))
84	35281x	, n_(size)
85		{
86	35281x	}
87
88		/** Return a pointer to the memory region.
89
90		Returns `void*`, symmetric with the constructor, so the
91		caller can reinterpret the raw region as whatever type it needs.
92
93		@return A pointer to the first byte of the region.
94		*/
95	54037x	constexpr void* data() const noexcept
96		{
97	54037x	return p_;
98		}
99
100		/** Return the size in bytes.
101
102		@return The size of the region, in bytes.
103		*/
104	80565x	constexpr std::size_t size() const noexcept
105		{
106	80565x	return n_;
107		}
108
109		/** Advance the buffer start, shrinking the region.
110
111		@param n Bytes to skip. Clamped to `size()`.
112
113		@return A reference to `*this`.
114		*/
115		mutable_buffer&
116	17732x	operator+=(std::size_t n) noexcept
117		{
118	17732x	if( n > n_)
119	1x	n = n_;
120	17732x	p_ += n;
121	17732x	n_ -= n;
122	17732x	return *this;
123		}
124		};
125
126		/** A reference to a contiguous region of read-only memory.
127
128		Represents a pointer and size pair for a non-modifiable byte range.
129		Does not own the memory. Satisfies `ConstBufferSequence` (as a
130		single-element sequence). Implicitly constructible from
131		`mutable_buffer`.
132
133		@see mutable_buffer, ConstBufferSequence
134		*/
135		class const_buffer
136		{
137		unsigned char const* p_ = nullptr;
138		std::size_t n_ = 0;
139
140		public:
141		/// Construct an empty buffer.
142	13x	const_buffer() = default;
143
144		/** Construct a copy.
145
146		@param other The buffer to copy.
147		*/
148		const_buffer(const_buffer const& other) = default;
149
150		/** Assign by copying.
151
152		@param other The buffer to copy.
153
154		@return A reference to `*this`.
155		*/
156		const_buffer& operator=(
157		const_buffer const& other) = default;
158
159		/** Construct from a pointer and size.
160
161		Takes `void const*` so a pointer to any object type binds
162		without a cast, since the buffer represents a raw, untyped
163		read-only region. Stored internally as `unsigned char const*`
164		for byte-wise pointer arithmetic (see `operator+=`).
165
166		@param data A pointer to the first byte of the region.
167
168		@param size The size of the region, in bytes.
169		*/
170	32088x	constexpr const_buffer(
171		void const* data, std::size_t size) noexcept
172	32088x	: p_(static_cast<unsigned char const*>(data))
173	32088x	, n_(size)
174		{
175	32088x	}
176
177		/** Construct from mutable_buffer.
178
179		@param b The writable buffer whose region is referenced.
180		*/
181	7887x	constexpr const_buffer(
182		mutable_buffer const& b) noexcept
183	7887x	: p_(static_cast<unsigned char const*>(b.data()))
184	7887x	, n_(b.size())
185		{
186	7887x	}
187
188		/** Return a pointer to the memory region.
189
190		Returns `void const*`, symmetric with the constructor, so the
191		caller can reinterpret the raw region as whatever type it needs.
192
193		@return A pointer to the first byte of the region.
194		*/
195	46527x	constexpr void const* data() const noexcept
196		{
197	46527x	return p_;
198		}
199
200		/** Return the size in bytes.
201
202		@return The size of the region, in bytes.
203		*/
204	77663x	constexpr std::size_t size() const noexcept
205		{
206	77663x	return n_;
207		}
208
209		/** Advance the buffer start, shrinking the region.
210
211		@param n Bytes to skip. Clamped to `size()`.
212
213		@return A reference to `*this`.
214		*/
215		const_buffer&
216	17380x	operator+=(std::size_t n) noexcept
217		{
218	17380x	if( n > n_)
219	1x	n = n_;
220	17380x	p_ += n;
221	17380x	n_ -= n;
222	17380x	return *this;
223		}
224		};
225
226		/** Requires a type to convert to `const_buffer`, or be a range of such buffers.
227
228		A type satisfies `ConstBufferSequence` if it represents one or more
229		contiguous memory regions that can be read. This includes single
230		buffers (convertible to `const_buffer`) and ranges of buffers.
231
232		@par Syntactic Requirements
233		@li Convertible to `const_buffer`, OR
234		@li A bidirectional range with value type convertible to `const_buffer`
235
236		@see const_buffer, MutableBufferSequence
237		*/
238		template<typename T>
239		concept ConstBufferSequence =
240		std::is_convertible_v<T, const_buffer> \|\| (
241		std::ranges::bidirectional_range<T> &&
242		std::is_convertible_v<std::ranges::range_value_t<T>, const_buffer>);
243
244		/** Requires a type to convert to `mutable_buffer`, or be a range of such buffers.
245
246		A type satisfies `MutableBufferSequence` if it represents one or more
247		contiguous memory regions that can be written. This includes single
248		buffers (convertible to `mutable_buffer`) and ranges of buffers.
249
250		This does not imply `ConstBufferSequence`. A type reaching
251		`mutable_buffer` through its own conversion operator would need a
252		second conversion, to `const_buffer`. An implicit conversion
253		sequence allows only one user-defined step.
254
255		@par Syntactic Requirements
256		@li Convertible to `mutable_buffer`, OR
257		@li A bidirectional range with value type convertible to `mutable_buffer`
258
259		@see mutable_buffer, ConstBufferSequence
260		*/
261		template<typename T>
262		concept MutableBufferSequence =
263		std::is_convertible_v<T, mutable_buffer> \|\| (
264		std::ranges::bidirectional_range<T> &&
265		std::is_convertible_v<std::ranges::range_value_t<T>, mutable_buffer>);
266
267		/** Return an iterator to the first buffer in a sequence.
268
269		@functionobject
270		*/
271		constexpr struct
272		{
273		/** Return a pointer to a single buffer, forming a one-element range.
274
275		@param b A single buffer.
276
277		@return A pointer to `b`.
278		*/
279		template<std::convertible_to<const_buffer> ConvertibleToBuffer>
280	6664x	auto operator()(ConvertibleToBuffer const& b) const noexcept -> ConvertibleToBuffer const*
281		{
282	6664x	return std::addressof(b);
283		}
284
285		/** Return an iterator to the first buffer of a sequence.
286
287		@param bs The buffer sequence.
288
289		@return An iterator to the first buffer of `bs`.
290		*/
291		template<ConstBufferSequence BS>
292		requires (!std::convertible_to<BS, const_buffer>)
293	33709x	auto operator()(BS const& bs) const noexcept
294		{
295	33709x	return std::ranges::begin(bs);
296		}
297
298		/** Return an iterator to the first buffer of a sequence.
299
300		@param bs The buffer sequence.
301
302		@return An iterator to the first buffer of `bs`.
303		*/
304		template<ConstBufferSequence BS>
305		requires (!std::convertible_to<BS, const_buffer>)
306	9193x	auto operator()(BS& bs) const noexcept
307		{
308	9193x	return std::ranges::begin(bs);
309		}
310		} begin {};
311
312		/** Return an iterator past the last buffer in a sequence.
313
314		@functionobject
315		*/
316		constexpr struct
317		{
318		/** Return a pointer one past a single buffer, forming a one-element range.
319
320		@param b A single buffer.
321
322		@return A pointer one past `b`.
323		*/
324		template<std::convertible_to<const_buffer> ConvertibleToBuffer>
325	6666x	auto operator()(ConvertibleToBuffer const& b) const noexcept -> ConvertibleToBuffer const*
326		{
327	6666x	return std::addressof(b) + 1;
328		}
329
330		/** Return an iterator past the last buffer of a sequence.
331
332		@param bs The buffer sequence.
333
334		@return An iterator one past the last buffer of `bs`.
335		*/
336		template<ConstBufferSequence BS>
337		requires (!std::convertible_to<BS, const_buffer>)
338	33731x	auto operator()(BS const& bs) const noexcept
339		{
340	33731x	return std::ranges::end(bs);
341		}
342
343		/** Return an iterator past the last buffer of a sequence.
344
345		@param bs The buffer sequence.
346
347		@return An iterator one past the last buffer of `bs`.
348		*/
349		template<ConstBufferSequence BS>
350		requires (!std::convertible_to<BS, const_buffer>)
351	9193x	auto operator()(BS& bs) const noexcept
352		{
353	9193x	return std::ranges::end(bs);
354		}
355		} end {};
356
357		/** Return the total byte count across all buffers in a sequence.
358
359		@functionobject
360		*/
361		constexpr struct
362		{
363		// GCC 13 falsely flags reads of arr_[i].n_ in detail::buffer_array
364		// when iterating here. The class uses union storage with placement
365		// new for slots 0..n_-1, so reads inside this bounded loop are
366		// well-defined, but the optimizer can't prove the loop bound and
367		// warns. The runtime cost of value-initializing all N slots is
368		// non-trivial for non-trivial value types, so we suppress instead.
369		#if defined(__GNUC__) && !defined(__clang__)
370		#pragma GCC diagnostic push
371		#pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
372		#endif
373		/** Return the total byte count across all buffers in a sequence.
374
375		Sums the `size()` of each buffer in the sequence. This differs
376		from `buffer_length` which counts the number of buffer elements.
377
378		@param bs The buffer sequence.
379
380		@return The sum of the sizes of all buffers in `bs`.
381
382		@par Example
383		@code
384		std::array<mutable_buffer, 2> bufs = { ... };
385		std::size_t total = buffer_size( bufs ); // sum of both sizes
386		@endcode
387		*/
388		template<ConstBufferSequence CB>
389	6296x	constexpr std::size_t operator()(
390		CB const& bs) const noexcept
391		{
392	6296x	std::size_t n = 0;
393	6296x	auto const e = capy::end(bs);
394	14520x	for(auto it = capy::begin(bs); it != e; ++it)
395	8224x	n += const_buffer(*it).size();
396	6296x	return n;
397		}
398		#if defined(__GNUC__) && !defined(__clang__)
399		#pragma GCC diagnostic pop
400		#endif
401		} buffer_size {};
402
403		/** Check if a buffer sequence contains no data.
404
405		@functionobject
406		*/
407		constexpr struct
408		{
409		// See note on buffer_size above — same union-storage false positive.
410		#if defined(__GNUC__) && !defined(__clang__)
411		#pragma GCC diagnostic push
412		#pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
413		#endif
414		/** Check if a buffer sequence contains no data.
415
416		@param bs The buffer sequence.
417
418		@return `true` if all buffers have size zero or the sequence
419		is empty.
420		*/
421		template<ConstBufferSequence CB>
422	1584x	constexpr bool operator()(
423		CB const& bs) const noexcept
424		{
425	1584x	auto it = begin(bs);
426	1584x	auto const end_ = end(bs);
427	1632x	while(it != end_)
428		{
429	1596x	const_buffer b(*it++);
430	1596x	if(b.size() != 0)
431	1548x	return false;
432		}
433	36x	return true;
434		}
435		#if defined(__GNUC__) && !defined(__clang__)
436		#pragma GCC diagnostic pop
437		#endif
438		} buffer_empty {};
439
440		namespace detail {
441
442		template<class It>
443		auto
444	11x	length_impl(It first, It last, int)
445		-> decltype(static_cast<std::size_t>(last - first))
446		{
447	11x	return static_cast<std::size_t>(last - first);
448		}
449
450		template<class It>
451		std::size_t
452		length_impl(It first, It last, long)
453		{
454		std::size_t n = 0;
455		while(first != last)
456		{
457		++first;
458		++n;
459		}
460		return n;
461		}
462
463		} // detail
464
465		/** Return the number of buffer elements in a sequence.
466
467		Counts the number of individual buffer objects, not bytes.
468		For a single buffer, returns 1. For a range, returns the
469		distance from `begin` to `end`.
470
471		@param bs The buffer sequence.
472
473		@return The number of buffers in `bs`.
474
475		@see buffer_size
476		*/
477		template<ConstBufferSequence CB>
478		std::size_t
479	11x	buffer_length(CB const& bs)
480		{
481	11x	return detail::length_impl(
482	11x	begin(bs), end(bs), 0);
483		}
484
485		/// Names `mutable_buffer` for a mutable sequence, `const_buffer` otherwise.
486		template<typename BS>
487		using buffer_type = std::conditional_t<
488		MutableBufferSequence<BS>,
489		mutable_buffer, const_buffer>;
490
491		} // capy
492		} // boost
493
494		#endif
495