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);
+}
+```