@arrays

The @arrays module provides functions for manipulating and working with arrays.

Import

import @arrays

Adding and Removing Elements

`append()`

(arr [type], value type) -> void

Adds an element to the end of an array.

import @std, @arrays

do append_to_array(){
    temp arr [int] = {1, 2, 3}
    arrays.append(arr, 4)
    std.println(arr)  // {1, 2, 3, 4}
}

Parameters: arr - The array, value - Element to add.

Returns: Nothing (mutates array in place).

`pop()`

(arr [type]) -> type

Removes and returns the last element of an array.

import @std, @arrays

do pop_from_array(){
    temp arr [int] = {1, 2, 3}
    temp last int = arrays.pop(arr)
    std.println(last)  // 3
    std.println(arr)   // {1, 2}
}

Parameters: arr - The array.

Returns: The removed element.

Errors: E9001 if the array is empty.

`shift()`

(arr [type]) -> type

Removes and returns the first element of an array.

import @std, @arrays

do main(){
    temp arr [int] = {1, 2, 3}
    temp first int = arrays.shift(arr)
    std.println(first)  // 1
    std.println(arr)    // {2, 3}
}

Parameters: arr - The array.

Returns: The removed element.

Errors: E9001 if the array is empty.

`unshift()`

(arr [type], value type) -> void

Adds an element to the beginning of an array.

import @std, @arrays

do main(){
    temp arr [int] = {2, 3, 4}
    arrays.unshift(arr, 1)
    std.println(arr)  // {1, 2, 3, 4}
}

Parameters: arr - The array, value - Element to add.

Returns: Nothing (mutates array in place).

`insert()`

(arr [type], index int, value type) -> void

Inserts an element at a specific index.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 4}
    arrays.insert(arr, 2, 3)  // insert 3 at index 2
    std.println(arr)  // {1, 2, 3, 4}
}

Parameters: arr, index, value.

Returns: Nothing (mutates array in place).

Errors: E5003 if the index is out of bounds.

`remove_at()`

(arr [type], index int) -> void

Removes the element at a specific index.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4}
    arrays.remove_at(arr, 1)
    std.println(arr)  // {1, 3, 4}
}

Parameters: arr, index.

Returns: Nothing (mutates array in place).

Errors: E5003 if the index is out of bounds.

`remove_all()`

(arr [type], value type) -> void

Removes all occurrences of a value from an array (in place).

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 2, 4, 2}
    arrays.remove_all(arr, 2)
    std.println(arr)  // {1, 3, 4}
}

Parameters: arr - The array, value - The value to remove.

Returns: Nothing (mutates array in place).

`clear()`

(arr [type]) -> void

Removes all elements from an array (in place).

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3}
    arrays.clear(arr)
    std.println(arr)  // {}
}

Parameters: arr - The array.

Returns: Nothing (mutates array in place).

`fill()`

(arr [type], value type) -> void

Fills all elements of an array with a value (in place).

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    arrays.fill(arr, 0)
    std.println(arr)  // {0, 0, 0, 0, 0}
}

Parameters: arr - The array, value - The value to fill with.

Returns: Nothing (mutates array in place).

Accessing Elements

`get()`

(arr [type], index int) -> type

Returns the element at a specific index.

import @std, @arrays

do main() {
    temp arr [int] = {10, 20, 30}
    temp val int = arrays.get(arr, 1)
    std.println(val)  // 20
}

Parameters: arr, index.

Returns: The element at the index.

Errors: E5003 if the index is out of bounds.

`set()`

(arr [type], index int, value type) -> void

Sets the element at a specific index.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3}
    arrays.set(arr, 1, 20)
    std.println(arr)  // {1, 20, 3}
}

Parameters: arr, index, value.

Returns: Nothing (mutates array in place).

Errors: E5003 if the index is out of bounds.

`first()` / `last()`

(arr [type]) -> type

Returns the first or last element of an array.

import @std, @arrays

do main() {
    temp arr [int] = {10, 20, 30}
    std.println(arrays.first(arr))  // 10
    std.println(arrays.last(arr))   // 30
}

Parameters: arr - The array.

Returns: The first or last element.

`is_empty()`

(arr [type]) -> bool

Checks if an array is empty.

import @std, @arrays

do main() {
    temp arr [int] = {}
    std.println(arrays.is_empty(arr))  // true
    arrays.append(arr, 1)
    std.println(arrays.is_empty(arr))  // false
}

Parameters: arr - The array.

Returns: bool - true if the array has no elements.

`remove_value()`

(arr [type], value type) -> void

Removes the first occurrence of a value from an array (in place).

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 2, 4}
    arrays.remove_value(arr, 2)
    std.println(arr)  // {1, 3, 2, 4}
}

Parameters: arr - The array, value - The value to remove.

Returns: Nothing (mutates array in place).

Searching

`contains()`

(arr [type], value type) -> bool

Checks if an array contains a value.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    std.println(arrays.contains(arr, 3))  // true
    std.println(arrays.contains(arr, 9))  // false
}

Parameters: arr, value.

Returns: bool - true if found.

`index()`

(arr [type], value type) -> int

Returns the index of the first occurrence of a value, or -1 if not found.

import @std, @arrays

do main() {
    temp arr [int] = {10, 20, 30, 20}
    std.println(arrays.index(arr, 20))  // 1
    std.println(arrays.index(arr, 99))  // -1
}

Parameters: arr, value.

Returns: int - Index or -1.

`last_index()`

(arr [type], value type) -> int

Returns the index of the last occurrence of a value, or -1 if not found.

import @std, @arrays

do main() {
    temp arr [int] = {10, 20, 30, 20}
    std.println(arrays.last_index(arr, 20))  // 3
    std.println(arrays.last_index(arr, 99))  // -1
}

Parameters: arr, value.

Returns: int - Index or -1.

`count()`

(arr [type], value type) -> int

Counts the number of occurrences of a value in an array.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 2, 4, 2}
    std.println(arrays.count(arr, 2))  // 3
    std.println(arrays.count(arr, 9))  // 0
}

Parameters: arr, value.

Returns: int - Number of occurrences.

Transforming

`reverse()`

(arr [type]) -> void

Reverses an array in place.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    arrays.reverse(arr)
    std.println(arr)  // {5, 4, 3, 2, 1}
}

Parameters: arr - The array.

Returns: Nothing (mutates array in place).

`sort()`

(arr [type]) -> void

Sorts an array in ascending order (in place).

import @std, @arrays

do main() {
    temp arr [int] = {3, 1, 4, 1, 5}
    arrays.sort(arr)
    std.println(arr)  // {1, 1, 3, 4, 5}
}

Parameters: arr - The array.

Returns: Nothing (mutates array in place).

`sort_desc()`

(arr [type]) -> void

Sorts an array in descending order (in place).

import @std, @arrays

do main() {
    temp arr [int] = {3, 1, 4, 1, 5}
    arrays.sort_desc(arr)
    std.println(arr)  // {5, 4, 3, 1, 1}
}

Parameters: arr - The array.

Returns: Nothing (mutates array in place).

`shuffle()`

(arr [type]) -> void

Randomly shuffles the elements of an array (in place).

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    arrays.shuffle(arr)
    std.println(arr)  // random order, e.g., {3, 1, 5, 2, 4}
}

Parameters: arr - The array.

Returns: Nothing (mutates array in place).

Note: random.shuffle() returns a new shuffled array without modifying the original.

`slice()`

(arr [type], start int, end int) -> [type]

Returns a portion of an array.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    temp sub [int] = arrays.slice(arr, 1, 4)
    std.println(sub)  // {2, 3, 4}
}

Parameters: arr, start, end.

Returns: A new array with the slice.

Errors: E7004 if indices are not integers.

`take()`

(arr [type], n int) -> [type]

Returns a new array with the first n elements.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    temp first3 [int] = arrays.take(arr, 3)
    std.println(first3)  // {1, 2, 3}
}

Parameters: arr, n - Number of elements to take.

Returns: A new array.

`drop()`

(arr [type], n int) -> [type]

Returns a new array with the first n elements removed.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    temp rest [int] = arrays.drop(arr, 2)
    std.println(rest)  // {3, 4, 5}
}

Parameters: arr, n - Number of elements to drop.

Returns: A new array.

`concat()`

(arr1 [type], arr2 [type]) -> [type]

Concatenates two or more arrays.

import @std, @arrays

do main() {
    temp a [int] = {1, 2}
    temp b [int] = {3, 4}
    temp c [int] = arrays.concat(a, b)
    std.println(c)  // {1, 2, 3, 4}
}

Parameters: Two or more arrays.

Returns: A new concatenated array.

Errors: E7002 if arguments are not arrays.

`repeat()`

(value type, count int) -> [type]

Creates an array with a value repeated n times.

import @std, @arrays

do main() {
    temp arr [int] = arrays.repeat(0, 5)
    std.println(arr)  // {0, 0, 0, 0, 0}
}

Parameters: value, count.

Returns: A new array.

Errors: E7004 if count is not an integer.

Numeric Arrays

`sum()`

(arr [number]) -> number

Returns the sum of all elements in a numeric array.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    std.println(arrays.sum(arr))  // 15
}

Parameters: arr - A numeric array.

Returns: The sum.

Errors: E9002 if the array is not numeric.

`product()`

(arr [number]) -> number

Returns the product of all elements in a numeric array.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 3, 4, 5}
    std.println(arrays.product(arr))  // 120
}

Parameters: arr - A numeric array.

Returns: The product.

Errors: E9002 if the array is not numeric.

`min()` / `max()`

(arr [number]) -> number

Returns the minimum or maximum value in an array.

import @std, @arrays

do main() {
    temp arr [int] = {5, 2, 8, 1, 9}
    std.println(arrays.min(arr))  // 1
    std.println(arrays.max(arr))  // 9
}

Parameters: arr - A numeric array.

Returns: The min or max value.

Errors: E9001 if the array is empty.

`avg()`

(arr [number]) -> float

Returns the average of a numeric array.

import @std, @arrays

do main() {
    temp arr [int] = {2, 4, 6, 8, 10}
    std.println(arrays.avg(arr))  // 6.0
}

Parameters: arr - A numeric array.

Returns: float - The average.

Errors: E9001 if the array is empty, E9002 if not numeric.

Utilities

`range()`

(start int, end int, step? int) -> [int]

Creates an array of integers in a range.

import @std, @arrays

do main() {
    temp arr [int] = arrays.range(0, 5)
    std.println(arr)  // {0, 1, 2, 3, 4}

    // With step
    temp odds [int] = arrays.range(1, 10, 2)
    std.println(odds)  // {1, 3, 5, 7, 9}
}

Parameters: start, end, optional step.

Returns: A new array of integers.

Errors: E9003 if step is zero.

`join()`

(arr [type], separator string) -> string

Joins array elements into a string with a separator.

import @std, @arrays

do main() {
    temp arr [string] = {"a", "b", "c"}
    std.println(arrays.join(arr, "-"))  // "a-b-c"

    temp nums [int] = {1, 2, 3}
    std.println(arrays.join(nums, ", "))  // "1, 2, 3"
}

Parameters: arr, separator.

Returns: string - The joined string.

Errors: E7003 if separator is not a string.

`zip()`

(arr1 [type], arr2 [type]) -> [[type]]

Combines two arrays into an array of pairs.

import @arrays

do main() {
    temp names [string] = {"Alice", "Bob"}
    temp ages [int] = {25, 30}
    temp pairs [[type]] = arrays.zip(names, ages)
    // {{"Alice", 25}, {"Bob", 30}}
}

Parameters: Two arrays.

Returns: [[type]] - A 2D array of pairs.

Errors: E7002 if arguments are not arrays.

`chunk()`

(arr [type], size int) -> [[type]]

Splits an array into chunks of the specified size.

import @arrays

do main() {
    temp nums [int] = {1, 2, 3, 4, 5, 6, 7}
    temp chunks [[int]] = arrays.chunk(nums, 3)
    // {{1, 2, 3}, {4, 5, 6}, {7}}
}

Parameters: arr - The array to split, size - The chunk size.

Returns: [[type]] - A 2D array of chunks.

Errors: E9004 if chunk size is not greater than zero.

`flatten()`

(arr [[type]]) -> [type]

Flattens a 2D array into a 1D array.

import @arrays

do main() {
    temp matrix [[int]] = {{1, 2}, {3, 4}, {5, 6}}
    temp flat [int] = arrays.flatten(matrix)
    // {1, 2, 3, 4, 5, 6}
}

Parameters: arr - A 2D array to flatten.

Returns: [type] - A flattened 1D array.

Errors: E7002 if argument is not a 2D array.

`unique()`

(arr [type]) -> [type]

Returns a new array with duplicate elements removed.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 2, 3, 3, 3}
    temp uniq [int] = arrays.unique(arr)
    std.println(uniq)  // {1, 2, 3}
}

Parameters: arr - The array.

Returns: A new array with unique elements.

`duplicates()`

(arr [type]) -> [type]

Returns a new array containing only elements that appear more than once.

import @std, @arrays

do main() {
    temp arr [int] = {1, 2, 2, 3, 3, 4}
    temp dups [int] = arrays.duplicates(arr)
    std.println(dups)  // {2, 3}
}

Parameters: arr - The array.

Returns: A new array of duplicate values.

`all_equal()`

(arr [type]) -> bool

Checks if all elements in an array are equal.

import @std, @arrays

do main() {
    temp same [int] = {5, 5, 5, 5}
    temp diff [int] = {5, 5, 3, 5}
    std.println(arrays.all_equal(same))  // true
    std.println(arrays.all_equal(diff))  // false
}

Parameters: arr - The array.

Returns: bool - true if all elements are equal.

`equals()`

(arr1 [type], arr2 [type]) -> bool

Checks if two arrays have the same elements in the same order.

import @std, @arrays

do main() {
    temp a [int] = {1, 2, 3}
    temp b [int] = {1, 2, 3}
    temp c [int] = {3, 2, 1}

    std.println(arrays.equals(a, b))  // true
    std.println(arrays.equals(a, c))  // false
}

Parameters:

arr1 - First array.
arr2 - Second array.

Returns: bool - true if both arrays have equal elements in the same order.

Errors: E7002 if arguments are not arrays.

Example Program

import @std
import @arrays

do main() {
    // Build a list dynamically
    temp scores [int] = {}
    arrays.append(scores, 85)
    arrays.append(scores, 92)
    arrays.append(scores, 78)
    arrays.append(scores, 95)
    arrays.append(scores, 88)

    std.println("Scores:", scores)
    std.println("Count:", len(scores))
    std.println("Sum:", arrays.sum(scores))
    std.println("Average:", arrays.avg(scores))
    std.println("Highest:", arrays.max(scores))
    std.println("Lowest:", arrays.min(scores))

    // Remove lowest score
    temp lowest_idx int = arrays.index(scores, arrays.min(scores))
    arrays.remove_at(scores, lowest_idx)

    std.println("After dropping lowest:", scores)
    std.println("New average:", arrays.avg(scores))
}

@arrays

Import

Adding and Removing Elements

append()

pop()

shift()

unshift()

insert()

remove_at()

remove_all()

clear()

fill()

Accessing Elements

get()

set()

first() / last()

is_empty()

remove_value()

Searching

contains()

index()

last_index()

count()

Transforming

reverse()

sort()

sort_desc()

shuffle()

slice()

take()

drop()

concat()

repeat()

Numeric Arrays

sum()

product()

min() / max()

avg()

Utilities

range()

join()

zip()

chunk()

flatten()

unique()

duplicates()

all_equal()

equals()

Example Program

`append()`

`pop()`

`shift()`

`unshift()`

`insert()`

`remove_at()`

`remove_all()`

`clear()`

`fill()`

`get()`

`set()`

`first()` / `last()`

`is_empty()`

`remove_value()`

`contains()`

`index()`

`last_index()`

`count()`

`reverse()`

`sort()`

`sort_desc()`

`shuffle()`

`slice()`

`take()`

`drop()`

`concat()`

`repeat()`

`sum()`

`product()`

`min()` / `max()`

`avg()`

`range()`

`join()`

`zip()`

`chunk()`

`flatten()`

`unique()`

`duplicates()`

`all_equal()`

`equals()`