C++20 span tutorial
Posted on November 3, 2019 by Paul
According to the latest C++20 draft, a span is a non-owning view over a contiguous sequence of objects. In other words, a std::span is, in essence, a pointer, length pair that gives the user a view into a contiguous sequence of elements. The elements of a span can be, for example, stored in one of the standard library sequential containers (like std::array, std::vector), in a built-in C-style array or in a memory buffer.
Here is a simple example of using std::span as a general interface for a print function that receives as argument a contiguous sequence of integers:
1 // span_0.cpp 2 #include <iostream> 3 #include <vector> 4 #include <array> 5 #include <span> 6 7 void print_content(std::span<int> container) { 8 for(const auto &e : container) { 9 std::cout << e << ' '; 10 } 11 std::cout << '\n'; 12 } 13 14 int main() { 15 int a[]{23, 45, 67, 89}; 16 print_content(a); 17 18 std::vector v{1, 2, 3, 4, 5}; 19 print_content(v); 20 21 std::array a2{-14, 55, 24, 67}; 22 print_content(a2); 23 }This is what I see if I build and run the above file on a Linux machine with Clang 9:
1 $ clang++ -std=c++2a -stdlib=libc++ -Wall -Wextra -pedantic span_0.cpp 2 $ ./a.out 3 23 45 67 89 4 1 2 3 4 5 5 -14 55 24 67 6 $At the time of this writing, you can use std::span with Clang 9 and GCC 10, MSVC doesn’t have support for std::span. If you are using a compiler that doesn’t have support for std::span, you can use a 3rd party implementation like @tcbrindle or use the latest Clang or GCC from Compiler Explorer.
Here is an example of modifying the above program for a C++17 compiler. I assume that you’ve saved the span.hpp header from @tcbrindle in the same folder as your span_0.cpp file:
1 // span_0.cpp 2 #include <iostream> 3 #include <vector> 4 #include <array> 5 6 #if __has_include(<span>) 7 #include <span> 8 #else 9 #include "span.hpp" 10 // UGLY TEMPORARY HACK UNTIL YOUR CURRENT C++ COMPILER INCLUDES std::span SUPPORT 11 namespace std { 12 using tcb::span; 13 } 14 #endif 15 16 17 // ... same code as in the previous exampleWith the above modification, this is how you can build the example with the latest MSVC compiler:
1 C:\DEV> cl /std:c++latest /W4 /permissive- /EHsc span_0.cpp 2 C:\DEV>span_0.exe 3 23 45 67 89 4 1 2 3 4 5 5 -14 55 24 67 6 7 C:\DEV>Please note that while std::span doesn’t own the memory storage of the elements, as in you can’t increase or decrease the memory buffer that stores the elements, you can modify the actual elements, e.g.:
1 // span_1.cpp 2 3 // ... include headers ... 4 5 void print_content(std::span<int> container) { 6 // ... 7 } 8 9 void scale_2x_content(std::span<int> container) { 10 for(auto &e : container) { 11 e *= 2; 12 } 13 } 14 15 int main() { 16 int a[]{23, 45, 67, 89}; 17 scale_2x_content(a); 18 print_content(a); 19 20 std::vector v{1, 2, 3, 4, 5}; 21 scale_2x_content(v); 22 print_content(v); 23 24 std::array a2{-14, 55, 24, 67}; 25 scale_2x_content(a2); 26 print_content(a2); 27 }This is what I see, if I build and run the above program:
1 $ clang++ -std=c++2a -stdlib=libc++ -Wall -Wextra -pedantic span_1.cpp 2 $ ./a.out 3 46 90 134 178 4 2 4 6 8 10 5 -28 110 48 134 6 $You can also create a span from a pointer to a memory buffer and a size, e.g. :
1 // span_2.cpp 2 #include <iostream> 3 #include <vector> 4 #include <array> 5 #include <span> 6 #include <memory> 7 8 void print_content(std::span<int> container) { 9 // ... 10 } 11 12 void scale_2x_content(std::span<int> container) { 13 // ... 14 } 15 16 int main() { 17 18 // ... 19 20 // Allocate space for 10 integers on the heap 21 size_t sz{10}; 22 auto p = std::make_unique<int[]>(sz); 23 // Fill the previously allocated space 24 for(size_t i = 0; i < sz; ++i) { 25 p[i] = static_cast<int>(i); 26 } 27 // Pass a pointer/size pair to functions allow a std::span as the first argument 28 scale_2x_content({p.get(), sz}); 29 print_content({p.get(), sz}); 30 }This is what I see, if I build and run the above program:
1 $ clang++ -std=c++2a -stdlib=libc++ -Wall -Wextra -pedantic span_2.cpp 2 $ ./a.out 3 46 90 134 178 4 2 4 6 8 10 5 -28 110 48 134 6 0 2 4 6 8 10 12 14 16 18 7 $You can also create subviews, or subspans, from a span and operate on these. Keep in mind that when you modify a span or a subspan element you are actually modifying the original data, e.g.:
1 // span_3.cpp 2 #include <iostream> 3 #include <span> 4 #include <iterator> 5 6 void print_content(std::span<int> container) { 7 // ... 8 } 9 10 void scale_2x_content(std::span<int> container) { 11 // ... 12 } 13 14 int main() { 15 int a[]{44, -15, 45, 67, 89, 66}; 16 std::cout << "Original data:\n"; 17 print_content(a); 18 19 // Create a span from a C-style array 20 std::span s1{a, std::size(a)}; 21 22 // Double the subview/subspan elements created from the first 4 elements 23 // of the above s1 span 24 scale_2x_content(s1.first(4)); 25 std::cout << "Double the first 4 elements:\n"; 26 print_content(a); 27 28 // Double the subview/subspan elements created from the last 3 elements 29 // of the above s1 span 30 scale_2x_content(s1.last(3)); 31 std::cout << "Double the last 3 elements:\n"; 32 print_content(a); 33 }This is what you should see, if you build and run the above code:
1 $ clang++ -std=c++2a -stdlib=libc++ -Wall -Wextra -pedantic span_3.cpp 2 $ ./a.out 3 Original data: 4 44 -15 45 67 89 66 5 Double the first 4 elements: 6 88 -30 90 134 89 66 7 Double the last 3 elements: 8 88 -30 90 268 178 132 9 $Say that you want to sort a subspan from an existing contiguous sequence of integers. Here is an example of creating a subspan from an existing C-array, taking a subspan from the above span, without the first and the last elements and sorting the selected subspan:
1 // span_4.cpp 2 #include <iostream> 3 #include <span> 4 #include <iterator> 5 #include <algorithm> 6 7 void print_content(std::span<int> container) { 8 // ... 9 } 10 11 int main() { 12 int a[]{44, 45, -15, 89, 6, 66}; 13 std::cout << "Original data:\n"; 14 print_content(a); 15 16 // Create a span from a C-style array 17 std::span s1{a, std::size(a)}; 18 19 // Create and print a subspan from the above s1 span 20 // without the first and last elements: 21 std::span s2{s1.subspan(1, s1.size() - 2)}; 22 std::cout << "Subspan/subview from the original data without the first and last elements:\n"; 23 print_content(s2); 24 25 // Sort the s2 subspan and print the sorted subspan and the original data: 26 std::sort(s2.begin(), s2.end()); 27 std::cout << "Sorted subspan:\n"; 28 print_content(s2); 29 std::cout << "Original data, partially sorted:\n"; 30 print_content(a); 31 }This is what you should see, if you build and run the above code:
1 $ clang++ -std=c++2a -stdlib=libc++ -Wall -Wextra -pedantic span_4.cpp 2 $ ./a.out 3 Original data: 4 44 45 -15 89 6 66 5 Subspan/subview from the original data without the first and last elements: 6 45 -15 89 6 7 Sorted subspan: 8 -15 6 45 89 9 Original data, partially sorted: 10 44 -15 6 45 89 66 11 $As a side note, don’t confuse C++17 std::string_view with the std::span introduced by C++20. While both are non-owning views, std::string_view is a read-only view.
You can, obviously, create a modifiable span or subspan from a std::string or from a char pointer and a buffer size pair. Here is a simple example, that works only for ASCII strings:
1 // span_5.cpp 2 #include <iostream> 3 #include <span> 4 #include <string> 5 #include <cctype> 6 #include <stdexcept> 7 8 void print_content(std::span<char> container) { 9 for(const auto &e : container) { 10 std::cout << e; 11 } 12 std::cout << '\n'; 13 } 14 15 void uppersize(std::span<char> container) { 16 for(auto &e : container) { 17 unsigned char tmp = static_cast<unsigned char>(e); 18 if(tmp > 127) { 19 throw std::runtime_error("Error! Undefined conversion for non ASCII input strings!"); 20 } 21 e = std::toupper(tmp); 22 } 23 } 24 25 int main() { 26 std::string site_name{"Solarian Programmer"}; 27 std::cout << "Original string:\n"; 28 print_content(site_name); 29 std::cout << "Uppersized string:\n"; 30 uppersize(site_name); 31 print_content(site_name); 32 33 std::cout << '\n'; 34 35 char site_subtitle[]{"My programming ramblings"}; 36 std::cout << "Original char*:\n"; 37 print_content(site_subtitle); 38 std::cout << "Uppersized char*:\n"; 39 uppersize(site_subtitle); 40 print_content(site_subtitle); 41 }This is what you should see, if you build and run the above code:
1 $ clang++ -std=c++2a -stdlib=libc++ -Wall -Wextra -pedantic span_5.cpp 2 $ ./a.out 3 Original string: 4 Solarian Programmer 5 Uppersized string: 6 SOLARIAN PROGRAMMER 7 8 Original char*: 9 My programming ramblings 10 Uppersized char*: 11 MY PROGRAMMING RAMBLINGS 12 $You can find the complete source code on the GitHub repository for this article.
If you want to learn more about C++17 I would recommend reading C++17 in Detail by Bartlomiej Filipek:
or, C++17 - The Complete Guide by Nicolai M. Josuttis:
