BLArray< T > Class Template Reference

template<typename T>
class BLArray< T >

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

Member Functions

Construction & Destruction
Overloaded Operators
Common Functionality
Accessors
Data Manipulation
Equality & Comparison
Search

Additional Inherited Members

- Public Attributes inherited from BLObjectCore

Constructor & Destructor Documentation

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

Creates a default constructed array.

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

Move constructor.

Note
The other array is always reset by a move construction, so it becomes an empty array.

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

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

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 the 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>
bool BLArray<T>::empty() const

Tests whether the array is empty.

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>
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 uses a dynamically allocated memory and the instance is mutable the memory won't be released, it will be reused instead. Consider using reset() if you want to release the memory in such case 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(BLModifyOp 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(BLModifyOp 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>
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>::assignData(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>::assignData(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>
BLResult BLArray<T>::assignExternalData(T* data, size_t size, size_t capacity, BLDataAccessFlags accessFlags, BLDestroyExternalDataFunc destroyFunc = nullptr, void* userData = nullptr)

Assign an external buffer to the array, which would replace the existing content.

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.
accessFlagsFlags 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).
userDataUser data passed to destroyFunc.

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.

Note
The data in args cannot point to the same data that the array holds as the function that prepares the append operation has no way to know about the source (it only makes space for new data). It's an undefined behavior in such case.

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

Appends items to the array of the given array view.

Note
The implementation guarantees that a view pointing to the array data itself would work.

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

Appends items to the array of length n.

Note
The implementation guarantees that a items pointing to the array data itself would work.

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.

Note
The data in args cannot point to the same data that the array holds as the function that prepares the prepend operation has no way to know about the source (it only makes space for new data). It's an undefined behavior in such case.

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

Prepends items to the array of the given array view.

Note
The implementation guarantees that a view pointing to the array data itself would work.

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

Prepends items to the array of length n.

Note
The implementation guarantees that a items pointing to the array data itself would work.

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.

Note
The data in args cannot point to the same data that the array holds as the function that prepares the insert operation has no way to know about the source (it only makes space for new data). It's an undefined behavior in such case.

template<typename T>
BLResult BLArray<T>::insertData(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 guarantees that a view pointing to the array data itself would work.

template<typename T>
BLResult BLArray<T>::insertData(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 guarantees that a items pointing to the array data itself would work.

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>::replaceData(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>::replaceData(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>
bool BLArray<T>::equals(const BLArray<T>& other) const

Returnsn whether the content of this array and other matches.

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 found.

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.