420

Recently I've gotten suggestions to use span<T>'s in my code, or have seen some answers here on the site which use span's - supposedly some kind of container. But - I can't find anything like that in the C++17 standard library.

So what is this mysterious span<T>, and why (or when) is it a good idea to use it if it's non-standard?

4
  • 9
    @jww: span's are quite usable with C++11... as gsl::span rather than std::span. See also my answer below.
    – einpoklum
    Jan 24, 2018 at 6:39
  • Also documented on cppreference.com: en.cppreference.com/w/cpp/container/span Mar 24, 2020 at 19:18
  • 6
    @KeithThompson: Not in 2017 it wasn't...
    – einpoklum
    Mar 24, 2020 at 21:02
  • 8
    @jww All compilers support std::span<> now in C++20 mode. And span is available from many 3rd party libs. You were right - it was years: 2 years to be precise.
    – Contango
    Jun 20, 2020 at 7:43

4 Answers 4

494

What is it?

A span<T> is:

  • A very lightweight abstraction of a contiguous sequence of values of type T somewhere in memory.
  • Basically a struct { T * ptr; std::size_t length; } with a bunch of convenience methods.
  • A non-owning type (i.e. a "reference-type" rather than a "value type"): It never allocates nor deallocates anything and does not keep smart pointers alive.

It was formerly known as an array_view and even earlier as array_ref.

When should I use it?

First, when not to use spans:

  • Don't use a span in code that could just take any pair of start & end iterators (like std::sort, std::find_if, std::copy and other templated functions from <algorithm>), and also not in code that takes an arbitrary range (see The C++20 ranges library for information about those). A span has stricter requirements than a pair of iterators or a range: element contiguity and presence of the elements in memory.
  • Don't use a span if you have a standard library container (or a Boost container etc.) which you know is the right fit for your code. spans are not intended to supplant existing containers.

Now for when to actually use a span:

Use span<T> (respectively, span<const T>) instead of a free-standing T* (respectively const T*) when the allocated length or size also matter. So, replace functions like:

void read_into(int* buffer, size_t buffer_size);

with:

void read_into(span<int> buffer);

Why should I use it? Why is it a good thing?

Oh, spans are awesome! Using a span...

  • means that you can work with that pointer+length / start+end pointer combination like you would with a fancy, pimped-out standard library container, e.g.:

    • for (auto& x : my_span) { /* do stuff */ }
    • std::find_if(my_span.cbegin(), my_span.cend(), some_predicate);
    • std::ranges::find_if(my_span, some_predicate); (in C++20)

    ... but with absolutely none of the overhead most container classes incur.

  • lets the compiler do more work for you sometimes. For example, this:

    int buffer[BUFFER_SIZE];
    read_into(buffer, BUFFER_SIZE);
    

    becomes this:

    int buffer[BUFFER_SIZE];
    read_into(buffer);
    

    ... which will do what you would want it to do. See also Guideline P.5.

  • is the reasonable alternative to passing const vector<T>& to functions when you expect your data to be contiguous in memory. No more getting scolded by high-and-mighty C++ gurus!

  • facilitates static analysis, so the compiler might be able to help you catch silly bugs.

  • allows for debug-compilation instrumentation for runtime bounds-checking (i.e. span's methods will have some bounds-checking code within #ifndef NDEBUG ... #endif)

  • indicates that your code (that's using the span) doesn't own the pointed-to memory.

There's even more motivation for using spans, which you could find in the C++ core guidelines - but you catch the drift.

But is it in the standard library?

edit: Yes, std::span was added to C++ with the C++20 version of the language!

Why only in C++20? Well, While the idea is not new - its current form was conceived in conjunction with the C++ core guidelines project, which only started taking shape in 2015. So it took a while.

So how do I use it if I'm writing C++17 or earlier?

It's part of the Core Guidelines's Support Library (GSL). Implementations:

  • Microsoft / Neil Macintosh's GSL contains a standalone implementation: gsl/span
  • GSL-Lite is a single-header implementation of the whole GSL (it's not that big, don't worry), including span<T>.

The GSL implementation does generally assume a platform that implements C++14 support [12]. These alternative single-header implementations do not depend on GSL facilities:

Note that these different span implementations have some differences in what methods/support functions they come with; and they may also differ somewhat from the version adopted into the standard library in C++20.


Further reading: You can find all the details and design considerations in the final official proposal before C++17, P0122R7: span: bounds-safe views for sequences of objects by Neal Macintosh and Stephan J. Lavavej. It's a bit long though. Also, in C++20, the span comparison semantics changed (following this short paper by Tony van Eerd).

44
  • 6
    It would make more sense to standardize a general range (supporting iterator+sentinel and iterator+length, maybe even iterator+sentinel+length) and make span a simple typedef. Because, you know, that's more generic. Aug 17, 2017 at 12:47
  • 3
    @Deduplicator: Ranges are coming to C++, but the current proposal (by Eric Niebler) requires support for Concepts. So not before C++20.
    – einpoklum
    Aug 17, 2017 at 12:52
  • 8
    @HảiPhạmLê: Arrays don't immediately decay into pointers. try doing std::cout << sizeof(buffer) << '\n' and you'll see you get 100 sizeof(int)'s.
    – einpoklum
    Aug 23, 2017 at 7:59
  • 7
    @Jim std::array is a container, it owns the values. span is non-owning
    – Caleth
    Dec 4, 2018 at 14:18
  • 4
    @Jim: std::array is a completely different beast. Its length is fixed at compile-time and it's a value-type rather than a reference-type, as Caleth explained.
    – einpoklum
    Dec 4, 2018 at 14:56
51

A span<T> is this:

template <typename T>
struct span
{
    T * ptr_to_array;   // pointer to a contiguous C-style array of data
                        // (which memory is NOT allocated nor deallocated 
                        // nor in any way managed by the span)
    std::size_t length; // number of elements of type `T` in the array

    // Plus a bunch of constructors and convenience accessor methods here
}

It is a light-weight wrapper around a C-style array, preferred by C++ developers whenever they are using C libraries and want to wrap them with a C++-style data container for "type safety" and "C++-ishness" and "feelgoodery". :)

Note: I call the struct container defined above, known as a span, a "light-weight wrapper around a C-style array" because it points to a contiguous piece of memory, such as a C-style array, and wraps it with accessor methods and the array's size. This is what I mean by "light-weight wrapper": it is a wrapper around a pointer and a length variable, plus functions.

Unlike a std::vector<> and other C++ standard containers, however, which may also just have fixed class sizes and contain pointers which point to their storage memory, a span does not own the memory it points to, and will never delete it nor resize it nor allocate new memory automatically. Again, a container like a vector owns the memory it points to, and will manage (allocate, reallocate, etc.) it, but a span does not own the memory it points to, and therefore will not manage it.


Going further:

@einpoklum does a pretty good job of introducing what a span is in his answer here. However, even after reading his answer, it is easy for someone new to spans to still have a sequence of stream-of-thought questions which aren't fully answered, such as the following:

  1. How is a span different from a C array? Why not just use one of those? It seems like it's just one of those with the size known as well...
  2. Wait, that sounds like a std::array, how is a span different from that?
  3. Oh, that reminds me, isn't a std::vector like a std::array too?
  4. I'm so confused. :( What's a span?

So, here's some additional clarity on that:

DIRECT QUOTE OF HIS ANSWER--WITH MY ADDITIONS and parenthetical comments IN BOLD and my emphasis in italics:

What is it?

A span<T> is:

  • A very lightweight abstraction of a contiguous sequence of values of type T somewhere in memory.
  • Basically a single struct { T * ptr; std::size_t length; } with a bunch of convenience methods. (Notice this is distinctly different from std::array<> because a span enables convenience accessor methods, comparable to std::array, via a pointer to type T and length (number of elements) of type T, whereas std::array is an actual container which holds one or more values of type T.)
  • A non-owning type (i.e. a "reference-type" rather than a "value type"): It never allocates nor deallocates anything and does not keep smart pointers alive.

It was formerly known as an array_view and even earlier as array_ref.

Those bold parts are critical to one's understanding, so don't miss them or misread them! A span is NOT a C-array of structs, nor is it a struct of a C-array of type T plus the length of the array (this would be essentially what the std::array container is), NOR is it a C-array of structs of pointers to type T plus the length, but rather it is a single struct containing one single pointer to type T, and the length, which is the number of elements (of type T) in the contiguous memory block that the pointer to type T points to! In this way, the only overhead you've added by using a span are the variables to store the pointer and length, and any convenience accessor functions you use which the span provides.

This is UNLIKE a std::array<> because the std::array<> actually allocates memory for the entire contiguous block, and it is UNLIKE std::vector<> because a std::vector is basically just a std::array that also does dynamic growing (usually doubling in size) each time it fills up and you try to add something else to it. A std::array is fixed in size, and a span doesn't even manage the memory of the block it points to, it just points to the block of memory, knows how long the block of memory is, knows what data type is in a C-array in the memory, and provides convenience accessor functions to work with the elements in that contiguous memory.

It is part of the C++ standard:

std::span is part of the C++ standard as of C++20. You can read its documentation here: https://en.cppreference.com/w/cpp/container/span. To see how to use Google's absl::Span<T>(array, length) in C++11 or later today, see below.

Summary Descriptions, and Key References:

  1. std::span<T, Extent> (Extent = "the number of elements in the sequence, or std::dynamic_extent if dynamic". A span just points to memory and makes it easy to access, but does NOT manage it!):
  2. https://en.cppreference.com/w/cpp/container/span
  3. std::array<T, N> (notice it has a fixed size N!):
  4. https://en.cppreference.com/w/cpp/container/array
  5. http://www.cplusplus.com/reference/array/array/
  6. std::vector<T> (automatically dynamically grows in size as necessary):
  7. https://en.cppreference.com/w/cpp/container/vector
  8. http://www.cplusplus.com/reference/vector/vector/

How Can I Use span in C++11 or later today?

Google has open-sourced their internal C++11 libraries in the form of their "Abseil" library. This library is intended to provide C++14 to C++20 and beyond features which work in C++11 and later, so that you can use tomorrow's features, today. They say:

Compatibility with the C++ Standard

Google has developed many abstractions that either match or closely match features incorporated into C++14, C++17, and beyond. Using the Abseil versions of these abstractions allows you to access these features now, even if your code is not yet ready for life in a post C++11 world.

Here are some key resources and links:

  1. Main site: https://abseil.io/
  2. https://abseil.io/docs/cpp/
  3. GitHub repository: https://github.com/abseil/abseil-cpp
  4. span.h header, and absl::Span<T>(array, length) template class: https://github.com/abseil/abseil-cpp/blob/master/absl/types/span.h#L153

Other references:

  1. Struct with template variables in C++
  2. Wikipedia: C++ classes
  3. default visibility of C++ class/struct members

Related:

  1. [another one of my answers on templates and spans] How to make span of spans
9
  • 5
    I would really not recommend using all of abseil to get a span class.
    – einpoklum
    Aug 28, 2020 at 10:19
  • got it. The biggest advantage is light-weight.
    – yushang
    Jul 1, 2021 at 12:33
  • 1
    @yushang, from a C++ developer's point-of-view, I think the biggest advantage isn't "light-weight", but is rather: "wraps around already-existing C arrays", so that no copying is necessary, and you now have a wrapper around a container which holds its size inside of it, unlike C arrays, which don't know nor carry around information about their own size. As an embedded developer, with more experience in C than in C++, myself, however, I'd generally prefer to just use raw C arrays anyway, over a span. Aug 8, 2021 at 22:46
  • void array_operator ( const size_t count_, char arr [ static count_ ] ); that is standard C. In there one has full array info. Plus arr must have min count_ elements. Context is this discussion not "C is better" rant. Aug 12, 2021 at 18:10
  • 1
    It is not a wrapper to a C-style array; std::array is a wrapper to a C-style array. std::span is a reference to a contiguous sequence, such as a C-style array. Nov 2, 2021 at 14:05
5

The answer provided by Einpoklum is great but I had to dive deep into the comments section to understand one specific detail so this is meant as an extension to clarify that detail.

First, when not to use it:

Don't use it in code that could just take any pair of start & end iterators, like std::sort, std::find_if, std::copy and all of those super-generic templated functions. Don't use it if you have a standard library container (or a Boost container etc.) which you know is the right fit for your code. It's not intended to supplant any of them.

Any pair of start & end iterators as opposed to start and end pointers of continuous storage.

As someone who rarely gets into contact with the interior of iterators it escaped me during my reading of the answer that iterators could iterate over a linked list, which simple pointers(and a span) could not.

5
  • spans are constructible from contiguous iterators, which are not necessarily pointers. vector::iterator is contiguous, but not a pointer -- for example. The comment you quoted effectively boils down to "use the right tool for the job"; if you are writing an algorithm/utility over an arbitrary sequence, don't try to erase it into a span since this prevents any normal container from being used. However, if you want to have a container that represents non-owning contiguous data, span is likely the right call. Jul 6, 2022 at 1:20
  • iterators could iterate over.... a linked-list, a red-black tree, a hashmap (all of which have implementations in the C++ Standard Library), and anything else including third-party exotic containers.
    – Ben Voigt
    Jul 14, 2022 at 15:44
  • I agree with what you two wrote. It seems to be a rephrasing/repetition of the very fact that I tried summarizing/highlighting here.
    – Tolar
    Jul 21, 2022 at 15:25
  • 1
    This answer inspired me to expand mine somewhat. So, +1 for it, but I hope now the point you are making is obvious enough when reading my answer.
    – einpoklum
    Sep 10, 2022 at 16:32
  • I think it is obvious now, but I can no longer proof-read, because now I know and it's a detail that is hard to unlearn so I wouldn't know if earlier me would repeat my oversight. I'll leave it to others to decide if my answer should be deleted.
    – Tolar
    Sep 27, 2022 at 9:01
0

A span is (or rather: has) a pointer to data not owned by that span. In effect you can do ranged operations on a span that affect someone else's data.

This means you can write things like an in-place quicksort:

void qs( span<T> data ) {
   split(data);
   qs( span{ data+0,sizeoffirst } );
   qs( span{ data+sizeoffirst,sizeofsecond } );

or any number of Lapack-style linear algebra functions by recursion or parallelism.

7
  • 1
    This is more of a comment.
    – einpoklum
    Aug 10 at 21:14
  • After edit, is my about "when should I use it" clearer? Aug 10 at 21:47
  • This does not provide an answer to the question. To critique or request clarification from an author, leave a comment below their post. - From Review Aug 14 at 19:19
  • @SwissCodeMen I have no idea what you're telling me about critique or clarification. I'm not doing either. Also: are you a C++ expert? I'm giving a usage scenario when it can be used, which answers the question. Aug 14 at 19:36
  • 1
    @SwissCodeMen I don't see my point about operating on (non-owned) sub-arrays covered anywhere. The important application area of linear algebra is not mentioned anywhere. For application scientists that is much much much more important than the fact that it's something light-weight. So the "when should I use one" is covered only in my answer: if you do linear algebra, or other operations (such as in-place sorting) where you want a non-owned sub-array. And that is unique to my answer. Aug 15 at 10:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.