Array Spans and std::span

In the previous lesson, we introduced classic, C-style arrays. We also outlined some of their main problems and recommended they not be used because of those issues.

But sometimes, we can’t avoid them. In complex projects, we’ll often integrate with third-party libraries, or APIs provided by the platforms or operating systems we’re building for. Those libraries may provide us with C-style arrays, or expect us to provide them as arguments for their functions.

C++20 introduced the std::span class to help us work with these arrays, while mitigating most of their problems.

Creating Spans

The std::span template class is available by including <span> and can be constructed in the same way as any other object. We can provide a template parameter to specify what type of objects will be in the span:

1#include <span>
2std::span<int> Span{Values};

Below, we create a std::span that is connected to a C-style array. Using class template argument deduction, we don’t need to explicitly state the elements are integers in this case:

1#include <span>
2
3int main(){
4  int Values[]{1, 2, 3, 4, 5};
5  std::span Span{Values};
6}

By connected, we mean that the span has not created a copy of the elements. It simply provides a lightweight interface with which to access and work with the underlying array. We’ll discuss these properties in more detail a little later.

Span Size

The most common place we’ll use a span is as a function parameter type, to receive a C-style array argument:

1#include <span>
2#include <iostream>
3
4void HandleValues(std::span<int> Values){
5  std::cout << "Span Size: " << Values.size();
6}
7
8int main(){
9  int Values[]{1, 2, 3, 4, 5};
10  HandleValues(Values);
11}

1Span Size: 5

This example shows spans overcoming the first big problem with C-style arrays - the fact they decay to a pointer, and lose track of their size. With spans, this doesn’t happen - we’ve received a regular type, and we can access its size using the size() method.

Element Access

Similar to containers like std::vector and std::array, we can access elements using the [] operator, using an index or an expression that results in an index:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7  std::cout
8    << "First: " << Span[0]
9    << "\nSecond: " << Span[1]
10    << "\nLast: " << Span[Span.size() - 1];
11}

1First: 1
2Second: 2
3Last: 5

The front() and back() methods give us direct access to the first and last elements of the span:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7  std::cout
8    << "First: " << Span.front()
9    << "\nLast: " << Span.back();
10}

1First: 1
2Last: 5

Spans are a View

Spans are an example of a view - they do not own the underlying elements they’re providing access to. Those are owned by a different container - the container we provided to the std::span constructor.

In the previous example, the elements are owned by the C-style array called Values. The std::span we called Span simply provides a lightweight wrapper, allowing us to access the underlying container in a friendlier way.

In other words, a span is an example of a view. We’ll see more examples of views throughout the course.

This has two effects:

1. Creating a span is inexpensive. There is a minimal performance overhead because a view does not need to copy any of the underlying elements.
2. Because a view and the container it is viewing point to the same memory address, modifying an object through one affects the other

We can demonstrate the second point below:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7 
8  // Modifying an object in the container:
9  Values[0] = 42;
10
11  // The change is reflected in the view:
12  std::cout << "First: " << Span.front();
13}

1First: 42

The opposite is also true - changing an element through the span also affects the original container that the span is viewing:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7
8  // Modifying an object through the view:
9  Span[0] = 42;
10
11  // The change is reflected in the container:
12  std::cout << "First: " << Values[0];
13}

1First: 42

The const Keyword with Spans

In most scenarios, we want the span to be a read-only view of the container from which it was created.

We can be explicit about this using the const keyword. We can specify that the individual elements will not be changed, by marking their type as const:

1#include <span>
2
3int main(){
4  int Values[]{1, 2, 3, 4, 5};
5  std::span<const int> Span{Values};
6  Span[0] = 42; // Error - Span[n] is const 
7}

1error C3892: 'Span': you cannot assign to a variable that is const

When using a view as a function parameter, it is a relatively important tenet of const-correctness that we mark implement this technique:

1#include <iostream>
2#include <span>
3
4void LogFirst(std::span<const int> Values) {
5  std::cout << Values.front();
6}
7
8int main() {
9  int Values[]{1, 2, 3, 4, 5};
10  LogFirst(Values);
11}

As we covered above, spans are a view - they’re accessing elements within the original collection. If we don’t plan to modify those elements, we should mark them as const just as if we were passing them by reference.

Constants and const-Correctness

Learn the intricacies of using const and how to apply it in different contexts

Less importantly, we can also make the span itself const, which will prevent it from being reassigned:

1#include <span>
2
3int main(){
4  int Values[]{1, 2, 3, 4, 5};
5  const std::span<int> Span{Values};
6  Span = Values; // Error - Span is const 
7}

1error C2678: binary '=': no operator found which takes a left-hand operand of type 'const std::span'

Finally, we can combine both techniques using the const specifier twice, to ensure neither the span, nor the elements it is viewing are modified:

1#include <span>
2
3int main(){
4  int Values[]{1, 2, 3, 4, 5};
5  const std::span<const int> Span{Values};
6  Span[0] = 42; // Error - Span[n] is const 
7  Span = Values; // Error - Span is const 
8}

1error C3892: 'Span': you cannot assign to a variable that is const
2error C2678: binary '=': no operator found which takes a left-hand operand of type 'const std::span'

Iteration

We can iterate over the elements of a span in the usual ways. Because spans implement iterators, we will most typically use a range-based for loop:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7
8  for (int x : Span) {
9    std::cout << x << ", ";
10  }
11}

We cover iterators and range-based for loops in more detail a little later in the chapter.

Multiple Array Types

Throughout this lesson, we’ve been creating spans from C-style arrays, but that is not their only use. Spans can be created from any container that holds its elements in a contiguous area of memory, such as a std::vector, a std::array, or any custom type for which we provide appropriate methods.

This allows us to create functions that can provide a simple, consistent interface for working with any type of array.

Below, our LogFirst() function accepts a std::span, meaning it is not unnecessarily tying consumers to any specific array implementation. They can use whatever they want:

1#include <span>
2#include <iostream>
3#include <vector>
4#include <array>
5
6void LogFirst(const std::span<int> Values){
7  std::cout << Values.front() << ", ";
8}
9
10int main(){
11  int ValuesA[]{1, 2, 3, 4};
12  std::vector ValuesB{5, 6, 7};
13  std::array ValuesC{8, 9};
14
15  LogFirst(ValuesA);
16  LogFirst(ValuesB);
17  LogFirst(ValuesC);
18}

11, 5, 8,

Span Templates

Remember, we also have access to all of the template-based techniques we covered in the previous lesson, allowing us to create even more versatile code:

1#include <span>
2#include <iostream>
3#include <vector>
4#include <array>
5
6template <typename T>
7void LogFirst(std::span<T> Values){
8  std::cout << Values.front() << ", ";
9}
10
11int main(){
12  int ValuesA[]{1, 2, 3, 4};
13  std::vector ValuesB{5.f, 6.f, 7.f};
14  std::array ValuesC{true, false};
15
16  LogFirst<int>(ValuesA);
17  LogFirst<float>(ValuesB);
18  LogFirst<bool>(ValuesC);
19}

11, 5, 1,

Creating C-Style Arrays from Spans

When we need to get a C-style array from a span, we can access a pointer to the first element using the data() method.

Typically, the use case for this will be to generate arguments for a third-party library, in which case we’ll typically also need to include the size:

1#include <span>
2#include <iostream>
3
4void HandleArray(int Array[], size_t Size){
5  for (size_t i{0}; i < Size; ++i) {
6    std::cout << Array[i] << ", ";
7  }
8}
9
10int main(){
11  int Values[]{1, 2, 3, 4, 5};
12  std::span<int> Span{Values};
13  HandleArray(Span.data(), Span.size());
14}

11, 2, 3, 4, 5,

Note this technique will create a shallow copy of the array. The Array parameter in HandleArray() will be pointing to the same memory location as the Values variable in main().

If we want a deep copy of all elements in the array, we’ll need to use one of the techniques covered in the previous lesson on C-style arrays, such as memcpy().

Creating Other Containers from Spans

When we need to create a standard library container such as an array or span, the easiest way typically involves iterators.

We cover iterators in more detail soon but, for now, we can just note that spans include a begin() and end() method, denoting where their elements start and where they end.

Most sequential containers will support iterators, and this includes standard library containers such as std::vector and std::array

Both of these containers have a constructor that can accept such a pair of iterators, and will use them to initialize themselves with a copy of everything in that range:

1#include <iostream>
2#include <vector>
3#include <span>
4
5int main(){
6  int Values[]{1, 2, 3, 4, 5};
7  std::span<int> Span{Values};
8
9  std::vector<int> Vec{
10    Span.begin(), Span.end()
11  };
12
13  std::cout << "Vec Size: " << Vec.size();
14}

1Vec Size: 5

The typical scenario where we’ll want to convert a span to a vector or array is to pass it as a function argument.

In those cases, we shouldn’t create an intermediate copy of the array and then copy it, as that has a performance impact. Instead, we can just pass the constructor arguments as a list, and let our function call create the vector:

1#include <iostream>
2#include <vector>
3#include <span>
4
5void HandleVector(std::vector<int> Vec){
6  for (int x : Vec) { std::cout << x << ", "; }
7}
8
9int main(){
10  int Values[]{1, 2, 3, 4, 5};
11  std::span<int> Span{Values};
12  HandleVector(
13    {Span.begin(), Span.end()}
14  );
15}

11, 2, 3, 4, 5,

Creating Subspans using first(), last() and subspan()

Spans can be created from other spans in the usual way:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values}; 
7  std::span<int> Another{Span};
8
9  for (int x : Another) {
10    std::cout << x << ", ";
11  }
12}

These spans can also be restricted to just including a subset of the original span. For example, using the first() method, we can restrict the subspan to just viewing an initial number of records, defined by the argument we pass:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7  std::span<int> First3{Span.first(3)}; 
8
9  std::cout << "First Three: ";
10  for (int x : First3) {
11    std::cout << x << ", ";
12  }
13}

1First Three: 1, 2, 3,

The last() method returns a span that includes records from the end of the collection. Below, we return a view of the last 3 elements:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7  std::span<int> Last3{Span.last(3)}; 
8
9  std::cout << "Last Three: ";
10  for (int x : Last3) {
11    std::cout << x << ", ";
12  }
13}

1Last Three: 3, 4, 5,

Finally, we can pass a starting position and record count to the subspan() method, constraining the view to any range. Below, we return a view that starts at index 1, and contains 3 elements:

1#include <span>
2#include <iostream>
3
4int main(){
5  int Values[]{1, 2, 3, 4, 5};
6  std::span<int> Span{Values};
7  std::span<int> Middle3{Span.subspan(1, 3)}; 
8
9  std::cout << "Middle Three: ";
10  for (int x : Middle3) {
11    std::cout << x << ", ";
12  }
13}

Remember, spans are just a view of an underlying record. This includes spans created from other spans. A sub-span is just restricting the view to a smaller set of elements in the underlying array.

The elements we’re viewing are still the elements in that array, and by accessing them through the span, we are still accessing the original memory locations.

Views are a large part of modern C++, and a span is just one type of view. We’ll cover views in more detail later in this course, including more robust ways to create them, and how we can use them to make complex tasks much easier.

Summary

In this lesson, we explored the functionality and purpose of std::span in C++20. Spans provide a safe and efficient way to handle and manipulate arrays and other contiguous data structures without owning the data.

Key Takeaways:

• std::span was introduced in C++20 to provide a safer and more flexible way to handle arrays, especially when dealing with legacy C-style arrays.
• Spans are lightweight and do not own the data they point to, allowing for efficient manipulation of arrays without data duplication.
• The use of std::span overcomes the limitation of C-style arrays by maintaining size information, allowing safer and more robust code.
• Elements within a span can be accessed using standard subscript notation and methods like front() and back().
• Spans support iteration using range-based for loops, similar to standard C++ containers.
• The const keyword can be used with spans to create read-only views of the data.
• std::span is versatile, supporting various container types like std::vector, std::array, and C-style arrays.
• Template-based techniques can be employed with spans to handle different data types more flexibly.
• Spans can be converted back to C-style arrays or other containers, providing interoperability with different parts of a codebase.
• Subspans can be created using first(), last(), and subspan() methods for more targeted data manipulation.

Next Lesson

Multidimensional Arrays and std::mdspan

A guide to std::mdspan, allowing us to interact with arrays as if they have multiple dimensions

ContinueView Course