core.containers

ArrayList : struct<T> {
    inline IArray<T>
}

Array : struct<T> {
    inline IArray<T>
}

Fixed-Size Array

IArray : struct<T> {
    data     : ^T = null
    count    : i64 = 0
    capacity : i64 = 0
    allocator: ^Allocator = null
}

common interface

MapFindResult : struct {
    index : i64 = -1
    found : bool = false
}

MapEntry : struct<K, V> {
    key        : K
    value      : V
    hash       : u64 = 0
    state      : MapSlotState = MapSlotState.Empty
}

Map : struct<K, V> {
    entries    : ArrayList<MapEntry<K,V>>
    allocator  : ^Allocator = null
    tombstones : i64 = 0
    capacity   : i32 = 0
}

Set : struct<T> {
    map : Map<T,bool>
}

Unique-value container backed by Map<T,bool>.

T must provide `get_hash()` and `are_equals(other : T)` extension methods.

Stack : struct<T> {
    items : ArrayList<T>
}

Last-in, first-out container backed by ArrayList<T>.

InitArrayList : func <T>() -> ArrayList<T>

Constructs an ArrayList with the default capacity and context allocator.

Parameters:
  none

Returns:
  ArrayList<T> - initialized list with `ARRAY_DEFAULT_CAPACITY`, the current
                 context allocator, and zero elements.

Notes:
  - This allocates backing storage for `ARRAY_DEFAULT_CAPACITY` elements.
  - Allocation failure is reflected by `data` remaining null.

InitArrayList : func<T>(capacity : i64, allocator : ^Allocator) -> ArrayList<T>

Constructs an ArrayList with a requested capacity and allocator.

Parameters:
  capacity  : i64        - initial element capacity to allocate.
  allocator : ^Allocator - allocator used for the backing storage.

Returns:
  ArrayList<T> - initialized list with the requested capacity, allocator,
                 and zero elements.

Notes:
  - Allocation failure is reflected by `data` remaining null.

InitArrayList : func<T>(capacity : i64 ) -> ArrayList<T>

Constructs an ArrayList with a requested capacity and context allocator.

Parameters:
  capacity : i64 - initial element capacity to allocate.

Returns:
  ArrayList<T> - initialized list with the requested capacity, the current
                 context allocator, and zero elements.

Notes:
  - Allocation failure is reflected by `data` remaining null.

InitArrayList : func<T>(allocator : ^Allocator) -> ArrayList<T>

Constructs an ArrayList with the default capacity and an allocator.

Parameters:
  allocator : ^Allocator - allocator to associate with the list.

Returns:
  ArrayList<T> - initialized list with `ARRAY_DEFAULT_CAPACITY`, the supplied
                 allocator, and zero elements.

Notes:
  - This allocates backing storage for `ARRAY_DEFAULT_CAPACITY` elements.
  - Allocation failure is reflected by `data` remaining null.

DeinitArrayList : func<T>(list : ^ArrayList<T>)

Frees an ArrayList's backing storage and resets its fields.

Parameters:
  list : ^ArrayList<T> - list to destroy. Must have a valid allocator.

Returns:
  void

Notes:
  - This frees only the list's internal buffer. It does not recursively
    destroy values stored in the list.

as_slice : func<T>(self : ^ArrayList<T>) -> []T

Creates a slice view over the live elements of an ArrayList.

Parameters:
  self : ^ArrayList<T> - list to view.

Returns:
  []T - slice view over `self.data` with length `self.count`.

Notes:
  - The returned slice does not own the backing storage.
  - Mutating or freeing the list may invalidate the slice.

get_at : func<T>(self : ^ArrayList<T>, index : i32 ) -> [T, ContainerStatus]

Returns the element at an index.

Parameters:
  self  : ^ArrayList<T> - list to read from.
  index : i32           - zero-based element index.

Returns:
  [T, ContainerStatus] - element value and status.
                        On success returns the value and ContainerStatus.Ok.
                        On failure returns a default T value and:
                          ContainerStatus.IndexOutOfRange - `self` was null
                            or `index` was outside the live item range.

add : func<T>(self : ^ArrayList<T>, value : T ) -> bool

Appends a value to the end of an ArrayList, growing the backing storage when
full.

Parameters:
  self  : ^ArrayList<T> - list to mutate. Must be initialized.
  value : T             - value to append.

Returns:
  bool - true when the value was appended, false if the list was invalid or
         allocation failed while growing.

Notes:
  - Growth doubles capacity, falling back to ARRAY_DEFAULT_CAPACITY when the
    current capacity is zero or negative.

increase_capacity : func<T>(self : ^ArrayList<T>, capacity : i32) -> [bool, ContainerStatus]

Reallocates an ArrayList backing buffer to the requested capacity.

Parameters:
  self     : ^ArrayList<T> - list to resize. Must have a valid allocator.
  capacity : i32           - requested element capacity. Must be at least
                             `self.count`.

Returns:
  [bool, ContainerStatus] - resize result and status.
                           On success returns [true, ContainerStatus.Ok].
                           On failure returns false and:
                             ContainerStatus.InvalidAllocator - list or
                               allocator was invalid.
                             ContainerStatus.ArgOutOfRange - requested
                               capacity was smaller than live count.
                             ContainerStatus.AllocatorFailed - allocation
                               failed.

Notes:
  - Existing live elements are copied into the new buffer.
  - This does not initialize unused capacity.

remove_at : func<T>(self : ^ArrayList<T>, index : i32 ) -> [bool, ContainerStatus]

Removes the element at an index by swapping the final live element into its
slot.

Parameters:
  self  : ^ArrayList<T> - list to mutate.
  index : i32           - zero-based element index to remove.

Returns:
  [bool, ContainerStatus] - removal result and status.
                           On success returns [true, ContainerStatus.Ok].
                           Returns ContainerStatus.InvalidContainer when
                           `self` is null.
                           Returns ContainerStatus.IndexOutOfRange when
                           `index` is outside the live item range.

Notes:
  - This does not preserve element order.

remove : func<T>(self : ^ArrayList<T>, value : T, eq : func(T, T) -> bool ) -> [bool, ContainerStatus]

Removes the first element equal to `value` according to a caller-provided
equality function.

Parameters:
  self  : ^ArrayList<T>       - list to mutate.
  value : T                   - value to remove.
  eq    : func(T, T) -> bool  - equality predicate used to compare elements.

Returns:
  [bool, ContainerStatus] - removal result and status.
                           On success returns [true, ContainerStatus.Ok].
                           If absent returns [false, ContainerStatus.ItemNotFound].

Notes:
  - This does not preserve element order because removal swaps with the last
    live element.

remove_range : func<T>(self : ^ArrayList<T>, index : i32, count : i32 ) -> [bool, ContainerStatus]

Removes a range of elements starting at `index`.

Parameters:
  self  : ^ArrayList<T> - list to mutate.
  index : i32           - first index to remove.
  count : i32           - number of elements to remove.

Returns:
  [bool, ContainerStatus] - range removal result and status.
                           On success returns [true, ContainerStatus.Ok].
                           Returns ContainerStatus.IndexOutOfRange when the
                           requested range exceeds the live item range.

Notes:
  - This uses `remove_at`, so element order is not preserved.

contains : func<T>(self : ^ArrayList<T>, value : T) -> [bool, ContainerStatus]

Reports whether a list contains a value using the built-in `==` operator.

Parameters:
  self  : ^ArrayList<T> - list to search.
  value : T             - value to find.

Returns:
  [bool, ContainerStatus] - containment result and status.
                           On success returns [true, ContainerStatus.Ok].
                           If absent returns [false, ContainerStatus.ItemNotFound].

Notes:
  - T must support the built-in `==` operator.

contains : func<T>(self : ^ArrayList<T>, value : T, eq : func(T, T) -> bool) -> [bool, ContainerStatus]

Reports whether a list contains a value using a caller-provided equality
function.

Parameters:
  self  : ^ArrayList<T>       - list to search.
  value : T                   - value to find.
  eq    : func(T, T) -> bool  - equality predicate used to compare elements.

Returns:
  [bool, ContainerStatus] - containment result and status.
                           On success returns [true, ContainerStatus.Ok].
                           If absent returns [false, ContainerStatus.ItemNotFound].

clear : func<T>(self : ^ArrayList<T>) -> void

Removes all live elements from an ArrayList without freeing capacity.

Parameters:
  self : ^ArrayList<T> - list to clear. May be null, in which case this is a
                         no-op.

Returns:
  void

Notes:
  - This does not recursively destroy values stored in the list.

clone : func<T>(self : ^ArrayList<T>) -> ArrayList<T>

Creates a shallow copy of an ArrayList and its live backing storage.

Parameters:
  self : ^ArrayList<T> - list to clone.

Returns:
  ArrayList<T> - new list with copied live elements and the same capacity.

Notes:
  - Values are copied byte-for-byte; pointed-to resources are not cloned.
  - The returned list uses the same allocator as `self`.

swap : func<T>(self: ^ArrayList<T>, idx0 : i32, idx1 : i32 ) -> bool

Swaps two live elements in an ArrayList.

Parameters:
  self : ^ArrayList<T> - list to mutate.
  idx0 : i32           - first element index.
  idx1 : i32           - second element index.

Returns:
  bool - true when both indexes were valid and the swap completed; false
         otherwise.

InitArray : func<T>() -> Array<T>

Constructs an Array with the default capacity and context allocator.

Parameters:
  none

Returns:
  Array<T> - initialized array with `ARRAY_DEFAULT_CAPACITY`, the current
             context allocator, and zero elements.

Notes:
  - This allocates backing storage for `ARRAY_DEFAULT_CAPACITY` elements.
  - Allocation failure is reflected by `data` remaining null.

InitArray : func<T>(capacity : i64) -> Array<T>

Constructs an Array with the requested capacity and context allocator.

Parameters:
  capacity : i64 - number of elements to allocate.

Returns:
  Array<T> - initialized array with the requested capacity, the current
             context allocator, and zero elements.

Notes:
  - Allocation failure is reflected by `data` remaining null.

InitArray : func<T>(capacity : i64, allocator : ^Allocator) -> Array<T>

Constructs an Array with the requested capacity and allocator.

Parameters:
  capacity  : i64        - number of elements to allocate.
  allocator : ^Allocator - allocator used for the backing storage.

Returns:
  Array<T> - initialized array with the requested capacity, allocator, and
             zero elements.

Notes:
  - Allocation failure is reflected by `data` remaining null.

InitArray : func<T>(allocator : ^Allocator) -> Array<T>

Constructs an Array with the default capacity and an allocator.

Parameters:
  allocator : ^Allocator - allocator associated with the array.

Returns:
  Array<T> - initialized array with `ARRAY_DEFAULT_CAPACITY`, the supplied
             allocator, and zero elements.

Notes:
  - This allocates backing storage for `ARRAY_DEFAULT_CAPACITY` elements.
  - Allocation failure is reflected by `data` remaining null.

DeinitArray : func<T>(self : ^Array<T>)

Frees an Array's backing storage and resets its fields.

Parameters:
  self : ^Array<T> - array to deinitialize. May be null.

Returns:
  void

Notes:
  - This frees only the internal buffer. It does not recursively destroy
    stored values.

insert : func<T>(self : ^Array<T>, index : i64, value : T) -> [bool, ContainerStatus]

Inserts a value at an index, shifting following elements one slot to the right.

Parameters:
  self  : ^Array<T> - array to mutate.
  index : i64       - insertion index. May be equal to `self.count` to append.
  value : T         - value to insert.

Returns:
  [bool, ContainerStatus] - insertion result and status.
                           On success returns [true, ContainerStatus.Ok].
                           Returns ContainerStatus.IndexOutOfRange when the
                           index is beyond the live range or the array is full.

Notes:
  - This preserves element order.

append : func<T>(self : ^Array<T>, value : T) -> [bool, ContainerStatus]

Appends a value to the end of an Array.

Parameters:
  self  : ^Array<T> - array to mutate.
  value : T         - value to append.

Returns:
  [bool, ContainerStatus] - append result and status.
                           On success returns [true, ContainerStatus.Ok].
                           Returns ContainerStatus.IndexOutOfRange when the
                           array is full.

get_at : func<T>(self : ^Array<T>, index : i64) -> [T, ContainerStatus]

Returns the element at an index.

Parameters:
  self  : ^Array<T> - array to read from.
  index : i64       - zero-based element index.

Returns:
  [T, ContainerStatus] - element value and status.
                        On success returns the value and ContainerStatus.Ok.
                        On failure returns a default T value and:
                          ContainerStatus.IndexOutOfRange - `index` was
                            outside the live item range.

get_last: func<T>(self : ^Array<T> ) -> T

Removes and returns the last live element.

Parameters:
  self : ^Array<T> - array to mutate.

Returns:
  T - previous last live element.

Notes:
  - The count is decremented before reading.
  - Calling this on an empty array returns `self.data[0]`.

clear : func<T>(self : ^Array<T>)

Removes all live elements from an Array without freeing capacity.

Parameters:
  self : ^Array<T> - array to clear.

Returns:
  void

Notes:
  - This does not recursively destroy stored values.

empty : func<T>(self : ^Array<T>) -> bool

Reports whether an Array contains no live elements.

Parameters:
  self : ^Array<T> - array to query.

Returns:
  bool - true when `self.count` is zero, false otherwise.

full : func<T>(self : ^Array<T>) -> bool

Reports whether an Array has reached its fixed capacity.

Parameters:
  self : ^Array<T> - array to query.

Returns:
  bool - true when `self.count` is greater than or equal to `self.capacity`,
         false otherwise.

as_slice : func<T>(self : ^IArray<T>) -> []T

Creates a slice view over the live elements of an IArray-compatible container.

Parameters:
  self : ^IArray<T> - list header containing data pointer and live count.

Returns:
  []T - slice view over `self.data` with length `self.count`.

Notes:
  - The returned slice does not own the backing storage.
  - Mutating or freeing the source list may invalidate the slice.

InitMap : func<K,V>() -> [Map<K,V>, ContainerStatus]

Constructs a Map with the default capacity and context allocator.

Parameters:
  none

Returns:
  [Map<K,V>, ContainerStatus] - the initialized map header and status.
                               On success returns ContainerStatus.Ok.
                               A missing context allocator returns
                               ContainerStatus.InvalidAllocator.
                               Allocation failure returns
                               ContainerStatus.AllocatorFailed.

Notes:
  - The default capacity is `ARRAY_DEFAULT_CAPACITY`.
  - This allocates the initial entry buffer.

InitMap : func<K,V>(capacity : i32, allocator : ^Allocator) -> [Map<K,V>, ContainerStatus]

Constructs a Map with a requested capacity and allocator.

Parameters:
  capacity  : i32        - requested initial slot capacity. Rounded up to
                           the next power of two when necessary.
  allocator : ^Allocator - non-null allocator to associate with the map.
Returns:
  [Map<K,V>, ContainerStatus] - the constructed map and a status.
                               On success returns ContainerStatus.Ok.
                               On failure returns a zero-valued map and:
                                 ContainerStatus.InvalidAllocator -
                                   `allocator` was null.
                                 ContainerStatus.InvalidArg -
                                   `capacity` was invalid.
                                 ContainerStatus.AllocatorFailed -
                                   backing storage allocation failed.

Notes:
  - K must provide `get_hash()` and `are_equals(other : K)` extension methods.
  - This allocates the initial entry buffer.

InitMap : func<K,V>(capacity : i32) -> [Map<K,V>, ContainerStatus]

Constructs a Map with a requested capacity and context allocator.

Parameters:
  capacity : i32 - requested slot capacity. Rounded up to the next power
                   of two when necessary.

Returns:
  [Map<K,V>, ContainerStatus] - the initialized map header and status.
                               Returns ContainerStatus.InvalidArg when
                               `capacity` is not positive.
                               Returns ContainerStatus.InvalidAllocator
                               when the context allocator is null.
                               Returns ContainerStatus.AllocatorFailed
                               when backing storage allocation fails.

Notes:
  - This allocates the initial entry buffer.

InitMap : func<K,V>(allocator : ^Allocator) -> [Map<K,V>, ContainerStatus]

Constructs a Map with the default capacity and an allocator.

Parameters:
  allocator : ^Allocator - non-null allocator to associate with the map.

Returns:
  [Map<K,V>, ContainerStatus] - the initialized map header and status.
                               Returns ContainerStatus.InvalidAllocator
                               when `allocator` is null.
                               Returns ContainerStatus.AllocatorFailed
                               when backing storage allocation fails.

Notes:
  - The default capacity is `ARRAY_DEFAULT_CAPACITY`.
  - This allocates the initial entry buffer.

DeinitMap : func<K,V>(map : ^Map<K,V>)

Releases the backing storage owned by a Map and resets its fields.

Parameters:
  map : ^Map<K,V> - map to deinitialize. May be null.

Returns:
  void

Notes:
  - This frees only the map's internal entry buffer. It does not recursively
    destroy keys or values stored inside entries.

add : func<K,V>(self : ^Map<K,V>, key : K, value : V) -> [bool, ContainerStatus]

Inserts a key/value pair into a Map, or updates the value for an existing key.

Parameters:
  self  : ^Map<K,V> - map to mutate. Must be initialized.
  key   : K         - key to insert or update.
  value : V         - value to store for the key.

Returns:
  [bool, ContainerStatus] - insertion flag and status.
                           On success:
                             [true,  ContainerStatus.Ok] - inserted new key.
                             [false, ContainerStatus.Ok] - updated existing key.
                           On failure:
                             ContainerStatus.InternalError      - `self` was null.
                             ContainerStatus.InvalidContainer  - backing storage
                               was invalid or no slot could be found.
                             ContainerStatus.InvalidArg         - capacity was invalid.
                             Any ContainerStatus propagated from reserve.

Notes:
  - The map grows before insertion when live entries plus tombstones reach
    the configured load threshold.
  - Deleted slots marked as tombstones may be reused for new entries.

get : func<K,V>(self : ^Map<K,V>, key : K) -> [V, ContainerStatus]

Looks up a value by key.

Parameters:
  self : ^Map<K,V> - map to search. Must be initialized.
  key  : K         - key to find.

Returns:
  [V, ContainerStatus] - found value and status.
                        On success returns the stored value and
                        ContainerStatus.Ok.
                        On failure returns a default V value and:
                          ContainerStatus.InternalError     - `self` was null.
                          ContainerStatus.InvalidContainer - backing storage
                            was invalid.
                          ContainerStatus.InvalidArg        - capacity was invalid.
                          ContainerStatus.ItemNotFound      - key was absent.

contains : func<K,V>(self : ^Map<K,V>, key : K) -> [bool, ContainerStatus]

Reports whether a Map contains a key.

Parameters:
  self : ^Map<K,V> - map to search. Must be initialized.
  key  : K         - key to find.

Returns:
  [bool, ContainerStatus] - containment result and status.
                           On success returns [true, ContainerStatus.Ok].
                           If absent returns [false, ContainerStatus.ItemNotFound].
                           On invalid input returns false with:
                             ContainerStatus.InternalError
                             ContainerStatus.InvalidContainer
                             ContainerStatus.InvalidArg

remove : func<K,V>(self : ^Map<K,V>, key : K) -> [bool, ContainerStatus]

Removes a key/value pair from a Map.

Parameters:
  self : ^Map<K,V> - map to mutate. Must be initialized.
  key  : K         - key to remove.

Returns:
  [bool, ContainerStatus] - removal flag and status.
                           On success returns [true, ContainerStatus.Ok].
                           If absent returns [false, ContainerStatus.ItemNotFound].
                           On invalid input returns false with:
                             ContainerStatus.InternalError
                             ContainerStatus.InvalidContainer
                             ContainerStatus.InvalidArg

Notes:
  - Removed slots become tombstones so existing probe chains remain valid.
  - This does not recursively destroy the removed key or value.

clear : func<K,V>(self : ^Map<K,V>) -> ContainerStatus

Removes all entries from a Map while keeping its allocated capacity.

Parameters:
  self : ^Map<K,V> - map to clear. Must be initialized.

Returns:
  ContainerStatus - ContainerStatus.Ok on success, or:
                     ContainerStatus.InternalError     - `self` was null.
                     ContainerStatus.InvalidContainer - backing storage was invalid.
                     ContainerStatus.InvalidArg        - capacity was invalid.

Notes:
  - All slots are reset to Empty and the tombstone count is reset to zero.
  - This does not recursively destroy keys or values stored inside entries.

InitSet : func<T>() -> [Set<T>, ContainerStatus]

Constructs a Set with the default capacity and context allocator.

Parameters:
  none

Returns:
  [Set<T>, ContainerStatus] - initialized set and status.
                             On success returns ContainerStatus.Ok.
                             Allocation failure returns
                             ContainerStatus.AllocatorFailed.

Notes:
  - T must provide `get_hash()` and `are_equals(other : T)` extension methods.
  - This allocates the initial Map entry buffer.

InitSet : func<T>(capacity : i32) -> [Set<T>, ContainerStatus]

Constructs a Set with a requested capacity and context allocator.

Parameters:
  capacity : i32 - requested initial capacity. Rounded up to the next power
                   of two when necessary.

Returns:
  [Set<T>, ContainerStatus] - initialized set and status.
                             On success returns ContainerStatus.Ok.
                             Invalid capacity returns
                             ContainerStatus.InvalidArg.
                             Allocation failure returns
                             ContainerStatus.AllocatorFailed.

Notes:
  - T must provide `get_hash()` and `are_equals(other : T)` extension methods.
  - This allocates the initial Map entry buffer.

InitSet : func<T>(allocator : ^Allocator) -> [Set<T>, ContainerStatus]

Constructs a Set with the default capacity and an allocator.

Parameters:
  allocator : ^Allocator - non-null allocator used for backing storage.

Returns:
  [Set<T>, ContainerStatus] - initialized set and status.
                             On success returns ContainerStatus.Ok.
                             A null allocator returns
                             ContainerStatus.InvalidAllocator.
                             Allocation failure returns
                             ContainerStatus.AllocatorFailed.

Notes:
  - T must provide `get_hash()` and `are_equals(other : T)` extension methods.
  - This allocates the initial Map entry buffer.

InitSet : func<T>(capacity : i32, allocator : ^Allocator) -> [Set<T>, ContainerStatus]

Constructs a Set with a requested capacity and allocator.

Parameters:
  capacity  : i32        - requested initial capacity. Rounded up to the
                           next power of two when necessary.
  allocator : ^Allocator - non-null allocator used for backing storage.

Returns:
  [Set<T>, ContainerStatus] - initialized set and status.
                             On success returns ContainerStatus.Ok.
                             A null allocator returns
                             ContainerStatus.InvalidAllocator.
                             Invalid capacity returns
                             ContainerStatus.InvalidArg.
                             Allocation failure returns
                             ContainerStatus.AllocatorFailed.

Notes:
  - T must provide `get_hash()` and `are_equals(other : T)` extension methods.
  - This allocates the initial Map entry buffer.

DeinitSet : func<T>(set : ^Set<T>)

Releases the backing storage owned by a Set and resets its internal Map.

Parameters:
  set : ^Set<T> - set to deinitialize. May be null.

Returns:
  void

Notes:
  - This frees only the internal Map entry buffer owned by the Set.
  - It does not recursively destroy values stored in the Set.
  - It does not free the Set value or pointer itself.

add : func<T>(self : ^Set<T>, value : T) -> [bool, ContainerStatus]

Adds a value to a Set.

Parameters:
  self  : ^Set<T> - set to mutate. Must be initialized.
  value : T       - value to add.

Returns:
  [bool, ContainerStatus] - insertion flag and status.
                           On success:
                             [true,  ContainerStatus.Ok] - value was new.
                             [false, ContainerStatus.Ok] - value already existed.
                           Other statuses are propagated from Map.add.

Notes:
  - T must provide `get_hash()` and `are_equals(other : T)` extension methods.

contains : func<T>(self : ^Set<T>, value : T) -> [bool, ContainerStatus]

Reports whether a Set contains a value.

Parameters:
  self  : ^Set<T> - set to search. Must be initialized.
  value : T       - value to find.

Returns:
  [bool, ContainerStatus] - containment result and status.
                           On success returns [true, ContainerStatus.Ok].
                           If absent returns
                           [false, ContainerStatus.ItemNotFound].
                           Other statuses are propagated from Map.contains.

Notes:
  - T must provide `get_hash()` and `are_equals(other : T)` extension methods.

remove : func<T>(self : ^Set<T>, value : T) -> [bool, ContainerStatus]

Removes a value from a Set.

Parameters:
  self  : ^Set<T> - set to mutate. Must be initialized.
  value : T       - value to remove.

Returns:
  [bool, ContainerStatus] - removal flag and status.
                           On success returns [true, ContainerStatus.Ok].
                           If absent returns
                           [false, ContainerStatus.ItemNotFound].
                           Other statuses are propagated from Map.remove.

Notes:
  - This does not recursively destroy the removed value.

clear : func<T>(self : ^Set<T>) -> ContainerStatus

Removes all values from a Set while keeping its allocated capacity.

Parameters:
  self : ^Set<T> - set to clear. Must be initialized.

Returns:
  ContainerStatus - ContainerStatus.Ok on success. Other statuses are
                    propagated from Map.clear.

Notes:
  - This does not recursively destroy values stored in the Set.

count : func<T>(self : ^Set<T>) -> i64

Returns the number of values in a Set.

Parameters:
  self : ^Set<T> - set to query.

Returns:
  i64 - live value count, or zero for a null Set.

empty : func<T>(self : ^Set<T>) -> bool

Reports whether a Set contains no values.

Parameters:
  self : ^Set<T> - set to query.

Returns:
  bool - true when the Set is null or contains no values.

InitStack : func<T>() -> Stack<T>

Constructs a Stack with the default capacity and context allocator.

Parameters:
  none

Returns:
  Stack<T> - stack with `ARRAY_DEFAULT_CAPACITY`, the current context
             allocator, and zero elements.

Notes:
  - This allocates backing storage for `ARRAY_DEFAULT_CAPACITY` elements.
  - Allocation failure is reflected by `items.data` remaining null.

InitStack : func<T>(capacity : i64, allocator : ^Allocator) -> Stack<T>

Constructs a Stack with a requested capacity and allocator.

Parameters:
  capacity  : i64        - initial element capacity to allocate.
  allocator : ^Allocator - allocator used for the backing storage.

Returns:
  Stack<T> - stack with the requested capacity and allocator, and zero
             elements.

Notes:
  - Allocation failure is reflected by `items.data` remaining null.

InitStack : func<T>(capacity : i64) -> Stack<T>

Constructs a Stack with a requested capacity and context allocator.

Parameters:
  capacity : i64 - initial element capacity to allocate.

Returns:
  Stack<T> - stack with the requested capacity, the current context
             allocator, and zero elements.

Notes:
  - Allocation failure is reflected by `items.data` remaining null.

InitStack : func<T>(allocator : ^Allocator) -> Stack<T>

Constructs a Stack with the default capacity and an allocator.

Parameters:
  allocator : ^Allocator - allocator to associate with the stack.

Returns:
  Stack<T> - stack with `ARRAY_DEFAULT_CAPACITY`, the supplied allocator,
             and zero elements.

Notes:
  - This allocates backing storage for `ARRAY_DEFAULT_CAPACITY` elements.
  - Allocation failure is reflected by `items.data` remaining null.

DeinitStack : func<T>(stack : ^Stack<T>)

Frees a Stack's backing storage and resets its internal list.

Parameters:
  stack : ^Stack<T> - stack to deinitialize. May be null.

Returns:
  void

Notes:
  - This frees only the internal buffer. It does not recursively destroy
    values stored in the stack.

push : func<T>(self : ^Stack<T>, value : T) -> [bool, ContainerStatus]

Pushes a value onto the top of the stack.

Parameters:
  self  : ^Stack<T> - stack to mutate.
  value : T         - value to push.

Returns:
  [bool, ContainerStatus] - push result and status.
                           On success returns [true, ContainerStatus.Ok].
                           On failure returns false with:
                             ContainerStatus.InvalidContainer
                             ContainerStatus.AllocatorFailed

pop : func<T>(self : ^Stack<T>) -> [T, ContainerStatus]

Removes and returns the top value from the stack.

Parameters:
  self : ^Stack<T> - stack to mutate.

Returns:
  [T, ContainerStatus] - popped value and status.
                        On empty or invalid stack, returns a default T value
                        with ContainerStatus.ItemNotFound or
                        ContainerStatus.InvalidContainer.

peek : func<T>(self : ^Stack<T>) -> [T, ContainerStatus]

Returns the top value without removing it.

Parameters:
  self : ^Stack<T> - stack to read from.

Returns:
  [T, ContainerStatus] - top value and status.
                        On empty or invalid stack, returns a default T value
                        with ContainerStatus.ItemNotFound or
                        ContainerStatus.InvalidContainer.

clear : func<T>(self : ^Stack<T>) -> void

Removes all values from a stack without freeing capacity.

Parameters:
  self : ^Stack<T> - stack to clear. May be null.

Returns:
  void

empty : func<T>(self : ^Stack<T>) -> bool

Reports whether a stack contains no values.

Parameters:
  self : ^Stack<T> - stack to query.

Returns:
  bool - true when the stack is null or contains no values.

count : func<T>(self : ^Stack<T>) -> i64

Returns the number of live values in a stack.

Parameters:
  self : ^Stack<T> - stack to query.

Returns:
  i64 - live value count, or zero for a null stack.