#include <Corrade/Containers/BitArrayView.h>
template<class T>
Corrade::Containers::BasicBitArrayView class new in Git master

Base for bit array views.

A view over an arbitrary range of bits, including sub-byte offsets — a bit-sized variant of an ArrayView. For sparse and multi-dimensional views see StridedBitArrayView. An owning version of this container is a BitArray.

Usage

The class is meant to be used through either the BitArrayView or MutableBitArrayView typedefs. The class is implicitly convertible from BitArray instances, it's also possible to implicitly create a const view on a mutable array. Besides that, a view can be created manually by specifying a pointer, initial bit offset and bit count:

/* Create a view on a BitArray */
Containers::BitArray array = …;
Containers::BitArrayView a = array;

/* Mutable view on bits 7 to 34 of a 64-bit number */
std::uint64_t data = …;
Containers::MutableBitArrayView b{&data, 7, 27};

Data access

Only a small subset of the usual ArrayView access interface is provided — size(), isEmpty() and querying particular bits using operator[](). Unlike e.g. std::vector<bool>, there's no array subscript operator for setting bits as it would have to create a temporary setter object each time a bit is set, causing unnecessary overhead. Instead, you're supposed to use set(std::size_t) const, reset(std::size_t) const or set(std::size_t, bool) const. For a similar reason, there's no iterator or range-for access.

There's also data() for raw data access, but because the view can point to an arbitrary bit in the first byte, you're expected to take also offset() into account when accessing the data.

View slicing

Slicing functions match the ArrayView interface — slice(), sliceSize(), prefix(), suffix(), exceptPrefix() and exceptSuffix(), all operating with bit offsets. No pointer-taking overloads are provided as byte-level slicing would be too coarse.

Public types

using ErasedType = std::conditional<std::is_const<T>::value, const void, void>::type
Erased type.

Constructors, destructors, conversion operators

BasicBitArrayView(std::nullptr_t = nullptr) constexpr noexcept
Default constructor.
template<std::size_t size, class U>
BasicBitArrayView(U(&data)[size]) constexpr noexcept
Construct a view on a fixed-size array.
BasicBitArrayView(ErasedType* data, std::size_t offset, std::size_t size) constexpr noexcept
Construct a view on an array with explicit offset and size.
template<std::size_t dataSize, class U>
BasicBitArrayView(U(&data)[dataSize], std::size_t offset, std::size_t size) constexpr noexcept
Construct a view on a fixed-size array with explicit offset and size.
template<class U, class = typename std::enable_if<std::is_same<const U, T>::value>::type>
BasicBitArrayView(BasicBitArrayView<U> mutable_) constexpr noexcept
Construct a BitArrayView from a MutableBitArrayView.

Public functions

auto data() const -> ErasedType* constexpr
Array data.
auto offset() const -> std::size_t constexpr
Bit offset.
auto size() const -> std::size_t constexpr
Size in bits.
auto isEmpty() const -> bool constexpr
Whether the view is empty.
auto operator[](std::size_t i) const -> bool
Bit at given position.
void set(std::size_t i) const
Set a bit at given position.
void setAll() const
Set all bits.
void reset(std::size_t i) const
Reset a bit at given position.
void resetAll() const
Reset all bits.
void set(std::size_t i, bool value) const
Set or reset a bit at given position.
void setAll(bool value) const
Set or reset all bits.
auto slice(std::size_t begin, std::size_t end) const -> BasicBitArrayView<T>
View slice.
auto sliceSize(std::size_t begin, std::size_t size) const -> BasicBitArrayView<T>
View slice of given size.
auto prefix(std::size_t size) const -> BasicBitArrayView<T>
View on the first size bits.
auto suffix(std::size_t size) const -> BasicBitArrayView<T>
View on the last size bits.
auto exceptPrefix(std::size_t size) const -> BasicBitArrayView<T>
View except the first size bits.
auto exceptSuffix(std::size_t size) const -> BasicBitArrayView<T>
View except the last size bits.
auto count() const -> std::size_t
Count of set bits.

Typedef documentation

template<class T>
typedef std::conditional<std::is_const<T>::value, const void, void>::type Corrade::Containers::BasicBitArrayView<T>::ErasedType

Erased type.

Either a const void for a BitArrayView or a void for a MutableBitArrayView.

Function documentation

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

Default constructor.

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

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

Construct a view on a fixed-size array.

Parameters
data Fixed-size array

In case of a MutableBitArrayView enabled only if data is also mutable. Offset is implicitly set to 0, size to sizeof(U)*8.

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

Construct a view on an array with explicit offset and size.

Parameters
data Data pointer
offset Bit offset in data
size Bit count

The offset is expected to be less than 8, size has to fit into 29 bits on 32-bit platforms and 61 bits on 64-bit platforms.

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

Construct a view on a fixed-size array with explicit offset and size.

Parameters
data Fixed-size array
offset Bit offset in data
size Bit count

Compared to BasicBitArrayView(ErasedType*, std::size_t, std::size_t) expects that offset and size fits into data.

template<class T>
ErasedType* Corrade::Containers::BasicBitArrayView<T>::data() const constexpr

Array data.

Use offset() to get location of the first bit pointed to by the array.

template<class T>
std::size_t Corrade::Containers::BasicBitArrayView<T>::offset() const constexpr

Bit offset.

Added to the pointer returned by data() to get location of the first bit. The returned value is always less than 8 and is non-zero if the view was originally constructed with a non-zero offset or if it's a result of slicing that wasn't on a byte boundary.

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

Size in bits.

template<class T>
bool Corrade::Containers::BasicBitArrayView<T>::isEmpty() const constexpr

Whether the view is empty.

template<class T>
bool Corrade::Containers::BasicBitArrayView<T>::operator[](std::size_t i) const

Bit at given position.

Expects that i is less than size(). Setting bit values is only possible on mutable views with set(std::size_t) const, reset(std::size_t) const or set(std::size_t, bool) const.

template<class T>
void Corrade::Containers::BasicBitArrayView<T>::set(std::size_t i) const

Set a bit at given position.

Expects that i is less than size(). Enabled only on a MutableBitArrayView.

template<class T>
void Corrade::Containers::BasicBitArrayView<T>::setAll() const

Set all bits.

Enabled only on a MutableBitArrayView. You can set just a range of bits by making a slice() first.

template<class T>
void Corrade::Containers::BasicBitArrayView<T>::reset(std::size_t i) const

Reset a bit at given position.

Expects that i is less than size(). Enabled only on a MutableBitArrayView.

template<class T>
void Corrade::Containers::BasicBitArrayView<T>::resetAll() const

Reset all bits.

Enabled only on a MutableBitArrayView. You can set just a range of bits by making a slice() first.

template<class T>
void Corrade::Containers::BasicBitArrayView<T>::set(std::size_t i, bool value) const

Set or reset a bit at given position.

Expects that i is less than size(). Enabled only on a MutableBitArrayView. For a value known at compile time, explicitly calling either set(std::size_t) const or reset(std::size_t) const is a simpler operation.

template<class T>
void Corrade::Containers::BasicBitArrayView<T>::setAll(bool value) const

Set or reset all bits.

Enabled only on a MutableBitArrayView. Calls either setAll() const or resetAll() const based on value. You can set or reset just a range of bits by making a slice() first.

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

View slice.

Both arguments are expected to be less than size().

template<class T>
BasicBitArrayView<T> Corrade::Containers::BasicBitArrayView<T>::sliceSize(std::size_t begin, std::size_t size) const

View slice of given size.

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

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

View on the first size bits.

Equivalent to data.slice(0, size).

template<class T>
BasicBitArrayView<T> Corrade::Containers::BasicBitArrayView<T>::suffix(std::size_t size) const

View on the last size bits.

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

template<class T>
BasicBitArrayView<T> Corrade::Containers::BasicBitArrayView<T>::exceptPrefix(std::size_t size) const

View except the first size bits.

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

template<class T>
BasicBitArrayView<T> Corrade::Containers::BasicBitArrayView<T>::exceptSuffix(std::size_t size) const

View except the last size bits.

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

template<class T>
std::size_t Corrade::Containers::BasicBitArrayView<T>::count() const

Count of set bits.

Count of unset bits is size() minus the result of this function.

template<class T>
Utility::Debug& operator<<(Utility::Debug& debug, BitArrayView value) new in Git master

Debug output operator.

Prints the value as {a, b, …}, with each element being the next 8 bits from the array. To have a monotonic order, the first character in each element is the first bit in the 8-bit group — i.e., the order is reversed compared to binary literals.

For example, the following 64-bit number, shifted by 5 bits (and correspondingly the view created with a 5-bit offset), will print like this on a Little-Endian machine:

const std::uint64_t data[]{0b00'0101'0101'0011'0011'0000'1111 << 5};
Utility::Debug{} << Containers::BitArrayView{data, 5, 26};

{11110000, 11001100, 10101010, 00}

template<class T>
Utility::Debug& operator<<(Utility::Debug& debug, MutableBitArrayView value) new in Git master

Debug output operator.