Array

An Array object owns a single block of memory, allocated on the heap, that contains an array of typed items. The items are destructed and freed when the Array is destroyed.

When an Array is const, the items it owns are immutable.

The array items must be relocatable; that is, it must always be possible to move items to a new address by calling memmove on the memory that contains them. Most Plywood containers, including Array, Owned, HashMap and BTree, are relocatable, so it's OK to create an Array of such types or structures of such types.

Header File

#include <ply-runtime/container/Array.h>

Also included from <ply-runtime/Base.h>.

Member Functions

Array() [code]

Constructs an empty Array.

Array(const Array& other) [code]

Copy constructor. This constructor is always defined because, in C++14, there is no way to conditionally disable it if T itself is not copy constructible. Instead, a runtime error occurs if this constructor is called when T is not copy constructible.

Array(Array&& other) [code]

Move constructor. other is reset to an empty Array.

template <typename Other, std::enable_if_t<std::is_constructible<T, Other>::value, int> = 0>
Array(ArrayView<Other> other) [code]

Construct an Array from an ArrayView of any type from which T can be constructed.

Array(std::initializer_list<T> init) [code]

Constructs an Array from a std::initializer_list<T>.

template <typename Other, std::enable_if_t<std::is_constructible<T, Other>::value, int> = 0>
Array(std::initializer_list<Other> init) [code]

Constructs an Array from a std::initializer_list of any type from which T can be constructed.

void operator=(const Array& other) [code]

Copy assignment operator. This operator is always defined because, in C++14, there is no way to conditionally disable it if T itself is not copy assignable. Instead, a runtime error occurs if this operator is called when T is not copy assignable.

template <typename Other, typename std::enable_if_t<std::is_constructible<T, Other>::value, int> = 0>
void operator=(ArrayView<Other> other) [code]

Copy assignment from an ArrayView of any type from which T can be constructed.

void operator=(Array&& other) [code]

Move assignment operator.

Array operator+(Array&& other) && [code]

Returns the concatenation of two Arrays. The array items are moved, not copied. Both Array operands must be rvalue references, and both are reset to empty Arrays.

T& operator[](u32 index) [code]
const T& operator[](u32 index) const [code]

Subscript operator with runtime bounds checking.

T& back(s32 offset = -1) [code]
const T& back(s32 offset = -1) const [code]

Reverse subscript operator with runtime bound checking. Expects a negative index. -1 returns the last item in the array; -2 returns the second-last item, etc.

explicit operator bool() const [code]

Explicit conversion to bool. Returns true if the array is not empty. Allows you to use an Array object inside an if condition.

if (array) {
    ...
}
bool isEmpty() const [code]

Returns true if the array is empty.

u32 numItems() const [code]

Returns the number of items in the array.

u32 sizeBytes() const [code]

Returns the total size, in bytes, of the items in the array. Equivalent to this->numItems() * sizeof(T).

ArrayView<T> view() [code]
ArrayView<const T> view() const [code]

Explicitly create an ArrayView into the array. The ArrayView items are const or non-const depending on whether the Array itself is const.

ArrayView<T> subView(u32 start) [code]
ArrayView<const T> subView(u32 start) const [code]
ArrayView<T> subView(u32 start, u32 numItems_) [code]
ArrayView<const T> subView(u32 start, u32 numItems_) const [code]

Returns a subview that starts at the offset given by start. The optional numItems argument determines the number of items in the subview. If numItems is not specified, the subview continues to the end of the view. The subview items are const or non-const depending on whether the Array itself is const.

void reserve(u32 numItems) [code]

Ensures the underlying memory block is large enough to accomodate the given number of items. If numItems is greater than the current capacity, the memory block is reallocated. No items are constructed or destructed by this function. This function can help avoid repeated memory reallocation as the array grows in size.

void resize(u32 numItems) [code]

Resizes the array to the given number of items. If numItems is greater that the current array size, new items are constructed. If numItems is smaller than the current array size, existing items are destructed.

void truncate() [code]

Shrinks the size of the underlying memory block to exactly fit the current number of array items.

T& append(T&& item) [code]
T& append(const T& item) [code]
template <typename Args>
T& append(Args&& args) [code]

Appends a single item to the array and returns a reference to it. The arguments are forwarded directly to the item's constructor. The returned reference remains valid until the array is resized or reallocated.

void extend(ArrayView<const T> view) [code]

Appends multiple items to the array. The new array items are copy constructed from view.

void moveExtend(ArrayView<T> view) [code]

Appends multiple items to the array. The new array items are move constructed from view.

void pop(u32 count = 1) [code]

Shrinks the array by count items. Equivalent to resize(numItems() - count).

T& insert(u32 pos, u32 count = 1) [code]

Inserts count new items into the array at offset pos. The new items are default constructed. All existing items after pos are shifted upward to accomodate the new items.

void erase(u32 pos, u32 count = 1) [code]

Destructs count array items starting at offset pos. Any remaining items starting at index (count + pos) are shifted downward to replace the erased items. The size of the array then shrinks by count.

void eraseQuick(u32 pos) [code]
void eraseQuick(u32 pos, u32 count) [code]

Destructs count array items starting at offset pos. The last count items in the array are moved to the space previously occupied by the erased items. The size of the array then shrinks by count.

When the array is large and number of erased items is small, eraseQuick() is typically faster than erase().

void clear() [code]

Destructs all items in the array and frees the internal memory block.

T* begin() const [code]
T* end() const [code]

Required functions to support range-for syntax. Allows you to iterate over all the items in the array as follows:

for (const T& item : array) {
    ...
}