#include <MemSpan.h>

Inheritance diagram for swoc::MemSpan< T >:

Collaboration diagram for swoc::MemSpan< T >:

Public Types
using	value_type = T
	Element type for span.

using	iterator = T *
	Iterator.

using	const_iterator = T const *
	Constant iterator.

Public Member Functions
constexpr	MemSpan ()=default
	Default constructor (empty buffer).

constexpr	MemSpan (self_type const &that)=default
	Copy constructor.

constexpr	MemSpan (self_type &that)=default
	Copy constructor.

constexpr	MemSpan (value_type *ptr, size_t count)

constexpr	MemSpan (value_type begin, value_type end)

template<auto N>
constexpr	MemSpan (T(&a)[N])

template<auto N, typename U, typename META = std::enable_if_t<std::conjunction_v<std::is_const<T>, std::is_same<std::remove_const_t<U>, std::remove_const_t<T>>>>>
constexpr	MemSpan (std::array< U, N > const &a)

template<auto N>
constexpr	MemSpan (std::array< T, N > &a)

template<typename U, typename META = std::enable_if_t<std::conjunction_v<std::is_const<T>, std::is_same<U, std::remove_const_t<T>>>>>
constexpr	MemSpan (MemSpan< U > const &that)

template<typename C, typename = std::enable_if_t<std::is_convertible_v<decltype(std::declval<C>().data()), T *> && std::is_convertible_v<decltype(std::declval<C>().size()), size_t>>
constexpr	MemSpan (C &c)

template<typename C, typename = std::enable_if_t<std::is_convertible_v<decltype(std::declval<C>().data()), T *> && std::is_convertible_v<decltype(std::declval<C>().size()), size_t>>
constexpr	MemSpan (C const &c)

constexpr	MemSpan (std::nullptr_t)

constexpr bool	operator== (self_type const &that) const

bool	is_same (self_type const &that) const

constexpr bool	operator!= (self_type const &that) const

self_type &	operator= (self_type const &that)=default
	Assignment - the span is copied, not the content.

T &	operator[] (size_t idx) const
	Access element at index idx.

bool	operator! () const

	operator bool () const

constexpr bool	empty () const

template<typename... Args>
auto	make (Args &&...args) -> self_type &

template<typename U>
constexpr	MemSpan (MemSpan< U > const &that)

template<auto N, typename U>
constexpr	MemSpan (U(&a)[N])

auto	rebind () const -> self_type

Protected Attributes
T *	_ptr = nullptr
	Pointer to base of memory chunk.

size_t	_count = 0
	Number of elements.

Accessors.
constexpr T *	begin () const
	Pointer to the first element in the span.

constexpr T *	end () const
	Pointer to first element not in the span.

constexpr size_t	size () const
	Number of elements in the span.

constexpr size_t	count () const

constexpr size_t	length () const
	Number of elements in the span.

constexpr size_t	data_size () const
	Number of bytes in the span.

T *	data () const

constexpr T *	data_end () const

T &	front ()

T &	back ()

template<typename F>
self_type &	apply (F &&f)

template<typename U = std::conditional_t<std::is_const_v<T>, void const, void>>
MemSpan< U >	rebind () const

self_type &	assign (T *ptr, size_t count)

self_type &	assign (T first, T const last)

self_type &	clear ()
	Clear the span (become an empty span).

bool	contains (value_type const *p) const

constexpr self_type	prefix (size_t count) const

constexpr self_type	first (size_t count) const

self_type &	remove_prefix (size_t count)

self_type	clip_prefix (size_t count)

constexpr self_type	suffix (size_t count) const

constexpr self_type	last (size_t count) const

self_type &	remove_suffix (size_t count)

self_type	clip_suffix (size_t count)

constexpr self_type	subspan (size_t offset, size_t count) const

constexpr self_type &	restrict (size_t n)

template<typename... Args>
self_type &	make (Args &&...args)

void	destroy ()
	Destruct all elements in the span.

Detailed Description

template<typename T>
class swoc::MemSpan< T >

A span of contiguous piece of memory.

A MemSpan does not own the memory to which it refers, it is simply a span of part of some (presumably) larger memory object. It acts as a pointer, not a container - copy and assignment change the span, not the memory to which the span refers.

The purpose is that frequently code needs to work on a specific part of the memory. This can avoid copying or allocation by allocating all needed memory at once and then working with it via instances of this class.

Note: The issue of const correctness is tricky. Because this class is intended as a "smart" pointer, its constancy does not carry over to its elements, just as a constant pointer doesn't make its target constant. This makes it different than containers such as std::array or std::vector. This means when creating an instance based on such containers the constancy of the container affects the element type of the span. E.g.

A std::array<T,N> maps to a MemSpan<T>
A const std::array<T,N> maps to a MemSpan<const T>

For convenience a MemSpan<const T> can be constructed from a MemSpan<T> because this maintains const correctness and models how a T const* can be constructed from a T* .

Definition at line 50 of file MemSpan.h.

Member Typedef Documentation

◆ const_iterator

template<typename T>

using swoc::MemSpan< T >::const_iterator = T const *

Constant iterator.

Definition at line 60 of file MemSpan.h.

◆ iterator

template<typename T>

using swoc::MemSpan< T >::iterator = T *

Iterator.

Definition at line 59 of file MemSpan.h.

◆ value_type

template<typename T>

using swoc::MemSpan< T >::value_type = T

Element type for span.

Definition at line 58 of file MemSpan.h.

Constructor & Destructor Documentation

◆ MemSpan() [1/11]

template<typename T>

swoc::MemSpan< T >::MemSpan	(	value_type *	ptr,
		size_t	count )

inlineconstexpr

Construct from a first element start and a count of elements.

Parameters

start	First element.
count	Total number of elements.

Definition at line 1064 of file MemSpan.h.

◆ MemSpan() [2/11]

template<typename T>

swoc::MemSpan< T >::MemSpan	(	value_type *	begin,
		value_type *	end )

inlineconstexpr

Construct from a half open range [start, last).

Parameters

begin	Start of range.
end	Past end of range.

Definition at line 1066 of file MemSpan.h.

◆ MemSpan() [3/11]

template<typename T>

template<auto N>

swoc::MemSpan< T >::MemSpan ( T(&) a[N] )

constexpr

Construct to cover an array.

Template Parameters

N	Number of elements in the array.

Parameters

a	The array.

Definition at line 1068 of file MemSpan.h.

◆ MemSpan() [4/11]

template<typename T>

template<auto N, typename U, typename META>

swoc::MemSpan< T >::MemSpan ( std::array< U, N > const & a )

constexpr

Construct from constant std::array.

Template Parameters

N	Array size.

Parameters

a	Array instance.

Note: Because the elements in a constant array are constant the span value type must be constant.

Definition at line 1081 of file MemSpan.h.

◆ MemSpan() [5/11]

template<typename T>

template<auto N>

swoc::MemSpan< T >::MemSpan ( std::array< T, N > & a )

constexpr

Construct from a std::array.

Template Parameters

N	Array size.

Parameters

a	Array instance.

Definition at line 1082 of file MemSpan.h.

◆ MemSpan() [6/11]

template<typename T>

template<typename U, typename META = std::enable_if_t<std::conjunction_v<std::is_const<T>, std::is_same<U, std::remove_const_t<T>>>>>

swoc::MemSpan< T >::MemSpan ( MemSpan< U > const & that )

inlineconstexpr

Construct a span of constant values from a span of non-constant.

Template Parameters

U	Span types.
META	Metaprogramming type to control conversion existence.

Parameters

that	Source span.

This enables the standard conversion from non-const to const.

Definition at line 120 of file MemSpan.h.

◆ MemSpan() [7/11]

template<typename T>

template<typename C, typename>

swoc::MemSpan< T >::MemSpan ( C & c )

constexpr

Construct from any vector like container.

Template Parameters

C	Container type.

Parameters

c container

The container type must have the methods data and size which must return values convertible to the pointer type for T and size_t respectively.

Definition at line 1083 of file MemSpan.h.

◆ MemSpan() [8/11]

template<typename T>

template<typename C, typename>

swoc::MemSpan< C, typename >::MemSpan ( C const & c )

constexpr

Construct from any vector like container.

Template Parameters

C	Container type.

Parameters

c container

The container type must have the methods data and size which must return values convertible to the pointer type for T and size_t respectively.

Note: Because the container is passed as a constant reference, this may cause the span type to also be a constant element type.

Definition at line 1086 of file MemSpan.h.

◆ MemSpan() [9/11]

template<typename T>

swoc::MemSpan< T >::MemSpan ( std::nullptr_t )

inlineconstexpr

Construct from nullptr. This implicitly makes the length 0.

Definition at line 1077 of file MemSpan.h.

◆ MemSpan() [10/11]

template<typename T>

template<typename U>

swoc::MemSpan< T >::MemSpan ( MemSpan< U > const & that )

constexpr

Definition at line 1333 of file MemSpan.h.

◆ MemSpan() [11/11]

template<typename T>

template<auto N, typename U>

swoc::MemSpan< T >::MemSpan ( U(&) a[N] )

constexpr

Definition at line 1349 of file MemSpan.h.

Member Function Documentation

◆ apply()

template<typename T>

template<typename F>

MemSpan< T >::self_type & swoc::MemSpan< T >::apply ( F && f )

Apply a function f to every element of the span.

Template Parameters

F	Functor type.

Parameters

f	Functor instance.

Returns: this

Definition at line 1294 of file MemSpan.h.

◆ assign() [1/2]

template<typename T>

auto swoc::MemSpan< T >::assign	(	T *	first,
		T const *	last )

inline

Adjust the span.

Parameters

first	Starting point of the span.
last	Past the end of the span.

Returns: this

Definition at line 1098 of file MemSpan.h.

◆ assign() [2/2]

template<typename T>

auto swoc::MemSpan< T >::assign	(	T *	ptr,
		size_t	count )

inline

Set the span. This is faster but equivalent to constructing a new span with the same arguments and assigning it.

Returns: this.

Parameters

ptr	Buffer start.
count	of elements.

Definition at line 1090 of file MemSpan.h.

◆ back()

template<typename T>

T & swoc::MemSpan< T >::back ( )

Access the last element in the span.

Returns: A reference to the last element in the span.

Definition at line 1287 of file MemSpan.h.

◆ begin()

template<typename T>

T * swoc::MemSpan< T >::begin ( ) const

constexpr

Pointer to the first element in the span.

Definition at line 1148 of file MemSpan.h.

◆ clear()

template<typename T>

auto swoc::MemSpan< T >::clear ( )

inline

Clear the span (become an empty span).

Definition at line 1106 of file MemSpan.h.

◆ clip_prefix()

template<typename T>

auto swoc::MemSpan< T >::clip_prefix ( size_t count )

inline

Remove and return a prefix.

Parameters

count Number of items in the prefix.

Returns: The removed prefix.

count items are removed from the beginning of this and a view of those elements is returned.

Definition at line 1249 of file MemSpan.h.

◆ clip_suffix()

template<typename T>

auto swoc::MemSpan< T >::clip_suffix ( size_t count )

inline

Remove and return a suffix.

Parameters

count Number of items in the suffix.

Returns: The removed suffix.

count items are removed from the end of this and a view of those elements is returned.

Definition at line 1263 of file MemSpan.h.

◆ contains()

template<typename T>

bool swoc::MemSpan< T >::contains ( value_type const * p ) const

inline

Returns: true if the byte at *p is in the span.

Definition at line 1202 of file MemSpan.h.

◆ count()

template<typename T>

size_t swoc::MemSpan< T >::count ( ) const

inlineconstexpr

Number of elements in the span

Note: Deprecate for 1.5.0.

Definition at line 1184 of file MemSpan.h.

◆ data()

template<typename T>

void const * swoc::MemSpan< T >::data ( ) const

inlineconstexpr

Returns: Pointer to memory in the span.

Definition at line 1154 of file MemSpan.h.

◆ data_end()

template<typename T>

void const * swoc::MemSpan< T >::data_end ( ) const

inlineconstexpr

Returns: Pointer to immediate after memory in the span.

Definition at line 1160 of file MemSpan.h.

◆ data_size()

template<typename T>

size_t swoc::MemSpan< T >::data_size ( ) const

inlineconstexpr

Number of bytes in the span.

Definition at line 1196 of file MemSpan.h.

◆ destroy()

template<typename T>

void swoc::MemSpan< T >::destroy ( )

Destruct all elements in the span.

Definition at line 1324 of file MemSpan.h.

◆ empty()

template<typename T>

bool swoc::MemSpan< T >::empty ( ) const

inlineconstexpr

Check for empty span (no content).

See also: operator bool

Definition at line 1142 of file MemSpan.h.

◆ end()

template<typename T>

T * swoc::MemSpan< T >::end ( ) const

constexpr

Pointer to first element not in the span.

Definition at line 1166 of file MemSpan.h.

◆ first()

template<typename T>

auto swoc::MemSpan< T >::first ( size_t count ) const

constexpr

Get the initial segment of count elements.

Returns: An instance that contains the leading count elements of this.

Note: Synonymn for prefix for STL compatibility.

Definition at line 1214 of file MemSpan.h.

◆ front()

template<typename T>

T & swoc::MemSpan< T >::front ( )

Access the first element in the span.

Returns: A reference to the first element in the span.

Definition at line 1281 of file MemSpan.h.

◆ is_same()

template<typename T>

bool swoc::MemSpan< T >::is_same ( self_type const & that ) const

inline

Identical.

Check if the spans refer to the same span of memory.

Returns: true if this and that refer to the same span, false if not.

Definition at line 1114 of file MemSpan.h.

◆ last()

template<typename T>

MemSpan< T > swoc::MemSpan< T >::last ( size_t count ) const

constexpr

Get the trailing segment of count elements.

Parameters

count Number of elements to retrieve.

Returns: An instance that contains the trailing count elements of this.

Note: Synonymn for suffix for STL compatibility.

Definition at line 1236 of file MemSpan.h.

◆ length()

template<typename T>

size_t swoc::MemSpan< T >::length ( ) const

inlineconstexpr

Number of elements in the span.

Definition at line 1190 of file MemSpan.h.

◆ make() [1/2]

template<typename T>

template<typename... Args>

self_type & swoc::MemSpan< T >::make ( Args &&... args )

Construct all elements in the span.

For each element in the span, construct an instance of the span type using the args. If the instances need destruction this must be done explicitly.

◆ make() [2/2]

template<typename T>

template<typename... Args>

auto swoc::MemSpan< T >::make ( Args &&... args ) -> self_type &

Definition at line 1315 of file MemSpan.h.

◆ operator bool()

template<typename T>

swoc::MemSpan< T >::operator bool ( ) const

inlineexplicit

Check for non-empty span.

Returns: true if the span contains bytes.

Definition at line 1136 of file MemSpan.h.

◆ operator!()

template<typename T>

bool swoc::MemSpan< T >::operator! ( ) const

inline

Check for empty span.

Returns: true if the span is empty (no contents), false otherwise.

Definition at line 1132 of file MemSpan.h.

◆ operator!=()

template<typename T>

bool swoc::MemSpan< T >::operator!= ( self_type const & that ) const

inlineconstexpr

Inequality.

Returns: true if that does not refer to the same span as this, false otherwise.

Definition at line 1126 of file MemSpan.h.

◆ operator=()

template<typename T>

auto swoc::MemSpan< T >::operator= ( self_type const & that )

inlineconstexprdefault

Assignment - the span is copied, not the content.

Definition at line 1401 of file MemSpan.h.

◆ operator==()

template<typename T>

bool swoc::MemSpan< T >::operator== ( self_type const & that ) const

inlineconstexpr

Equality.

Compare the span contents.

Returns: true if the contents of that are the same as the content of this, false otherwise.

Definition at line 1120 of file MemSpan.h.

◆ operator[]()

template<typename T>

T & swoc::MemSpan< T >::operator[] ( size_t idx ) const

Access element at index idx.

Definition at line 1172 of file MemSpan.h.

◆ prefix()

template<typename T>

auto swoc::MemSpan< T >::prefix ( size_t count ) const

inlineconstexpr

Get the initial segment of count elements.

Returns: An instance that contains the leading count elements of this.

Definition at line 1208 of file MemSpan.h.

◆ rebind() [1/2]

template<typename T>

template<typename U>

MemSpan< U > swoc::MemSpan< U >::rebind ( ) const

Make a copy of this span on the same memory but of type U.

Template Parameters

U	Type for the created span.

Returns: A MemSpan which contains the same memory as instances of U.

if no type is specified, the default is void or void const according to whether value_type is const.

Definition at line 1304 of file MemSpan.h.

◆ rebind() [2/2]

auto swoc::MemSpan< voidconst >::rebind ( ) const -> self_type

inline

Definition at line 1665 of file MemSpan.h.

◆ remove_prefix()

template<typename T>

auto swoc::MemSpan< T >::remove_prefix ( size_t count )

inline

Shrink the span by removing count leading elements.

Parameters

count The number of elements to remove.

Returns: *this

Definition at line 1220 of file MemSpan.h.

◆ remove_suffix()

template<typename T>

auto swoc::MemSpan< T >::remove_suffix ( size_t count )

inline

Shrink the span by removing count trailing elements.

Parameters

count Number of elements to remove.

Returns: *this

Definition at line 1242 of file MemSpan.h.

◆ restrict()

template<typename T>

auto swoc::MemSpan< T >::restrict ( size_t n )

constexpr

Limit the size of the span.

Parameters

n	Maximum number of elements.

Returns: this

If the number of elements is greater than n, the size is changed to n.

Definition at line 1598 of file MemSpan.h.

◆ size()

template<typename T>

size_t swoc::MemSpan< T >::size ( ) const

inlineconstexpr

Number of elements in the span.

Definition at line 1178 of file MemSpan.h.

◆ subspan()

template<typename T>

auto swoc::MemSpan< T >::subspan	(	size_t	offset,
		size_t	count ) const

inlineconstexpr

Return a sub span of this span.

Parameters

offset	Offset (index) of first element in subspan.
count	Number of elements in the subspan.

Returns: A subspan starting at offset for count elements.

The result is clipped by this - if offset is out of range an empty span is returned. Otherwise count is clipped by the number of elements available in this.

Definition at line 1275 of file MemSpan.h.

◆ suffix()

template<typename T>

auto swoc::MemSpan< T >::suffix ( size_t count ) const

inlineconstexpr

Get the trailing segment of count elements.

Parameters

count Number of elements to retrieve.

Returns: An instance that contains the trailing count elements of this.

Definition at line 1229 of file MemSpan.h.

Friends And Related Symbol Documentation

◆ MemSpan

template<typename T>

template<typename U>

friend class MemSpan

friend

Definition at line 372 of file MemSpan.h.

Member Data Documentation

◆ _count

template<typename T>

size_t swoc::MemSpan< T >::_count = 0

protected

Number of elements.

Definition at line 55 of file MemSpan.h.

◆ _ptr

template<typename T>

T* swoc::MemSpan< T >::_ptr = nullptr

protected

Pointer to base of memory chunk.

Definition at line 54 of file MemSpan.h.

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

MemSpan.h

Public Types

Public Member Functions

Protected Attributes

Accessors.

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ iterator

◆ value_type

Constructor & Destructor Documentation

◆ MemSpan() [1/11]

◆ MemSpan() [2/11]

◆ MemSpan() [3/11]

◆ MemSpan() [4/11]

◆ MemSpan() [5/11]

◆ MemSpan() [6/11]

◆ MemSpan() [7/11]

◆ MemSpan() [8/11]

◆ MemSpan() [9/11]

◆ MemSpan() [10/11]

◆ MemSpan() [11/11]

Member Function Documentation

◆ apply()

◆ assign() [1/2]

◆ assign() [2/2]

of elements.

◆ back()

◆ begin()

◆ clear()

◆ clip_prefix()

◆ clip_suffix()

◆ contains()

◆ count()

◆ data()

◆ data_end()

◆ data_size()

◆ destroy()

◆ empty()

◆ end()

◆ first()

◆ front()

◆ is_same()

◆ last()

◆ length()

◆ make() [1/2]

◆ make() [2/2]

◆ operator bool()

◆ operator!()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ operator[]()

◆ prefix()

◆ rebind() [1/2]

◆ rebind() [2/2]

◆ remove_prefix()

◆ remove_suffix()

◆ restrict()

◆ size()

◆ subspan()

◆ suffix()

Friends And Related Symbol Documentation

◆ MemSpan

Member Data Documentation

◆ _count

◆ _ptr