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();

$AddToArray

Adds a value to the end of an array and returns the array.

Signature: $AddToArray(array, value)

Examples:

table = $Array();
table = $AddToArray(table, { "PolicyType": "Single", "Commission": 0.25 });
table = $AddToArray(table, { "PolicyType": "Multi", "Commission": 0.18 });

Global Array Functions

Standalone alternatives to some instance methods. The optional property argument works on arrays of objects.

$Length

Returns the number of elements in an array (or characters in a string).

Signature: $Length(array)

count = $Length([1, 2, 3]); // 3

$Sort

Sorts ascending, by the values themselves or by an object property.

Signature: $Sort(array) or $Sort(array, property)

sorted = $Sort([2, 3, 4, 1]); // [1, 2, 3, 4]
byValue = $Sort(items, "Value");

$Reverse

Reverses the order of the elements.

Signature: $Reverse(array)

reversed = $Reverse([1, 2, 3]); // [3, 2, 1]

$Map

Extracts a property from each object.

Signature: $Map(array, property)

values = $Map(items, "Value"); // [1, 2, 3, ...]

Filtering & Finding

.Filter(predicate)

Filters array elements matching predicate.

Signature: array.Filter(element => condition)

.Where() is an alias.

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

There is no .All() method. Negate .Any() with the inverted condition instead:

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

Transformation

.Map(transform)

Transforms each element.

Signature:

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

.Select() is an alias.

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

The reduce methods take a single lambda. The accumulator always starts at a fixed value that depends on the method; there is no initial-value argument. The lambda may also take the element index as a third parameter.

.ReduceToNum(fn)

Reduces array to a single number. The accumulator starts at 0.

Signature:

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

Examples:

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

// Use the index to start from the first element
product = numbers.ReduceToNum((acc, x, i) => (i == 0 ? x : acc * x)); // 120
max = numbers.ReduceToNum((acc, x, i) => (i == 0 || x > acc ? x : acc)); // 5

.ReduceToStr(fn)

Reduces array to a single string. The accumulator starts at "".

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

Examples:

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

numbers = [1, 2, 3];
csv = numbers.ReduceToStr((acc, n, i) => acc + (i == 0 ? "" : ",") + n); // "1,2,3"

.ReduceToObj(fn)

Reduces array to a single object. The accumulator starts at {}.

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

Examples:

options = ["Gold##G", "Silver##S"];
lookup = options.ReduceToObj((acc, x) => acc.AddProperty(x.GetOptionName(), x.GetOptionValue()));
// { Gold: "G", Silver: "S" }

There is no .ReduceToArr(). To build an array, push into a new array with .ForEach(), or use .Map():

doubled = numbers.Map((x) => x * 2);

flat = [];
nested.ForEach((arr) => flat.AddRange(arr));

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);

.Slice(start, end)

Extracts slice from start index up to (not including) end index. Without end, returns everything from start (skips the first start elements).

Signature: array.Slice(startIndex) or array.Slice(startIndex, endIndex)

Examples:

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

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

Adding Elements

.Push(value)

Adds element to end.

Signature: array.Push(value)

.Add() is an alias.

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(i.ToString() + ": " + 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);
// 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, i) => (i == 0 || x > acc ? x : acc));
min = numbers.ReduceToNum((acc, x, i) => (i == 0 || x < acc ? x : acc));

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.ForEach((arr) => flat.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.Slice(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