A mutable (modifiable) byte buffer class with convenience methods, internally reference-counted for efficient copying and lifetime management. More...

#include <shared_buffer.hpp>

Public Types
using	byte_vec = std::vector<std::byte>

using	size_type = typename byte_vec::size_type

Public Member Functions
	mutable_shared_buffer (const mutable_shared_buffer &)=default

	mutable_shared_buffer (mutable_shared_buffer &&)=default

mutable_shared_buffer &	operator= (const mutable_shared_buffer &)=default

mutable_shared_buffer &	operator= (mutable_shared_buffer &&)=default

	mutable_shared_buffer () noexcept
	Default construct the `mutable_shared_buffer`.

template<std::size_t Ext>
	mutable_shared_buffer (std::span< const std::byte, Ext > sp)
	Construct by copying from a `std::span` of `std::byte`.

	mutable_shared_buffer (const std::byte *buf, std::size_t sz)
	Construct by copying from a `std::byte` array.

	mutable_shared_buffer (byte_vec &&bv) noexcept
	Move construct from a `std::vector` of `std::bytes`.

	mutable_shared_buffer (size_type sz)
	Construct a `mutable_shared_buffer` with an initial size, contents of each byte set to zero.

template<typename T , std::size_t Ext>
	mutable_shared_buffer (std::span< const T, Ext > sp)
	Construct by copying bytes from a `std::span`.

template<typename T >
	mutable_shared_buffer (const T *buf, size_type num)
	Construct by copying bytes from an arbitrary pointer.

	mutable_shared_buffer (const void *buf, size_type sz)
	Construct by copying bytes from a void pointer.

template<typename InIt >
	mutable_shared_buffer (InIt beg, InIt end)
	Construct from input iterators.

std::byte *	data () noexcept
	Return `std::byte` pointer to beginning of buffer.

const std::byte *	data () const noexcept
	Return `const` `std::byte` pointer to beginning of buffer.

size_type	size () const noexcept
	Return size (number of bytes) of buffer.

byte_vec &	get_byte_vec () noexcept
	Return access to underlying `std::vector`.

bool	empty () const noexcept
	Query to see if size is zero.

void	clear () noexcept
	Clear the internal contents back to an empty state.

void	resize (size_type sz)
	Resize internal buffer.

void	swap (mutable_shared_buffer &rhs) noexcept
	Swap with the contents of another `mutable_shared_buffer` object.

mutable_shared_buffer &	append (const std::byte *buf, std::size_t sz)
	Append a `std::byte` buffer to the end of the internal buffer.

template<std::size_t Ext>
mutable_shared_buffer &	append (std::span< const std::byte, Ext > sp)
	Append a `std::span` of `std::bytes` to the end of the internal buffer.

template<typename T >
mutable_shared_buffer &	append (const T *buf, std::size_t num)
	Append by copying bytes from an arbitrary pointer.

mutable_shared_buffer &	append (const void *buf, size_type sz)
	Append by copying bytes from a void pointer.

template<typename T , std::size_t Ext>
mutable_shared_buffer &	append (std::span< const T, Ext > sp)
	Append a `std::span` that is a non `std::byte` buffer.

mutable_shared_buffer &	append (const mutable_shared_buffer &rhs)
	Append the contents of another `mutable_shared_buffer` to the end.

mutable_shared_buffer &	operator+= (const mutable_shared_buffer &rhs)
	Append the contents of another `mutable_shared_buffer` to the end.

mutable_shared_buffer &	append (std::byte b)
	Append a single `std::byte` to the end.

mutable_shared_buffer &	operator+= (std::byte b)
	Append a single `std::byte` to the end.

bool	operator== (const mutable_shared_buffer &rhs) const noexcept
	Compare two `mutable_shared_buffer` objects for internal buffer byte-by-byte equality.

auto	operator<=> (const mutable_shared_buffer &rhs) const noexcept
	Compare two `mutable_shared_buffer` objects for internal buffer byte-by-byte spaceship operator ordering.

Friends
class	const_shared_buffer

bool	operator== (const mutable_shared_buffer &lhs, const const_shared_buffer &rhs)
	Compare a `mutable_shared_buffer` object with a `const_shared_buffer` for internal buffer byte-by-byte equality.

bool	operator== (const const_shared_buffer &lhs, const mutable_shared_buffer &rhs)
	Compare a `const_shared_buffer` object with a `mutable_shared_buffer` for internal buffer byte-by-byte equality.

Detailed Description

A mutable (modifiable) byte buffer class with convenience methods, internally reference-counted for efficient copying and lifetime management.

This class provides ownership, copying, and lifetime management for byte oriented buffers. In particular, it is designed to be used in conjunction with the const_shared_buffer class for efficient transfer and correct lifetime management of buffers in asynchronous libraries (such as Asio). In particular, a reference counted buffer can be passed among multiple layers of software without any one layer "owning" the buffer.

A std::byte pointer returned by the data method may be invalidated if the mutable_shared_buffer is modified in any way (this follows the usual constraints on std::vector iterator invalidation).

This class is similar to const_shared_buffer, but with mutable characteristics.

Invariant: There will always be an internal buffer of data, even if the size is zero.

Note: Modifying the underlying buffer of data (for example by writing bytes using the data method, or appending data) will show up in any other mutable_shared_buffer objects that have been copied to or from the original object.

Constructor & Destructor Documentation

◆ mutable_shared_buffer() [1/8]

template<std::size_t Ext>

chops::mutable_shared_buffer::mutable_shared_buffer ( std::span< const std::byte, Ext > sp )

inlineexplicit

Construct by copying from a std::span of std::byte.

Parameters

sp	`std::byte` span pointing to buffer of data. The data is copied into the internal buffer of the `mutable_shared_buffer`.

◆ mutable_shared_buffer() [2/8]

chops::mutable_shared_buffer::mutable_shared_buffer	(	const std::byte *	buf,
		std::size_t	sz )

inline

Construct by copying from a std::byte array.

A std::span is first created, then the constructor taking a std::span is called.

Precondition: Size cannot be greater than the source buffer.

Parameters

buf	Non-null pointer to a `std::byte` buffer of data. The data is copied into the internal buffer of the `mutable_shared_buffer`.
sz	Size of buffer.

◆ mutable_shared_buffer() [3/8]

chops::mutable_shared_buffer::mutable_shared_buffer ( byte_vec && bv )

inlineexplicitnoexcept

Move construct from a std::vector of std::bytes.

Efficiently construct from a std::vector of std::bytes by moving into a mutable_shared_buffer.

Note: The std::byte std::vector passed in will be left in a "moved from" state (as it typical with move operations).

◆ mutable_shared_buffer() [4/8]

chops::mutable_shared_buffer::mutable_shared_buffer ( size_type sz )

inlineexplicit

Construct a mutable_shared_buffer with an initial size, contents of each byte set to zero.

Allocate zero initialized space which can be overwritten with data as needed. The data method is called to get access to the underlying std::byte buffer.

Parameters

sz	Size for internal `std::byte` buffer.

◆ mutable_shared_buffer() [5/8]

template<typename T , std::size_t Ext>

chops::mutable_shared_buffer::mutable_shared_buffer ( std::span< const T, Ext > sp )

inline

Construct by copying bytes from a std::span.

The type of the span must be convertible to or be layout compatible with std::byte.

Parameters

sp	`std::span` pointing to buffer of data. The `std::span` pointer is cast into a `std::byte` pointer and bytes are then copied.

◆ mutable_shared_buffer() [6/8]

template<typename T >

chops::mutable_shared_buffer::mutable_shared_buffer	(	const T *	buf,
		size_type	num )

inline

Construct by copying bytes from an arbitrary pointer.

The pointer passed into this constructor is cast into a std::byte pointer and bytes are then copied. In particular, this method can be used for char pointers, unsigned char pointers, std::uint8_t pointers, etc. Non character types that are trivially copyable are also allowed, although the usual care must be taken (padding bytes, alignment, etc).

Precondition: Size cannot be greater than the source buffer.

Parameters

buf	Non-null pointer to a contiguous array of data.
num	Number of elements in the array.

Note: For void pointers, see specific constructor taking a void pointer.

◆ mutable_shared_buffer() [7/8]

chops::mutable_shared_buffer::mutable_shared_buffer	(	const void *	buf,
		size_type	sz )

inline

Construct by copying bytes from a void pointer.

The pointer passed into this constructor is cast into a std::byte pointer and bytes are then copied.

Precondition: Size cannot be greater than the source buffer.

Parameters

buf	Non-null `void` pointer to a buffer of data.
sz	Size of buffer, in bytes.

◆ mutable_shared_buffer() [8/8]

template<typename InIt >

chops::mutable_shared_buffer::mutable_shared_buffer	(	InIt	beg,
		InIt	end )

inline

Construct from input iterators.

Precondition: Valid iterator range, where each element is convertible to a std::byte.

Parameters

beg	Beginning input iterator of range.
end	Ending input iterator of range.

Member Function Documentation

◆ append() [1/7]

mutable_shared_buffer & chops::mutable_shared_buffer::append ( const mutable_shared_buffer & rhs )

inline

Append the contents of another mutable_shared_buffer to the end.

Parameters

rhs	`mutable_shared_buffer` to append from.

Returns: Reference to this (to allow method chaining).

◆ append() [2/7]

mutable_shared_buffer & chops::mutable_shared_buffer::append	(	const std::byte *	buf,
		std::size_t	sz )

inline

Append a std::byte buffer to the end of the internal buffer.

Parameters

buf	Non-null pointer to `std::byte` buffer of data.
sz	Size of buffer.

Returns: Reference to this (to allow method chaining).

◆ append() [3/7]

template<typename T >

mutable_shared_buffer & chops::mutable_shared_buffer::append	(	const T *	buf,
		std::size_t	num )

inline

Append by copying bytes from an arbitrary pointer.

The pointer passed into this method is cast into a std::byte pointer and bytes are then copied. In particular, this method can be used for char pointers, void pointers, unsigned char pointers, std::uint8_t pointers, etc. Non character types that are layout compatible with std::byte are allowed.

Parameters

buf	Non-null pointer to an array of data.
num	Number of elements in the array.

◆ append() [4/7]

mutable_shared_buffer & chops::mutable_shared_buffer::append	(	const void *	buf,
		size_type	sz )

inline

Append by copying bytes from a void pointer.

The pointer passed into this constructor is cast into a std::byte pointer and bytes are then appended.

Precondition: Size cannot be greater than the source buffer.

Parameters

buf	Non-null `void` pointer to a buffer of data.
sz	Size of buffer, in bytes.

◆ append() [5/7]

mutable_shared_buffer & chops::mutable_shared_buffer::append ( std::byte b )

inline

Append a single std::byte to the end.

Parameters

b	Byte to append.

Returns: Reference to this (to allow method chaining).

◆ append() [6/7]

template<std::size_t Ext>

mutable_shared_buffer & chops::mutable_shared_buffer::append ( std::span< const std::byte, Ext > sp )

inline

Append a std::span of std::bytes to the end of the internal buffer.

Parameters

sp	`std::span` of `std::byte` data.

Returns: Reference to this (to allow method chaining).

◆ append() [7/7]

template<typename T , std::size_t Ext>

mutable_shared_buffer & chops::mutable_shared_buffer::append ( std::span< const T, Ext > sp )

inline

Append a std::span that is a non std::byte buffer.

The std::span passed into this method is performs a cast on the data. In particular, this method can be used for char pointers, void pointers, @ unsigned char pointers, etc.

The type of the span must be convertible to or be layout compatible with std::byte.

Parameters

sp	`std::span` of arbitrary bytes.

◆ clear()

void chops::mutable_shared_buffer::clear ( )

inlinenoexcept

Clear the internal contents back to an empty state.

This method is handy after a mutable_shared_buffer has been moved into another object (e.g. a const_shared_buffer). At that point the contents are in a consistent but unknown state. Calling clear puts the internal buffer into a known and empty state.

◆ data() [1/2]

const std::byte * chops::mutable_shared_buffer::data ( ) const

inlinenoexcept

Return const std::byte pointer to beginning of buffer.

const method providing pointer access to the beginning of the buffer.

Returns: const std::byte pointer to buffer.

◆ data() [2/2]

std::byte * chops::mutable_shared_buffer::data ( )

inlinenoexcept

Return std::byte pointer to beginning of buffer.

This method provides pointer access to the beginning of the buffer. If the buffer is empty the pointer cannot be dereferenced or undefined behavior will occur.

Accessing past the end of the internal buffer (as defined by the size() method) results in undefined behavior.

Returns: std::byte pointer to buffer.

◆ empty()

bool chops::mutable_shared_buffer::empty ( ) const

inlinenoexcept

Query to see if size is zero.

Returns: true if empty (size equals zero).

◆ get_byte_vec()

byte_vec & chops::mutable_shared_buffer::get_byte_vec ( )

inlinenoexcept

Return access to underlying std::vector.

This can be used to instantiate a dynamic_buffer as defined in the Networking TS or Asio API. Changing the std::vector from outside this class works because no state data is stored within this object that needs to be consistent with the std::vector contents.

Returns: Reference to std::vector<std::byte>.

◆ operator+=() [1/2]

mutable_shared_buffer & chops::mutable_shared_buffer::operator+= ( const mutable_shared_buffer & rhs )

inline

Append the contents of another mutable_shared_buffer to the end.

See append method for details.

◆ operator+=() [2/2]

mutable_shared_buffer & chops::mutable_shared_buffer::operator+= ( std::byte b )

inline

Append a single std::byte to the end.

See append method (single std::byte) for details.

◆ operator<=>()

auto chops::mutable_shared_buffer::operator<=> ( const mutable_shared_buffer & rhs ) const

inlinenoexcept

Compare two mutable_shared_buffer objects for internal buffer byte-by-byte spaceship operator ordering.

Internally this invokes the std::vector <=> on std::byte elements.

Returns: Spaceship operator comparison result.

◆ operator==()

bool chops::mutable_shared_buffer::operator== ( const mutable_shared_buffer & rhs ) const

inlinenoexcept

Compare two mutable_shared_buffer objects for internal buffer byte-by-byte equality.

Internally this invokes the std::vector operator== on std::byte elements.

Returns: true if size() same for each, and each byte compares true.

◆ resize()

void chops::mutable_shared_buffer::resize ( size_type sz )

inline

Resize internal buffer.

Parameters

sz	New size for buffer. If the buffer is expanded, new bytes are added, each zero initialized. The size can also be contracted. `resize` does not destroy old data in the internal buffer, so `clear` may need to be called first.

Resizing to zero results in an empty buffer, although calling clear is preferred.

◆ size()

size_type chops::mutable_shared_buffer::size ( ) const

inlinenoexcept

Return size (number of bytes) of buffer.

Returns: Size of buffer, which may be zero.

Friends And Related Symbol Documentation

◆ operator== [1/2]

bool operator==	(	const const_shared_buffer &	lhs,
		const mutable_shared_buffer &	rhs )

friend

Compare a const_shared_buffer object with a mutable_shared_buffer for internal buffer byte-by-byte equality.

Returns: true if size() same for each, and each byte compares true.

◆ operator== [2/2]

bool operator==	(	const mutable_shared_buffer &	lhs,
		const const_shared_buffer &	rhs )

friend

Compare a mutable_shared_buffer object with a const_shared_buffer for internal buffer byte-by-byte equality.

Returns: true if size() same for each, and each byte compares true.

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

/github/workspace/include/buffer/shared_buffer.hpp

Public Types

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ mutable_shared_buffer() [1/8]

◆ mutable_shared_buffer() [2/8]

◆ mutable_shared_buffer() [3/8]

◆ mutable_shared_buffer() [4/8]

◆ mutable_shared_buffer() [5/8]

◆ mutable_shared_buffer() [6/8]

◆ mutable_shared_buffer() [7/8]

◆ mutable_shared_buffer() [8/8]

Member Function Documentation

◆ append() [1/7]

◆ append() [2/7]

◆ append() [3/7]

◆ append() [4/7]

◆ append() [5/7]

◆ append() [6/7]

◆ append() [7/7]

◆ clear()

◆ data() [1/2]

◆ data() [2/2]

◆ empty()

◆ get_byte_vec()

◆ operator+=() [1/2]

◆ operator+=() [2/2]

◆ operator<=>()

◆ operator==()

◆ resize()

◆ size()

Friends And Related Symbol Documentation

◆ operator== [1/2]

◆ operator== [2/2]