span.h File Reference

#include <cassert>
#include <cstddef>
#include <span>
#include <type_traits>
#include <utility>

Include dependency graph for span.h:

Go to the source code of this file.

Concepts
concept	BasicByte

Functions
template<typename T >
T &	SpanPopBack (std::span< T > &span)
	A span is an object that can refer to a contiguous sequence of objects. More...
template<typename V >
auto	MakeByteSpan (const V &v) noexcept
template<typename V >
auto	MakeWritableByteSpan (V &&v) noexcept
unsigned char *	UCharCast (char *c)
unsigned char *	UCharCast (unsigned char *c)
unsigned char *	UCharCast (signed char *c)
unsigned char *	UCharCast (std::byte *c)
const unsigned char *	UCharCast (const char *c)
const unsigned char *	UCharCast (const unsigned char *c)
const unsigned char *	UCharCast (const signed char *c)
const unsigned char *	UCharCast (const std::byte *c)
template<typename T , size_t N>
constexpr auto	UCharSpanCast (std::span< T, N > s)
template<typename V >
constexpr auto	MakeUCharSpan (const V &v) -> decltype(UCharSpanCast(std::span{v}))
	Like the std::span constructor, but for (const) unsigned char member types only. More...
template<typename V >
constexpr auto	MakeWritableUCharSpan (V &&v) -> decltype(UCharSpanCast(std::span{std::forward< V >(v)}))

Function Documentation

MakeByteSpan()

template<typename V >

auto MakeByteSpan ( const V &  v )

noexcept

Definition at line 84 of file span.h.

Here is the caller graph for this function:

MakeUCharSpan()

template<typename V >

constexpr auto MakeUCharSpan ( const V &  v ) -> decltype(UCharSpanCast(std::span{v}))

constexpr

Like the std::span constructor, but for (const) unsigned char member types only.

Only works for (un)signed char containers.

Definition at line 111 of file span.h.

Here is the caller graph for this function:

MakeWritableByteSpan()

template<typename V >

auto MakeWritableByteSpan ( V &&  v )

noexcept

Definition at line 89 of file span.h.

Here is the caller graph for this function:

MakeWritableUCharSpan()

template<typename V >

constexpr auto MakeWritableUCharSpan ( V &&  v ) -> decltype(UCharSpanCast(std::span{std::forward<V>(v)}))

constexpr

Definition at line 112 of file span.h.

SpanPopBack()

template<typename T >

T & SpanPopBack

(

std::span< T > &

span

)

A span is an object that can refer to a contiguous sequence of objects.

Things to be aware of when writing code that deals with spans:

• Similar to references themselves, spans are subject to reference lifetime issues. The user is responsible for making sure the objects pointed to by a span live as long as the span is used. For example:

  std::vector<int> vec{1,2,3,4};
  std::span<int> sp(vec);
  vec.push_back(5);
  printf("%i\n", sp.front()); // UB!
  

  may exhibit undefined behavior, as increasing the size of a vector may invalidate references.
• One particular pitfall is that spans can be constructed from temporaries, but this is unsafe when the span is stored in a variable, outliving the temporary. For example, this will compile, but exhibits undefined behavior:

  std::span<const int> sp(std::vector<int>{1, 2, 3});
  printf("%i\n", sp.front()); // UB!
  

  The lifetime of the vector ends when the statement it is created in ends. Thus the span is left with a dangling reference, and using it is undefined.

• Due to spans automatic creation from range-like objects (arrays, and data types that expose a data() and size() member function), functions that accept a span as input parameter can be called with any compatible range-like object. For example, this works:

  void Foo(std::span<const int> arg);
  
  Foo(std::vector<int>{1, 2, 3}); // Works
  

  This is very useful in cases where a function truly does not care about the container, and only about having exactly a range of elements. However it may also be surprising to see automatic conversions in this case.

  When a function accepts a span with a mutable element type, it will not accept temporaries; only variables or other references. For example:

  void FooMut(std::span<int> arg);
  
  FooMut(std::vector<int>{1, 2, 3}); // Does not compile
  std::vector<int> baz{1, 2, 3};
  FooMut(baz); // Works
  

  This is similar to how functions that take (non-const) lvalue references as input cannot accept temporaries. This does not work either:

  void FooVec(std::vector<int>& arg);
  FooVec(std::vector<int>{1, 2, 3}); // Does not compile
  

  The idea is that if a function accepts a mutable reference, a meaningful result will be present in that variable after the call. Passing a temporary is useless in that context. Pop the last element off a span, and return a reference to that element.

Definition at line 75 of file span.h.

Here is the caller graph for this function:

UCharCast() [1/8]

unsigned char * UCharCast ( char *  c )

inline

Definition at line 95 of file span.h.

Here is the caller graph for this function:

UCharCast() [2/8]

const unsigned char * UCharCast ( const char *  c )

inline

Definition at line 99 of file span.h.

UCharCast() [3/8]

const unsigned char * UCharCast ( const signed char *  c )

inline

Definition at line 101 of file span.h.

UCharCast() [4/8]

const unsigned char * UCharCast ( const std::byte *  c )

inline

Definition at line 102 of file span.h.

UCharCast() [5/8]

const unsigned char * UCharCast ( const unsigned char *  c )

inline

Definition at line 100 of file span.h.

UCharCast() [6/8]

unsigned char * UCharCast ( signed char *  c )

inline

Definition at line 97 of file span.h.

UCharCast() [7/8]

unsigned char * UCharCast ( std::byte *  c )

inline

Definition at line 98 of file span.h.

UCharCast() [8/8]

unsigned char * UCharCast ( unsigned char *  c )

inline

Definition at line 96 of file span.h.

UCharSpanCast()

template<typename T , size_t N>

constexpr auto UCharSpanCast ( std::span< T, N >  s )

constexpr

Definition at line 108 of file span.h.

Here is the call graph for this function: