Library reference
Collection functions
Signatures, results and failures for strings, arrays and tensor construction.
Use these functions to construct and transform collections. They are available without an import. T and U in the signatures stand for supported element types; they are reference notation, not generic declarations. Examples on this page are complete CPU programs.
Inputs must be values rather than pending tasks; await task results first. Numeric and Bool array operations also execute inside GPU helpers on arrays constructed there. They keep their sequential ordering and access rules; placement does not parallelize each callback or loop iteration. Arrays of Strings, records, enums or function values remain limited to CPU programs. Arrays cannot cross CPU/device entry boundaries. On the host, tensor construction creates CPU storage; use transfer to move that snapshot to a GPU.
Built-in names cannot be passed directly as callbacks. Wrap a built-in call in a named or anonymous function when an API requires a callback.
length
length(value: String | [T]) -> int
Count Unicode scalar values in a String or elements in an array. Combining marks count separately; this is not a grapheme count. Empty values have length zero. Tensors use shape instead; length does not return a tensor element count. GPU helpers support length on local numeric and Bool arrays; String queries remain CPU operations.
byteLength
byteLength(text: String) -> int
Count UTF-8 bytes, not characters or Unicode scalars. Empty text returns zero. Accepts only a completed CPU String.
slice
slice(value: String | [T], start: integer, end: integer) -> same collection kind
Return the half-open range from start through end, excluding end. Both bounds must be integer scalars and satisfy 0 <= start <= end <= length(value). String bounds count Unicode scalars. Equal bounds produce an empty value. Invalid constant bounds are diagnosed; invalid runtime bounds fail with a checked bounds fault. The result has independent outer array storage; no zero-copy view is promised. String values remain immutable. GPU helpers support slicing local numeric and Bool arrays; String and other array element kinds remain CPU operations.
concat
concat(left: [T], right: [T]) -> [T]
Join two arrays with the same element type, retaining left-to-right order. Empty arrays are allowed when their element type can be inferred. Supported array element kinds include numeric, Bool, String, records, enums and function values; nested arrays and tensors are not general array elements. The combined size is checked. This is not String concatenation; use + for Strings. GPU helpers support concatenating local numeric and Bool arrays.
map
map(input: [T], callback: fn(T) -> U) -> [U]
Call a one-argument function once per element, sequentially and in input order. The callback may be a named function, a function value or a supported closure. Its input and output must be supported array element kinds. The callback cannot return a task or an expected-error result; use parallelMap for supported fallible callbacks. An empty input calls no callbacks. Allocation and execution faults remain checked. GPU helpers support numeric/Bool input and output arrays with eligible nonrecursive callbacks and supported captures; general function-value callbacks remain CPU-only.
copy
copy(input: [T]) -> [T]
Return an independent array with the same length, element order and exact numeric bits. Supported elements are the ten numeric types, Bool and String. The array storage is fresh; String elements remain immutable values and may share their own text backing. Records, function values and nested arrays are not accepted. Empty arrays need an element type from context. Allocation and execution faults remain checked. CPU worker tasks are supported. GPU helpers can copy their local numeric and Bool arrays. String arrays require CPU programs.
sort
sort(mut input: [T]) -> [T]
Sort a numeric or Bool array in ascending order, in place, and return the same array. Existing aliases observe the writes. Ordinary array parameters and captured arrays are read-only; a function that sorts its caller's array must declare a mut parameter. A live task reader prevents sorting that storage until the task settles, and spawn sort(input) is rejected. Arrays of Strings, records, enums or function values, tensor arguments and custom comparators are not supported.
Sorting is unstable: equal elements have no guaranteed relative order. It takes O(n log n) time with constant auxiliary storage. Cancellation can leave a partially sorted input; completed writes remain visible. Checked faults and cancellation checks remain enabled. GPU helpers can also sort local numeric and Bool arrays, with cancellation checkpoints between bounded comparison/swap steps.
Integer ordering is numeric; Bool orders false before true. Floating-point ordering is deterministic and preserves exact bits: negative NaNs, negative infinity, negative finite values, negative zero, positive zero, positive finite values, positive infinity, then positive NaNs. Within a NaN sign, negative encodings are ordered by decreasing raw bits and positive encodings by increasing raw bits, including their quiet/signaling bit and payload. Sorting uses integer bit keys, without floating-point arithmetic or comparisons, and does not change the rounding mode or raise floating-point exception flags.
sorted
sorted(input: [T]) -> [T]
Return a fresh sorted array without changing the input. Accepts the same numeric and Bool element types and uses the same ordering as sort. The copy requires O(n) additional element storage; sorting that copy uses constant auxiliary storage. Ordinary read-only inputs and worker tasks are supported. Allocation failures and cancellation remain checked; a canceled operation does not modify the input. GPU helpers can also sort local numeric and Bool arrays, with cancellation checkpoints between bounded comparison/swap steps.
fn main() -> [int]:
values = [3, 1, 2]
ordered = sorted(values)
alias = values
result = sort(values)
ordered[0] = 9
[alias[0], result[2], ordered[0]]generate
generate(count: int, callback: fn(int) -> T) -> [T]
Construct a fresh array in ascending index order, without an intermediate index array. Call the callback once for each index from zero through count, excluding count. The callback may be a named function, function value or closure and must return a completed supported array element, as for sequential map. A zero count invokes no callbacks. A negative constant count is rejected; a negative runtime count produces a checked bounds fault. Byte-size overflow, allocation failures and callback execution faults remain checked. The count must be int (int64); use an explicit conversion for other integer widths. GPU helpers support numeric and Bool results with eligible nonrecursive callbacks and supported captures, executing callbacks sequentially on the device. Other element kinds and general function-value callbacks remain CPU-only.
tensor
tensor(value: numeric scalar | numeric literal | [T]) -> Tensor[T, ...]
tensor(values: [T], dimensions: fixed-length dimension list) -> Tensor[T, ...]
Construct a dense numeric tensor without changing its element type. A scalar produces rank zero; a flat array produces rank one; a rectangular nested numeric literal produces its corresponding rank. A shape argument is a list expression whose length fixes the rank at compile time, though individual extents may be runtime integer values. Extents must be nonnegative and fit the indexing range; their product must match the flat array length. An empty shape describes one rank-zero element; a zero extent describes zero elements. Ragged literals, mismatched counts and invalid sizes are rejected or produce checked shape/size faults. Construction creates host storage; it does not transfer to a GPU.
array
array(values: Tensor[T, ...]) -> [T]
Flatten a completed CPU numeric tensor in row-major logical order, preserving the element type. A rank-zero tensor becomes a one-element array; a tensor with zero elements becomes an empty array. Download a resident GPU tensor before using this operation. It does not change numeric precision.
shape
shape(values: Tensor[T, ...]) -> [int]
Return one extent per dimension of a completed CPU numeric tensor. A rank-zero tensor returns an empty array. The dimensions describe the logical shape rather than storage byte strides. Download a resident result before querying it on the host.
reshape
reshape(values: Tensor[T, ...], dimensions: fixed-length dimension list) -> Tensor[T, ...]
Change the shape of a completed CPU numeric tensor while retaining its numeric identity, element count and row-major logical order. As with tensor, the shape must be a list expression with statically known length; each extent can be a runtime integer. Negative extents, indexing-size overflow and different element counts are checked failures. No inferred -1 dimension, broadcasting or layout transpose is performed. A one-element tensor can become rank zero with an empty shape list.
Example
fn double(value: int) -> int:
value * 2
fn main() -> [int]:
values = concat(slice([1, 2, 3], 0, 2), [4])
matrix = tensor(map(values, double), [1, 3])
flat = array(reshape(matrix, [3]))
[length("سلام"), byteLength("سلام"), length(flat), shape(matrix)[1], flat[2]]