Arrays

Arrays are mutable objects with one declared element type and reference semantics. All operations on this page are Controls.

array

Evaluates an element type description and returns the corresponding array type. It does not create an array. Repeated calls with the same element type identify the same array type.

declare(numbers, array(integer), array_of(1, 2, 3))

A non-type argument fails. Array types are invariant: an array(integer) is not accepted where array(optional(integer)) is required. See optional compatibility.

array_of

Evaluates one or more values from left to right and constructs an array. Its element type is the first value’s runtime type; every other value must have exactly that type. All values are evaluated before the types are compared.

declare(words, array(string), array_of("one", "two"))
print(to_string(words)) / ["one","two"]

Zero arguments and mixed runtime types fail. array_of(1, none) does not infer an optional element type. Use empty_array(optional(integer)) and push when both values and absence must be accepted.

empty_array

Evaluates an element type description and creates an empty array of that type. A non-type argument fails.

declare(answers, array(optional(integer)), empty_array(optional(integer)))
push(answers, 42)
push(answers, none)
print(to_string(answers)) / [42,null]

get_at

Evaluates the array once, then each index expression once from left to right. Indices are zero-based integers. With several indices, each selected value except the last must itself be an array.

declare(grid, array(array(integer)), array_of(array_of(1, 2), array_of(3, 4)))
print(get_at(grid, 1, 0)) / 3

A negative or out-of-bounds index, non-integer index, or non-array at a traversed position fails. Later indices are not evaluated after a failed segment. Selecting an object returns a reference to it, not a copy.

For mixed record/array paths, use chain with get_field.

set_at

Traverses indices with the same rules as get_at, then replaces the final existing element. It validates the whole destination path before evaluating the new value. The new value must be accepted by the destination array’s element type. It does not grow an array or create missing intermediate objects.

declare(grid, array(array(integer)), array_of(array_of(1, 2), array_of(3, 4)))
set_at(grid, 1, 0, 9)
print(get_at(grid, 1, 0)) / 9

The array and indices are evaluated once, from left to right. If the path is invalid, the value expression is skipped. If the path is valid but the value’s type is wrong, its expression has already run when the type error occurs. Mutation is visible through every reference to the destination object.

push

Evaluates the array, then the new value, and appends one element. The array must be an array object, and the value must be accepted by its element type. Produces no value.

declare(numbers, array(integer), empty_array(integer))
push(numbers, 7)
print(array_length(numbers)) / 1

array_length

Evaluates an array and returns its current element count as an integer. A non-array fails; a length exceeding the integer range also fails.

print(array_length(array_of(2, 4, 6))) / 3

remove_at

Evaluates the array, then one index, removes that element, and returns it. Later elements shift down by one index. Negative, non-integer, or out-of-bounds indices fail, as does a non-array input. Unlike get_at and set_at, this operation accepts only one index.

declare(numbers, array(integer), array_of(10, 20, 30))
print(remove_at(numbers, 1)) / 20
print(to_string(numbers)) / [10,30]

To iterate over an array, see for_each.