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.