legate::Span#

template<typename T> class Span#

A simple span implementation used in Legate.

Should eventually be replaced with std::span once we bump up the C++ standard version to C++20.

Public Functions

template<typename C, typename = std::enable_if_t<detail::is_container_v<C> && !std::is_same_v<C, std::initializer_list<T>> && !std::is_same_v<C, tuple<value_type>>>> constexpr Span( C &container )#

Construct a span from a container-like object.

This overload only participates in overload resolution if C satisfies ContainerLike. It must have a valid overload of std::data() and std::size() which refer to a contiguous buffer of data and its size respectively.

Parameters:: container – The container-like object.

constexpr Span(const tuple<value_type> &tup)#

Construct a Span from a tuple.

This overload must exist because tuple::data() returns a reference to the underlying container, not the underlying pointer (as is usually expected by data()) which causes the Span(C& container) overload to brick.

Parameters:: tup – The tuple to construct the span from.

constexpr Span(std::initializer_list<T> il)#

Construct a span from an initializer list of items directly.

This overload is relatively dangerous insofar that the span can very easily outlive the initializer list. It is generally only preferred to target this overload when taking a Span as a function argument where the ability to simply do foo({1, 2, 3, 4}) is preferred.

Parameters:: il – The initializer list.

constexpr Span(T *data, size_type size)#

Creates a span with an existing pointer and a size.

The caller must guarantee that the allocation is big enough (i.e., bigger than or equal to sizeof(T) * size) and that the allocation is alive while the span is alive.

Parameters:

data – Pointer to the data.
size – Number of elements.

size_type size() const#

Returns the number of elements.

Returns:: The number of elements.

bool empty() const#

Returns:: true if the span has size 0, false otherwise.

reference at(size_type pos) const#

Access an element with bounds checking.

Parameters:: pos – The index of the element to access.
Throws:: std::out_of_range – if pos is not in bounds of the span.
Returns:: A reference to the element as index pos

const_iterator cbegin() const noexcept#

Returns the pointer to the first element.

Returns:: Pointer to the first element.

const_iterator cend() const noexcept#

Returns the pointer to the end of allocation.

Returns:: Pointer to the end of allocation.

const_iterator begin() const#

Returns the pointer to the first element.

Returns:: Pointer to the first element.

const_iterator end() const#

Returns the pointer to the end of allocation.

Returns:: Pointer to the end of allocation.

iterator begin()#

Returns the pointer to the first element.

Returns:: Pointer to the first element.

iterator end()#

Returns the pointer to the end of allocation.

Returns:: Pointer to the end of allocation.

const_reverse_iterator crbegin() const noexcept#

Returns:: An iterator to the last element.

const_reverse_iterator crend() const noexcept#

Returns:: An iterator to the location preceding the first element.

const_reverse_iterator rbegin() const#

Returns:: An iterator to the last element.

const_reverse_iterator rend() const#

Returns:: An iterator to the location preceding the first element.

reverse_iterator rbegin()#

Returns:: An iterator to the last element.

reverse_iterator rend()#

Returns:: An iterator to the location preceding the first element.

reference front() const#

Returns:: A reference to the first element in the span.

reference back() const#

Returns:: A reference to the last element in the span.

Span subspan(size_type off)#

Slices off the first off elements. Passing an off greater than the size will fail with an assertion failure.

Parameters:: off – Number of elements to skip.
Returns:: A span for range [off, size())

const_pointer ptr() const#

Returns a const pointer to the data.

Returns:: Pointer to the data

pointer data() const#

Returns a pointer to the data.

Returns:: Pointer to the data.

bool deep_equal(const Span<const value_type> &other) const#

Compare the values of the span for equality.

Since span is fundamentally a “view” or “handle” type, when a user writes:

span == other_span

It is not immediately clear what they mean to compare. Should operator==() behave like std::shared_ptr and compare the pointer values? Should it compare the container values? For this reason, the standard does not actually define operator==() (or any of the other comparison operators) for std::span, and we don’t either. Instead, we provide this helper function to make the comparison explicit.

If we ever have need for pointer comparisons, we could add shallow_compare(), but then it’s just as easy (and expressive) for the user to write

span.data() == other_span.data()

Parameters:: other – The span to compare against.
Returns:: true if all values of this span are equal to that of other, false otherwise.