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?
A span<T> is:
T somewhere in memory.struct { T * ptr; std::size_t length; } with a bunch of convenience methods.It was formerly known as an array_view and even earlier as array_ref.
First, when not to use spans:
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.Now for when to actually use a span:
Use
span<T>(respectively,span<const T>) instead of a free-standingT*(respectivelyconst 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);
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.
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.
It's part of the Core Guidelines's Support Library (GSL). Implementations:
gsl/spanspan<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:
martinmoene/span-lite requires C++98 or latertcbrindle/span requires C++11 or laterNote 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).
read_into(int* from, int* to) be way more in line with the usual (iterator based) approach of the standard library? –
Impenetrability read_into(int* from, int* to, size_t n)? That's mentioned in the Core Guidelines document as a "bad example" actually. –
Cassondracassoulet read_into(int* begin, int* end) –
Impenetrability span<T>, you don't know/don't care whether internally it has int* begin; size_t length or int* begin; int* end; So I don't think it matters all that much. –
Cassondracassoulet new or malloc, so they can correctly delete it later)? I can not find any article about this, and hint is appreciated. Thanks. –
Briareus std::cout << sizeof(buffer) << '\n' and you'll see you get 100 sizeof(int)'s. –
Cassondracassoulet sizeof is also compile time function. But, what about memory allocated dynamically by new or malloc? Can span work with them ? –
Briareus std::array is a container, it owns the values. span is non-owning –
Juta 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. –
Cassondracassoulet read_into(buffer); is the key issue I am having here. Native array reference, very successfully kills the 'span' idea in that scenario. It is "fundamental vocabulary type" in the same way std::span might be. I "need" this clearly mentioned in 'span' jubilation's. –
Bunkhouse span has the benefit to be only a single header-file with few lines of code, supports C++11 or later and has no dependencies to other GSL facilities. –
Collarbone span (like array or vector), @Jim, is that you don't need to awkwardly turn it into a reference type by storing a pile of pointers or reference_wrappers to the data you'd want to view. –
Licentious span is like string_view, but works with any type, not only with char, right? –
Igor span differs from std::array, and which one is better for what, why. –
Lillith std::array here, as opposed to any other specific container. Also, if you know std::array at all, then the answer does explain how they differ. IMHO. –
Cassondracassoulet 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 of type T, whereas std::array is an actual container which holds one or more values of type T.) ". Done. That's all I'm asking for. This helps so much. –
Lillith std::vector. –
Cassondracassoulet std::vector - any contiguous sequence of memory will do, and the span is just the container to represent it. –
Cassondracassoulet std::find_if and then you use it yourself... I feel like a different wording is needed –
Partain cstring_span<>, this specific span doesn't store any character data, correct? So hypothetically, if I had a cstring_span<> that was, e.g., allocated from std::string::c_str(), it would also have the same lifetime that the char* from c_str would have, correct? What value does a cstring_span add over just working with the char* or std::string? –
Oliana cstring_span; that's not in the standard library and not in my answer. But generally - spans don't store any data. And, yes, its lifetime is the same as the pointer. "What value does it add" <- It has the length, on the one hand, and it's a cheap simple structure which doesn't own any memory, on the other. –
Cassondracassoulet std::span meant to get rid of pairs? –
Phosphaturia std::list's beginning and end are two iterators, but the elements are not consecutive in memory, so it doesn't fit a span. –
Cassondracassoulet <ranges> header). –
Stylist std::array owns the data; std::span does not. –
Cassondracassoulet std::array but who knows. –
Cassondracassoulet 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.
@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:
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...std::array, how is a span different from that?std::vector like a std::array too?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
Tsomewhere in memory.- Basically a single struct
{ T * ptr; std::size_t length; }with a bunch of convenience methods. (Notice this is distinctly different fromstd::array<>because aspanenables convenience accessor methods, comparable tostd::array, via a pointer to typeTand length (number of elements) of typeT, whereasstd::arrayis an actual container which holds one or more values of typeT.)- 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_viewand even earlier asarray_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.
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.
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!):std::array<T, N> (notice it has a fixed size N!):std::vector<T> (automatically dynamically grows in size as necessary):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.
span.h header, and absl::Span<T>(array, length) template class: https://github.com/abseil/abseil-cpp/blob/master/absl/types/span.h#L153void 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. –
Bunkhouse 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. –
Ase span is certainly not a container. It does not own the pointee or control its lifetime. OTOH, it does owns a pointer and control that pointer's lifetime. So if span is a wrapper, then it's a wrapper around a pointer. –
Ase span is a wrapper around a pointer and a length variable (plus functions). That's what I mean by "light-weight". –
Lillith 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.
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. –
Dorso 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.
span<T> in that regard and isn‘t answered in any other answers. –
Quite © 2022 - 2024 — McMap. All rights reserved.
gsl::spanrather thanstd::span. See also my answer below. – Cassondracassoulet