#include <Corrade/Containers/ArrayView.h>
template<class T>
Corrade::Containers::ArrayView class

Array view.

A non-owning wrapper around a sized continuous range of data, similar to a dynamic std::span from C++20. For a variant with compile-time size information see StaticArrayView, for sparse and multi-dimensional views see StridedArrayView, for efficient bit manipulation see BitArrayView. An owning version of this container is an Array.

Usage

The class is implicitly convertible from compile-time-sized C arrays and Array / StaticArray instances of the same underlying type; it's also possible to implicitly create a const view on a mutable array. Besides that, a view can be created manually from a pointer and size:

/* Convert from a compile-time-sized C array */
int data1[]{5, 17, -36, 185};
Containers::ArrayView<int> a = data1;               // a.size() == 4

/* Create a const view on a mutable Array */
Containers::Array<int> data2{15};
Containers::ArrayView<const int> b = data2;         // b.size() == 15

/* Construct from a pointer and explicit size */
float* data3 = …;
Containers::ArrayView<float> c{data3, 1337};        // c.size() == 1337

In addition there are ArrayView<void> / ArrayView<const void> specializations, which are meant to be used in cases where APIs accept opaque blobs of data, such as writing data to a file. These provide no element access, only data pointer and size in bytes, and an ArrayView of any type is convertible to them:

Containers::ArrayView<const int> d = data1;         // d.size() == 4
Containers::ArrayView<const void> e = d;            // e.size() == 16

Data access

The class provides the usual C++ container interface — data(), size() and isEmpty(); subscript access via operator T*(), range access via begin() / end(), and their overloads and acess to the front() and back() element, if the view is non-empty. The view itself is immutable and thus all member functions are const, but if the underlying type is mutable the references and pointers returned from these are mutable as well.

Containers::ArrayView<int> view = …;

if(!view.isEmpty()) {
    int min = view.front();
    for(int i: view) if(i < min) min = i;

    …
}

if(view.size() > 2 && view[2] < 3) view[2] += 5;

View slicing

Except for the usual element access via begin(), end() and operator T*() that provides also access via [], there's a collection of slicing functions — slice(), sliceSize(), prefix(), suffix(), exceptPrefix() and exceptSuffix():

int data[]{0, 10, 20, 30, 40, 50, 60};
Containers::ArrayView<int> view = data;

Containers::ArrayView<int> a1 = view.slice(3, 5);       // {30, 40}
Containers::ArrayView<int> a2 = view.sliceSize(3, 2);   // {30, 40}
Containers::ArrayView<int> b = view.prefix(4);       // {0, 10, 20, 30}
Containers::ArrayView<int> c = view.exceptPrefix(4); // {40, 50, 60}
Containers::ArrayView<int> d = view.exceptSuffix(2); // {0, 10, 20, 30, 40}

The slice(), sliceSize(), prefix(), suffix() APIs accept also a pointer as the begin/end arguments. As a special case, if prefix() and suffix() are called with nullptr, they return a zero-sized nullptr view. Both are useful when doing various kinds of searches and propagating failure states, for example as shown below:

int* end = view;
while(*end < 25) ++end;
Containers::ArrayView<int> numbersLessThan25 = view.prefix(end); // {0, 10, 20}

int* fortyfive = nullptr;
for(int& i: view) if(i == 45) {
    fortyfive = &i;
    break;
}
Containers::ArrayView<int> fortyfiveAndBeyond = view.suffix(fortyfive); // {}

Finally, the slicing operations provide a conversion to StaticArrayView (or its convenience typedefs ArrayView2, ArrayView3 etc.). Compile-time-sized arrays are useful for APIs that want to enforce a particular number of elements at compile time:

int min3(Containers::ArrayView3<const int>);

int minOfFirstThree = min3(view.prefix<3>());

All slice operations fire an assert if the arguments are out of range, for StaticArrayView conversions the checks are done at compile time when possible.

Convenience functions and type conversion

To avoid having to specify the full type when constructing a view or when you need to disambiguate in a function call, the arrayView() (or staticArrayView()) function can be used. These also provide a safe conversion from std::initializer_list that avoids the pitfalls described below As a safer alternative to a reinterpret_cast, arrayCast() performs a cast, recalculates the view size accordingly and additionally checks that the type change makes sense for given type combination and array size:

int data[15];
auto a = Containers::arrayView(data);           // a.size() == 15
auto b = Containers::arrayCast<char>(a);        // b.size() == 60

Finally, arraySize() can be used to query size of compile-time C arrays in a failproof way:

int data[15];

std::size_t size = Containers::arraySize(data);         // size == 15

STL compatibility

Instances of ArrayView and StaticArrayView are convertible from std::vector and std::array if you include Corrade/Containers/ArrayViewStl.h. The conversion is provided in a separate header to avoid unconditional #include <vector> or #include <array>, which significantly affect compile times. Additionally, the arrayView(T&&) overload also allows for such a conversion. The following table lists allowed conversions:

Corrade type↭STL type
ArrayView<T>←std::array<T, size>
ArrayView<void>←std::array<T, size>
ArrayView<const T>←const std::array<T, size>
ArrayView<const void>←const std::array<T, size>
ArrayView<T>←std::vector<T, Allocator>
ArrayView<void>←std::vector<T, Allocator>
ArrayView<const T>←const std::vector<T, Allocator>
ArrayView<const void>←const std::vector<T, Allocator>
StaticArrayView<size, T>←std::array<T, size>
StaticArrayView<size, const T>←const std::array<T, size>

Example:

#include <Corrade/Containers/ArrayViewStl.h>

…

std::vector<int> a;

Containers::ArrayView<int> b = a;

On compilers that support C++2a and std::span, implicit conversion from and also to it is provided in Corrade/Containers/ArrayViewStlSpan.h. For similar reasons, it's a dedicated header to avoid unconditional #include <span>, but this one is even significantly heavier than the <vector> etc. includes, so it's separate from the others as well. The following table lists allowed conversions:

Corrade type↭STL type
ArrayView<T>⇆std::span<T>
ArrayView<T>←std::span<T, size>
ArrayView<void>←std::span<T>
ArrayView<void>←std::span<T, size>
ArrayView<const void>←std::span<T>
ArrayView<const void>←std::span<T, size>
StaticArrayView<size, T>⇆std::span<T, size>
StaticArrayView<size, T>→std::span<T>

Example:

#include <Corrade/Containers/ArrayViewStlSpan.h>

…

std::span<int> a;
Containers::ArrayView<int> b = a;

float c[3]{42.0f, 13.37f, -25.0f};
std::span<float, 3> d = Containers::staticArrayView(c);

Other array classes provide a subset of this STL compatibility as well, see the documentation of StaticArrayView, Array, StaticArray and StridedArrayView for more information.

Public types

using Type = T
Element type.

Constructors, destructors, conversion operators

ArrayView(std::nullptr_t = nullptr) constexpr noexcept
Default constructor.
ArrayView(T* data, std::size_t size) constexpr noexcept
Construct a view on an array with explicit size.
template<class U, std::size_t size>
ArrayView(U(&data)[size]) constexpr noexcept
Construct a view on a fixed-size array.
template<class U>
ArrayView(ArrayView<U> view) constexpr noexcept
Construct a view on an ArrayView.
template<std::size_t size, class U>
ArrayView(StaticArrayView<size, U> view) constexpr noexcept
Construct a view on a StaticArrayView.
template<class U, class = decltype(Implementation::ArrayViewConverter<T, typename std::decay<U && >::type>::from(std::declval<U && >()))>
ArrayView(U&& other) constexpr noexcept
Construct a view on an external type / from an external representation.
template<class U, class = decltype(Implementation::ArrayViewConverter<T, U>::to(std::declval<ArrayView<T>>()))>
operator U() const constexpr
Convert the view to external representation.
operator bool() const explicit constexpr
Whether the view is non-empty.
operator T*() const constexpr
Conversion to the underlying type.

Public functions

auto data() const -> T* constexpr
View data.
auto size() const -> std::size_t constexpr
View size.
auto isEmpty() const -> bool constexpr new in Git master
Whether the view is empty.
auto empty() const -> bool deprecated in Git master constexpr
Whether the view is empty.
auto begin() const -> T* constexpr
Pointer to the first element.
auto cbegin() const -> T* constexpr
auto end() const -> T* constexpr
Pointer to (one item after) the last element.
auto cend() const -> T* constexpr
auto front() const -> T& constexpr
First element.
auto back() const -> T& constexpr
Last element.
auto operator[](std::size_t i) const -> T& constexpr new in Git master
Element access.
auto slice(T* begin, T* end) const -> ArrayView<T> constexpr
View slice.
auto slice(std::size_t begin, std::size_t end) const -> ArrayView<T> constexpr
auto sliceSize(T* begin, std::size_t size) const -> ArrayView<T> constexpr new in Git master
View slice of given size.
auto sliceSize(std::size_t begin, std::size_t size) const -> ArrayView<T> constexpr new in Git master
template<std::size_t size_>
auto slice(T* begin) const -> StaticArrayView<size_, T> constexpr
Fixed-size view slice.
template<std::size_t size_>
auto slice(std::size_t begin) const -> StaticArrayView<size_, T> constexpr
template<std::size_t begin_, std::size_t end_>
auto slice() const -> StaticArrayView<end_ - begin_, T> constexpr new in 2019.10
Fixed-size view slice.
template<std::size_t begin_, std::size_t size_>
auto sliceSize() const -> StaticArrayView<size_, T> constexpr new in Git master
Fixed-size view slice of given size.
auto prefix(T* end) const -> ArrayView<T> constexpr
View prefix until a pointer.
auto suffix(T* begin) const -> ArrayView<T> constexpr
View suffix after a pointer.
auto prefix(std::size_t size) const -> ArrayView<T> constexpr
View on the first size items.
template<std::size_t size_>
auto prefix() const -> StaticArrayView<size_, T> constexpr
Fixed-size view on the first size_ items.
template<std::size_t size_>
auto suffix() const -> StaticArrayView<size_, T> constexpr new in Git master
Fixed-size view on the last size_ items.
auto exceptPrefix(std::size_t size) const -> ArrayView<T> constexpr new in Git master
View except the first size items.
auto suffix(std::size_t begin) const -> ArrayView<T> deprecated in Git master constexpr
View except the first size items.
auto exceptSuffix(std::size_t size) const -> ArrayView<T> constexpr new in Git master
View except the last size items.
auto except(std::size_t count) const -> ArrayView<T> deprecated in Git master constexpr
View except the last size items.

Function documentation

template<class T>
Corrade::Containers::ArrayView<T>::ArrayView(std::nullptr_t = nullptr) constexpr noexcept

Default constructor.

Creates an empty nullptr view. Copy a non-empty Array or ArrayView onto the instance to make it useful.

template<class T>
Corrade::Containers::ArrayView<T>::ArrayView(T* data, std::size_t size) constexpr noexcept

Construct a view on an array with explicit size.

Parameters
data Data pointer
size Data size

template<class T> template<class U, std::size_t size>
Corrade::Containers::ArrayView<T>::ArrayView(U(&data)[size]) constexpr noexcept

Construct a view on a fixed-size array.

Parameters
data Fixed-size array

Enabled only if T* is implicitly convertible to U*. Expects that both types have the same size.

template<class T> template<class U>
Corrade::Containers::ArrayView<T>::ArrayView(ArrayView<U> view) constexpr noexcept

Construct a view on an ArrayView.

Enabled only if T* is implicitly convertible to U*. Expects that both types have the same size.

template<class T> template<std::size_t size, class U>
Corrade::Containers::ArrayView<T>::ArrayView(StaticArrayView<size, U> view) constexpr noexcept

Construct a view on a StaticArrayView.

Enabled only if T* is implicitly convertible to U*. Expects that both types have the same size.

template<class T> template<class U, class = decltype(Implementation::ArrayViewConverter<T, typename std::decay<U && >::type>::from(std::declval<U && >()))>
Corrade::Containers::ArrayView<T>::ArrayView(U&& other) constexpr noexcept

Construct a view on an external type / from an external representation.

template<class T> template<class U, class = decltype(Implementation::ArrayViewConverter<T, U>::to(std::declval<ArrayView<T>>()))>
Corrade::Containers::ArrayView<T>::operator U() const constexpr

Convert the view to external representation.

template<class T>
std::size_t Corrade::Containers::ArrayView<T>::size() const constexpr

View size.

template<class T>
bool Corrade::Containers::ArrayView<T>::isEmpty() const constexpr new in Git master

Whether the view is empty.

template<class T>
bool Corrade::Containers::ArrayView<T>::empty() const constexpr

Whether the view is empty.

template<class T>
T* Corrade::Containers::ArrayView<T>::begin() const constexpr

Pointer to the first element.

template<class T>
T* Corrade::Containers::ArrayView<T>::cbegin() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
T* Corrade::Containers::ArrayView<T>::end() const constexpr

Pointer to (one item after) the last element.

template<class T>
T* Corrade::Containers::ArrayView<T>::cend() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
T& Corrade::Containers::ArrayView<T>::front() const constexpr

First element.

Expects there is at least one element.

template<class T>
T& Corrade::Containers::ArrayView<T>::back() const constexpr

Last element.

Expects there is at least one element.

template<class T>
T& Corrade::Containers::ArrayView<T>::operator[](std::size_t i) const constexpr new in Git master

Element access.

Expects that i is less than size().

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::slice(T* begin, T* end) const constexpr

View slice.

Both arguments are expected to be in range.

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::slice(std::size_t begin, std::size_t end) const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::sliceSize(T* begin, std::size_t size) const constexpr new in Git master

View slice of given size.

Equivalent to data.slice(begin, begin + size).

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::sliceSize(std::size_t begin, std::size_t size) const constexpr new in Git master

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<std::size_t size_>
StaticArrayView<size_, T> Corrade::Containers::ArrayView<T>::slice(T* begin) const constexpr

Fixed-size view slice.

Both begin and begin + size_ are expected to be in range.

template<class T> template<std::size_t size_>
StaticArrayView<size_, T> Corrade::Containers::ArrayView<T>::slice(std::size_t begin) const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<std::size_t begin_, std::size_t end_>
StaticArrayView<end_ - begin_, T> Corrade::Containers::ArrayView<T>::slice() const constexpr new in 2019.10

Fixed-size view slice.

At compile time expects that begin < end_, at runtime that end_ is not larger than size().

template<class T> template<std::size_t begin_, std::size_t size_>
StaticArrayView<size_, T> Corrade::Containers::ArrayView<T>::sliceSize() const constexpr new in Git master

Fixed-size view slice of given size.

Expects that begin_ + size_ is not larger than size().

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::prefix(T* end) const constexpr

View prefix until a pointer.

Equivalent to data.slice(data.begin(), end). If end is nullptr, returns zero-sized nullptr array.

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::suffix(T* begin) const constexpr

View suffix after a pointer.

Equivalent to data.slice(begin, data.end()). If begin is nullptr and the original array isn't, returns zero-sized nullptr array.

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::prefix(std::size_t size) const constexpr

View on the first size items.

Equivalent to data.slice(0, size).

template<class T> template<std::size_t size_>
StaticArrayView<size_, T> Corrade::Containers::ArrayView<T>::prefix() const constexpr

Fixed-size view on the first size_ items.

Equivalent to data.slice<0, size_>().

template<class T> template<std::size_t size_>
StaticArrayView<size_, T> Corrade::Containers::ArrayView<T>::suffix() const constexpr new in Git master

Fixed-size view on the last size_ items.

Equivalent to data.slice<size_>(data.size() - size_).

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::exceptPrefix(std::size_t size) const constexpr new in Git master

View except the first size items.

Equivalent to data.slice(size, data.size()).

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::suffix(std::size_t begin) const constexpr

View except the first size items.

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::exceptSuffix(std::size_t size) const constexpr new in Git master

View except the last size items.

Equivalent to data.slice(0, data.size() - size).

template<class T>
ArrayView<T> Corrade::Containers::ArrayView<T>::except(std::size_t count) const constexpr

View except the last size items.

#include <Corrade/Containers/Array.h>
template<class T> template<class T, class D>
ArrayView<T> arrayView(Array<T, D>& array)

Make a view on an Array.

Convenience alternative to converting to an ArrayView explicitly. The following two lines are equivalent:

Containers::Array<std::uint32_t> data;

Containers::ArrayView<std::uint32_t> a{data};
auto b = Containers::arrayView(data);

#include <Corrade/Containers/Array.h>
template<class T> template<class T, class D>
ArrayView<const T> arrayView(const Array<T, D>& array)

Make a view on a const Array.

Convenience alternative to converting to an ArrayView explicitly. The following two lines are equivalent:

const Containers::Array<std::uint32_t> data;

Containers::ArrayView<const std::uint32_t> a{data};
auto b = Containers::arrayView(data);

template<class T> template<class T>
ArrayView<T> arrayView(T* data, std::size_t size) constexpr

Make a view on an array of specific length.

Convenience alternative to ArrayView::ArrayView(T*, std::size_t). The following two lines are equivalent:

std::uint32_t* data = …;

Containers::ArrayView<std::uint32_t> a{data, 5};
auto b = Containers::arrayView(data, 5);

template<class T> template<std::size_t size, class T>
ArrayView<T> arrayView(T(&data)[size]) constexpr

Make a view on fixed-size array.

Convenience alternative to ArrayView::ArrayView(U(&)[size]). The following two lines are equivalent:

std::uint32_t data[15];

Containers::ArrayView<std::uint32_t> a{data};
auto b = Containers::arrayView(data);

template<class T> template<class T>
ArrayView<const T> arrayView(std::initializer_list<T> list) new in 2020.06

Make a view on an initializer list.

Not present as a constructor in order to avoid accidental dangling references with r-value initializer lists. See the class documentation for more information.

template<class T> template<std::size_t size, class T>
ArrayView<T> arrayView(StaticArrayView<size, T> view) constexpr

Make a view on StaticArrayView.

Convenience alternative to ArrayView::ArrayView(StaticArrayView<size, U>). The following two lines are equivalent:

Containers::StaticArrayView<15, std::uint32_t> data;

Containers::ArrayView<std::uint32_t> a{data};
auto b = Containers::arrayView(data);

template<class T> template<class T>
ArrayView<T> arrayView(ArrayView<T> view) constexpr

Make a view on a view.

Equivalent to the implicit ArrayView copy constructor — it shouldn't be an error to call arrayView() on itself.

template<class T> template<class T, class U = decltype(Implementation::ErasedArrayViewConverter<typename std::remove_reference<T && >::type>::from(std::declval<T && >()))>
U arrayView(T&& other) constexpr

Make a view on an external type / from an external representation.

template<class T> template<class U, class T>
ArrayView<U> arrayCast(ArrayView<T> view)

Reinterpret-cast an array view.

Size of the new array is calculated as view.size()*sizeof(T)/sizeof(U). Expects that both types are standard layout and the total byte size doesn't change. Example usage:

int data[15];
auto a = Containers::arrayView(data);           // a.size() == 15
auto b = Containers::arrayCast<char>(a);        // b.size() == 60

template<class T> template<class U>
ArrayView<U> arrayCast(ArrayView<const void> view) new in 2020.06

Reinterpret-cast a void array view.

Size of the new array is calculated as view.size()/sizeof(U). Expects that the target type is standard layout and the total byte size doesn't change.

template<class T> template<class U>
ArrayView<U> arrayCast(ArrayView<void> view) new in 2020.06

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<class T>
std::size_t arraySize(ArrayView<T> view) constexpr

Array view size.

Alias to ArrayView::size(). See also arraySize(T(&)[size_]) for querying size of a C array and arraySize(U(T::*)[size_]) for querying size of a C array member.