ludus::foundation::core::Array¶

Class

Owning, contiguous, growable sequence with explicit fallible mutation APIs.

Growth invalidates all element borrows; ordered insertion/removal invalidates borrows at and after the affected position. Failed Try operations preserve the container. Infallible allocating operations terminate on exhaustion or capacity overflow. A default or moved-from array owns no storage.

Note

One owner; synchronize access externally. See docs/architecture/containers.md.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

#include <ludus/foundation/containers/array.hpp>

template <typename ElementType>
class ludus::foundation::core::Array

Types¶

ValueType¶

using ludus::foundation::core::Array< ElementType >::ValueType = ElementType

Stored element type.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

SizeType¶

using ludus::foundation::core::Array< ElementType >::SizeType = usize

Size and index type.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Iterator¶

using ludus::foundation::core::Array< ElementType >::Iterator = ElementType*

Contiguous mutable iterator; invalidated with element borrows.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

ConstIterator¶

using ludus::foundation::core::Array< ElementType >::ConstIterator = const ElementType*

Contiguous read-only iterator; invalidated with element borrows.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Methods¶

Array¶

constexpr ludus::foundation::core::Array< ElementType >::Array() noexcept=default

Empty array that owns no storage. Never allocates.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Array¶

ludus::foundation::core::Array< ElementType >::Array(std::initializer_list< ElementType > items)
requires std::is_copy_constructible_v<ElementType>

Braces supply elements: Array<int32>{3} holds one value, whereas (3) value-initializes three elements.

The list's const elements are copied.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Array¶

explicit ludus::foundation::core::Array< ElementType >::Array(usize count)

Construct count value-initialized elements in one exact allocation.

Allocation failure or capacity overflow is fatal. Use TryResize on an empty array for a fallible equivalent.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Array¶

ludus::foundation::core::Array< ElementType >::Array(usize count, const ElementType &value)

Construct count copies of value in one exact allocation.

Allocation failure or capacity overflow is fatal.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Array¶

ludus::foundation::core::Array< ElementType >::Array(const Array &other)

Deep copy with capacity equal to other's size. Allocation failure is fatal.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Array¶

ludus::foundation::core::Array< ElementType >::Array(Array &&other) noexcept

Take other's storage without allocating. other becomes empty and owns no storage.

Borrows into other's elements now refer to this array's elements.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

operator=¶

Array & ludus::foundation::core::Array< ElementType >::operator=(const Array &other)

Replace the contents with a copy of other.

Reuses capacity when it suffices; otherwise frees and reallocates exactly. Existing elements are destroyed first, and allocation failure is fatal. Self-assignment does nothing.

Related types: Array

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

operator=¶

Array & ludus::foundation::core::Array< ElementType >::operator=(Array &&other) noexcept

Destroy the current elements, free the storage, then take other's storage.

other becomes empty. Self-assignment does nothing. Never allocates.

Related types: Array

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

~Array¶

ludus::foundation::core::Array< ElementType >::~Array()

Destroy the live elements and free the storage.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetSize¶

usize ludus::foundation::core::Array< ElementType >::GetSize() const noexcept

Number of live elements.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetCapacity¶

usize ludus::foundation::core::Array< ElementType >::GetCapacity() const noexcept

Number of elements the current storage holds without reallocating.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

IsEmpty¶

bool ludus::foundation::core::Array< ElementType >::IsEmpty() const noexcept

True when the array holds no live elements; capacity may still be retained.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetData¶

ElementType * ludus::foundation::core::Array< ElementType >::GetData() noexcept

First element, or nullptr when no storage is owned. Valid until the next reallocation or destruction.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetData¶

const ElementType * ludus::foundation::core::Array< ElementType >::GetData() const noexcept

Read-only first element, or nullptr when no storage is owned.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

EnsureCapacity¶

void ludus::foundation::core::Array< ElementType >::EnsureCapacity(usize newCapacity)

Guarantee GetCapacity() >= newCapacity without changing GetSize().

If the current capacity already satisfies the request, does nothing (never shrinks). This is the Ludus- native spelling of "reserve": the name states the postcondition. Infallible (fatal on OOM/overflow).

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryEnsureCapacity¶

bool ludus::foundation::core::Array< ElementType >::TryEnsureCapacity(usize newCapacity)

Fallible EnsureCapacity: returns false (container unchanged) on OOM/overflow.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Resize¶

void ludus::foundation::core::Array< ElementType >::Resize(usize newSize)

Set the size to newSize, destroying the tail or value-initializing new elements.

Growth reallocates to exactly newSize and invalidates all borrows. Allocation failure is fatal. Supports move-only element types.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Resize¶

void ludus::foundation::core::Array< ElementType >::Resize(usize newSize, const ElementType &value)
requires std::is_copy_constructible_v<ElementType>

Copy-fill resize requires copy-constructible elements; value-initialized resize supports move-only types.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryResize¶

bool ludus::foundation::core::Array< ElementType >::TryResize(usize newSize)

Fallible Resize with value-initialized new elements.

Returns

False on allocation failure or overflow, leaving the size, capacity and elements unchanged. Shrinking always succeeds without allocating.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryResize¶

bool ludus::foundation::core::Array< ElementType >::TryResize(usize newSize, const ElementType &value)
requires std::is_copy_constructible_v<ElementType>

Fallible Resize that copies value into new elements.

value may refer to an element of this array; it is copied before any relocation.

Returns

False on allocation failure or overflow, leaving the array and value unchanged.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TrimCapacity¶

void ludus::foundation::core::Array< ElementType >::TrimCapacity()

Release capacity down to the current size (best effort; never grows, never fails observably — on OOM it keeps the larger allocation).

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Clear¶

void ludus::foundation::core::Array< ElementType >::Clear() noexcept

Destroy every live element and keep the capacity. Never allocates.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

operator[]¶

ElementType & ludus::foundation::core::Array< ElementType >::operator[](usize index) noexcept

Element at index.

Precondition

index < GetSize() (asserted in checked builds).

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

operator[]¶

const ElementType & ludus::foundation::core::Array< ElementType >::operator[](usize index) const noexcept

Read-only element at index.

Precondition

index < GetSize() (asserted in checked builds).

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetFirst¶

ElementType & ludus::foundation::core::Array< ElementType >::GetFirst() noexcept

First element.

Precondition

The array is not empty.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetFirst¶

const ElementType & ludus::foundation::core::Array< ElementType >::GetFirst() const noexcept

Read-only first element.

Precondition

The array is not empty.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetLast¶

ElementType & ludus::foundation::core::Array< ElementType >::GetLast() noexcept

Last element.

Precondition

The array is not empty.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

GetLast¶

const ElementType & ludus::foundation::core::Array< ElementType >::GetLast() const noexcept

Read-only last element.

Precondition

The array is not empty.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

begin¶

Iterator ludus::foundation::core::Array< ElementType >::begin() noexcept

Range-for/standard interop: pointer to the first element (null when no storage is owned).

Related types: Iterator

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

begin¶

ConstIterator ludus::foundation::core::Array< ElementType >::begin() const noexcept

Range-for/standard interop: read-only pointer to the first element.

Related types: ConstIterator

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

cbegin¶

ConstIterator ludus::foundation::core::Array< ElementType >::cbegin() const noexcept

Standard interop: read-only pointer to the first element.

Related types: ConstIterator

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

end¶

Iterator ludus::foundation::core::Array< ElementType >::end() noexcept

Range-for/standard interop: one past the last live element.

Related types: Iterator

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

end¶

ConstIterator ludus::foundation::core::Array< ElementType >::end() const noexcept

Range-for/standard interop: read-only one past the last live element.

Related types: ConstIterator

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

cend¶

ConstIterator ludus::foundation::core::Array< ElementType >::cend() const noexcept

Standard interop: read-only one past the last live element.

Related types: ConstIterator

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

data¶

ElementType * ludus::foundation::core::Array< ElementType >::data() noexcept

Standard interop spelling of GetData().

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

data¶

const ElementType * ludus::foundation::core::Array< ElementType >::data() const noexcept

Standard interop spelling of the read-only GetData().

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

size¶

usize ludus::foundation::core::Array< ElementType >::size() const noexcept

Standard interop spelling of GetSize().

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Add¶

void ludus::foundation::core::Array< ElementType >::Add(const ElementType &value)

Append a copy of value; allocation failure is fatal.

value may refer to an element of this array. Growth invalidates all borrows.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Add¶

void ludus::foundation::core::Array< ElementType >::Add(ElementType &&value)

Append by moving value; allocation failure is fatal.

Growth invalidates all borrows. Use TryAdd at a status-returning boundary.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

AddInPlace¶

template <typename... Args>
ElementType & ludus::foundation::core::Array< ElementType >::AddInPlace(Args &&... args)

Construct a new element in place at the end from args.

Returns a reference to the new element.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryAdd¶

bool ludus::foundation::core::Array< ElementType >::TryAdd(const ElementType &value)

Fallible add: returns false (container unchanged) on OOM/overflow.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryAdd¶

bool ludus::foundation::core::Array< ElementType >::TryAdd(ElementType &&value)

Fallible move append.

Returns

False on allocation failure or overflow; the array is unchanged and value is not moved from, even when it refers to an element of this array.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryAddInPlace¶

template <typename... Args>
ElementType * ludus::foundation::core::Array< ElementType >::TryAddInPlace(Args &&... args)

Fallible append that constructs the element from args.

On growth the new element is constructed in the new block before existing elements are relocated, so args may borrow from this array.

Returns

The new element, or nullptr on allocation failure or overflow with the array and args untouched.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

AddRange¶

void ludus::foundation::core::Array< ElementType >::AddRange(std::span< const ElementType > items)

Append a contiguous range to the end; allocation failure is fatal.

Precondition

Input must not overlap this array's storage.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryAddRange¶

bool ludus::foundation::core::Array< ElementType >::TryAddRange(std::span< const ElementType > items)

Fallible append of copies of items, with at most one allocation.

Precondition

items does not overlap this array's storage (asserted).

Returns

False on allocation failure or overflow, leaving the array unchanged.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

RemoveLast¶

void ludus::foundation::core::Array< ElementType >::RemoveLast() noexcept

Destroy the last element.

Precondition

The array is not empty. Keeps the capacity.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

RemoveAt¶

void ludus::foundation::core::Array< ElementType >::RemoveAt(usize index) noexcept

Order-preserving remove at index (shifts the tail left). O(n).

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

RemoveRange¶

void ludus::foundation::core::Array< ElementType >::RemoveRange(usize first, usize last) noexcept

Order-preserving remove of the index range [first, last). O(n).

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

RemoveAtSwap¶

void ludus::foundation::core::Array< ElementType >::RemoveAtSwap(usize index) noexcept

O(1) removal when order does not matter: overwrite the slot with the last element, then drop the last.

The engine-preferred removal; named so the O(1) swap behaviour (and the resulting reorder) is explicit at call sites.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

InsertAt¶

ElementType & ludus::foundation::core::Array< ElementType >::InsertAt(usize index, const ElementType &value)

Insert a copy of value at index, shifting later elements; allocation failure is fatal.

Precondition

index <= GetSize(). value may refer to an element of this array. Invalidates borrows at and after index, or all borrows on growth.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

InsertAt¶

ElementType & ludus::foundation::core::Array< ElementType >::InsertAt(usize index, ElementType &&value)

Move value into index, shifting later elements; allocation failure is fatal.

Precondition

index <= GetSize().

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

InsertAtInPlace¶

template <typename... Args>
ElementType & ludus::foundation::core::Array< ElementType >::InsertAtInPlace(usize index, Args &&... args)

Construct a new element in place at index, shifting the tail right. O(n).

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryInsertAt¶

ElementType * ludus::foundation::core::Array< ElementType >::TryInsertAt(usize index, const ElementType &value)

Fallible ordered insertion.

Allocate before touching arguments so OOM also preserves aliased rvalues and caller-owned move-only values.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryInsertAt¶

ElementType * ludus::foundation::core::Array< ElementType >::TryInsertAt(usize index, ElementType &&value)

Fallible move insertion at index.

Precondition

index <= GetSize().

Returns

The inserted element, or nullptr on allocation failure with the array unchanged and value not moved from.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

TryInsertAtInPlace¶

template <typename... Args>
ElementType * ludus::foundation::core::Array< ElementType >::TryInsertAtInPlace(usize index, Args &&... args)

Fallible ordered insertion that constructs the element from args.

Allocation happens before args are read; on growth the element is built in the new block while borrows into the old block remain valid.

Precondition

index <= GetSize().

Returns

The inserted element, or nullptr on allocation failure or overflow with the array and args untouched.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Swap¶

void ludus::foundation::core::Array< ElementType >::Swap(Array &other) noexcept

Exchange storage with other without allocating. Element borrows follow their storage.

Related types: Array

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

operator std::span\< ElementType >¶

ludus::foundation::core::Array< ElementType >::operator std::span< ElementType >() noexcept

Borrow the live elements as a mutable span; invalidated with element borrows.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

operator std::span\< const ElementType >¶

ludus::foundation::core::Array< ElementType >::operator std::span< const ElementType >() const noexcept

Borrow the live elements as a read-only span; invalidated with element borrows.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

AsSpan¶

std::span< ElementType > ludus::foundation::core::Array< ElementType >::AsSpan() noexcept

Mutable span over the live elements; invalidated with element borrows.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

AsSpan¶

std::span< const ElementType > ludus::foundation::core::Array< ElementType >::AsSpan() const noexcept

Read-only span over the live elements; invalidated with element borrows.

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Static methods¶

GetMaxSize¶

static constexpr usize ludus::foundation::core::Array< ElementType >::GetMaxSize() noexcept

Largest element count the array can request without byte-size overflow.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

FromRange¶

static Array ludus::foundation::core::Array< ElementType >::FromRange(std::span< const ElementType > items)

Build an Array by copying a contiguous view (explicit range factory).

Related types: Array

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

Members¶

operator==¶

bool operator==(const Array &a, const Array &b)

Element-wise equality; arrays of different sizes are unequal. Capacity is ignored.

Related types: Array

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp