Array operations
Operations for creating and manipulating arrays.
Overview
Arrays are created by a literal; there is no creation instruction. The operations below act on one once it exists.
| Instruction | Signature | Description |
|---|---|---|
len |
(arr -- n) |
Number of elements; a string's characters |
nth |
(arr i -- elem) |
Element at index i; a string's character, as its codepoint |
set |
(arr i x --) |
Store x at index i |
append |
(arr x -- arr) |
Append x |
clone |
(arr -- arr2) |
A shallow copy |
free |
(p --) |
Release one reference to an array or struct |
Array access
len
Returns the number of elements in an array, or of characters in a string.
Signature: (arr -- n)
arr len // number of elements
"héllo" len // 5
nth
Returns the element at index i; in a string, the character there, as its codepoint.
Signature: (arr i -- elem)
arr 0 nth // first element
"abc" 1 nth // 98
set
Stores a value at the given index.
Signature: (arr i x --)
arr 0 42 set
Modification
append
Appends a value to the array, returning the modified array.
Signature: (arr x -- arr)
arr 42 append -> arr
free
Releases one reference to an array or struct. The memory is freed when that was the last reference; if another local, field or array still holds the value, it stays alive.
Signature: (p --)
arr free
Creating arrays
Every array comes from a […] literal. Whether the brackets hold elements or a size
is decided by what follows the ]: a type name immediately after it, with no whitespace,
makes the brackets a size.
Elements
[1 2 3 4 5] -> arr
["a" "b" "c"] -> strings
[1.0 2.0 3.0] -> floats
[] -> empty // element type decided by the first append
A size and an element type
[n]T creates n elements, each the zero value of T.
[10]i64 -> ints // ten 0
[10]f64 -> floats // ten 0.0
[10]str -> strings // ten ""
[10]ptr -> ptrs // ten null
[]i64 -> empty // the size left out, so none of them -- an empty []i64
The size may be any expression leaving one i64:
[src len]i64 -> dst
[n 2 *]i64 -> twice
T |
zero value |
|---|---|
i64, i32, i16, i8, u64, u32, u16, u8, bool |
0 |
f64 |
0.0 |
d128 |
0 |
str |
"" — an empty string, not null |
ptr |
null |
| a struct | a distinct T {} per element — see below |
Arrays of structs
[n]T for a struct holds n distinct instances, each built as T {}. It is allowed
exactly where T {} is: every field needs a default.
struct Point { x:f64 = 0.0 y:f64 = 0.0 }
[3]Point -> ps
ps 0 nth <<x print nl // 0 -- a real Point, not a null slot
ps 0 nth 9.0 >>x drop // writing one leaves the others alone
A struct whose fields have no defaults has no zero, so [n]T reports the field that is
missing one. Build those with []T and append instead.
!!! note "[n]T is an expression, not a type"
Arrays are dynamic, and `[]T` is the only array type there is. `[10]i64` and `[]i64`
both produce a value of type `[]i64`, differing only in starting length, so a size
never appears in a signature or a field declaration.