Span: Add example

Author: pan-

docs/reference/api/platform/Span.md

@@ -90,3 +90,57 @@ When you encode the size of the sequence viewed in the Span value, Span instance
 
 [![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)
 
+
+### Span example
+
+```
+template<typename T>
+Span<const T> split(Span<const T> &range, const T& separator) {
+ const ptrdiff_t out_of_range = range.size();
+
+ ptrdiff_t start;
+ for (start = 0; start != out_of_range && range[start] == separator; ++start) { }
+
+ ptrdiff_t last;
+ for (last = start; last != out_of_range && range[last] != separator; ++last) { }
+
+ Span<const T> result = range.subspan(start, last - start);
+ range = range.subspan(last);
+ return result;
+}
+
+Span<const char> buffer("Hello World! Hello mbed-os!");
+while(buffer.empty() == false) {
+ Span<const char> token = split(buffer, ' ');
+ printf("token: %.*s\r\n", token.size(), token.data());
+}
+
+//------------------------------------------------------------------------------
+// Equivalent C-like code
+
+template<typename T>
+void split(const T** in_ptr, ptrdiff_t* in_size, const T** token_ptr, ptrdiff_t* token_size, const T& separator) {
+ const ptrdiff_t out_of_range = *in_size;
+
+ ptrdiff_t start;
+ for (start = 0; start != out_of_range && (*in_ptr)[start] == separator; ++start) { }
+
+ ptrdiff_t last;
+ for (last = start; last != out_of_range && (*in_ptr)[last] != separator; ++last) { }
+
+ *token_ptr = *in_ptr + start;
+ *token_size = last - start;
+
+ *in_size = *in_size - last;
+ *in_ptr = *in_ptr + last;
+}
+
+const char* buffer_ptr = str;
+ptrdiff_t buffer_size = sizeof(str);
+while (buffer_size) {
+ const char* token_ptr = NULL;
+ ptrdiff_t token_size = 0;
+ split(&buffer_ptr, &buffer_size, &token_ptr, &token_size, ' ');
+ printf("token: %.*s\r\n", token_size, token_ptr);
+}
+```