Skip to content

Array Functions

Array manipulation, transformation, filtering, and aggregation functions. Most are instance methods called on array values.

Array Creation

$Array

Creates an array from values.

Signature: $Array(value1, value2, ...)

Examples:

arr = $Array(1, 2, 3, 4, 5);
mixed = $Array("a", 1, true, null);
empty = $Array();

Filtering & Finding

.Filter(predicate)

Filters array elements matching predicate.

Signature: array.Filter(element => condition)

Examples:

numbers = [1, 2, 3, 4, 5, 6];
evens = numbers.Filter((x) => x % 2 == 0); // [2, 4, 6]

customers = getCustomers();
active = customers.Filter((c) => c.isActive);

.Find(predicate)

Returns first element matching predicate.

Signature: array.Find(element => condition)

Examples:

numbers = [1, 2, 3, 4, 5];
firstEven = numbers.Find((x) => x % 2 == 0); // 2

customers = getCustomers();
alice = customers.Find((c) => c.name == "Alice");

.Any(predicate)

Checks if any element matches.

Signature: array.Any(element => condition)

Returns: (boolean)

Examples:

numbers = [1, 2, 3, 4, 5];
hasEvens = numbers.Any((x) => x % 2 == 0); // true
hasNegatives = numbers.Any((x) => x < 0); // false

.All(predicate)

Checks if all elements match.

Signature: array.All(element => condition)

Returns: (boolean)

Examples:

numbers = [2, 4, 6, 8];
allEven = numbers.All((x) => x % 2 == 0); // true

allPositive = numbers.All((x) => x > 0); // true

Transformation

.Map(transform)

Transforms each element.

Signature:

array.Map((element) => newValue);
array.Map((element, index) => newValue);

Examples:

numbers = [1, 2, 3, 4, 5];
doubled = numbers.Map((x) => x * 2); // [2, 4, 6, 8, 10]

customers = getCustomers();
names = customers.Map((c) => c.name);

withIndex = numbers.Map((x, i) => x + i); // [1, 3, 5, 7, 9]

Reduction

.ReduceToNum(fn, initial)

Reduces array to single number.

Signature:

array.ReduceToNum((accumulator, element) => result, initialValue);
array.ReduceToNum((accumulator, element, index) => result, initialValue);

Examples:

numbers = [1, 2, 3, 4, 5];
sum = numbers.ReduceToNum((acc, x) => acc + x, 0); // 15
product = numbers.ReduceToNum((acc, x) => acc * x, 1); // 120

max = numbers.ReduceToNum((acc, x) => (x > acc ? x : acc), 0); // 5

.Reduce(fn, initial)

Reduces array to single string value.

Signature: array.Reduce((accumulator, element) => result, initialValue)

Examples:

words = ["hello", "world"];
sentence = words.Reduce((acc, w) => acc + " " + w, "");

numbers = [1, 2, 3];
csv = numbers.Reduce((acc, n) => acc + "," + $ToString(n), "");

.ReduceToArr(fn, initial)

Reduces to array.

Signature: array.ReduceToArr((accumulator, element) => result, initialValue)

Examples:

numbers = [1, 2, 3];
doubled = numbers.ReduceToArr((acc, x) => {
  acc.Push(x * 2);
  return acc;
}, []);

Sorting

.OrderBy(selector)

Sorts ascending by selector.

Signature: array.OrderBy(element => sortValue)

Examples:

numbers = [5, 2, 8, 1, 9];
sorted = numbers.OrderBy((x) => x); // [1, 2, 5, 8, 9]

customers = getCustomers();
byAge = customers.OrderBy((c) => c.age);
byName = customers.OrderBy((c) => c.name);

.OrderByDescending(selector)

Sorts descending by selector.

Signature: array.OrderByDescending(element => sortValue)

Examples:

numbers = [5, 2, 8, 1, 9];
sorted = numbers.OrderByDescending((x) => x); // [9, 8, 5, 2, 1]

byPremium = customers.OrderByDescending((c) => c.premium);

Slicing & Pagination

.Take(count)

Takes first N elements.

Signature: array.Take(count)

Examples:

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
first3 = numbers.Take(3); // [1, 2, 3]

top5 = customers.OrderByDescending((c) => c.premium).Take(5);

.Skip(count)

Skips first N elements.

Signature: array.Skip(count)

Examples:

numbers = [1, 2, 3, 4, 5];
rest = numbers.Skip(2); // [3, 4, 5]

page2 = items.Skip(10).Take(10); // Pagination

.Slice(start, end)

Extracts slice from start to end index.

Signature: array.Slice(startIndex, endIndex)

Examples:

numbers = [1, 2, 3, 4, 5];
middle = numbers.Slice(1, 4); // [2, 3, 4]

Adding Elements

.Push(value)

Adds element to end.

Signature: array.Push(value)

Examples:

items = [1, 2, 3];
items.Push(4); // [1, 2, 3, 4]

items.Push(5);
items.Push(6); // [1, 2, 3, 4, 5, 6]

.Insert(index, value)

Inserts element at index.

Signature: array.Insert(index, value)

Examples:

items = [1, 2, 4, 5];
items.Insert(2, 3); // [1, 2, 3, 4, 5]

.AddRange(otherArray)

Adds all elements from another array.

Signature: array.AddRange(otherArray)

Returns: New array with combined elements

Examples:

arr1 = [1, 2, 3];
arr2 = [4, 5, 6];
combined = arr1.AddRange(arr2); // [1, 2, 3, 4, 5, 6]

Removing Elements

.Remove(value)

Removes first occurrence of value.

Signature: array.Remove(value)

Examples:

items = [1, 2, 3, 2, 4];
items.Remove(2); // [1, 3, 2, 4]

.RemoveAt(index)

Removes element at index.

Signature: array.RemoveAt(index)

Examples:

items = [1, 2, 3, 4, 5];
items.RemoveAt(2); // [1, 2, 4, 5]

.Clear()

Removes all elements.

Signature: array.Clear()

Examples:

items = [1, 2, 3, 4, 5];
items.Clear(); // []

Distinct & Unique

.Distinct()

Returns unique elements.

Signature: array.Distinct()

Examples:

numbers = [1, 2, 2, 3, 3, 3, 4, 5, 5];
unique = numbers.Distinct(); // [1, 2, 3, 4, 5]

ids = customers.Map((c) => c.departmentId).Distinct();

Iteration

.ForEach(action)

Executes action for each element.

Signature:

array.ForEach((element) => action);
array.ForEach((element, index) => action);

Examples:

names = ["Alice", "Bob", "Charlie"];
names.ForEach((name) => $Log(name));

names.ForEach((name, i) => {
  $Log($ToString(i) + ": " + name);
});

Searching

.IndexOf(value)

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

Signature: array.IndexOf(value)

Examples:

items = ["a", "b", "c", "d"];
index = items.IndexOf("c"); // 2
notFound = items.IndexOf("z"); // -1

Reversal

.Reverse()

Reverses array order.

Signature: array.Reverse()

Examples:

numbers = [1, 2, 3, 4, 5];
reversed = numbers.Reverse(); // [5, 4, 3, 2, 1]

Joining

.Join(separator)

Joins elements into string.

Signature: array.Join(separator)

Examples:

words = ["hello", "world"];
sentence = words.Join(" "); // "hello world"

numbers = [1, 2, 3];
csv = numbers.Join(","); // "1,2,3"

Property Access

.Length

Number of elements in array.

Signature: array.Length

Examples:

items = [1, 2, 3, 4, 5];
count = items.Length; // 5

isEmpty = items.Length == 0;

Common Patterns

Sum

numbers = [1, 2, 3, 4, 5];
sum = numbers.ReduceToNum((acc, x) => acc + x, 0);
// Or: sum = $Sum(numbers);

Average

numbers = [10, 20, 30, 40, 50];
sum = $Sum(numbers);
average = sum / numbers.Length;

Max/Min

numbers = [5, 2, 8, 1, 9];
max = numbers.ReduceToNum((acc, x) => (x > acc ? x : acc), numbers[0]);
min = numbers.ReduceToNum((acc, x) => (x < acc ? x : acc), numbers[0]);

Count Matching

numbers = [1, 2, 3, 4, 5, 6];
evenCount = numbers.Filter((x) => x % 2 == 0).Length;

Flatten Nested Arrays

nested = [
  [1, 2],
  [3, 4],
  [5, 6],
];
flat = nested.ReduceToArr((acc, arr) => acc.AddRange(arr), []);

Grouping

items = getItems();
low = items.Filter((x) => x.value < 10);
medium = items.Filter((x) => x.value >= 10 && x.value < 100);
high = items.Filter((x) => x.value >= 100);

Pagination

page = 2;
pageSize = 10;
pageData = allItems.Skip(page * pageSize).Take(pageSize);

Best Practices

  1. Chain operations for readability
  2. Use .Any() instead of .Length > 0 for existence checks
  3. Prefer native functions over manual loops
  4. Extract complex lambdas to named functions
  5. Check .Length before accessing elements

Next Steps