bslstl_span

Functions
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span () BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (const span &original) BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (pointer ptr, size_type count)
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (pointer first, pointer last)
template<size_t SIZE>
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (typename Span_Utility::TypeIdentity< element_type >::type(&arr)[SIZE]) BSLS_KEYWORD_NOEXCEPT
template<class t_OTHER_TYPE >
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (bsl::array< t_OTHER_TYPE, EXTENT > &arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type=NULL) BSLS_KEYWORD_NOEXCEPT
template<class t_OTHER_TYPE >
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (const bsl::array< t_OTHER_TYPE, EXTENT > &arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< const t_OTHER_TYPE, element_type >::value, void * >::type=NULL) BSLS_KEYWORD_NOEXCEPT
template<class t_OTHER_TYPE >
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (std::array< t_OTHER_TYPE, EXTENT > &arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type=NULL) BSLS_KEYWORD_NOEXCEPT
template<class t_OTHER_TYPE >
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (const std::array< t_OTHER_TYPE, EXTENT > &arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< const t_OTHER_TYPE, element_type >::value, void * >::type=NULL) BSLS_KEYWORD_NOEXCEPT
template<class t_OTHER_TYPE >
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (const span< t_OTHER_TYPE, EXTENT > &other, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type=NULL) BSLS_KEYWORD_NOEXCEPT
template<class t_OTHER_TYPE >
BSLS_KEYWORD_CONSTEXPR_CPP14	bsl::span< TYPE, EXTENT >::span (const bsl::span< t_OTHER_TYPE, bsl::dynamic_extent > &other, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type) BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR pointer	bsl::span< TYPE, EXTENT >::data () const BSLS_KEYWORD_NOEXCEPT
	Return a pointer to the data referenced by this span.
BSLS_KEYWORD_CONSTEXPR bool	bsl::span< TYPE, EXTENT >::empty () const BSLS_KEYWORD_NOEXCEPT
template<size_t COUNT>
BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, COUNT >	bsl::span< TYPE, EXTENT >::first () const
BSLS_KEYWORD_CONSTEXPR_CPP14 span< element_type, dynamic_extent >	bsl::span< TYPE, EXTENT >::first (size_type count) const
template<size_t COUNT>
BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, COUNT >	bsl::span< TYPE, EXTENT >::last () const
BSLS_KEYWORD_CONSTEXPR_CPP14 span< element_type, dynamic_extent >	bsl::span< TYPE, EXTENT >::last (size_type count) const
BSLS_KEYWORD_CONSTEXPR size_type	bsl::span< TYPE, EXTENT >::size_bytes () const BSLS_KEYWORD_NOEXCEPT
	Return the size of this span in bytes.
BSLS_KEYWORD_CONSTEXPR_CPP14 span< element_type, dynamic_extent >	bsl::span< TYPE, EXTENT >::subspan (size_type offset, size_type count=dynamic_extent) const
BSLS_KEYWORD_CONSTEXPR_CPP14 iterator	bsl::span< TYPE, EXTENT >::begin () const BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14 iterator	bsl::span< TYPE, EXTENT >::end () const BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14 reverse_iterator	bsl::span< TYPE, EXTENT >::rbegin () const BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14 reverse_iterator	bsl::span< TYPE, EXTENT >::rend () const BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14 span &	bsl::span< TYPE, EXTENT >::operator= (const span &) BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14 void	bsl::span< TYPE, EXTENT >::swap (span &other) BSLS_KEYWORD_NOEXCEPT
BSLS_KEYWORD_CONSTEXPR_CPP14 reference	bsl::span< TYPE, EXTENT >::back () const
BSLS_KEYWORD_CONSTEXPR_CPP14 reference	bsl::span< TYPE, EXTENT >::front () const
BSLS_KEYWORD_CONSTEXPR size_type	bsl::span< TYPE, EXTENT >::size () const BSLS_KEYWORD_NOEXCEPT
	Return the size of this span.
template<size_t OFFSET, size_t COUNT>
BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, COUNT >	bsl::span< TYPE, EXTENT >::subspan () const
BSLS_KEYWORD_CONSTEXPR_CPP14 reference	bsl::span< TYPE, EXTENT >::operator[] (size_type index) const

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Using Span To Pass A Portion Of An Array As A Container
    • Example 2: Returning A Subset Of A Container From A Function

Purpose

Provide a (mostly) standard-compliant span class template.

Classes

• bsl::span: C++03-compliant implementation of std::span.

Canonical header: bsl_span.h

See also

ISO C++ Standard

Description

This component provides the C+20 standard view type span, that is a view over a contiguous sequence of objects. Note that if compiler supports the C++20 standard, then the std implementation of span is used.

There are two implementations of span; one for statically sized (i. e., size fixed at compile time) spans, and dynamically sized (size can be altered at run-time).

bsl::span differs from std::span in the following ways:

• The constexpr inline symbol std::dynamic_extent has been replaced by an enumeration for C++03 compatibility.
• A bsl::span can be implicitly constructed from a bsl::array.
• The implicit construction from an arbitrary container that supports data() and size() is enabled only for C++11 and later.
• bsl::span is implicitly constructible from a bsl::vector in C++03.

Usage

This section illustrates intended usage of this component.

Example 1: Using Span To Pass A Portion Of An Array As A Container

Suppose we already have an array of values of type TYPE, and we want to pass a subset of the array to a function, which is expecting some kind of a container. We can create a span from the array, and then pass that. Since the span is a view into the array, i.e, the span owns no storage, the elements in the span are the same as the ones in the array.

First, we create a template function that takes a generic container. This function inspects each of the (numeric) values in the container, and if the low bit is set, flips it. This has the effect of turning odd values into even values.

template <class CONTAINER>
void MakeEven(CONTAINER &c)
    // Make every value in the specified container 'c' even.
{
    for (typename CONTAINER::iterator it = c.begin();
                                      it != c.end();
                                      ++it) {
        if (*it & 1) {
            *it ^= 1;
        }
    }
}

We then create a span, and verify that it contains the values that we expect, and pass it to MakeEven to modify it. Afterwards, we check that none of the elements in the array that were not included in the span are unchanged, and the ones in the span were.

int            arr[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
bsl::span<int> sp(arr + 3, 4);   // 4 elements, starting at 3.
for (int i = 0; i < 10; ++i)
{
    assert(arr[i] == i);
}
 
assert(sp[0] == 3);
assert(sp[1] == 4);
assert(sp[2] == 5);
assert(sp[3] == 6);
 
MakeEven(sp);
 
assert(sp[0] == 2); // Has been changed
assert(sp[1] == 4);
assert(sp[2] == 4); // Has been changed
assert(sp[3] == 6);
 
assert(arr[0] == 0); // Not part of the span
assert(arr[1] == 1); // Not part of the span
assert(arr[2] == 2); // Not part of the span
assert(arr[3] == 2); // Has been changed
assert(arr[4] == 4);
assert(arr[5] == 4); // Has been changed
assert(arr[6] == 6);
assert(arr[7] == 7); // Not part of the span
assert(arr[8] == 8); // Not part of the span
assert(arr[9] == 9); // Not part of the span

Example 2: Returning A Subset Of A Container From A Function

Suppose we already have a vector of values of type TYPE, and we want to return a (contiguous) subset of the vector from a function, which can then be processed processed using a range-based for loop. To achieve that, we can use span as the return type. The calling code can then interate over the span as if it was a container. Note that since the span doesn't own the elements of the vector, the span might become invalid when the vector is changed (or resized, or destroyed).

First, we create the vector and define our function that returns a slice as a span.

bsl::vector<int> v = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
 
/// Return a span into the specified `vec`, starting at the specified
/// `first` index, and continuing up to (but not including) the
/// specified `last` index.
bsl::span<const int> slice(const bsl::vector<int>& vec,
                           size_t                  first,
                           size_t                  last)
{
    return bsl::span<const int>(vec.data() + first, last-first);
}

We can now iterate over the elements in the slice using the span:

bsl::span<const int> sp = slice(v, 4, 7);
int            val = 4;
for (int x: sp) {
     assert(x == val++);
 }

Note that we can use the return value directly and avoid declaring the variable sp:

 val = 2;
 for (int x: slice(v, 2, 8)) {
     assert(x == val++);
 }

Function Documentation

back()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent >::reference bsl::span< TYPE >::back ( ) const

inline

Return a reference to the last element of this span. The behavior is undefined if this span is empty.

begin()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent >::iterator bsl::span< TYPE >::begin ( ) const

inline

Return an iterator providing modifiable access to the first element of this span, and the past-the-end iterator if this span is empty.

data()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR bsl::span< TYPE, bsl::dynamic_extent >::pointer bsl::span< TYPE >::data ( ) const

inline

empty()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR bool bsl::span< TYPE >::empty ( ) const

inline

Return true if this span contains no elements and false otherwise.

end()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent >::iterator bsl::span< TYPE >::end ( ) const

inline

Return the past-the-end iterator providing modifiable access to this span.

first() [1/2]

template<class TYPE >

template<size_t COUNT>

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, COUNT > bsl::span< TYPE >::first ( ) const

inline

first() [2/2]

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent > bsl::span< TYPE >::first ( size_type  count ) const

inline

Return a dynamically-sized span consisting of the first (specified) count elements of this span. The behavior is undefined unless count <= size().

front()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent >::reference bsl::span< TYPE >::front ( ) const

inline

Return a reference to the first element of this span. The behavior is undefined if this span is empty.

last() [1/2]

template<class TYPE >

template<size_t COUNT>

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, COUNT > bsl::span< TYPE >::last ( ) const

inline

last() [2/2]

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent > bsl::span< TYPE >::last ( size_type  count ) const

inline

Return a dynamically-sized span consisting of the last (specified) count elements of this span. The behavior is undefined unless count <= size().

operator=()

template<class TYPE , size_t EXTENT>

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, EXTENT > & bsl::span< TYPE, EXTENT >::operator= ( const span< TYPE, EXTENT > &  rhs )

inline

Assign to this span the value of the specified rhs object, and return a reference providing modifiable access to this span.

operator[]()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent >::reference bsl::span< TYPE >::operator[] ( size_type  index ) const

inline

Return a reference to the element at the specified index. The behavior is undefined unless index < size().

rbegin()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent >::reverse_iterator bsl::span< TYPE >::rbegin ( ) const

inline

Return a reverse iterator providing modifiable access to the last element of this span, and the past-the-end reverse iterator if this span is empty.

rend()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent >::reverse_iterator bsl::span< TYPE >::rend ( ) const

inline

Return the past-the-end reverse iterator providing modifiable access to this span.

size()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR bsl::span< TYPE, bsl::dynamic_extent >::size_type bsl::span< TYPE >::size ( ) const

inline

size_bytes()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR bsl::span< TYPE, bsl::dynamic_extent >::size_type bsl::span< TYPE >::size_bytes ( ) const

inline

span() [1/11]

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE >::span ( )

inline

Construct an empty span object. The behavior is undefined unless 0 == EXTENT

span() [2/11]

template<class TYPE , size_t EXTENT>

template<class t_OTHER_TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, EXTENT >::span ( bsl::array< t_OTHER_TYPE, EXTENT > &  arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type  = NULL  )

inline

Construct a span from the specified bsl::array arr. This constructor participates in overload resolution only if t_OTHER_TYPE(*)[] is convertible to element_type(*)[].

span() [3/11]

template<class TYPE , size_t EXTENT>

template<class t_OTHER_TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, EXTENT >::span ( const bsl::array< t_OTHER_TYPE, EXTENT > &  arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< const t_OTHER_TYPE, element_type >::value, void * >::type  = NULL  )

inline

Construct a span from the specified bsl::array arr. This constructor participates in overload resolution only if t_OTHER_TYPE(*)[] is convertible to element_type(*)[].

span() [4/11]

template<class TYPE , size_t EXTENT>

template<class t_OTHER_TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, EXTENT >::span ( const bsl::span< t_OTHER_TYPE, bsl::dynamic_extent > &  other, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type    )

inline

span() [5/11]

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE >::span ( const span< TYPE, EXTENT > &  original )

inline

Create a span that refers to the same data as the specified original object.

span() [6/11]

template<class TYPE , size_t EXTENT>

template<class t_OTHER_TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, EXTENT >::span ( const span< t_OTHER_TYPE, EXTENT > &  other, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type  = NULL  )

inline

Construct a span from the specified span other. This constructor participates in overload resolution only if t_OTHER_TYPE(*)[] is convertible to element_type(*)[].

span() [7/11]

template<class TYPE , size_t EXTENT>

template<class t_OTHER_TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, EXTENT >::span ( const std::array< t_OTHER_TYPE, EXTENT > &  arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< const t_OTHER_TYPE, element_type >::value, void * >::type  = NULL  )

inline

Construct a span from the specified std::array arr. This constructor participates in overload resolution only if t_OTHER_TYPE(*)[] is convertible to element_type(*)[].

span() [8/11]

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE >::span ( pointer  first, pointer  last  )

inlineexplicit

Construct a span from the specified first and specified last. The behavior is undefined unless EXTENT == bsl::distance(first, last).

span() [9/11]

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE >::span ( pointer  ptr, size_type  count  )

inlineexplicit

Construct a span that refers to the specified count consecutive objects starting from the specified ptr. The behavior is undefined unless EXTENT == count.

span() [10/11]

template<class TYPE , size_t EXTENT>

template<class t_OTHER_TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, EXTENT >::span ( std::array< t_OTHER_TYPE, EXTENT > &  arr, typename bsl::enable_if< Span_Utility::IsArrayConvertible< t_OTHER_TYPE, element_type >::value, void * >::type  = NULL  )

inline

Construct a span from the specified std::array arr. This constructor participates in overload resolution only if t_OTHER_TYPE(*)[] is convertible to element_type(*)[].

span() [11/11]

template<class TYPE >

template<size_t SIZE>

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE >::span ( typename Span_Utility::TypeIdentity< element_type >::type(&)  arr[SIZE] )

inline

Construct a span from the specified C-style array arr. The behavior is undefined unless SIZE == EXTENT.

subspan() [1/2]

template<class TYPE , size_t EXTENT>

template<size_t OFFSET, size_t COUNT>

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, COUNT > bsl::span< TYPE, EXTENT >::subspan ( ) const

inline

subspan() [2/2]

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 bsl::span< TYPE, bsl::dynamic_extent > bsl::span< TYPE >::subspan ( size_type  offset, size_type  count = dynamic_extent  ) const

inline

Return a dynamically-sized span starting at the specified offset. If the optionally specified count is dynamic_extent , the span will consist of the half-open range [offset, size () - offset) and the behavior is undefined if offset > size(). Otherwise, the span will consist of the half-open range [offset, count) and the behavior is undefined if offset + count > size().

swap()

template<class TYPE >

BSLS_KEYWORD_CONSTEXPR_CPP14 void bsl::span< TYPE >::swap ( span< TYPE, EXTENT > &  other )

inline

Exchange the value of this span with the value of the specified other object.