Overview

Represents a mutable view of a contiguous block of bytes.

An empty() Buf has no bytes (size() == 0). A null Buf has no bytes, its base_size() is 0, and its base() and data() are nullptr. A Buf is null when default-constructed, moved-from, reset, or when allocation fails.

An empty Buf is not necessarily null (for example, if it was created with Buf::ZeroLength() or sliced or truncated to length 0), in which case base() and data() return non-null pointers and base_size() returns the base allocation size.

Nullness can be checked via comparison to nullptr (buf == nullptr, buf != nullptr). operator bool is not provided to prevent confusion between nullness and emptiness.

Public Types
using	value_type = std::byte

using	size_type = size_t

using	difference_type = ptrdiff_t

using	pointer = std::byte *

using	reference = std::byte &

using	const_pointer = const std::byte *

using	const_reference = const std::byte &

using	iterator = containers::PtrIterator< Buf >

using	const_iterator = containers::ConstPtrIterator< Buf >

Public Member Functions
constexpr	Buf ()
	Constructs a null `Buf`.

constexpr	Buf (std::nullptr_t) noexcept
	Constructs a null `Buf`.

template<typename T , typename = std::enable_if_t<std::is_integral_v<T>>>
	Buf (T)=delete

constexpr	Buf (Buf &&other) noexcept

	Buf (UniquePtr< std::byte[]> &&buffer)

	Buf (UniquePtr< std::byte[]> &&buffer, size_t offset)

	Buf (UniquePtr< std::byte[]> &&buffer, size_t offset, size_t size)
	Constructs an owned `Buf` from a `UniquePtr`, offset, and size.

constexpr	Buf (std::byte *allocation, size_t size, Deallocator &deallocator)
	Constructs an owned `Buf` from a raw buffer, size, and deallocator.

constexpr	Buf (std::byte *allocation, size_t offset, size_t size, Deallocator &deallocator)

	Buf (const Buf &)=delete

	~Buf ()
	Destructor. Releases the owned memory (if any) back to the allocator.

Buf &	operator= (Buf &&other) noexcept

Buf &	operator= (const Buf &)=delete

Buf &	operator= (std::nullptr_t) noexcept

template<typename T , typename = std::enable_if_t<std::is_integral_v<T>>>
Buf &	operator= (T)=delete
	Integers cannot be assigned to a `Buf`, not even the literal `0`.

	operator bool () const =delete

const_reference	operator[] (size_t index) const
	Accesses the byte at the specified index as read-only.

reference	operator[] (size_t index)
	Accesses the byte at the specified index as mutable.

constexpr const_pointer	data () const

constexpr pointer	data ()

constexpr size_t	size () const
	Returns the size of the buffer.

constexpr bool	empty () const

constexpr const std::byte *	base () const

constexpr size_t	base_size () const

constexpr size_t	prefix_size () const

constexpr size_t	suffix_size () const

constexpr bool	sliced () const

constexpr bool	owned () const

constexpr Deallocator *	deallocator () const

const_iterator	begin () const
	Returns a read-only iterator pointing to the beginning of the data.

const_iterator	end () const
	Returns a read-only iterator pointing past the end of the data.

const_iterator	cbegin () const
	Returns a read-only iterator pointing to the beginning of the data.

const_iterator	cend () const
	Returns a read-only iterator pointing past the end of the data.

iterator	begin ()
	Returns a mutable iterator pointing to the beginning of the data.

iterator	end ()
	Returns a mutable iterator pointing past the end of the data.

void	reset ()
	Frees the owned memory (if any) and sets the buffer to null.

void	swap (Buf &other) noexcept
	Exchanges the contents of this `Buf` with `other`.

Static Public Member Functions
static Buf	ZeroLength () noexcept

static Buf	Unowned (ByteSpan span, size_t offset, size_t size)
	Creates an unowned `Buf` from a `ByteSpan`, offset, and size.

static Buf	Unowned (ByteSpan span, size_t offset=0)

static Buf	Unowned (std::byte *base, size_t offset, size_t size)
	Creates an unowned `Buf` from a pointer, offset, and size.

static Buf	Unowned (std::byte *base, size_t size)
	Creates an unowned `Buf` from a pointer and size.

static Buf	Allocate (Allocator &allocator, size_t size_bytes)

static Buf	AllocateFill (Allocator &allocator, size_t size_bytes, std::byte value=std::byte{0})

static Buf	AllocateCopy (Allocator &allocator, ConstByteSpan data)

static Buf	AllocateCopy (Allocator &allocator, const std::byte *data, size_t size_bytes)

static Buf	TryAllocate (Allocator &allocator, size_t size_bytes)

static Buf	TryAllocateFill (Allocator &allocator, size_t size_bytes, std::byte value=std::byte{0})

static Buf	TryAllocateCopy (Allocator &allocator, ConstByteSpan data)

static Buf	TryAllocateCopy (Allocator &allocator, const std::byte *data, size_t size_bytes)

Friends
constexpr bool	operator== (const Buf &lhs, std::nullptr_t) noexcept

constexpr bool	operator== (std::nullptr_t, const Buf &rhs) noexcept

constexpr bool	operator!= (const Buf &lhs, std::nullptr_t) noexcept

constexpr bool	operator!= (std::nullptr_t, const Buf &rhs) noexcept

void	swap (Buf &lhs, Buf &rhs) noexcept
	Exchanges the contents of two `Buf`s.

Buf	Slice (Buf &&buf, size_t offset, size_t length)
	Slices a mutable `Buf` by shifting its start address and setting its size.

Buf	Reclaim (Buf &&buf, size_t prefix_count, size_t suffix_count)

UniquePtr< std::byte[]>	TakeAllocation (Buf &&buf)

Constructor & Destructor Documentation

◆ Buf() [1/4]

template<typename T , typename = std::enable_if_t<std::is_integral_v<T>>>

pw::Buf::Buf ( T )

delete

Integers do not convert to Buf. Without this, the literal 0 would convert through the nullptr_t constructor, so passing 0 where a Buf is expected would silently produce a null buffer.

◆ Buf() [2/4]

constexpr pw::Buf::Buf ( Buf && other )

inlineconstexprnoexcept

Move constructor.

The moved-from Buf is left null.

◆ Buf() [3/4]

pw::Buf::Buf ( UniquePtr< std::byte[]> && buffer )

inlineexplicit

Constructs an owned Buf from a UniquePtr.

If buffer is empty/null, constructs a null Buf.

◆ Buf() [4/4]

constexpr pw::Buf::Buf	(	std::byte *	allocation,
		size_t	offset,
		size_t	size,
		Deallocator &	deallocator
	)

inlineexplicitconstexpr

Constructs an owned Buf from a raw buffer, offset, size, and deallocator.

Member Function Documentation

◆ Allocate()

static Buf pw::Buf::Allocate	(	Allocator &	allocator,
		size_t	size_bytes
	)

static

Allocates a new owned Buf of the specified size, or returns Buf::ZeroLength() (unowned) if size_bytes is 0.

Asserts if allocation fails.

◆ AllocateCopy() [1/2]

static Buf pw::Buf::AllocateCopy	(	Allocator &	allocator,
		const std::byte *	data,
		size_t	size_bytes
	)

static

Allocates a new owned Buf of the specified size and copies from data into it, or returns Buf::ZeroLength() (unowned) if size_bytes is 0.

Asserts if allocation fails.

◆ AllocateCopy() [2/2]

static Buf pw::Buf::AllocateCopy	(	Allocator &	allocator,
		ConstByteSpan	data
	)

inlinestatic

Allocates a new owned Buf the same size as data and copies the contents of data into it, or returns Buf::ZeroLength() (unowned) if data is empty.

Asserts if allocation fails.

◆ AllocateFill()

static Buf pw::Buf::AllocateFill	(	Allocator &	allocator,
		size_t	size_bytes,
		std::byte	value = `std::byte{0}`
	)

static

Allocates a new owned Buf of the specified size and fills it with value, or returns Buf::ZeroLength() (unowned) if size_bytes is 0.

Asserts if allocation fails.

◆ base()

constexpr const std::byte * pw::Buf::base ( ) const

inlineconstexpr

Returns a pointer to the base address of the original, underlying memory buffer, or nullptr if the Buf is null.

◆ base_size()

constexpr size_t pw::Buf::base_size ( ) const

inlineconstexpr

Returns the size of the original, underlying memory buffer, or 0 if the Buf is null.

◆ data() [1/2]

constexpr pointer pw::Buf::data ( )

inlineconstexpr

Returns a pointer to the mutable data, or nullptr if the Buf is null.

Note: An empty Buf that is not null (e.g. sliced or truncated to length 0) returns a non-null pointer. data() is only nullptr when the buffer is null.

◆ data() [2/2]

constexpr const_pointer pw::Buf::data ( ) const

inlineconstexpr

Returns a pointer to the read-only data, or nullptr if the Buf is null.

Note: An empty Buf that is not null (e.g. sliced or truncated to length 0) returns a non-null pointer. data() is only nullptr when the buffer is null.

◆ deallocator()

constexpr Deallocator * pw::Buf::deallocator ( ) const

inlineconstexpr

Returns a pointer to the deallocator if this buffer owns the underlying memory allocation, or nullptr if the buffer is unowned or null.

◆ empty()

constexpr bool pw::Buf::empty ( ) const

inlineconstexpr

Returns true if the buffer is empty (has no bytes).

empty() returns true for both null buffers and non-null buffers of size zero (e.g. after being sliced or truncated to length 0).

◆ operator bool()

pw::Buf::operator bool ( ) const

explicitdelete

operator bool is not provided to prevent confusion between nullness and emptiness. Use buf == nullptr to check for null, or buf.empty() for size 0.

◆ operator=() [1/2]

Buf & pw::Buf::operator= ( Buf && other )

noexcept

Move assignment operator.

The moved-from Buf is left null.

◆ operator=() [2/2]

Buf & pw::Buf::operator= ( std::nullptr_t )

inlinenoexcept

Frees the owned memory (if any) and sets the buffer to null. Same as reset().

◆ owned()

constexpr bool pw::Buf::owned ( ) const

inlineconstexpr

Returns true if this buffer owns the underlying memory allocation (deallocator() != nullptr), or false if the buffer is unowned or null.

◆ prefix_size()

constexpr size_t pw::Buf::prefix_size ( ) const

inlineconstexpr

Returns the number of bytes between base() and data(). These bytes were excluded by slicing and may be recovered with ReclaimPrefix().

◆ sliced()

constexpr bool pw::Buf::sliced ( ) const

inlineconstexpr

Returns true if the Buf views only part of its underlying memory buffer, i.e. it was sliced or truncated, or constructed with an offset.

◆ suffix_size()

constexpr size_t pw::Buf::suffix_size ( ) const

inlineconstexpr

Returns the number of bytes after the end of the data in the underlying memory buffer. These bytes were excluded by slicing or truncating and may be recovered with ReclaimSuffix().

◆ TryAllocate()

static Buf pw::Buf::TryAllocate	(	Allocator &	allocator,
		size_t	size_bytes
	)

static

Allocates a new owned Buf of the specified size, or returns Buf::ZeroLength() (unowned) if size_bytes is 0.

Returns a null Buf if allocation fails.

◆ TryAllocateCopy() [1/2]

static Buf pw::Buf::TryAllocateCopy	(	Allocator &	allocator,
		const std::byte *	data,
		size_t	size_bytes
	)

static

Allocates a new owned Buf of the specified size and copies from data into it, or returns Buf::ZeroLength() (unowned) if size_bytes is 0.

Returns a null Buf if allocation fails.

◆ TryAllocateCopy() [2/2]

static Buf pw::Buf::TryAllocateCopy	(	Allocator &	allocator,
		ConstByteSpan	data
	)

inlinestatic

Allocates a new owned Buf the same size as data and copies the contents of data into it, or returns Buf::ZeroLength() (unowned) if data is empty.

Returns a null Buf if allocation fails.

◆ TryAllocateFill()

static Buf pw::Buf::TryAllocateFill	(	Allocator &	allocator,
		size_t	size_bytes,
		std::byte	value = `std::byte{0}`
	)

static

Allocates a new owned Buf of the specified size and fills it with value, or returns Buf::ZeroLength() (unowned) if size_bytes is 0.

Returns a null Buf if allocation fails.

◆ ZeroLength()

static Buf pw::Buf::ZeroLength ( )

inlinestaticnoexcept

Returns an empty, non-null, unowned Buf (empty() == true, buf != nullptr, owned() == false).

Friends And Related Function Documentation

◆ Reclaim

Buf Reclaim	(	Buf &&	buf,
		size_t	prefix_count,
		size_t	suffix_count
	)

friend

Reclaims prefix_count bytes at the beginning and suffix_count bytes at the end of the buffer.

Precondition: prefix_count cannot exceed buf.prefix_size(), and suffix_count cannot exceed buf.suffix_size().

◆ TakeAllocation

UniquePtr< std::byte[]> TakeAllocation ( Buf && buf )

friend

Transfers ownership of a Buf's underlying memory allocation to a UniquePtr. The Buf is null after this call.

The returned UniquePtr spans the entire base allocation (base() and base_size()), not only the bytes in the current view. To preserve the view, record prefix_size() and size() before calling TakeAllocation(), then pass them to Buf(UniquePtr<std::byte[]>&&, size_t, size_t).

To take sole responsibility for the memory, call Release() on the returned UniquePtr after saving its deallocator() and size().

If the Buf is null, returns a null UniquePtr.

Precondition: buf must be owned (buf.owned()) or null. An unowned Buf has no allocation to take.

The documentation for this class was generated from the following file:

pw_buf/public/pw_buf/buf.h

Overview

Public Types

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

◆ Buf() [1/4]

◆ Buf() [2/4]

◆ Buf() [3/4]

◆ Buf() [4/4]

Member Function Documentation

◆ Allocate()

◆ AllocateCopy() [1/2]

◆ AllocateCopy() [2/2]

◆ AllocateFill()

◆ base()

◆ base_size()

◆ data() [1/2]

◆ data() [2/2]

◆ deallocator()

◆ empty()

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ owned()

◆ prefix_size()

◆ sliced()

◆ suffix_size()

◆ TryAllocate()

◆ TryAllocateCopy() [1/2]

◆ TryAllocateCopy() [2/2]

◆ TryAllocateFill()

◆ ZeroLength()

Friends And Related Function Documentation

◆ Reclaim

◆ TakeAllocation