Mbed OS Reference
Loading...
Searching...
No Matches
Span< ElementType, Extent > Struct Template Reference

Nonowning view to a sequence of contiguous elements. More...

#include <Span.h>

Public Types

typedef ElementType element_type
 Type of the element contained. More...
 
typedef ptrdiff_t index_type
 Type of the index. More...
 
typedef element_typepointer
 Pointer to an ElementType. More...
 
typedef element_typereference
 Reference to an ElementType. More...
 
typedef pointer iterator
 Iterator to an ElementType. More...
 
typedef std::reverse_iterator< iteratorreverse_iterator
 Reverse iterator to an ElementType. More...
 

Public Member Functions

 Span ()
 Construct an empty Span. More...
 
 Span (pointer ptr, index_type count)
 Construct a Span from a pointer to a buffer and its size. More...
 
 Span (pointer first, pointer last)
 Construct a Span from the range [first, last). More...
 
 Span (element_type(&elements)[Extent])
 Construct a Span from the reference to an array. More...
 
template<typename OtherElementType >
 Span (const Span< OtherElementType, Extent > &other)
 Construct a Span object from another Span of the same size. More...
 
index_type size () const
 Return the size of the sequence viewed. More...
 
bool empty () const
 Return if the sequence is empty or not. More...
 
iterator begin () const
 Return an iterator to the first element of the sequence. More...
 
iterator end () const
 Return an iterator to the element following the last element of the sequence. More...
 
reverse_iterator rbegin () const
 Return a reverse_iterator to the first element of the reversed sequence. More...
 
reverse_iterator rend () const
 Return a reverse_iterator to the element following the last element of the reversed sequence. More...
 
reference operator[] (index_type index) const
 Returns a reference to the element at position index. More...
 
pointer data () const
 Return a pointer to the first element of the sequence or NULL if the Span is empty(). More...
 
template<ptrdiff_t Count>
Span< element_type, Count > first () const
 Create a new Span over the first Count elements of the existing view. More...
 
template<ptrdiff_t Count>
Span< element_type, Count > last () const
 Create a new Span over the last Count elements of the existing view. More...
 
template<std::ptrdiff_t Offset, std::ptrdiff_t Count>
Span< element_type, Count==SPAN_DYNAMIC_EXTENT ? Extent - Offset :Count > subspan () const
 Create a subspan that is a view of other Count elements; the view starts at element Offset. More...
 
Span< element_type, SPAN_DYNAMIC_EXTENTfirst (index_type count) const
 Create a new Span over the first count elements of the existing view. More...
 
Span< element_type, SPAN_DYNAMIC_EXTENTlast (index_type count) const
 Create a new Span over the last count elements of the existing view. More...
 
Span< element_type, SPAN_DYNAMIC_EXTENTsubspan (index_type offset, index_type count=SPAN_DYNAMIC_EXTENT) const
 Create a subspan that is a view of other count elements; the view starts at element offset. More...
 

Static Public Attributes

static const index_type extent = Extent
 Size of the Extent; -1 if dynamic. More...
 

Related Functions

(Note that these are not member functions.)

const ptrdiff_t SPAN_DYNAMIC_EXTENT = -1
 Special value for the Extent parameter of Span. More...
 
template<typename T , typename U , ptrdiff_t LhsExtent, ptrdiff_t RhsExtent>
bool operator== (const Span< T, LhsExtent > &lhs, const Span< U, RhsExtent > &rhs)
 Equality operator between two Span objects. More...
 
template<typename T , typename U , ptrdiff_t LhsExtent, ptrdiff_t RhsExtent>
bool operator!= (const Span< T, LhsExtent > &lhs, const Span< U, RhsExtent > &rhs)
 Not equal operator. More...
 
template<typename T , size_t Size>
Span< T, Size > make_Span (T(&elements)[Size])
 Generate a Span from a reference to a C/C++ array. More...
 
template<typename T >
Span< T > make_Span (T *array_ptr, ptrdiff_t array_size)
 Generate a Span from a C/C++ pointer and the size of the array. More...
 
template<size_t Extent, typename T >
Span< const T, Extent > make_const_Span (const T *elements)
 Generate a Span to a const content from a pointer to a C/C++ array. More...
 
template<typename T >
Span< const T > make_const_Span (T *array_ptr, size_t array_size)
 Generate a Span to a const content from a C/C++ pointer and the size of the array. More...
 

Detailed Description

template<typename ElementType, ptrdiff_t Extent = SPAN_DYNAMIC_EXTENT>
struct mbed::Span< ElementType, Extent >

Nonowning view to a sequence of contiguous elements.

Spans encapsulate a pointer to a sequence of contiguous elements and its size into a single object. Span can replace the traditional pair of pointer and size arguments passed as array definitions in function calls.

Operations

Span objects can be copied and assigned like regular value types with the help of the copy constructor or the copy assignment (=) operator.

You can retrieve elements of the object with the subscript ([]) operator. You can access the pointer to the first element of the sequence viewed with data(). The function size() returns the number of elements in the sequence, and empty() informs whether there is any element in the sequence.

You can slice Span from the beginning of the sequence (first()), from the end of the sequence (last()) or from an arbitrary point of the sequence (subspan()).

Size encoding

The size of the sequence can be encoded in the type itself or in the value of the instance with the help of the template parameter Extent:

  • Span<uint8_t, 6>: Span over a sequence of 6 elements.
  • Span<uint8_t>: Span over an arbitrary long sequence.

When the size is encoded in the type itself, it is guaranteed that the Span view is a valid sequence (not empty() and not NULL) - unless Extent equals 0. The type system also prevents automatic conversion from Span of different sizes. Finally, the Span object is internally represented as a single pointer.

When the size of the sequence viewed is encoded in the Span value, Span instances can view an empty sequence. The function empty() helps client code decide whether Span is viewing valid content or not.

Example
  • Encoding fixed size array: Array values in parameter decays automatically to pointer, which leaves room for subtitle bugs:
typedef uint8_t mac_address_t[6];
void process_mac(mac_address_t);
// compile just fine
uint8_t *invalid_value = NULL;
process_mac(invalid_value);
// correct way
typedef Span<uint8_t, 6> mac_address_t;
void process_mac(mac_address_t);
// compilation error
uint8_t *invalid_value = NULL;
process_mac(invalid_value);
// compilation ok
uint8_t valid_value[6];
process_mac(valid_value);
Nonowning view to a sequence of contiguous elements.
Definition: Span.h:215
  • Arbitrary buffer: When dealing with multiple buffers, it becomes painful to keep track of every buffer size and pointer.
const uint8_t options_tag[OPTIONS_TAG_SIZE];
struct parsed_value_t {
uint8_t *header;
uint8_t *options;
uint8_t *payload;
size_t payload_size;
}
parsed_value_t parse(uint8_t *buffer, size_t buffer_size)
{
parsed_value_t parsed_value { 0 };
if (buffer != NULL && buffer_size <= MINIMAL_BUFFER_SIZE) {
return parsed_value;
}
parsed_value.header = buffer;
parsed_value.header_size = BUFFER_HEADER_SIZE;
if (memcmp(buffer + HEADER_OPTIONS_INDEX, options_tag, sizeof(options_tag)) == 0) {
options = buffer + BUFFER_HEADER_SIZE;
payload = buffer + BUFFER_HEADER_SIZE + OPTIONS_SIZE;
payload_size = buffer_size - BUFFER_HEADER_SIZE + OPTIONS_SIZE;
} else {
payload = buffer + BUFFER_HEADER_SIZE;
payload_size = buffer_size - BUFFER_HEADER_SIZE;
}
return parsed_value;
}
//with Span
struct parsed_value_t {
Span<uint8_t> header;
Span<uint8_t> options;
Span<uint8_t> payload;
}
parsed_value_t parse(const Span<uint8_t> &buffer)
{
parsed_value_t parsed_value;
if (buffer.size() <= MINIMAL_BUFFER_SIZE) {
return parsed_value;
}
parsed_value.header = buffer.first(BUFFER_HEADER_SIZE);
if (buffer.subspan<HEADER_OPTIONS_INDEX, sizeof(options_tag)>() == option_tag) {
options = buffer.supspan(parsed_value.header.size(), OPTIONS_SIZE);
}
payload = buffer.subspan(parsed_value.header.size() + parsed_value.options.size());
return parsed_value;
}
Note
You can create Span instances with the help of the function template make_Span() and make_const_Span().
Span<T, Extent> objects can be implicitly converted to Span<T> objects where required.
Template Parameters
ElementTypetype of objects the Span views.
ExtentThe size of the contiguous sequence viewed. The default value SPAN_DYNAMIC_SIZE is special because it allows construction of Span objects of any size (set at runtime).

Definition at line 215 of file Span.h.

Member Typedef Documentation

◆ element_type

typedef ElementType element_type

Type of the element contained.

Definition at line 220 of file Span.h.

◆ index_type

typedef ptrdiff_t index_type

Type of the index.

Definition at line 225 of file Span.h.

◆ pointer

Pointer to an ElementType.

Definition at line 230 of file Span.h.

◆ reference

Reference to an ElementType.

Definition at line 235 of file Span.h.

◆ iterator

typedef pointer iterator

Iterator to an ElementType.

Definition at line 240 of file Span.h.

◆ reverse_iterator

typedef std::reverse_iterator<iterator> reverse_iterator

Reverse iterator to an ElementType.

Definition at line 245 of file Span.h.

Constructor & Destructor Documentation

◆ Span() [1/5]

Span ( )

Construct an empty Span.

Postcondition
a call to size() returns 0, and data() returns NULL.
Note
This function is not accessible if Extent != SPAN_DYNAMIC_EXTENT or Extent != 0 .

Definition at line 262 of file Span.h.

◆ Span() [2/5]

Span ( pointer  ptr,
index_type  count 
)

Construct a Span from a pointer to a buffer and its size.

Parameters
ptrPointer to the beginning of the data viewed.
countNumber of elements viewed.
Precondition
[ptr, ptr + count) must be be a valid range.
count must be equal to Extent.
Postcondition
a call to size() returns Extent, and data() returns ptr.

Definition at line 283 of file Span.h.

◆ Span() [3/5]

Span ( pointer  first,
pointer  last 
)

Construct a Span from the range [first, last).

Parameters
firstPointer to the beginning of the data viewed.
lastEnd of the range (element after the last element).
Precondition
[first, last) must be be a valid range.
first <= last.
last - first must be equal to Extent.
Postcondition
a call to size() returns Extent, and data() returns first.

Definition at line 302 of file Span.h.

◆ Span() [4/5]

Span ( element_type(&)  elements[Extent])

Construct a Span from the reference to an array.

Parameters
elementsReference to the array viewed.
Postcondition
a call to size() returns Extent, and data() returns a pointer to elements.

Definition at line 320 of file Span.h.

◆ Span() [5/5]

Span ( const Span< OtherElementType, Extent > &  other)

Construct a Span object from another Span of the same size.

Parameters
otherThe Span object used to construct this.
Note
For Span with a positive extent, this function is not accessible.
OtherElementType(*)[] must be convertible to ElementType(*)[].

Definition at line 333 of file Span.h.

Member Function Documentation

◆ size()

index_type size ( ) const

Return the size of the sequence viewed.

Returns
The size of the sequence viewed.

Definition at line 348 of file Span.h.

◆ empty()

bool empty ( ) const

Return if the sequence is empty or not.

Returns
true if the sequence is empty and false otherwise.

Definition at line 358 of file Span.h.

◆ begin()

iterator begin ( ) const

Return an iterator to the first element of the sequence.

Returns
An iterator to the first element of the sequence.

Definition at line 368 of file Span.h.

◆ end()

iterator end ( ) const

Return an iterator to the element following the last element of the sequence.

Returns
An iterator to the element following the last element of the sequence.

Definition at line 378 of file Span.h.

◆ rbegin()

reverse_iterator rbegin ( ) const

Return a reverse_iterator to the first element of the reversed sequence.

Returns
A reverse_iterator to the first element of the reversed sequence.

Definition at line 388 of file Span.h.

◆ rend()

reverse_iterator rend ( ) const

Return a reverse_iterator to the element following the last element of the reversed sequence.

Returns
A reverse_iterator to the element following the last element of the reversed sequence.

Definition at line 398 of file Span.h.

◆ operator[]()

reference operator[] ( index_type  index) const

Returns a reference to the element at position index.

Parameters
indexIndex of the element to access.
Returns
A reference to the element at the index specified in input.
Precondition
0 <= index < Extent.

Definition at line 412 of file Span.h.

◆ data()

pointer data ( ) const

Return a pointer to the first element of the sequence or NULL if the Span is empty().

Returns
The pointer to the first element of the Span.

Definition at line 426 of file Span.h.

◆ first() [1/2]

Span< element_type, Count > first ( ) const

Create a new Span over the first Count elements of the existing view.

Template Parameters
CountThe number of element viewed by the new Span
Returns
A new Span over the first Count elements.
Precondition
Count >= 0 && Count <= size().

Definition at line 441 of file Span.h.

◆ last() [1/2]

Span< element_type, Count > last ( ) const

Create a new Span over the last Count elements of the existing view.

Template Parameters
CountThe number of element viewed by the new Span.
Returns
A new Span over the last Count elements.
Precondition
Count >= 0 && Count <= size().

Definition at line 460 of file Span.h.

◆ subspan() [1/2]

Span< element_type, Count==SPAN_DYNAMIC_EXTENT ? Extent - Offset :Count > subspan ( ) const

Create a subspan that is a view of other Count elements; the view starts at element Offset.

Template Parameters
OffsetThe offset of the first element viewed by the subspan.
CountThe number of elements present in the subspan. If Count is equal to SPAN_DYNAMIC_EXTENT, then a Span starting at offset and containing the rest of the elements is returned.
Returns
A subspan of this starting at Offset and Count long.

Definition at line 485 of file Span.h.

◆ first() [2/2]

Span< element_type, SPAN_DYNAMIC_EXTENT > first ( index_type  count) const

Create a new Span over the first count elements of the existing view.

Parameters
countThe number of element viewed by the new Span.
Returns
A new Span over the first count elements.

Definition at line 510 of file Span.h.

◆ last() [2/2]

Span< element_type, SPAN_DYNAMIC_EXTENT > last ( index_type  count) const

Create a new Span over the last count elements of the existing view.

Parameters
countThe number of elements viewed by the new Span.
Returns
A new Span over the last count elements.

Definition at line 523 of file Span.h.

◆ subspan() [2/2]

Span< element_type, SPAN_DYNAMIC_EXTENT > subspan ( index_type  offset,
index_type  count = SPAN_DYNAMIC_EXTENT 
) const

Create a subspan that is a view of other count elements; the view starts at element offset.

Parameters
offsetThe offset of the first element viewed by the subspan.
countThe number of elements present in the subspan. If Count is equal to SPAN_DYNAMIC_EXTENT, then a span starting at offset and containing the rest of the elements is returned.
Returns

Definition at line 544 of file Span.h.

Field Documentation

◆ extent

const index_type extent = Extent
static

Size of the Extent; -1 if dynamic.

Definition at line 250 of file Span.h.