Corrade::Containers::BitArray class new in Git master
#include <Corrade/Containers/BitArray.h>

Bit array.

Owning container for an array of bits. Eight times more memory-efficient than Array<bool>; a lighter alternative to std::vector<bool>. A non-owning version of this container is a BitArrayView and a MutableBitArrayView, implemented using a generic BasicBitArrayView.

As with Array itself, the container is non-copyable with a size specified upfront. At the moment, there's no growing functionality.

Usage

The following snippet shows using a bit array for marking which mesh vertices are used by an index buffer:

Containers::BitArray used{ValueInit, vertexCount};

for(unsigned index: indexBuffer) used.set(index);

The BitArray class provides access and slicing APIs similar to BitArrayView, see its usage docs for details. All BitArray slicing APIs return a (mutable) BitArrayView, additionally BitArray instances are also implicitly convertible to it. The only difference is due to the owning aspect — mutable access to the data is provided only via non const overloads.

Bit array initialization

The following explicit initialization constructors are provided, similarly to the Array class:

Unlike an Array, there's no DefaultInitT constructor, as the same behavior is already provided by BitArray(NoInitT, std::size_t).

/* 200 zero bits */
Containers::BitArray a{ValueInit, 200};

/* 200 one bits */
Containers::BitArray b{DirectInit, 200, true};

/* 100 uninitialized bits */
Containers::BitArray c{NoInit, 100};

Wrapping externally allocated bit arrays

Similarly to Array, by default the class makes all allocations using operator new[] and deallocates using operator delete[]. It's however also possible to wrap an externally allocated array using BitArray(void*, std::size_t, std::size_t, Deleter) together with specifying which function to use for deallocation. In addition to a size in bits, there's also an offset argument specifying the starting bit in the fist byte, consistently with a BitArrayView. Often it will be 0 however.

For example, properly deallocating a bit array allocated using std::malloc():

{
    void* data = std::malloc(250);

    // Will call std::free() on destruction
    Containers::BitArray array{data, 0, 250*8,
        [](char* data, std::size_t) { std::free(data); }};
}

Public types

using Deleter = void(*)(char*, std::size_t)
Deleter type.

Constructors, destructors, conversion operators

BitArray(std::nullptr_t = nullptr) noexcept
Default constructor.
BitArray(Corrade::ValueInitT, std::size_t size) explicit
Construct a zero-initialized array.
BitArray(Corrade::NoInitT, std::size_t size) explicit
Construct an array without initializing its contents.
BitArray(Corrade::DirectInitT, std::size_t size, bool value) explicit
Construct an array initialized to a particular bit value.
BitArray(void* data, std::size_t offset, std::size_t size, Deleter deleter) explicit noexcept
Take ownership of an external bit array.
BitArray(const BitArray&) deleted
Copying is not allowed.
BitArray(BitArray&& other) noexcept
Move constructor.
~BitArray()
Destructor.
operator MutableBitArrayView()
Conversion to a view.
operator BitArrayView() const

Public functions

auto operator=(const BitArray&) -> BitArray& deleted
Copying is not allowed.
auto operator=(BitArray&& other) -> BitArray& noexcept
Move assignment.
auto data() -> char*
Array data.
auto data() const -> const char*
auto deleter() const -> Deleter
Array deleter.
auto offset() const -> std::size_t
Offset in the first byte.
auto size() const -> std::size_t
Size in bits.
auto isEmpty() const -> bool
Whether the array is empty.
auto operator[](std::size_t i) const -> bool
Bit at given position.
void set(std::size_t i)
Set a bit at given position.
void setAll()
Set all bits.
void reset(std::size_t i)
Reset a bit at given position.
void resetAll()
Reset all bits.
void set(std::size_t i, bool value)
Set or reset a bit at given position.
void setAll(bool value)
Set or reset all bits.
auto slice(std::size_t begin, std::size_t end) -> MutableBitArrayView
View on a slice.
auto slice(std::size_t begin, std::size_t end) const -> BitArrayView
auto sliceSize(std::size_t begin, std::size_t size) -> MutableBitArrayView
View on a slice of given size.
auto sliceSize(std::size_t begin, std::size_t size) const -> BitArrayView
auto prefix(std::size_t size) -> MutableBitArrayView
View on the first size bits.
auto prefix(std::size_t size) const -> BitArrayView
auto suffix(std::size_t size) -> MutableBitArrayView
View on the last size bits.
auto suffix(std::size_t size) const -> BitArrayView
auto exceptPrefix(std::size_t size) -> MutableBitArrayView
View except the first size bits.
auto exceptPrefix(std::size_t size) const -> BitArrayView
auto exceptSuffix(std::size_t size) -> MutableBitArrayView
View except the last size bits.
auto exceptSuffix(std::size_t size) const -> BitArrayView
auto count() const -> std::size_t
Count of set bits.
auto release() -> char*
Release data storage.

Function documentation

Corrade::Containers::BitArray::BitArray(std::nullptr_t = nullptr) noexcept

Default constructor.

Creates a zero-sized array. Move a BitArray with a nonzero size onto the instance to make it useful.

Corrade::Containers::BitArray::BitArray(Corrade::ValueInitT, std::size_t size) explicit

Construct a zero-initialized array.

Parameters
size Size in bits

If the size is zero, no allocation is done.

Corrade::Containers::BitArray::BitArray(Corrade::NoInitT, std::size_t size) explicit

Construct an array without initializing its contents.

Parameters
size Size in bits

The contents are not initialized. If the size is zero, no allocation is done. Useful if you will be overwriting all elements later anyway.

Corrade::Containers::BitArray::BitArray(Corrade::DirectInitT, std::size_t size, bool value) explicit

Construct an array initialized to a particular bit value.

Parameters
size Size in bits
value Bit value

If the size is zero, no allocation is done.

Corrade::Containers::BitArray::BitArray(void* data, std::size_t offset, std::size_t size, Deleter deleter) explicit noexcept

Take ownership of an external bit array.

Parameters
data Data
offset Initial bit offset in data. Expected to be less than 8.
size Size in bits, excluding offset
deleter Deleter. Use nullptr for the standard delete[].

The deleter will be unconditionally called on destruction with data and (offset + size + 7)/8 (i.e., size including the initial offset in bytes) as an argument. In particular, it will be also called if data is nullptr or size is 0.

In case of a moved-out instance, the deleter gets reset to a default-constructed value alongside the array pointer and size. It effectively means delete[] nullptr gets called when destructing a moved-out instance (which is a no-op).

Corrade::Containers::BitArray::BitArray(BitArray&& other) noexcept

Move constructor.

Resets data pointer, offset, size and deleter of other to be equivalent to a default-constructed instance.

Corrade::Containers::BitArray::~BitArray()

Destructor.

Calls deleter() on the owned data().

Corrade::Containers::BitArray::operator BitArrayView() const

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

BitArray& Corrade::Containers::BitArray::operator=(BitArray&& other) noexcept

Move assignment.

Swaps data pointer, offset, size and deleter of the two instances.

char* Corrade::Containers::BitArray::data()

Array data.

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

const char* Corrade::Containers::BitArray::data() const

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

Deleter Corrade::Containers::BitArray::deleter() const

Array deleter.

If set to nullptr, the contents are deleted using standard operator delete[].

std::size_t Corrade::Containers::BitArray::offset() const

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 BitArray(void*, std::size_t, std::size_t, Deleter) constructor.

std::size_t Corrade::Containers::BitArray::size() const

Size in bits.

bool Corrade::Containers::BitArray::isEmpty() const

Whether the array is empty.

bool Corrade::Containers::BitArray::operator[](std::size_t i) const

Bit at given position.

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

void Corrade::Containers::BitArray::set(std::size_t i)

Set a bit at given position.

Expects that i is less than size().

void Corrade::Containers::BitArray::setAll()

Set all bits.

You can set just a range of bits by making a slice() first.

void Corrade::Containers::BitArray::reset(std::size_t i)

Reset a bit at given position.

Expects that i is less than size().

void Corrade::Containers::BitArray::resetAll()

Reset all bits.

You can set just a range of bits by making a slice() first.

void Corrade::Containers::BitArray::set(std::size_t i, bool value)

Set or reset a bit at given position.

Expects that i is less than size(). For a value known at compile time, explicitly calling either set(std::size_t) or reset(std::size_t) is more efficient.

void Corrade::Containers::BitArray::setAll(bool value)

Set or reset all bits.

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

MutableBitArrayView Corrade::Containers::BitArray::slice(std::size_t begin, std::size_t end)

View on a slice.

Equivalent to BasicBitArrayView::slice().

BitArrayView Corrade::Containers::BitArray::slice(std::size_t begin, std::size_t end) const

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

MutableBitArrayView Corrade::Containers::BitArray::sliceSize(std::size_t begin, std::size_t size)

View on a slice of given size.

Equivalent to BasicBitArrayView::sliceSize().

BitArrayView Corrade::Containers::BitArray::sliceSize(std::size_t begin, std::size_t size) const

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

MutableBitArrayView Corrade::Containers::BitArray::prefix(std::size_t size)

View on the first size bits.

Equivalent to BasicBitArrayView::prefix().

BitArrayView Corrade::Containers::BitArray::prefix(std::size_t size) const

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

MutableBitArrayView Corrade::Containers::BitArray::suffix(std::size_t size)

View on the last size bits.

Equivalent to BasicBitArrayView::suffix().

BitArrayView Corrade::Containers::BitArray::suffix(std::size_t size) const

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

MutableBitArrayView Corrade::Containers::BitArray::exceptPrefix(std::size_t size)

View except the first size bits.

Equivalent to BasicBitArrayView::exceptPrefix().

BitArrayView Corrade::Containers::BitArray::exceptPrefix(std::size_t size) const

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

MutableBitArrayView Corrade::Containers::BitArray::exceptSuffix(std::size_t size)

View except the last size bits.

Equivalent to BasicBitArrayView::exceptSuffix().

BitArrayView Corrade::Containers::BitArray::exceptSuffix(std::size_t size) const

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

std::size_t Corrade::Containers::BitArray::count() const

Count of set bits.

Equivalent to BasicBitArrayView::count().

char* Corrade::Containers::BitArray::release()

Release data storage.

Returns the data pointer and resets data pointer, offset, size and deleter to be equivalent to a default-constructed instance. Deleting the returned array is user responsibility — note the array might have a custom deleter() and so delete[] might not be always appropriate.

Utility::Debug& operator<<(Utility::Debug& debug, const BitArray& value) new in Git master

Debug output operator.

Equivalent to operator<<(Utility::Debug&, BitArrayView), see its documentation for more information.