{"id":5983,"date":"2020-09-08T18:54:21","date_gmt":"2020-09-08T18:54:21","guid":{"rendered":"https:\/\/www.modernescpp.com\/index.php\/c-20-std-span\/"},"modified":"2024-01-09T11:24:34","modified_gmt":"2024-01-09T11:24:34","slug":"c-20-std-span","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/c-20-std-span\/","title":{"rendered":"std::span in C++20: Bounds-Safe Views for Sequences of Objects"},"content":{"rendered":"

In my seminar, I often hear the question: How can I safely pass a plain array to a function? With C++20, the answer is quite easy: Use a std::span<\/span>.<\/p>\n

<\/p>\n

\"\"<\/p>\n

\u00a0<\/p>\n

A std::span<\/span> is an object that can refer to a contiguous sequence of objects. A std::span<\/span>, sometimes also called a view, is never an owner. This contiguous memory can be a plain array, a pointer with a size, a std::array<\/span>, a std::vector, <\/span>or a std::string<\/span>. A typical implementation consists of a pointer to its first element and a size. The main reason for having a std::span<T><\/span> is that a plain array will decay to a pointer if passed to a function; therefore, the size is lost. This decay is a typical reason for errors in C\/C++.<\/p>\n

Automatically deduces the size of a contiguous sequence of objects<\/h3>\n

In contrast, std:<\/strong>:span<T><\/span> automatically deduces the size of contiguous sequences of objects.<\/span><\/p>\n

\u00a0<\/p>\n

\n
\/\/ printSpan.cpp<\/span>\n\n#include <iostream><\/span>\n#include <vector><\/span>\n#include <array><\/span>\n#include <span><\/span>\n\nvoid<\/span> printMe<\/span>(std::<\/span>span<<\/span>int<\/span>><\/span> container) {\n    \n    std::<\/span>cout <<<\/span> \"container.size(): \"<\/span> <<<\/span> container.size() <<<\/span> '\\n'<\/span>;  \/\/ (4)<\/span>\n    for<\/span>(auto<\/span> e :<\/span> container) std::<\/span>cout <<<\/span> e <<<\/span> ' '<\/span>;\n    std::<\/span>cout <<<\/span> \"<\/span>\\n\\n<\/span>\"<\/span>;\n}\n\nint<\/span> main<\/span>() {\n    \n    std::<\/span>cout <<<\/span> std::<\/span>endl;\n    \n    int<\/span> arr[]{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>};              \/\/ (1)<\/span>\n    printMe(arr);\n    \n    std::<\/span>vector vec{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>, 5<\/span>};     \/\/ (2)<\/span>\n    printMe(vec);\n\n    std::<\/span>array arr2{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>, 5<\/span>, 6<\/span>}; \/\/ (3)<\/span>\n    printMe(arr2);\n    \n}\n<\/pre>\n<\/div>\n
\u00a0<\/p>\n
The C-array (1), std::vector\u00a0<\/span>(2), and the std::array<\/span> (3) have int<\/span>‘s. Consequently, std::span<\/span> also holds int’<\/span>s. There is something more interesting in this simple example. For each container, std::span<\/span> can deduce its size (4).<\/p>\n
The big three C++ compilers, MSVC, GCC, and Clang, support std::span<\/span>.<\/p>\n
\"printSpan\"<\/p>\n
\u00a0<\/p>\n
There are more ways to create a std::span<\/span>.<\/p>\n
Create a std::span from a pointer and a size<\/h3>\n
You can create a std::span<\/span> from a pointer and a size.<\/p>\n
\n
\/\/ createSpan.cpp<\/span>\n\n#include <algorithm><\/span>\n#include <iostream><\/span>\n#include <span><\/span>\n#include <vector><\/span>\n\nint<\/span> main<\/span>() {\n\n    std::<\/span>cout <<<\/span> std::<\/span>endl;\n    std::<\/span>cout <<<\/span> std::<\/span>boolalpha;\n\n    std::<\/span>vector myVec{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>, 5<\/span>};\n\t\n    std::<\/span>span mySpan1{myVec};                                        \/\/ (1)<\/span>\n    std::<\/span>span mySpan2{myVec.data(), myVec.size()};                   \/\/ (2)<\/span>\n\t\n    bool<\/span> spansEqual =<\/span> std::<\/span>equal(mySpan1.begin(), mySpan1.end(),\n                                 mySpan2.begin(), mySpan2.end());\n\t\n    std::<\/span>cout <<<\/span> \"mySpan1 == mySpan2: \"<\/span> <<<\/span> spansEqual <<<\/span> std::<\/span>endl;  \/\/ (3)<\/span>\n\n    std::<\/span>cout <<<\/span> std::<\/span>endl;\n\t\n}\n<\/pre>\n<\/div>\n
\u00a0<\/p>\n
As you may expect, the from a std::vector<\/span> created mySpan1<\/span> (1), and the from a pointer and a size created mySpan<\/span> (2)\u00a0 are equal (3).<\/p>\n
\"createSpan\"<\/p>\n
\u00a0<\/p>\n
You may remember that a std::span <\/span>is sometimes called a view. Don’t confuse a std::span<\/span>\u00a0with a view from the ranges library<\/a>\u00a0(C++20) or a std::string_view <\/span>(C++17).<\/p>\n
A view from the ranges library<\/a> is something that you can apply on a range and performs some operations. A view does not own data, and it’s time to copy, move, and assignment it’s constant. Here is a quote from Eric Niebler’s range-v3 implementation<\/a>,\u00a0which is the base for the C++20 ranges: “Views are composable adaptations of ranges where the adaptation happens lazily as the view is iterated.<\/em>” These are all my posts to the ranges library: category ranges library<\/a>.\u00a0<\/p>\n
A view (std::span<\/span>) and a std::string_view<\/span> are non-owning views and can deal with strings. The main difference between a std::span<\/span> and a std::string_view<\/span> is that a std::span<\/span> can modify its objects. When you want to read more about std::string_vie<\/span>w, read my previous post: “C++17 – What’s New in the Library?<\/a>” and “C++17 – Avoid Copying with std::string_view<\/span><\/a>“.\u00a0<\/p>\n
Modifying its objects<\/h3>\n
You can modify the entire span or only a subspan. When you modify the span, you modify the referenced objects.<\/p>\n
The following program shows how a subspan can modify the referenced objects from a std::vector<\/span>.<\/p>\n
\n
\/\/ spanTransform.cpp<\/span>\n\n#include <algorithm><\/span>\n#include <iostream><\/span>\n#include <vector><\/span>\n#include <span><\/span>\n\nvoid<\/span> printMe<\/span>(std::<\/span>span<<\/span>int<\/span>><\/span> container) {\n    \n    std::<\/span>cout <<<\/span> \"container.size(): \"<\/span> <<<\/span> container.size() <<<\/span> std::<\/span>endl;\n    for<\/span>(auto<\/span> e :<\/span> container) std::<\/span>cout <<<\/span> e <<<\/span> ' '<\/span>;\n    std::<\/span>cout <<<\/span> \"<\/span>\\n\\n<\/span>\"<\/span>;\n}\n\nint<\/span> main<\/span>() {\n    \n    std::<\/span>cout <<<\/span> std::<\/span>endl;\n    \n    std::<\/span>vector vec{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>, 5<\/span>, 6<\/span>, 7<\/span>, 8<\/span>, 9<\/span>, 10<\/span>};    \n    printMe(vec);\n    \n    std::<\/span>span span1(vec);                                 \/\/ (1)<\/span> \n    std::<\/span>span span2{span1.subspan(1<\/span>, span1.size() -<\/span> 2<\/span>)};  \/\/ (2)<\/span>\n    \n                                                 \n    std::<\/span>transform(span2.begin(), span2.end(),            \/\/ (3)<\/span>  \n                   span2.begin(), \n                   [](int<\/span> i){ return<\/span> i *<\/span> i; });\n    \n    \n    printMe(vec);                                       \n    \n}\n<\/pre>\n<\/div>\n
\u00a0<\/p>\n
span1<\/span> references the std::vector vec\u00a0<\/span>(1). In contrast, span2<\/span> only references all elements of the underlying vec<\/span> without the first and the last element (2). Consequently, mapping each element to its square (3) only addresses these elements.\u00a0<\/p>\n
\"spanTransform\"<\/p>\n
There are many convenience functions to refer to the elements of the span.<\/p>\n
Addressing the elements of a\u00a0std::span<\/span><\/h3>\n
The table presents the functions to refer to the elements of a span.<\/p>\n
\u00a0<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Function\u00a0<\/strong><\/span><\/td>\nDescription<\/strong><\/span><\/td>\n<\/tr>\n
\u00a0span.front()<\/span><\/td>\nAccess the first element<\/td>\n<\/tr>\n
\u00a0span.back()<\/span><\/td>\nAccess the last element<\/td>\n<\/tr>\n
\u00a0span[i]<\/span><\/td>\nAccess the i-th element<\/td>\n<\/tr>\n
\u00a0span.data()<\/span><\/td>\nReturns a pointer to the beginning of the sequence\u00a0<\/td>\n<\/tr>\n
\u00a0span.size()<\/span><\/td>\nReturns the number of elements of the sequence<\/td>\n<\/tr>\n
\u00a0span.size_bytes()<\/span><\/td>\nReturns the size of the sequence\u00a0<\/td>\n<\/tr>\n
\u00a0span.empty()<\/span><\/td>\nReturns if the sequence is empty<\/td>\n<\/tr>\n
\n
span<count>.first()<\/span><\/p>\n
span.first(count)<\/span><\/p>\n<\/td>\n
Returns a subspan consisting of the first count<\/span> elements of the sequence<\/td>\n<\/tr>\n
\n
span<count>last()<\/span><\/p>\n
span.last<count><\/span><\/p>\n<\/td>\n
Returns a subspan consisting of the last count<\/span> elements of the sequence<\/td>\n<\/tr>\n
\n
span<first, count>.subspan()<\/span><\/p>\n
span.subspan(first, count)<\/span><\/p>\n<\/td>\n
Returns a subspan consisting of count<\/span> elements starting at first<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\u00a0<\/p>\n
The small program shows the usage of the function subspan<\/span>.<\/p>\n
\n
\/\/ subspan.cpp<\/span>\n\n#include <iostream><\/span>\n#include <numeric><\/span>\n#include <span><\/span>\n#include <vector><\/span>\n\nint<\/span> main<\/span>() {\n\n    std::<\/span>cout <<<\/span> std::<\/span>endl;\n\n    std::<\/span>vector<<\/span>int<\/span>><\/span> myVec(20<\/span>);\n    std::<\/span>iota(myVec.begin(), myVec.end(), 0<\/span>);                   \/\/ (1)<\/span>\n    for<\/span> (auto<\/span> v:<\/span> myVec) std::<\/span>cout <<<\/span> v <<<\/span> \" \"<\/span>;\n\n    std::<\/span>cout <<<\/span> \"<\/span>\\n\\n<\/span>\"<\/span>;\n\n    std::<\/span>span<<\/span>int<\/span>><\/span> mySpan(myVec);                               \/\/ (2)<\/span>\n    auto<\/span> length =<\/span> mySpan.size();\n\n    auto<\/span> count =<\/span> 5<\/span>;                                             \/\/ (3)<\/span>\n    for<\/span> (long<\/span> unsigned<\/span> int<\/span> first =<\/span> 0<\/span>; first <=<\/span> (length -<\/span> count); first +=<\/span> count ) {\n        for<\/span> (auto<\/span> ele:<\/span> mySpan.subspan(first, count)) std::<\/span>cout <<<\/span> ele <<<\/span> \" \"<\/span>;\n        std::<\/span>cout <<<\/span> std::<\/span>endl;\n    }\n\n}\n<\/pre>\n<\/div>\n
\u00a0<\/p>\n
The program fills the vector with all numbers from 0 to 19 (1) and initializes a std::span<\/span> with it (2). The algorithm\u00a0std::iota<\/span> fills myVec<\/span> with the\u00a0sequentially increasing values, starting with 0. Finally<\/span>, the for-loop (3) uses the function subspan<\/span> to create all subspans starting at first<\/span> and having count<\/span> elements until mySpan<\/span> is consumed.<\/p>\n
\"subspan\"<\/p>\n
What’s next?\u00a0<\/h2>\n
Containers of the STL become more potent with C++20. For example, a std::string<\/span> and std::vecto<\/span>r can be created and modified at compile-time. Further, thanks to the functions std::erase<\/span> and std::erase_if<\/span>, the deletion of the elements of a container works like a charm.<\/p>\n
\u00a0<\/p>\n
\u00a0<\/p>\n
\u00a0<\/p>\n
\u00a0<\/p>\n\n\n\n\n\n\n
<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n","protected":false},"excerpt":{"rendered":"
In my seminar, I often hear the question: How can I safely pass a plain array to a function? With C++20, the answer is quite easy: Use a std::span.<\/p>\n","protected":false},"author":21,"featured_media":5945,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[375],"tags":[456],"class_list":["post-5983","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-c-20","tag-span"],"_links":{"self":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/5983","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/comments?post=5983"}],"version-history":[{"count":2,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/5983\/revisions"}],"predecessor-version":[{"id":8905,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/5983\/revisions\/8905"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media\/5945"}],"wp:attachment":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media?parent=5983"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/categories?post=5983"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/tags?post=5983"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}