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);
uint8_t *invalid_value = NULL;
process_mac(invalid_value);
typedef Span<uint8_t, 6> mac_address_t;
void process_mac(mac_address_t);
uint8_t *invalid_value = NULL;
process_mac(invalid_value);
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;
}
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 214 of file Span.h.
