diff --git a/docs/reference/api/platform/Span.md b/docs/reference/api/platform/Span.md new file mode 100644 index 0000000000..c567d5e04c --- /dev/null +++ b/docs/reference/api/platform/Span.md @@ -0,0 +1,104 @@ +## Span + +A Span is a nonowning view to a sequence of contiguous elements. + +It can replace the traditional pair of pointer and size arguments passed as +array definitions in function calls. + +### Construction + +Span objects can be constructed from a reference to a C++ array, a pointer to the +sequence viewed and its size or the range of the sequence viewed: + +``` +const uint8_t str[] = "Hello mbed!"; + +Span span_from_array(str); +Span span_from_ptr_and_size(str, sizeof(str)); +Span span_from_range(str, str + sizeof(str)); +``` + +### Operations + +Span objects can be copied and assigned like regular value types with the help +of the copy constructor or the copy assignment (=) operator. + +``` +const uint8_t str[] = "Hello mbed!"; + +Span str_span(hello_mbed); +Span copy_constructed_span(str_span); +Span copy_assigned_span; + +copy_assigned_span = str_span; +``` + +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. + +``` +void process_unit(uint8_t); + +void process(const Span &data) +{ + if (data.empty()) { + // nothing to process + return; + } + + for (ptrdiff_t i = 0; i < data.size(); ++i) { + process_unit(data[i]); + } +} +``` + +You can slice Span from the beginning of the sequence (`first()`), from the end +of the sequence (`last()`) or from an arbitrary point in the sequence (`subspan()`). + +``` +const uint8_t str[] = "Hello mbed!"; + +Span str_span(hello_mbed); + +ptrdiff_t half_size = str_span.size() / 2; + +Span first_half = str_span.first(half_size); +Span second_half = str_span.last(half_size); +Span middle_half = str_span.subspan(/* offset */ half_size / 2, half_size); +``` + +### 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`: Span over a sequence of 6 `uint8_t`. + - `Span`: Span over an arbitrary long sequence of `uint8_t`. + +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. + +``` +Span long_span; + +// illegal +Span span_mac_address; +Span from_long_span(long_span); + +// legal +uint8_t mac_address[6] = { }; +Span span_mac_address(mac_address); +long_span = span_mac_address; +``` + +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. + +### Span class reference + +[![View code](https://www.mbed.com/embed/?type=library)](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_span.html) +