BLArray< T > Class Template Reference

template<typename T>
class BLArray< T >

Array container (template) [C++ API].

Member Functions

Construction & Destruction
Overloaded Operators
Common Functionality
Create Functionality
Array Storage
Array Manipulation
Search
- Public Member Functions inherited from BLArrayCore

Static Functions

Additional Inherited Members

- Public Attributes inherited from BLArrayCore

Constructor & Destructor Documentation

template<typename T>
BLArray<T>:: BLArray()[1/4]

Creates a default constructed array.

Default constructed arrays share a built-in "none" instance.

template<typename T>
BLArray<T>:: BLArray(BLArray<T>&& other)[2/4]

Move constructor.

Note
The other array is reset by move construction, so its state after the move operation is the same as a default constructed array.

template<typename T>
BLArray<T>:: BLArray(const BLArray<T>& other)[3/4]

Copy constructor, performs weak copy of the data held by the other array.

template<typename T>
BLArray<T>:: BLArray(BLArrayImpl* impl)explicit[4/4]

Constructor that creates an array from the given impl.

Note
The reference count of the passed impl is not increased.

template<typename T>
BLArray<T>::~BLArray()

Destroys the array.

Member Function Documentation

template<typename T>
BLArray<T>::operator bool() constexplicit

Tests whether the array has items. Returns true if the array is not empty.

Note
This is essentially the opposite of empty().

template<typename T>
BLArray& BLArray<T>::operator=(BLArray<T>&& other)[1/2]

Move assignment.

Note
The other array is reset by move assignment, so its state after the move operation is the same as a default constructed array.

template<typename T>
BLArray& BLArray<T>::operator=(const BLArray<T>& other)[2/2]

Copy assignment, performs weak copy of the data held by the other array.

template<typename T>
bool BLArray<T>::operator==(const BLArray<T>& other)

Returns true if this and other arrays are equal.

template<typename T>
bool BLArray<T>::operator!=(const BLArray<T>& other)

Returns true if this and other arrays are not equal.

template<typename T>
const T& BLArray<T>::operator[](size_t index) const

Returns a read-only reference to the array item at the given index.

Note
This is the same as calling at(index).

template<typename T>
BLResult BLArray<T>::reset()

Resets the array into a default constructed state by clearing its content and releasing its memory.

template<typename T>
void BLArray<T>::swap(BLArray<T>& other)

Swaps the content of this array with the other array.

template<typename T>
BLResult BLArray<T>::assign(BLArray<T>&& other)[1/2]

Move assignment, the same as operator=, but returns a BLResult instead of this.

template<typename T>
BLResult BLArray<T>::assign(const BLArray<T>& other)[2/2]

Copy assignment, the same as operator=, but returns a BLResult instead of this.

template<typename T>
BLResult BLArray<T>::assignDeep(const BLArray<T>& other)

Copy assignment, but creates a deep copy of the other array instead of weak copy.

template<typename T>
template<typename... Args>
BLResult BLArray<T>::assign_v(Args&&... args)

Replaces the content of the array with variadic number of items passed in args....

template<typename T>
BLResult BLArray<T>::assignView(const BLArrayView<T>& view)[1/2]

Replaces the content of the array by items in the passed array view.

Note
The implementation can handle view pointing to the array's data as well, so it's possible to create a slice of the array if required.

template<typename T>
BLResult BLArray<T>::assignView(const T* items, size_t n)[2/2]

Replaces the content of the array items of length n.

Note
The implementation can handle items pointing to the array's data as well, so it's possible to create a slice of the array if required.

template<typename T>
bool BLArray<T>::isNone() const

Tests whether the array is a built-in null instance.

template<typename T>
bool BLArray<T>::empty() const

Tests whether the array is empty.

template<typename T>
bool BLArray<T>::equals(const BLArray<T>& other) const

Returnsn whether the content of this array and other matches.

template<typename T>
BLResult BLArray<T>::createFromData(T* data, size_t size, size_t capacity, uint32_t dataAccessFlags, BLDestroyImplFunc destroyFunc = nullptr, void* destroyData = nullptr)

Create array that uses an external data buffer.

Parameters
dataExternal data buffer to use (cannot be NULL).
sizeSize of the data buffer in items.
capacityCapacity of the buffer, cannot be zero or smaller than size.
dataAccessFlagsFlags that describe whether the data is read-only or read-write, see BLDataAccessFlags.
destroyFuncA function that would be called when the array is destroyed (can be null if you don't need it).
destroyDataData passed to destroyFunc.
Note
The old content of the array is destroyed and replaced with an Impl that uses the external data passed.

template<typename T>
size_t BLArray<T>::size() const

Returns the size of the array (number of items).

template<typename T>
size_t BLArray<T>::capacity() const

Returns the capacity of the array (number of items).

template<typename T>
const T* BLArray<T>::data() const

Returns a pointer to the array data.

template<typename T>
const T* BLArray<T>::begin() const

Returns a pointer to the array data (iterator compatibility).

template<typename T>
const T* BLArray<T>::end() const

Returns a pointer to the end of array data (iterator compatibility).

template<typename T>
const BLArrayView<T>& BLArray<T>::view() const

Returns the array data as BLArrayView<T>.

template<typename T>
const T& BLArray<T>::at(size_t index) const

Returns a read-only reference to the array item at the given index.

Note
The index must be valid, which means it has to be less than the array length. Accessing items out of range is undefined behavior that would be catched by assertions in debug builds.

template<typename T>
const T& BLArray<T>::first() const

Returns a read-only reference to the first item.

Note
The array must have at least one item othewise calling first() would point to the end of the array, which is not initialized, and such reference would be invalid. Debug builds would catch this condition with an assertion.

template<typename T>
const T& BLArray<T>::last() const

Returns a read-only reference to the last item.

Note
The array must have at least one item othewise calling last() would point to the end of the array, which is not initialized, and such reference would be invalid. Debug builds would catch this condition with an assertion.

template<typename T>
BLResult BLArray<T>::clear()

Clears the content of the array.

Note
If the array used dynamically allocated memory and the instance is mutable the memory won't be released, instead, it will be ready for reuse. Consider using reset() if you want to release the memory instead.

template<typename T>
BLResult BLArray<T>::shrink()

Shrinks the capacity of the array to fit its length.

Some array operations like append() may grow the array more than necessary to make it faster when such manipulation operations are called consecutively. When you are done with modifications and you know the lifetime of the array won't be short you can use shrink() to fit its memory requirements to the number of items it stores, which could optimize the application's memory requirements.

template<typename T>
BLResult BLArray<T>::reserve(size_t n)

Reserves the array capacity to hold at least n items.

template<typename T>
BLResult BLArray<T>::truncate(size_t n)

Truncates the length of the array to maximum n items.

If the length of the array is less than nn then truncation does nothing.

template<typename T>
BLResult BLArray<T>::resize(size_t n, const T& fill)

Resizes the array to n items.

If n is greater than the array length then all new items will be initialized by fill item.

template<typename T>
BLResult BLArray<T>::makeMutable(T** dataOut)

Makes the array mutable by possibly creating a deep copy of the data if it's either read-only or shared with another array. Stores the pointer to the beginning of mutable data in dataOut.

if (a.append(0, 1, 2, 3, 4, 5, 6, 7) != BL_SUCCESS) {
// Handle error condition.
}
uint8_t* data;
// Handle error condition.
}
// `data` is a mutable pointer to array content of 8 items.
data[0] = 100;
// Calling array member functions (or C-API) could invalidate `data`.
a.append(9); // You shouldn't use `data` afterwards.

template<typename T>
BLResult BLArray<T>::modifyOp(uint32_t op, size_t n, T** dataOut)

Modify operation is similar to makeMutable, however, the op argument specifies the desired array operation, see BLModifyOp. The pointer returned in dataOut points to the first item to be either assigned or appended and it points to an unititialized memory.

Please note that assignments mean to wipe out the whole array content and to set the length of the array to n. The caller is responsible for initializing the data returned in dataOut.

template<typename T>
BLResult BLArray<T>::insertOp(size_t index, size_t n, T** dataOut)

Insert operation, the semantics is similar to modifyOp(), however, items are inserted at the given index instead of assigned or appended.

The caller is responsible for initializing the data returned in dataOut.

template<typename T>
template<typename... Args>
BLResult BLArray<T>::modify_v(uint32_t op, Args&&... args)

Similar to modifyOp(), but the items to assign/append to the array are given after the op argument.

Note
This is a varidic template that makes such modification easier if you have a constant number of items to assign or append.

template<typename T>
template<typename... Args>
BLResult BLArray<T>::append(Args&&... args)

Appends a variadic number of items items passed in args... to the array.

template<typename T>
BLResult BLArray<T>::appendView(const BLArrayView<T>& view)[1/2]

Appends items to the array of the given array view.

Note
The implementation can handle view pointing to the array's data as well, so it's possible to duplicate the given items by appending them.

template<typename T>
BLResult BLArray<T>::appendView(const T* items, size_t n)[2/2]

Appends items to the array of length n.

Note
The implementation can handle view pointing to the array's data as well, so it's possible to duplicate the given items by appending them.

template<typename T>
template<typename... Args>
BLResult BLArray<T>::prepend(Args&&... args)

Prepends a variadic number of items items passed in args... to the array.

template<typename T>
BLResult BLArray<T>::prependView(const BLArrayView<T>& view)[1/2]

Prepends items to the array of the given array view.

Note
The implementation can handle view pointing to the array's data as well, so it's possible to duplicate the given items by prepending them.

template<typename T>
BLResult BLArray<T>::prependView(const T* items, size_t n)[2/2]

Prepends items to the array of length n.

Note
The implementation can handle view pointing to the array's data as well, so it's possible to duplicate the given items by prepending them.

template<typename T>
template<typename... Args>
BLResult BLArray<T>::insert(size_t index, Args&&... args)

Inserts a variadic number of items items passed in args... at the given index.

template<typename T>
BLResult BLArray<T>::insertView(size_t index, const BLArrayView<T>& view)[1/2]

Inserts items to the array of the given array view at the given index.

Note
The implementation can handle view pointing to the array's data as well, so it's possible to duplicate the given items by inserting them.

template<typename T>
BLResult BLArray<T>::insertView(size_t index, const T* items, size_t n)[2/2]

Prepends items to the array of length n at the given index.

Note
The implementation can handle view pointing to the array's data as well, so it's possible to duplicate the given items by inserting them.

template<typename T>
BLResult BLArray<T>::replace(size_t index, const T& item)

Replaces an item at the given index by item.

template<typename T>
BLResult BLArray<T>::replaceView(const BLRange& range, BLArrayView<T>& view)[1/2]

Replaces the given range of items by the given array view.

template<typename T>
BLResult BLArray<T>::replaceView(const BLRange& range, const T* items, size_t n)[2/2]

Replaces the given range of items by items of length n.

template<typename T>
BLResult BLArray<T>::remove(size_t index)[1/2]

Removes an item at the given index.

template<typename T>
BLResult BLArray<T>::remove(const BLRange& range)[2/2]

Removes a range of items.

template<typename T>
size_t BLArray<T>::indexOf(const T& item) const[1/2]

Returns the first index at which a given item can be found in the array, or SIZE_MAX if not present.

template<typename T>
size_t BLArray<T>::indexOf(const T& item, size_t fromIndex) const[2/2]

Returns the index at which a given item can be found in the array starting from fromIndex, or SIZE_MAX if not present.

template<typename T>
size_t BLArray<T>::lastIndexOf(const T& item) const[1/2]

Returns the last index at which a given item can be found in the array, or SIZE_MAX if not present.

template<typename T>
size_t BLArray<T>::lastIndexOf(const T& item, size_t fromIndex) const[2/2]

Returns the index at which a given item can be found in the array starting from fromIndex and ending at 0, or SIZE_MAX if not present.