Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/container/span"

From cppreference.com
< cpp‎ | container
m (and -> &&)
(Addec LWG issue #3903 DR.)
Line 56: Line 56:
 
{{dsc inc|cpp/container/span/dsc constructor}}
 
{{dsc inc|cpp/container/span/dsc constructor}}
 
{{dsc inc|cpp/container/span/dsc operator{{=}}}}
 
{{dsc inc|cpp/container/span/dsc operator{{=}}}}
 +
{{dsc mem dtor|nolink=true|notes={{mark implicit}}|destructs a {{tt|span}}}}
  
 
{{dsc h2|Iterators}}
 
{{dsc h2|Iterators}}
Line 121: Line 122:
 
template<class T, std::size_t N>
 
template<class T, std::size_t N>
 
[[nodiscard]]
 
[[nodiscard]]
−
constexpr auto slide(std::span<T,N> s, std::size_t offset, std::size_t width)
+
constexpr auto slide(std::span<T, N> s, std::size_t offset, std::size_t width)
 
{
 
{
 
     return s.subspan(offset, offset + width <= s.size() ? width : 0U);
 
     return s.subspan(offset, offset + width <= s.size() ? width : 0U);
Line 127: Line 128:
  
 
template<class T, std::size_t N, std::size_t M>
 
template<class T, std::size_t N, std::size_t M>
−
constexpr bool starts_with(std::span<T,N> data, std::span<T,M> prefix)
+
constexpr bool starts_with(std::span<T, N> data, std::span<T, M> prefix)
 
{
 
{
 
     return data.size() >= prefix.size()
 
     return data.size() >= prefix.size()
Line 134: Line 135:
  
 
template<class T, std::size_t N, std::size_t M>
 
template<class T, std::size_t N, std::size_t M>
−
constexpr bool ends_with(std::span<T,N> data, std::span<T,M> suffix)
+
constexpr bool ends_with(std::span<T, N> data, std::span<T, M> suffix)
 
{
 
{
 
     return data.size() >= suffix.size()
 
     return data.size() >= suffix.size()
Line 142: Line 143:
  
 
template<class T, std::size_t N, std::size_t M>
 
template<class T, std::size_t N, std::size_t M>
−
constexpr bool contains(std::span<T,N> span, std::span<T,M> sub)
+
constexpr bool contains(std::span<T, N> span, std::span<T, M> sub)
 
{
 
{
 
     return std::ranges::search(span, sub).begin() != span.end();
 
     return std::ranges::search(span, sub).begin() != span.end();
Line 158: Line 159:
 
     constexpr int a[]{0, 1, 2, 3, 4, 5, 6, 7, 8};
 
     constexpr int a[]{0, 1, 2, 3, 4, 5, 6, 7, 8};
 
     constexpr int b[]{8, 7, 6};
 
     constexpr int b[]{8, 7, 6};
−
 
+
   
 
     for (std::size_t offset{}; ; ++offset)
 
     for (std::size_t offset{}; ; ++offset)
 
     {
 
     {
Line 167: Line 168:
 
         print(s);
 
         print(s);
 
     }
 
     }
−
 
+
   
 
     static_assert(
 
     static_assert(
 
         starts_with(std::span{a}, std::span{a, 4}) &&
 
         starts_with(std::span{a}, std::span{a, 4}) &&
Line 188: Line 189:
 
===Defect reports===
 
===Defect reports===
 
{{dr list begin}}
 
{{dr list begin}}
−
{{dr list item|paper=P2325R3|std=C++20|before={{tt|span}} of non-zero static extents were not {{tt|view}}|after=they are as {{lconcept|default_initializable}} is not required}}
+
{{dr list item|wg=lwg|dr=3903|std=C++20|before=the declaration of {{tt|span}}'s destructor was unnucessary|after=removed the declaration}}
 +
{{dr list item|paper=P2325R3|std=C++20|before=a {{tt|span}} of non-zero static extents was not a {{tt|view}}|after=any {{tt|span}} is a {{tt|view}}}}
 
{{dr list end}}
 
{{dr list end}}
  

Revision as of 00:21, 3 November 2023

 
C++
 
Containers library
 
std::span
 
Defined in header <span>
template<

    class T,
    std::size_t Extent = std::dynamic_extent

> class span;
 (since C++20)

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, a typical implementation holds two members: a pointer to T and a size. A span with static extent may have only one member: a pointer to T.

Every specialization of std::span is a TriviallyCopyable type.

(since C++23)

Contents

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 std::dynamic_extent if dynamic

Member types

Member type Definition
element_type T
value_type std::remove_cv_t<T>
size_type std::size_t
difference_type std::ptrdiff_t
pointer T*
const_pointer const T*
reference T&
const_reference const T&
iterator implementation-defined LegacyRandomAccessIterator, ConstexprIterator, and contiguous_iterator whose value_type is value_type
const_iterator(C++23) std::const_iterator<iterator>
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator(C++23) std::const_iterator<reverse_iterator>

Note: iterator is a mutable iterator if T is not const-qualified.

All requirements on the iterator types of a Container apply to the iterator type of span as well.

Member constant

static constexpr std::size_t extent = Extent;
 (since C++20)

Member functions

orphaned, replaced with Template:cpp/container/dsc operator_at. orphaned, replaced with Template:cpp/container/dsc data.
constructs a span
(public member function) [edit]
assigns a span
(public member function) [edit]
(destructor)
(implicitly declared)
 destructs a span
(public member function)
Iterators
(C++23)
 returns an iterator to the beginning
(public member function) [edit]
(C++23)
 returns an iterator to the end
(public member function) [edit]
(C++23)
 returns a reverse iterator to the beginning
(public member function) [edit]
(C++23)
 returns a reverse iterator to the end
(public member function) [edit]
Element access
access the first element
(public member function) [edit]
access the last element
(public member function) [edit]
Observers
(C++20)
 returns the number of elements in the sequence
(public member function) [edit]
returns the size of the sequence in bytes
(public member function) [edit]
checks if the sequence is empty
(public member function) [edit]
Subviews
obtains a subspan consisting of the first N elements of the sequence
(public member function) [edit]
obtains a subspan consisting of the last N elements of the sequence
(public member function) [edit]
obtains a subspan
(public member function) [edit]

Non-member functions

(C++20)
 converts a span into a view of its underlying bytes
(function template) [edit]

Non-member constant

(C++20)
 a constant of type std::size_t signifying that the span has dynamic extent
(constant) [edit]

Helper templates

template< class T, std::size_t Extent >
inline constexpr bool ranges::enable_borrowed_range<std::span<T, Extent>> = true;
 (since C++20)

This specialization of ranges::enable_borrowed_range makes span satisfy borrowed_range.

template< class T, std::size_t Extent >
inline constexpr bool ranges::enable_view<std::span<T, Extent>> = true;
 (since C++20)

This specialization of ranges::enable_view makes span satisfy view.

Deduction guides(C++20)

Notes

Specializations of std::span are already trivially copyable types in all existing implementations, even before the formal requirement introduced in C++23.

Feature-test macro Value Std Feature
__cpp_lib_span 202002L (C++20) std::span

Example

The example uses std::span to implement some algorithms on contiguous ranges.

Run this code
#include <algorithm>
#include <cstddef>
#include <iostream>
#include <span>
 
template<class T, std::size_t N>
[[nodiscard]]
constexpr auto slide(std::span<T, N> s, std::size_t offset, std::size_t width)
{
    return s.subspan(offset, offset + width <= s.size() ? width : 0U);
}
 
template<class T, std::size_t N, std::size_t M>
constexpr bool starts_with(std::span<T, N> data, std::span<T, M> prefix)
{
    return data.size() >= prefix.size()
        && std::equal(prefix.begin(), prefix.end(), data.begin());
}
 
template<class T, std::size_t N, std::size_t M>
constexpr bool ends_with(std::span<T, N> data, std::span<T, M> suffix)
{
    return data.size() >= suffix.size()
        && std::equal(data.end() - suffix.size(), data.end(),
                      suffix.end() - suffix.size());
}
 
template<class T, std::size_t N, std::size_t M>
constexpr bool contains(std::span<T, N> span, std::span<T, M> sub)
{
    return std::ranges::search(span, sub).begin() != span.end();
}
 
void print(const auto& seq)
{
    for (const auto& elem : seq)
        std::cout << elem << ' ';
    std::cout << '\n';
}
 
int main()
{
    constexpr int a[]{0, 1, 2, 3, 4, 5, 6, 7, 8};
    constexpr int b[]{8, 7, 6};
 
    for (std::size_t offset{}; ; ++offset)
    {
        static constexpr std::size_t width{6};
        auto s = slide(std::span{a}, offset, width);
        if (s.empty())
            break;
        print(s);
    }
 
    static_assert(
        starts_with(std::span{a}, std::span{a, 4}) &&
        starts_with(std::span{a + 1, 4}, std::span{a + 1, 3}) &&
       !starts_with(std::span{a}, std::span{b}) &&
       !starts_with(std::span{a, 8}, std::span{a + 1, 3}) &&
        ends_with(std::span{a}, std::span{a + 6, 3}) &&
       !ends_with(std::span{a}, std::span{a + 6, 2}) &&
        contains(std::span{a}, std::span{a + 1, 4}) &&
       !contains(std::span{a, 8}, std::span{a, 9})
    );
}

Output: 

0 1 2 3 4 5
1 2 3 4 5 6
2 3 4 5 6 7
3 4 5 6 7 8

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 3903 C++20 the declaration of span's destructor was unnucessary removed the declaration
P2325R3 C++20 a span of non-zero static extents was not a view any span is a view

See also

(C++23)
 a multi-dimensional non-owning array view
(class template) [edit]
(C++20)
 combines an iterator-sentinel pair into a view
(class template) [edit]
(C++11)
 references a temporary array created in list-initialization
(class template) [edit]
(C++17)
 read-only string view
(class template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/span&oldid=161925"