carb::cpp::span

template<class T, size_t Extent = dynamic_extent> class span

An object that refers to a contiguous sequence of objects.

The class template span describes an object that can refer to a contiguous sequence of objects with the first element of the sequence at position zero. A span can either have a static extent, in which case the number of elements in the sequence is known at compile-time and encoded in the type, or a dynamic extent.

If a span has dynamic extent, this implementation holds two members: a pointer to T and a size. A span with static extent has only one member: a pointer to T.

Every specialization of span is a TriviallyCopyable type.

This implementation of span is a C++14-compatible implementation of the C++20 std::span, as such certain constructors that involve ranges or concepts are either not implemented or are implemented using C++14 paradigms.

This implementation of span is a guaranteed ABI- and interop-safe type.

Note

For function definitions below the following definitions are used: An ill-formed program will generate a compiler error via static_assert. Undefined behavior is typically signaled by throwing a std::out_of_range exception as this is allowed for constexpr functions to cause a compiler error, however, if exceptions are disabled a CARB_CHECK will occur (this also disables constexpr as CARB_CHECK is not constexpr).

Template Parameters

T – Element type; must be a complete object type that is not an abstract class type
Extent – The number of elements in the sequence, or dynamic_extent if dynamic

Public Types

using element_type = T : The element type T

using value_type = std::remove_cv_t<T>: The value type; const/volatile is removed from T

using size_type = std::size_t: The size type size_t

using difference_type = std::ptrdiff_t: The difference type ptrdiff_t

using pointer = T*: The pointer type T*

using const_pointer = const T*: The const pointer type const T*

using reference = T&: The reference type T&

using const_reference = const T&: The const reference type const T&

using iterator = omni::detail::PointerIterator<pointer, span>: The iterator type omni::detail::PointerIterator.

using reverse_iterator = std::reverse_iterator<iterator>: The reverse iterator type std::reverse_iterator<iterator>

Public Functions

inline constexpr span() noexcept

Default constructor.

Constructs an empty span whose data() is nullptr and size() is 0. This constructor participates in overload resolution only if extent == 0 || extent == dynamic_extent.

template<class It> inline explicit constexpr span(It first, size_type count)

Constructs a span that is a view over the range [first, first + count).

Behavior is undefined if count != extent (for static extent) or first does not model contiguous_iterator. However, since contiguous_iterator is not available until C++20, instead this function does not participate in overload resolution unless std::iterator_traits<It>::iterator_category == std::random_access_iterator_tag.

Parameters

first – An iterator or pointer type that models C++20 contiguous_iterator
count – The number of elements from first to include in the span. If extent != dynamic_extent then this must match extent.

template<class It> inline explicit constexpr span(It first, It last)

Constructs a span that is a view over the range [first, last).

Behavior is undefined if (last - first) != extent (for static extent) or if [first, last) does not represent a contiguous range. This function differs significantly from the C++20 definition since the concepts of contiguous_iterator and sized_sentinel_for are not available. Since these concepts are not available until C++20, instead this function does not participate in overload resolution unless std::iterator_traits<It>::iterator_category == std::random_access_iterator_tag. Also first and last must be a matching iterator type.

Parameters

first – An iterator or pointer type that represents the first element in the span.
last – An iterator or pointer type that represents the past-the-end element in the span.

template<std::size_t N> inline constexpr span(type_identity_t<element_type> (&arr)[N]) noexcept

Constructs a span that is a view over an array.

Behavior is undefined if extent != dynamic_extent && N != extent.

Parameters: arr – The array to view

template<class U, std::size_t N> inline constexpr span(std::array<U, N> &arr) noexcept

Constructs a span that is a view over an array.

Behavior is undefined if extent != dynamic_extent && N != extent.

Parameters: arr – The array to view

template<class U, std::size_t N> inline constexpr span(const std::array<U, N> &arr) noexcept

Constructs a span that is a view over an array.

Behavior is undefined if extent != dynamic_extent && N != extent.

Parameters: arr – The array to view

template<class R> inline explicit constexpr span(R &&range)

Constructs a span that is a view over a range.

The behavior is undefined if any of the following are true:

R does not actually model contiguous_range and sized_range
if R does not model borrowed_range while element_type is non-const
extent is not dynamic_extent and the size of the range != extent

Template Parameters: R – A range type. Since this implementation is for pre-C++20 and ranges are not available, this is an approximation of a range: This type must have data() and size() member functions that must be convertible to the pointer and size_type types respectively.
Parameters: range – The range to view. Behavior is undefined if [range.data(), range.data() + range.size()) is not a contiguous range or cannot be borrowed (i.e. it is a temporary that will expire leaving a danging pointer).

template<class U, std::size_t N> inline constexpr span(const span<U, N> &source) noexcept

Converting constructor from another span.

Behavior is undefined if extent != dynamic_extent && source.size() != extent.

Template Parameters

U – element_type of source; must be convertible to element_type
N – extent of source

Parameters

source – The span to convert from

constexpr span(const span &other) noexcept = default

Copy constructor.

Parameters: other – A span to copy from

constexpr span &operator=(const span &other) noexcept = default

Assignment operator.

Parameters: other – A span to copy from
Returns: *this

inline constexpr iterator begin() const noexcept

Returns an iterator to the first element of the span.

If the span is empty, the returned iterator will be equal to end().

Returns: an iterator to the first element of the span

inline constexpr iterator end() const noexcept

Returns an iterator to the element following the last element of the span.

This element acts as a placeholder; attempting to access it results in undefined behavior.

Returns: an iterator to the element following the last element of the span

inline constexpr reverse_iterator rbegin() const noexcept

Returns a reverse iterator to the first element of the reversed span.

It corresponds to the last element of the non-reversed span. If the span is empty, the returned iterator is equal to rend().

Returns: a reverse_iterator to the first element of the reversed span

inline constexpr reverse_iterator rend() const noexcept

Reverse a reverse iterator to the element following the last element of the reversed span.

It corresponds to the element preceding the first element of the non-reversed span. This element acts as a placeholder, attempting to access it results in undefined behavior.

Returns: a reverse_iterator to the element following the last element of the reversed span

inline constexpr reference front() const

Returns a reference to the first element in the span.

Calling this on an empty span results in undefined behavior.

Returns: a reference to the first element

inline constexpr reference back() const

Returns a reference to the last element in a span.

Calling this on an empty span results in undefined behavior.

Returns: a reference to the last element

inline constexpr reference operator[](size_type index) const

Returns a reference to the element in the span at the given index.

The behavior is undefined if index is out of range (i.e. if it is greater than or equal to size() or the span is empty()).

Parameters: index – The index of the element to access
Returns: a reference to the element at position index

inline constexpr pointer data() const noexcept

Returns a pointer to the beginning of the sequence.

Returns: a pointer to the beginning of the sequence

inline constexpr size_type size() const noexcept

Returns the number of elements in the span.

Returns: the number of elements in the span

inline constexpr size_type size_bytes() const noexcept

Returns the size of the sequence in bytes.

Returns: the size of the sequence in bytes

inline constexpr bool empty() const noexcept

Checks if the span is empty.

Returns: true if the span is empty (i.e. size() == 0); false otherwise

template<std::size_t Count> inline constexpr span<element_type, Count> first() const

Obtains a subspan consisting of the first N elements of the sequence.

The program is ill-formed if Count > extent. The behavior is undefined if Count > size().

Template Parameters: Count – the number of elements of the subspan
Returns: a span that is a view over the first Count elements of *this

inline constexpr span<element_type, dynamic_extent> first(size_type Count) const

Obtains a subspan consisting of the first N elements of the sequence.

The program is ill-formed if Count > extent. The behavior is undefined if Count > size().

Parameters: Count – the number of elements of the subspan
Returns: a span of dynamic extent that is a view over the first Count elements of *this

template<std::size_t Count> inline constexpr span<element_type, Count> last() const

Obtains a subspan consisting of the last N elements of the sequence.

The program is ill-formed if Count > Extent. The behavior is undefined if Count > size().

Template Parameters: Count – the number of elements of the subspan
Returns: a span that is a view over the last Count elements of *this

inline constexpr span<element_type, dynamic_extent> last(size_type Count) const

Obtains a subspan consisting of the last N elements of the sequence.

The program is ill-formed if Count > extent. The behavior is undefined if Count > size().

Parameters: Count – the number of elements of the subspan
Returns: a span of dynamic extent that is a view over the last Count elements of *this

template<std::size_t Offset, std::size_t Count = dynamic_extent> inline constexpr span<element_type, detail::DetermineSubspanExtent<extent, Offset, Count>::value> subspan() const

Obtains a subspan that is a view over Count elements of this span starting at Offset.

If Count is dynamic_extent, the number of elements in the subspan is size() - Offset (i.e. it ends at the end of *this). Ill-formed if Offset is greater than extent, or Count is not dynamic_extent and Count is greater than extent - Offset. Behavior is undefined if either Offset or Count is out of range. This happens if Offset is greater than size(), or Count is not dynamic_extent and Count is greater than size() - Offset. The extent of the returned span is determined as follows: if Count is not dynamic_extent, Count; otherwise, if Extent is not dynamic_extent, Extent - Offset; otherwise dynamic_extent.

Template Parameters

Offset – The offset within *this to start the subspan
Count – The length of the subspan, or dynamic_extent to indicate the rest of the span.

Returns

A subspan of the given range

inline constexpr span<element_type, dynamic_extent> subspan(size_type Offset, size_type Count = dynamic_extent) const

Obtains a subspan that is a view over Count elements of this span starting at Offset.

If Count is dynamic_extent, the number of elements in the subspan is size() - Offset (i.e. it ends at the end of *this). Behavior is undefined if either Offset or Count is out of range. This happens if Offset is greater than size(), or Count is not dynamic_extent and Count is greater than size() - Offset. The extent of the returned span is always dynamic_extent.

Parameters

Offset – The offset within *this to start the subspan
Count – The length of the subspan, or dynamic_extent to indicate the rest of the span.

Returns

A subspan of the given range

Public Static Attributes

static constexpr std::size_t extent = Extent : The number of elements in the sequence, or dynamic_extent if dynamic.