Skip to main content

Arrays

The Arrays category holds functions for slicing, searching, partitioning, joining, and aggregating lists. Each is callable in prefix form fn(array, …) or postfix/UFCS form array fn(…). Several functions (take, drop, slice, divideBy, takeWhile) also accept an Object, in which case they operate on its entries in insertion order.

Lambda predicates here receive the element and its index, e.g. (value, index) -> …. The $ shorthand binds to the first parameter (the element); $$ binds to the second (the index).

Slicing and Taking

FunctionSignatureDescriptionExample
take(:collection, :number)The first N items of an Array (or first N entries of an Object).[1,2,3,4] take(2) → [1, 2]
drop(:collection, :number)All items after the first N.[1,2,3,4] drop(2) → [3, 4]
slice(:collection, :number, :number?)Sub-list from a start index; with a length, that many items, else to the end.[10,20,30,40] slice(1, 2) → [20, 30]
takeWhile(:collection, :lambda)Leading items while the predicate holds; stops at the first failure.[1,2,3,1] takeWhile($ < 3) → [1, 2]
dropWhile(:array, :lambda)Drops leading items while the predicate holds, returns the rest.[1,2,3,1] dropWhile($ < 3) → [3, 1]
splitAt(:array, :number)Splits at an index into a two-element [before, after] pair.[1,2,3,4] splitAt(2) → [[1, 2], [3, 4]]
splitWhere(:array, :lambda)Splits just before the first item matching the predicate.[1,2,3,4] splitWhere($ == 3) → [[1, 2], [3, 4]]
divideBy(:collection, :number)Chunks the array into sub-arrays of size N (last chunk may be shorter).[1,2,3,4,5] divideBy(2) → [[1, 2], [3, 4], [5]]
FunctionSignatureDescriptionExample
every(:any, :lambda)True if every item satisfies the predicate (true for an empty collection or null).[2,4,6] every($ mod 2 == 0) → true
some(:any, :lambda)True if at least one item satisfies the predicate (false for an empty collection or null).[1,2,3] some($ > 2) → true
firstWith(:array, :lambda)The first item matching the predicate, or null if none.[1,2,3,4] firstWith($ > 2) → 3
indexWhere(:array, :lambda)Index of the first matching item, or -1 if none.[10,20,30] indexWhere($ == 20) → 1
countBy(:array, :lambda)Count of items satisfying the predicate.[1,2,3,4] countBy($ > 2) → 2

Partitioning and Grouping

FunctionSignatureDescriptionExample
partition(:array, :lambda)Splits into an Object with success (matched) and failure (rest).[1,2,3,4] partition($ mod 2 == 0) → {"success" => [2, 4], "failure" => [1, 3]}

Joins

These relate two arrays by comparing the keys produced by two criteria lambdas — one applied to each left item, one to each right item. Keys are compared as strings, and a criteria lambda that returns null raises an error.

FunctionSignatureDescriptionExample
join(:array, :array, :lambda, :lambda)Inner join: emits a [left, right] pair for every matching key; unmatched items on either side are dropped.see below
leftJoin(:array, :array, :lambda, :lambda)Keeps every left item; emits {l, r} per match, or {l} alone when nothing matches.see below
outerJoin(:array, :array, :lambda, :lambda)Like leftJoin but also emits {r} for unmatched right items.see below
// join (inner)
join(
  [{id:1, n:"a"}, {id:2, n:"b"}],
  [{id:1, c:"x"}, {id:3, c:"z"}],
  (l) -> l.id, (r) -> r.id
)
// → [[{"id" => 1, "n" => "a"}, {"id" => 1, "c" => "x"}]]

// leftJoin
leftJoin(
  [{id:1, n:"a"}, {id:2, n:"b"}],
  [{id:1, c:"x"}],
  (l) -> l.id, (r) -> r.id
)
// → [{"l" => {"id" => 1, "n" => "a"}, "r" => {"id" => 1, "c" => "x"}},
//    {"l" => {"id" => 2, "n" => "b"}}]

// outerJoin
outerJoin(
  [{id:1, n:"a"}],
  [{id:1, c:"x"}, {id:3, c:"z"}],
  (l) -> l.id, (r) -> r.id
)
// → [{"l" => {"id" => 1, "n" => "a"}, "r" => {"id" => 1, "c" => "x"}},
//    {"r" => {"id" => 3, "c" => "z"}}]

Note the difference between the two join shapes: leftJoin and outerJoin return objects with l and r keys, while join returns a plain [left, right] pair array rather than an {l, r} object.

Aggregation

FunctionSignatureDescriptionExample
sumBy(:array, :lambda)Sums the numbers the lambda returns for each item. Always returns a Number (a float).[{q:2},{q:5}] sumBy($.q) → 7.0