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.

Array is implicitly convertible to ArrayView and can be passed directly to any function that expects an ArrayView.

Header File

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

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

Constructors

Array::Array() [code]

Constructs an empty Array.

Array<u32> arr;

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<u32> arr = other;

Array::Array(Array&& other) [code]

Move constructor. other is reset to an empty Array.

Array<u32> arr = std::move(other);

Array::Array(InitList<T> init) [code]

Constructs an Array from a braced initializer list.

Array<u32> arr = {4, 5, 6};

template <typename Other, typename U = details::ArrayViewType<Other>> Array::Array(Other&& other) [code]

Construct an Array from any array-like object (ie. Array, ArrayView, FixedArray, etc.) of any type from which T can be constructed. The other object must have a member function named view() that returns an ArrayView.

FixedArray<u16, 3> fixed = {4, 5, 6};
Array<u32> arr = fixed;

Move semantics are used when the source object owns its items and can be moved from. In the following example, the right-hand side is a temporary Array<String> that can be moved from, so each HybridString in the result is constructed by moving from each String in the temporary object.

Array<HybridString> arr = Array<String>{"hello", "there"};

Array::~Array() [code]

Destructor. Destructs all items and frees the memory associated with the Array.

Assignment

void Array::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.

arr = other;

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

Move assignment operator. other is reset to an empty Array.

arr = std::move(other);

void Array::operator=(InitList<T> init) [code]

Assignment from a braced initializer list.

Array<u32> arr;
arr = {4, 5, 6};

template <typename Other, typename U = details::ArrayViewType<Other>> void Array::operator=(Other&& other) [code]

Array<u32> arr;
FixedArray<u16, 3> fixed = {4, 5, 6};
arr = fixed;

Array<HybridString> arr;
arr = Array<String>{"hello", "there"}; // uses move semantics

Element Access

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

Subscript operator with runtime bounds checking.

Array<u32> arr = {4, 5, 6};
arr[1];  // 5

T& Array::back(s32 offset = -1) [code] const T& Array::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.

Array<u32> arr = {4, 5, 6};
arr.back();  // 6

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

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

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

Capacity

explicit Array::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 (arr) {
    ...
}

bool Array::isEmpty() const [code]

Returns true if the array is empty.

u32 Array::numItems() const [code]

Returns the number of items in the array.

u32 Array::sizeBytes() const [code]

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

Modification

void Array::clear() [code]

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

void Array::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 Array::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 Array::truncate() [code]

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

T& Array::append(T&& item) [code] T& Array::append(const T& item) [code] template <typename Args> T& Array::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 Array::extend(InitList<T> init) [code] template <typename Other, typename U = details::ArrayViewType<Other>> void Array::extend(Other&& other) [code]

Appends multiple items to the array. The argument can be a braced initializer list or an array-like object (ie. Array, ArrayView, FixedArray, etc.) of any type from which T can be constructed.

Array<String> arr;
arr.extend({"hello", "there"});
arr.extend(ArrayView<const StringView>{"my", "friend"});

Move semantics are used when the source object owns its items and can be moved from. In the following example, the argument to extend is a temporary Array<String> that can be moved from, so each HybridString in the result is appended by moving from each String in the temporary object.

Array<HybridString> arr;
arr.extend(Array<String>{"hello", "there"}); // uses move semantics

void Array::moveExtend(ArrayView<T> other) [code]

Appends multiple items to the Array from an ArrayView. The new array items are move constructed from the items in other.

void Array::pop(u32 count = 1) [code]

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

T& Array::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 Array::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 Array::eraseQuick(u32 pos) [code] void Array::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().

template <typename Arr0, typename Arr1, typename T0 = details::ArrayViewType<Arr0>, typename T1 = details::ArrayViewType<Arr1>> auto operator+(Arr0&& a, Arr1&& b) [code]

Returns the concatenation of two array-like objects a and b. The arguments can be instances of Array, ArrayView, FixedArray or any class that has a member function named view() returning an ArrayView. The returned Array has the same item type as a, and b's items must be convertible to this type.

Move semantics are used when either operand owns its items and can be moved from.

Convert to View

ArrayView<T> Array::view() [code] ArrayView<const T> Array::view() const [code]: Explicitly create an ArrayView into the array.
Array::operator ArrayView<T>() [code] Array::operator ArrayView<const T>() const [code]: Implicit conversion to ArrayView. Makes is possible to pass Array to any function that expects an ArrayView.
StringView Array::stringView() const [code] MutableStringView Array::mutableStringView() const [code]: Explicitly creeate a StringView or MutableStringView into the array.
ArrayView<T> Array::subView(u32 start) [code] ArrayView<const T> Array::subView(u32 start) const [code] ArrayView<T> Array::subView(u32 start, u32 numItems_) [code] ArrayView<const T> Array::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.