Arrays

Arrays in Chuks are ordered, dynamic collections of elements of the same type (or any). Their size can change at runtime, and they come with a rich set of built-in methods — no imports needed.

Declaration and Initialization

// Empty array of integers
var numbers: []int = [];

// Array initialized with values
var colors: []string = ["red", "green", "blue"];

// Array of any type
var mixed: []any = [1, "two", true];

Multi-Dimensional Arrays

Chuks supports multi-dimensional arrays (arrays of arrays) using nested [] type syntax. This is useful for matrices, grids, game boards, tabular data, and any scenario requiring rows and columns.

Declaration

Use [][]T for a 2D array, [][][]T for 3D, and so on.

// 2D array of integers (a matrix)
var matrix: [][]int = [[1, 2, 3], [4, 5, 6]]

// 2D array of strings (a grid)
var grid: [][]string = [["a", "b"], ["c", "d"]]

// Untyped — inferred as []any of []any
var board = [["X", "O", "X"], ["O", "X", "O"], ["X", "O", "X"]]

Accessing Elements

Chain index expressions to access nested elements — array[row][col].

var matrix: [][]int = [[1, 2, 3], [4, 5, 6]]

println(matrix[0][0])  // 1  — first row, first col
println(matrix[1][2])  // 6  — second row, third col

Modifying Elements

Assign to nested indices to update individual cells.

var grid: [][]string = [["a", "b"], ["c", "d"]]
grid[1][0] = "z"
println(grid[1][0])  // z

Building Dynamically

Build a multi-dimensional array programmatically using nested loops and push().

// Create a 100×100 matrix
var matrix: any = []
for (var i: int = 0; i < 100; i++) {
    var row: []int = []
    for (var j: int = 0; j < 100; j++) {
        row.push(i * 100 + j)
    }
    matrix.push(row)
}

println(matrix[0][0])    // 0
println(matrix[99][99])  // 9999
println(matrix[50][25])  // 5025

Iterating

Use nested for loops to traverse rows and columns.

var matrix: [][]int = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

// Sum of all elements
var total: int = 0
for (var i: int = 0; i < length(matrix); i++) {
    for (var j: int = 0; j < length(matrix[i]); j++) {
        total = total + matrix[i][j]
    }
}
println(total)  // 45

// Diagonal sum (square matrix)
var diag: int = 0
for (var i: int = 0; i < length(matrix); i++) {
    diag = diag + matrix[i][i]
}
println(diag)  // 15  (1 + 5 + 9)

Matrix Multiplication

A practical example — standard O(n³) matrix multiply:

function matmul(a: any, b: any, n: int): any {
    var c: any = []
    for (var i: int = 0; i < n; i++) {
        var row: []int = []
        for (var j: int = 0; j < n; j++) {
            row.push(0)
        }
        c.push(row)
    }

    for (var i: int = 0; i < n; i++) {
        for (var k: int = 0; k < n; k++) {
            var aik: int = a[i][k]
            for (var j: int = 0; j < n; j++) {
                c[i][j] = c[i][j] + aik * b[k][j]
            }
        }
    }
    return c
}

Flattening

Use the .flat() method to collapse a 2D array into a 1D array.

var nested: any = [[1, 2], [3, 4], [5, 6]]
var flat: any = nested.flat()
println(flat)  // [1, 2, 3, 4, 5, 6]

Accessing Elements

Elements are accessed using zero-based indexing.

var firstColor = colors[0]; // "red"
colors[1] = "yellow";       // Update element at index 1

Slicing

Chuks supports Go-style slice expressions using [start:end] syntax to extract sub-arrays and substrings. The start index is inclusive and the end index is exclusive.

var nums = [10, 20, 30, 40, 50];

// Basic slice: elements from index 1 up to (not including) 3
var middle = nums[1:3];   // [20, 30]

// Omit start: from beginning
var first2 = nums[:2];    // [10, 20]

// Omit end: to the end
var last2 = nums[3:];     // [40, 50]

Slicing also works on strings:

var greeting = "Hello, World!";
var hello = greeting[:5];     // "Hello"
var world = greeting[7:12];   // "World"

Slicing always returns a new array or string — the original is not modified.

Properties

length: int

Returns the number of elements in the array. This is a property, not a method — access it without parentheses.

var nums = [1, 2, 3];
println(nums.length); // 3

Mutating Methods

These methods modify the original array.

push(...items: T): int

Adds one or more elements to the end and returns the new length.

var nums = [1, 2];
nums.push(3);
println(nums); // [1, 2, 3]

pop(): T | null

Removes and returns the last element. Returns null if empty.

var nums = [1, 2, 3];
var last: any = nums.pop();
println(last); // 3
println(nums); // [1, 2]

shift(): T | null

Removes and returns the first element. Returns null if empty.

var nums = [1, 2, 3];
var first: any = nums.shift();
println(first); // 1
println(nums);  // [2, 3]

unshift(...items: T): int

Adds one or more elements to the beginning and returns the new length.

var nums = [2, 3];
nums.unshift(0, 1);
println(nums); // [0, 1, 2, 3]

splice(start: int, deleteCount?: int, ...items: T): []T

Removes or replaces elements in place. Returns the removed elements.

var nums = [1, 2, 3, 4, 5];
var removed: any = nums.splice(1, 2);
println(removed); // [2, 3]
println(nums);    // [1, 4, 5]

// Insert elements
nums.splice(1, 0, 10, 20);
println(nums); // [1, 10, 20, 4, 5]

reverse(): []T

Reverses the array in place and returns it.

var nums = [1, 2, 3];
nums.reverse();
println(nums); // [3, 2, 1]

sort(compareFn?: function): []T

Sorts elements in place using natural ordering. An optional comparison function can be provided.

var nums = [3, 1, 2];
nums.sort();
println(nums); // [1, 2, 3]

var words = ["banana", "apple", "cherry"];
words.sort();
println(words); // ["apple", "banana", "cherry"]

append(...items: T): []T

Adds elements to the end and returns the modified array. Useful for chaining.

var nums = [1, 2];
nums.append(3).append(4);
println(nums); // [1, 2, 3, 4]

clear(): void

Removes all elements from the array.

var nums = [1, 2, 3];
nums.clear();
println(nums.length); // 0

Non-Mutating Methods

These methods return a new value without modifying the original array.

at(index: int): T

Returns the element at the given index. Supports negative indexing.

var nums = [10, 20, 30];
println(nums.at(0));   // 10
println(nums.at(-1));  // 30

indexOf(value: T, from?: int): int

Returns the first index of the given element, or -1.

var nums = [10, 20, 30, 20];
println(nums.indexOf(20)); // 1
println(nums.indexOf(99)); // -1

lastIndexOf(value: T, from?: int): int

Returns the last index of the given element, or -1.

var nums = [10, 20, 30, 20];
println(nums.lastIndexOf(20)); // 3

includes(value: T, from?: int): bool

Returns true if the array contains the given element.

var nums = [1, 2, 3];
println(nums.includes(2)); // true
println(nums.includes(5)); // false

join(separator?: string): string

Joins all elements into a string separated by the given separator (default ",").

var words = ["Hello", "World"];
println(words.join(" ")); // "Hello World"
println(words.join("-")); // "Hello-World"

toReversed(): []T

Returns a new array with elements in reversed order without modifying the original.

var nums = [1, 2, 3];
var reversed: any = nums.toReversed();
println(reversed); // [3, 2, 1]
println(nums);     // [1, 2, 3] (unchanged)

toSorted(compareFn?: function): []T

Returns a new sorted array without modifying the original.

var nums = [3, 1, 2];
var sorted: any = nums.toSorted();
println(sorted); // [1, 2, 3]
println(nums);   // [3, 1, 2] (unchanged)

toSpliced(start: int, deleteCount?: int, ...items: T): []T

Returns a new array with elements removed/replaced/added without modifying the original.

var nums = [1, 2, 3, 4, 5];
var newArr: any = nums.toSpliced(1, 2, 10, 20);
println(newArr); // [1, 10, 20, 4, 5]
println(nums);   // [1, 2, 3, 4, 5] (unchanged)

flat(depth?: int): []T

Flattens sub-array elements into a new array, up to the given depth (default 1).

var nested: any = [1, [2, [3, [4]]]];
println(nested.flat());  // [1, 2, [3, [4]]]
println(nested.flat(2)); // [1, 2, 3, [4]]

Callback Methods

These methods accept a callback function as an argument.

forEach(callback: function): void

Executes a callback for each element. Callback receives (element, index, array).

var nums = [1, 2, 3];
nums.forEach(function(val: any, idx: any, arr: any): any {
    println(idx, ":", val);
});
// 0 : 1
// 1 : 2
// 2 : 3

map(callback: function): []any

Creates a new array with the results of calling the callback on every element.

var nums = [1, 2, 3];
var doubled: any = nums.map(function(val: any, idx: any, arr: any): any {
    return val * 2;
});
println(doubled); // [2, 4, 6]

filter(callback: function): []T

Creates a new array with elements that pass the test in the callback.

var nums = [1, 2, 3, 4, 5];
var evens: any = nums.filter(function(val: any, idx: any, arr: any): any {
    return val % 2 == 0;
});
println(evens); // [2, 4]

reduce(callback: function, initial?: any): any

Reduces the array to a single value. Callback receives (accumulator, element, index, array).

var nums = [1, 2, 3, 4];
var sum: any = nums.reduce(function(acc: any, val: any, idx: any, arr: any): any {
    return acc + val;
}, 0);
println(sum); // 10

find(callback: function): T | null

Returns the first element that satisfies the callback, or null.

var nums = [1, 2, 3, 4, 5];
var found: any = nums.find(function(val: any, idx: any, arr: any): any {
    return val > 3;
});
println(found); // 4

findIndex(callback: function): int

Returns the index of the first element that satisfies the callback, or -1.

var nums = [10, 20, 30];
var idx: any = nums.findIndex(function(val: any, idx: any, arr: any): any {
    return val > 15;
});
println(idx); // 1

findLast(callback: function): T | null

Returns the last element that satisfies the callback, or null.

var nums = [1, 2, 3, 4, 5];
var found: any = nums.findLast(function(val: any, idx: any, arr: any): any {
    return val < 4;
});
println(found); // 3

findLastIndex(callback: function): int

Returns the index of the last element that satisfies the callback, or -1.

var nums = [1, 2, 3, 4, 5];
var idx: any = nums.findLastIndex(function(val: any, idx: any, arr: any): any {
    return val < 4;
});
println(idx); // 2

flatMap(callback: function): []any

Maps each element using the callback and flattens the result by one level.

var nums = [1, 2, 3];
var result: any = nums.flatMap(function(val: any, idx: any, arr: any): any {
    return [val, val * 2];
});
println(result); // [1, 2, 2, 4, 3, 6]

some(callback: function): bool

Returns true if at least one element satisfies the callback.

var nums = [1, 2, 3, 4, 5];
var hasEven: any = nums.some(function(val: any, idx: any, arr: any): any {
    return val % 2 == 0;
});
println(hasEven); // true

Returns false for an empty array.

every(callback: function): bool

Returns true if all elements satisfy the callback.

var nums = [2, 4, 6, 8];
var allEven: any = nums.every(function(val: any, idx: any, arr: any): any {
    return val % 2 == 0;
});
println(allEven); // true

Returns true for an empty array (vacuous truth).

copy(source: []T): int

Copies elements from a source array into the destination. Returns the number of elements copied (minimum of both lengths).

var src = [1, 2, 3];
var dst = [0, 0];
var count = dst.copy(src);
println(count); // 2
println(dst);   // [1, 2]

Standalone copy() builtin

You can also use the standalone copy() function to create a shallow clone of an array:

var original = [1, 2, 3];
var cloned = copy(original);
cloned.push(4);
println(original); // [1, 2, 3] — unchanged
println(cloned);   // [1, 2, 3, 4]

This works for both arrays and maps.