Arrays

Create arrays using square brackets with comma-separated values.

# Basic array literal
let numbers = [1, 2, 3, 4, 5];
let names = ["Alice", "Bob", "Charlie"];
let mixed = [1, "hello", true, null];

# Empty array
let empty = [];

# Nested arrays
let matrix = [[1, 2], [3, 4], [5, 6]];

Optionally specify array types for clarity and type safety.

# Typed arrays
let scores: Int[] = [95, 87, 92, 88, 90];
let names: String[] = ["Alice", "Bob", "Charlie"];
let flags: Bool[] = [true, false, true];

# Multi-dimensional arrays
let matrix: Int[][] = [[1, 2], [3, 4], [5, 6]];

Creates an array of numbers from start to end (exclusive).

range(0, 5)        # [0, 1, 2, 3, 4]
range(1, 10)       # [1, 2, 3, 4, 5, 6, 7, 8, 9]
range(0, 10, 2)    # [0, 2, 4, 6, 8] (step of 2)
range(5, 0, -1)    # [5, 4, 3, 2, 1] (reverse)

Access elements using zero-based indexing. Negative indices count from the end.

let arr = [10, 20, 30, 40, 50];

# Zero-based indexing
print(arr[0]);    # 10 (first element)
print(arr[2]);    # 30 (third element)

# Negative indexing
print(arr[-1]);   # 50 (last element)
print(arr[-2]);   # 40 (second to last)

# Out of bounds returns null
print(arr[10]);   # null

Arrays are mutable - you can modify elements by index.

let arr = [1, 2, 3, 4, 5];

# Modify existing element
arr[0] = 100;
print(arr);  # [100, 2, 3, 4, 5]

# Add new element (extends array)
arr[10] = 999;
print(arr);  # [100, 2, 3, 4, 5, null, null, null, null, null, 999]

Transform each element using a function. Returns a new array.

let numbers = [1, 2, 3, 4, 5];

# Double each number
let doubled = numbers.map(def(x) x * 2);
print(doubled);  # [2, 4, 6, 8, 10]

# Convert to strings
let strings = numbers.map(def(x) str(x));
print(strings);  # ["1", "2", "3", "4", "5"]

Keep elements matching a condition. Returns a new array.

let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

# Keep only even numbers
let evens = numbers.filter(def(x) x % 2 == 0);
print(evens);  # [2, 4, 6, 8, 10]

# Keep numbers greater than 5
let large = numbers.filter(def(x) x > 5);
print(large);  # [6, 7, 8, 9, 10]

Accumulate array elements to a single value.

let numbers = [1, 2, 3, 4, 5];

# Sum all numbers
let sum = numbers.reduce(def(acc, x) acc + x, 0);
print(sum);  # 15

# Product of all numbers
let product = numbers.reduce(def(acc, x) acc * x, 1);
print(product);  # 120

# Find maximum
let max = numbers.reduce(def(acc, x) if (x > acc) x else acc, numbers[0]);
print(max);  # 5

Iterate over elements for side effects. Returns the original array.

let numbers = [1, 2, 3];

# Print each number
numbers.each(def(x) print(x));
# Output: 1
#         2
#         3

# Modify external state
let sum = 0;
numbers.each(def(x) sum = sum + x);
print(sum);  # 6

Search and check array elements.

let numbers = [1, 2, 3, 4, 5];

# find - returns first matching element
let first_even = numbers.find(def(x) x % 2 == 0);
print(first_even);  # 2

# any? - returns true if any element matches
let has_large = numbers.any?(def(x) x > 4);
print(has_large);  # true

# all? - returns true if all elements match
let all_positive = numbers.all?(def(x) x > 0);
print(all_positive);  # true

Sort elements. Default is ascending order, or provide a custom comparator.

let numbers = [3, 1, 4, 1, 5, 9, 2, 6];

# Default sort (ascending)
let sorted = numbers.sort();
print(sorted);  # [1, 1, 2, 3, 4, 5, 6, 9]

# Custom comparator (descending)
let desc = numbers.sort(def(a, b) b - a);
print(desc);  # [9, 6, 5, 4, 3, 2, 1, 1]

# Sort by string length
let words = ["cherry", "pie", "apple"];
let by_length = words.sort(def(a, b) len(a) - len(b));
print(by_length);  # ["pie", "apple", "cherry"]

Sort an array of hashes by a key, or use a function to extract the sort value from each element.

let people = [
  { "name": "Charlie", "age": 30 },
  { "name": "Alice", "age": 25 },
  { "name": "Bob", "age": 20 }
];

# Sort by hash key (string argument)
let by_name = people.sort_by("name");
print(by_name.map(def(p) p.get("name")));  # [Alice, Bob, Charlie]

let by_age = people.sort_by("age");
print(by_age.map(def(p) p.get("age")));  # [20, 25, 30]

# Sort by function (for computed values)
let words = ["cherry", "pie", "apple"];
let by_length = words.sort_by(def(w) len(w));
print(by_length);  # [pie, apple, cherry]

Return a new array with elements in reverse order.

let arr = [1, 2, 3, 4, 5];
let reversed = arr.reverse();
print(reversed);  # [5, 4, 3, 2, 1]
print(arr);       # [1, 2, 3, 4, 5] (original unchanged)

Remove duplicate elements. Returns a new array with unique values.

let arr = [1, 2, 2, 3, 3, 3, 4];
let unique = arr.uniq();
print(unique);  # [1, 2, 3, 4]

Remove null values from the array.

let arr = [1, null, 2, null, 3, null];
let cleaned = arr.compact();
print(cleaned);  # [1, 2, 3]

Flatten nested arrays. Optionally specify depth.

let nested = [[1, 2], [3, 4], [5, 6]];
let flat = nested.flatten();
print(flat);  # [1, 2, 3, 4, 5, 6]

# Flatten only 1 level deep
let deep = [[1, 2], [[3, 4]]];
let partial = deep.flatten(1);
print(partial);  # [1, 2, [3, 4]]

Get the first or last element.

let arr = [10, 20, 30, 40, 50];
print(arr.first());  # 10
print(arr.last());   # 50

# Returns null for empty arrays
let empty = [];
print(empty.first());  # null
print(empty.last());   # null

Check if array is empty or contains a value.

let arr = [1, 2, 3];

print(arr.empty?());      # false
print(arr.include?(2));   # true
print(arr.include?(99));  # false

let empty = [];
print(empty.empty?());    # true

Random element selection and shuffling.

let arr = [1, 2, 3, 4, 5];

# Get random element
let random = arr.sample();
print(random);  # Random element (e.g., 3)

# Shuffle array
let shuffled = arr.shuffle();
print(shuffled);  # Randomized order (e.g., [3, 1, 5, 2, 4])

Take or skip the first n elements.

let arr = [1, 2, 3, 4, 5];

# Take first n elements
let first_three = arr.take(3);
print(first_three);  # [1, 2, 3]

# Skip first n elements
let rest = arr.drop(3);
print(rest);  # [4, 5]

Combine two arrays into pairs.

let names = ["Alice", "Bob", "Charlie"];
let scores = [95, 87, 92];

let pairs = names.zip(scores);
# [["Alice", 95], ["Bob", 87], ["Charlie", 92]]

Numeric aggregation methods.

let numbers = [10, 5, 8, 3, 12];

print(numbers.sum());   # 38.0
print(numbers.min());   # 3
print(numbers.max());   # 12

Joins array elements into a string using the specified delimiter.

let words = ["Hello", "World"];
print(words.join(" "));   # "Hello World"

let numbers = [1, 2, 3, 4, 5];
print(numbers.join("-")); # "1-2-3-4-5"

let paths = ["usr", "local", "bin"];
print(paths.join("/"));   # "usr/local/bin"

Returns a formatted string representation of the array. Called automatically in REPL.

let arr = [1, 2, 3];
# In REPL, displays: [1, 2, 3]
# Equivalent to: arr.to_string()

Returns the number of elements in the array.

let arr = [1, 2, 3];
arr.length();  # 3

Adds an element to the end or removes and returns the last element.

let arr = [];
arr.push(1);  # [1]
arr.push(2);  # [1, 2]
let last = arr.pop();  # 2, arr is now [1]

Returns the element at the specified index. Supports negative indices for backward access.

let arr = ["first", "second", "third"];
arr.get(0);      # "first"
arr.get(2);      # "third"
arr.get(-1);     # "third" (last)
arr.get(-2);     # "second"

Removes all elements from the array.

let arr = [1, 2, 3];
arr.clear();
arr.length();  # 0