Contiguous same-schema storage with explicit size and reserve management.
Storage and reserve model
size is the current item count.reserve is the current backing-storage capacity measured in items.data returns the current first-item reference and may be NIL before the first allocation or after release.clear removes all items while preserving the reserved capacity.release removes all items and frees the backing storage.setReserve only raises the reserved capacity.shrink reduces only the item count and leaves the reserved capacity unchanged.enlarge only grows the item count.resize may shrink or grow the item count according to the requested size.
Reference stability and invalidation
at, last, data, span, and slice return references or views into the current contiguous storage.- Any operation that reallocates the backing storage invalidates those earlier references and views.
- Reallocation can occur during
append, enlarge, resize growth, and setReserve when the current reserve is insufficient or the reserve is raised.
release invalidates all earlier references and views.clear preserves capacity but destroys the former items, so references to those former items are no longer valid values.erase moves the last item into the erased ordinal, and eraseIf compacts retained items. Earlier references to moved items must be treated as invalid.popBack, shrink, and resize shrink invalidate references to removed tail items.
Array
Methods
append |
(item/span/iter --) |
Appends item(s) to the end. |
Postconditions
- Item count increases by appended count.
- New items occupy consecutive positions after the former last item.
- Reserve is not less than size.
- If the former reserve is not less than the new size, the reserve remains unchanged.
- If new size is not zero, data is not Nil.
Remarks
Appending data may cause reallocation if the reserve is insufficient, potentially invalidating obtained Refs. If the reserve is already sufficient, reallocation does not occur. If the source projection has a size, the function reserves space in one operation to avoid multiple reallocations.
Examples
"Array" use
"algorithm" use
"control" use
{} () {} [
numbers: Int32 Array;
# Append single items
10 @numbers.append
20 @numbers.append
[numbers (10 20) =] "[.append] produced wrong result" ensure
# Append multiple items
(30 40 50) @numbers.append
[numbers (10 20 30 40 50) =] "[.append] produced wrong result" ensure
"Done.\n" print
] "main" exportFunction
assign |
(span/iter --) |
Clears and loads the array from the specified iteration source. |
- Source’s item type = @Item.
- If known size, ≥ 0.
- Array is valid.
Postconditions
- Old data cleared, then replaced by new source data.
- The item count becomes the source item count.
at |
(key -- ref) |
Returns Ref to the item at key. |
- key in [0..current item count - 1].
- Array valid.
Postconditions
- Returns a Ref to the item at key.
clear |
(--) |
Removes all items and preserves capacity. |
Postconditions
- The item count becomes
0.
- Reserve unchanged.
data |
(-- ref) |
Returns the stored Ref to the first item. |
Postconditions
- Result can be
NIL if the item count is 0.
enlarge |
(newSize --) |
Grows array size to newSize (≥ old size). |
- newSize ≥ current item count.
- Array valid.
Postconditions
- The item count becomes
newSize. Reallocation may occur if needed.
- New items constructed if automatic.
erase |
(key --) |
Removes the item at key and fills that position with the last item. |
- key in [0..current item count - 1].
- size > 0.
- Array valid.
Postconditions
- The item count decreases by
1.
eraseIf |
(predicate --) |
Removes all items for which predicate reports TRUE. |
predicate accepts one item and reports a Cond.- Array valid.
Postconditions
- Every removed item satisfied
predicate.
- Every retained item satisfied
predicate = FALSE.
- The relative order of retained items is preserved.
iter |
(-- iter) |
Returns an iteration source over the current items. |
Postconditions
- The result iterates over the same item range as
span.
last |
(-- ref) |
Returns Ref to the last item. |
Postconditions
- Returns a Ref to the last item.
popBack |
(--) |
Removes the last item. |
Postconditions
- The item count decreases by
1.
- Reserve unchanged.
release |
(--) |
Clears and frees all array memory. |
Postconditions
- The stored data Ref becomes
NIL, the item count becomes 0, and the reserved capacity becomes 0.
reserve |
(-- count) |
Returns the current reserved capacity. |
Postconditions
- Returns the current reserved capacity.
Examples
"Array" use
"control" use
{} () {} [
numbers: Int32 Array;
numbers.reserve printStack _:;
4 @numbers.setReserve
numbers.reserve printStack _:;
] "main" exportFunction
Expected Output During Compilation
0
4
resize |
(newSize --) |
Changes size; can shrink or grow array. |
- newSize ≥ 0.
- Array valid.
Postconditions
- The item count becomes
newSize.
- Extra items destroyed if shrinking; new items constructed if growing.
setReserve |
(newReserve --) |
Raises reserved capacity to newReserve. |
newReserve ≥ current reserve.- Array valid.
Postconditions
- The reserved capacity becomes
newReserve.
- The item count is unchanged.
- Reallocation may occur if the requested reserve differs from the current reserve.
shrink |
(newSize --) |
Reduces size to newSize without changing reserve. |
newSize ≤ current size.- Array valid.
Postconditions
- The item count becomes
newSize.
- Items above
newSize are removed.
- The reserved capacity is unchanged.
size |
(-- count) |
Returns the current number of items. |
Postconditions
- Returns the current item count.
slice |
(offset size -- theSpan) |
Returns a span over the selected subrange. |
offset in [0..current item count].size in [0..current item count - offset].- Array valid.
Postconditions
- The result spans exactly the requested subrange.
Runtime example
"Array" use
"String" use
"control" use
{} Int32 {} [
numbers: Int32 Array;
(10 20 30 40) @numbers.assign
part: 1 2 @numbers.slice;
("size=" part.size LF
"first=" 0 @part.at new LF
"second=" 1 @part.at new LF) printList
0
] "main" exportFunction
Expected Output
size=2
first=20
second=30
span |
(-- theSpan) |
Returns a span over [0..size-1]. |
Postconditions
- Span is invalidated by reallocation or release.
Struct Item Example
"Array" use
"control" use
Point: [{x: Int32; y: Int32;}];
{} () {} [
points: Point Array;
{x: 10; y: 20;} @points.append
{x: 30; y: 40;} @points.append
0 @points.at .x printStack _:;
] "main" exportFunction
Expected Output During Compilation
Int32 Cref
Usage Notes
clear removes all items while preserving capacity. release also frees the reserved storage.resize and enlarge apply when the target size is known in advance.at performs bounds checking on the supplied key.span provides a view for MPL iteration utilities.
MemoryDebugArray
Variant of Array with memory-debug instrumentation enabled.
- Public methods follow the same interface as
Array.
- The variant is intended for memory-accounting and debugging scenarios.
getHeapUsedSize (array -- size)
Returns total heap usage of the Array as Natx.
- The outer array buffer is counted by reserved capacity, not only by current size.
- Nested item heap usage is included recursively when the item schema also participates in
getHeapUsedSize.
toArray (source -- array)
Creates a new Array from a span, iteration source, or existing Array.
- Span sources are copied directly.
- Iteration sources are consumed item by item until exhausted.
- Existing
Array sources are copied through new.
Runtime example
"Array" use
"String" use
"control" use
{} Int32 {} [
numbers: Int32 Array;
10 @numbers.append
20 @numbers.append
30 @numbers.append
("size=" numbers.size LF
"last=" @numbers.last new LF) printList
1 @numbers.erase
("size2=" numbers.size LF
"item1=" 1 @numbers.at new LF) printList
0
] "main" exportFunction
Expected Output
size=3
last=30
size2=2
item1=30
Runtime example: eraseIf preserves retained order
"Array" use
"String" use
"control" use
{} Int32 {} [
numbers: Int32 Array;
(10 20 30 15) @numbers.assign
[15 >] @numbers.eraseIf
("size=" numbers.size LF
"first=" 0 @numbers.at new LF
"last=" @numbers.last new LF) printList
0
] "main" exportFunction
Expected Output
size=2
first=10
last=15
See also
- Span: Contiguous non-owning view of items of the same schema.
- SpanStatic: Contiguous non-owning view of items of the same schema with schema-level fixed size.
- Deque: Double-ended queue data structure.
- PriorityQueue: Priority queue with customizable comparison.
- algorithm: Collection interfaces, comparison helpers, iteration adapters, and view slicing utilities.