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. An owning version of this containers is a BitArray.

Usage

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.

Constructors, destructors, conversion operators

BasicBitArrayView(std::nullptr_t = nullptr) constexpr noexcept
Default constructor.
BasicBitArrayView(typename std::conditional<std::is_const<T>::value, const void, void>::type* data, std::size_t offset, std::size_t size) noexcept
Constructor.
BasicBitArrayView(T* data, std::size_t offset, std::size_t size) constexpr noexcept
Constexpr constructor.
BasicBitArrayView(std::nullptr_t, std::size_t offset, std::size_t size) constexpr noexcept
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 -> T* constexpr
Array data.
auto offset() const -> std::size_t constexpr
Offset in the first byte.
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 constexpr
Bit at given position.
void set(std::size_t i) const
Set a bit at given position.
void reset(std::size_t i) const
Reset a bit at given position.
void set(std::size_t i, bool value) const
Set or reset a bit at given position.
auto slice(std::size_t begin, std::size_t end) const -> BasicBitArrayView<T> constexpr
View slice.
auto sliceSize(std::size_t begin, std::size_t size) const -> BasicBitArrayView<T> constexpr
View slice of given size.
auto prefix(std::size_t size) const -> BasicBitArrayView<T> constexpr
View on the first size bits.
auto suffix(std::size_t size) const -> BasicBitArrayView<T> constexpr
View on the last size bits.
auto exceptPrefix(std::size_t size) const -> BasicBitArrayView<T> constexpr
View except the first size bits.
auto exceptSuffix(std::size_t size) const -> BasicBitArrayView<T> constexpr
View except the last size bits.

Function documentation

template<class T>
Corrade::Containers::BasicBitArrayView<T>::BasicBitArrayView(typename std::conditional<std::is_const<T>::value, const void, void>::type* data, std::size_t offset, std::size_t size) noexcept

Constructor.

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>
Corrade::Containers::BasicBitArrayView<T>::BasicBitArrayView(T* data, std::size_t offset, std::size_t size) constexpr noexcept

Constexpr constructor.

A variant of BasicBitArrayView(typename std::conditional<std::is_const<T>::value, const void, void>::type*, std::size_t, std::size_t) usable in a constexpr context — in order to satisfy the restrictions, the data parameter has to be (const) char*.

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

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::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

Offset in the first byte.

The returned value is always less than 8, and is non-zero only if the array was created with a non-zero offset passed to the BasicBitArrayView(typename std::conditional<std::is_const<T>::value, const void, void>::type*, std::size_t, std::size_t) constructor.

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 constexpr

Bit at given position.

Expects that i is less than size(). Use set(std::size_t) const, reset(std::size_t) const or set(std::size_t, bool) const to set a bit value.

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>::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>::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>
BasicBitArrayView<T> Corrade::Containers::BasicBitArrayView<T>::slice(std::size_t begin, std::size_t end) const constexpr

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 constexpr

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 constexpr

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 constexpr

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 constexpr

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 constexpr

View except the last size bits.

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

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

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 corresponds to a 64-bit value of 0b111'11001100'11110000'01010101 << 7 stored as Little-Endian, and printing a view on it will show it in reverse order:

const std::uint8_t data[]{0b10000000, 0b00101010, 0b01111000, 0b11100110, 0b11};
Utility::Debug{} << Containers::BitArrayView{data, 7, 27};

{10101010, 00001111, 00110011, 111}