mbed library sources. Supersedes mbed-src.
Dependents: Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more
Span< ElementType, Extent > Struct Template Reference
[Span class]
Nonowning view to a sequence of contiguous elements. More...
#include <Span.h>
Public Types | |
typedef ElementType | element_type |
Type of the element contained. | |
typedef ptrdiff_t | index_type |
Type of the index. | |
typedef element_type * | pointer |
Pointer to an ElementType. | |
typedef element_type & | reference |
Reference to an ElementType. | |
typedef ElementType | element_type |
Type of the element contained. | |
typedef ptrdiff_t | index_type |
Type of the index. | |
typedef element_type * | pointer |
Pointer to an ElementType. | |
typedef element_type & | reference |
Reference to an ElementType. | |
Public Member Functions | |
Span () | |
Construct an empty Span. | |
Span (pointer ptr, index_type count) | |
Construct a Span from a pointer to a buffer and its size. | |
Span (pointer first, pointer last) | |
Construct a Span from the range [first, last). | |
Span (element_type(&elements)[Extent]) | |
Construct a Span from the reference to an array. | |
template<typename OtherElementType > | |
Span (const Span< OtherElementType, Extent > &other) | |
Construct a Span object from another Span of the same size. | |
index_type | size () const |
Return the size of the sequence viewed. | |
bool | empty () const |
Return if the sequence is empty or not. | |
reference | operator[] (index_type index) const |
Returns a reference to the element at position index . | |
pointer | data () const |
Return a pointer to the first element of the sequence or NULL if the Span is empty(). | |
template<ptrdiff_t Count> | |
Span< element_type, Count > | first () const |
Create a new Span over the first Count elements of the existing view. | |
template<ptrdiff_t Count> | |
Span< element_type, Count > | last () const |
Create a new Span over the last Count elements of the existing view. | |
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. | |
Span< element_type, SPAN_DYNAMIC_EXTENT > | first (index_type count) const |
Create a new Span over the first count elements of the existing view. | |
Span< element_type, SPAN_DYNAMIC_EXTENT > | last (index_type count) const |
Create a new Span over the last count elements of the existing view. | |
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. | |
Span () | |
Construct an empty Span. | |
Span (pointer ptr, index_type count) | |
Construct a Span from a pointer to a buffer and its size. | |
Span (pointer first, pointer last) | |
Construct a Span from the range [first, last). | |
Span (element_type(&elements)[Extent]) | |
Construct a Span from the reference to an array. | |
template<typename OtherElementType > | |
Span (const Span< OtherElementType, Extent > &other) | |
Construct a Span object from another Span of the same size. | |
index_type | size () const |
Return the size of the sequence viewed. | |
bool | empty () const |
Return if the sequence is empty or not. | |
reference | operator[] (index_type index) const |
Returns a reference to the element at position index . | |
pointer | data () const |
Return a pointer to the first element of the sequence or NULL if the Span is empty(). | |
template<ptrdiff_t Count> | |
Span< element_type, Count > | first () const |
Create a new Span over the first Count elements of the existing view. | |
template<ptrdiff_t Count> | |
Span< element_type, Count > | last () const |
Create a new Span over the last Count elements of the existing view. | |
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. | |
Span< element_type, SPAN_DYNAMIC_EXTENT > | first (index_type count) const |
Create a new Span over the first count elements of the existing view. | |
Span< element_type, SPAN_DYNAMIC_EXTENT > | last (index_type count) const |
Create a new Span over the last count elements of the existing view. | |
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. | |
Static Public Attributes | |
static const index_type | extent = Extent |
Size of the Extent; -1 if dynamic. | |
Related Functions | |
(Note that these are not member functions.) | |
const ptrdiff_t | SPAN_DYNAMIC_EXTENT = -1 |
Special value for the Extent parameter of Span. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
const ptrdiff_t | SPAN_DYNAMIC_EXTENT |
Special value for the Extent parameter of Span. |
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);
- 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:
-
ElementType type of objects the Span views. Extent The 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 213 of file cmsis/BUILD/mbed/platform/Span.h.
Member Typedef Documentation
typedef ElementType element_type |
Type of the element contained.
Definition at line 218 of file cmsis/BUILD/mbed/platform/Span.h.
typedef ElementType element_type |
Type of the element contained.
Definition at line 218 of file platform/Span.h.
typedef ptrdiff_t index_type |
Type of the index.
Definition at line 223 of file cmsis/BUILD/mbed/platform/Span.h.
typedef ptrdiff_t index_type |
Type of the index.
Definition at line 223 of file platform/Span.h.
typedef element_type* pointer |
Pointer to an ElementType.
Definition at line 228 of file platform/Span.h.
typedef element_type* pointer |
Pointer to an ElementType.
Definition at line 228 of file cmsis/BUILD/mbed/platform/Span.h.
typedef element_type& reference |
Reference to an ElementType.
Definition at line 233 of file cmsis/BUILD/mbed/platform/Span.h.
typedef element_type& reference |
Reference to an ElementType.
Definition at line 233 of file platform/Span.h.
Constructor & Destructor Documentation
Span | ( | ) |
Construct an empty Span.
- Note:
- This function is not accessible if Extent != SPAN_DYNAMIC_EXTENT or Extent != 0 .
Definition at line 250 of file cmsis/BUILD/mbed/platform/Span.h.
Span | ( | pointer | ptr, |
index_type | count | ||
) |
Construct a Span from a pointer to a buffer and its size.
- Parameters:
-
ptr Pointer to the beginning of the data viewed. count Number of elements viewed.
- Precondition:
- [ptr, ptr + count) must be be a valid range.
- count must be equal to Extent.
Definition at line 271 of file cmsis/BUILD/mbed/platform/Span.h.
Construct a Span from the range [first, last).
- Parameters:
-
first Pointer to the beginning of the data viewed. last End 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.
Definition at line 290 of file cmsis/BUILD/mbed/platform/Span.h.
Span | ( | element_type(&) | elements[Extent] ) |
Construct a Span from the reference to an array.
- Parameters:
-
elements Reference to the array viewed.
Definition at line 308 of file cmsis/BUILD/mbed/platform/Span.h.
Construct a Span object from another Span of the same size.
- Parameters:
-
other The 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 321 of file cmsis/BUILD/mbed/platform/Span.h.
Span | ( | ) |
Construct an empty Span.
- Note:
- This function is not accessible if Extent != SPAN_DYNAMIC_EXTENT or Extent != 0 .
Definition at line 250 of file platform/Span.h.
Span | ( | pointer | ptr, |
index_type | count | ||
) |
Construct a Span from a pointer to a buffer and its size.
- Parameters:
-
ptr Pointer to the beginning of the data viewed. count Number of elements viewed.
- Precondition:
- [ptr, ptr + count) must be be a valid range.
- count must be equal to Extent.
Definition at line 271 of file platform/Span.h.
Construct a Span from the range [first, last).
- Parameters:
-
first Pointer to the beginning of the data viewed. last End 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.
Definition at line 290 of file platform/Span.h.
Span | ( | element_type(&) | elements[Extent] ) |
Construct a Span from the reference to an array.
- Parameters:
-
elements Reference to the array viewed.
Definition at line 308 of file platform/Span.h.
Member Function Documentation
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 374 of file cmsis/BUILD/mbed/platform/Span.h.
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 374 of file platform/Span.h.
bool empty | ( | ) | const |
Return if the sequence is empty or not.
- Returns:
- true if the sequence is empty and false otherwise.
Definition at line 346 of file cmsis/BUILD/mbed/platform/Span.h.
bool empty | ( | ) | const |
Return if the sequence is empty or not.
- Returns:
- true if the sequence is empty and false otherwise.
Definition at line 346 of file platform/Span.h.
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:
-
count The number of element viewed by the new Span.
- Returns:
- A new Span over the first
count
elements.
Definition at line 458 of file cmsis/BUILD/mbed/platform/Span.h.
Span<element_type, Count> first | ( | ) | const |
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:
-
count The number of element viewed by the new Span.
- Returns:
- A new Span over the first
count
elements.
Definition at line 458 of file platform/Span.h.
Span<element_type, Count> first | ( | ) | const |
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:
-
count The number of elements viewed by the new Span.
- Returns:
- A new Span over the last
count
elements.
Definition at line 471 of file platform/Span.h.
Span<element_type, Count> last | ( | ) | const |
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:
-
count The number of elements viewed by the new Span.
- Returns:
- A new Span over the last
count
elements.
Definition at line 471 of file cmsis/BUILD/mbed/platform/Span.h.
Span<element_type, Count> last | ( | ) | const |
reference operator[] | ( | index_type | index ) | const |
Returns a reference to the element at position index
.
- Parameters:
-
index Index of the element to access.
- Returns:
- A reference to the element at the index specified in input.
- Precondition:
- 0 <= index < Extent.
Definition at line 360 of file platform/Span.h.
reference operator[] | ( | index_type | index ) | const |
Returns a reference to the element at position index
.
- Parameters:
-
index Index of the element to access.
- Returns:
- A reference to the element at the index specified in input.
- Precondition:
- 0 <= index < Extent.
Definition at line 360 of file cmsis/BUILD/mbed/platform/Span.h.
index_type size | ( | ) | const |
Return the size of the sequence viewed.
- Returns:
- The size of the sequence viewed.
Definition at line 336 of file platform/Span.h.
index_type size | ( | ) | const |
Return the size of the sequence viewed.
- Returns:
- The size of the sequence viewed.
Definition at line 336 of file cmsis/BUILD/mbed/platform/Span.h.
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:
-
Offset The offset of the first element viewed by the subspan. Count The 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 433 of file cmsis/BUILD/mbed/platform/Span.h.
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:
-
offset The offset of the first element viewed by the subspan. count The 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 492 of file platform/Span.h.
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:
-
Offset The offset of the first element viewed by the subspan. Count The 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 433 of file platform/Span.h.
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:
-
offset The offset of the first element viewed by the subspan. count The 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 492 of file cmsis/BUILD/mbed/platform/Span.h.
Field Documentation
static const index_type extent = Extent [static] |
Size of the Extent; -1 if dynamic.
Definition at line 238 of file cmsis/BUILD/mbed/platform/Span.h.
Generated on Tue Jul 12 2022 20:41:18 by 1.7.2