Array Functions¶

Functions for transforming, grouping, and inspecting arrays.

Summary¶

Function	Signature	Description
`bsearch`	`array, any -> number`	Binary search in a sorted array, returns index or negative insertion point (jq parity)
`butlast`	`array -> array`	Return all elements except the last (alias for initial)
`cartesian`	`array, array? -> array`	Compute cartesian product of arrays (jq parity for N-way product)
`chunk`	`array, number -> array`	Split array into chunks of size n
`combinations`	`array, number -> array`	All k-element combinations of the array, preserving input order
`compact`	`array -> array`	Remove null values from array
`cycle`	`array, number -> array`	Cycle through array elements n times
`dedupe`	`array -> array`	Remove consecutive duplicate values (unlike unique, allows non-adjacent duplicates)
`difference`	`array, array -> array`	Elements in first array not in second
`drop`	`array, number -> array`	Drop first n elements
`fill`	`array, any, number -> array`	Replace elements in the range [start, end) with a value (start/end optional, negative indices supported)
`find_index`	`array, any -> number \\| null`	Find index of value in array
`first`	`array -> any`	Get first element of array
`flatten`	`array -> array`	Flatten array one level deep
`flatten_deep`	`array -> array`	Recursively flatten nested arrays
`frequencies`	`array -> object`	Count occurrences of each value
`group_by`	`array, expression\\|string -> object`	Group array elements by expression or field name
`includes`	`array, any -> boolean`	Check if array contains value
`index_at`	`array, number -> any`	Get element at index (supports negative)
`index_by`	`array, expression\\|string -> object`	Create lookup map from array using expression or key field (last value wins for duplicates)
`indices_array`	`array, any -> array`	Find all indices where a value appears in an array (jq parity)
`inside_array`	`array, array -> boolean`	Check if all elements of first array are contained in second array (inverse of contains, jq parity)
`interleave`	`array, array -> array`	Alternate elements from two arrays; remaining elements of the longer array are appended
`interpose`	`array, any -> array`	Insert separator value between each element of array
`intersection`	`array, array -> array`	Elements common to both arrays
`lag`	`array, number -> array`	Shift array by n positions forward, prepending nulls
`last`	`array -> any`	Get last element of array
`lead`	`array, number -> array`	Shift array by n positions backward, appending nulls
`nth`	`array, number -> array`	Take every nth element starting from the first (step, not index)
`pairwise`	`array -> array`	Return adjacent pairs from array
`partition`	`array, number -> array`	Split array into n contiguous parts as evenly as possible (earlier parts get the remainder)
`partition_by`	`array, expression\\|string -> array`	Split array into partitions when expression or field value changes (preserves order unlike group_by)
`pull_at`	`array, array -> array`	Return elements at the given indices, in the order requested (negative indices supported)
`range`	`number, number -> array`	Generate array of numbers
`repeat_array`	`any, number -> array`	Create array with value repeated n times
`rotate`	`array, number -> array`	Rotate array elements left by n positions (negative rotates right)
`sliding_window`	`array, number -> array`	Create overlapping windows of size n (alias for window)
`tail`	`array -> array`	All elements except the first
`take`	`array, number -> array`	Take first n elements
`transpose`	`array -> array`	Transpose a 2D array (swap rows and columns)
`union`	`array, array -> array`	Unique elements from both arrays
`unique`	`array -> array`	Remove duplicate values
`without`	`array, array -> array`	Remove all occurrences of the given values from the array
`xor`	`array, array -> array`	Symmetric difference: elements in exactly one of the two arrays
`zip`	`array, array -> array`	Zip two arrays together
`zipmap`	`array, array -> object`	Create object from parallel arrays of keys and values

Functions¶

bsearch¶

Binary search in a sorted array, returns index or negative insertion point (jq parity)

Signature: array, any -> number

Examples:

# Found at index 2
bsearch([1, 3, 5, 7, 9], `5`) -> 2
# Not found, would insert at index 2
bsearch([1, 3, 5, 7, 9], `4`) -> -3
# Not found, would insert at index 0
bsearch([1, 3, 5, 7, 9], `0`) -> -1

butlast¶

Return all elements except the last (alias for initial)

Signature: array -> array

Aliases: initial

Examples:

# Remove last element
butlast([1, 2, 3, 4]) -> [1, 2, 3]
# String values
butlast(['a', 'b', 'c']) -> ['a', 'b']
# Single element returns empty
butlast([1]) -> []
# Empty array returns empty
butlast([]) -> []

cartesian¶

Compute cartesian product of arrays (jq parity for N-way product)

Signature: array, array? -> array

Examples:

# Two-array product
cartesian([1, 2], [3, 4]) -> [[1, 3], [1, 4], [2, 3], [2, 4]]
# N-way product (jq style)
cartesian([[1, 2], [3, 4]]) -> [[1, 3], [1, 4], [2, 3], [2, 4]]
# Three-way product
cartesian([['a', 'b'], [1, 2], ['x', 'y']]) -> [['a', 1, 'x'], ['a', 1, 'y'], ...]
# Single array
cartesian([[1, 2]]) -> [[1], [2]]
# Empty array produces empty result
cartesian([[], [1, 2]]) -> []

chunk¶

Split array into chunks of size n

Signature: array, number -> array

Examples:

# Basic chunking
chunk([1, 2, 3, 4], `2`) -> [[1, 2], [3, 4]]
# Uneven chunks
chunk([1, 2, 3, 4, 5], `2`) -> [[1, 2], [3, 4], [5]]
# Empty array
chunk([], `2`) -> []

combinations¶

All k-element combinations of the array, preserving input order

Signature: array, number -> array

Examples:

# 2-combinations of 3
combinations([1, 2, 3], `2`) -> [[1, 2], [1, 3], [2, 3]]
# 1-combinations
combinations([1, 2, 3], `1`) -> [[1], [2], [3]]

compact¶

Remove null values from array

Signature: array -> array

Examples:

# Remove nulls
compact([1, null, 2, null]) -> [1, 2]
# All nulls
compact([null, null]) -> []
# No nulls
compact([1, 2, 3]) -> [1, 2, 3]

cycle¶

Cycle through array elements n times

Signature: array, number -> array

Examples:

# Cycle twice
cycle([1, 2, 3], `2`) -> [1, 2, 3, 1, 2, 3]
# Cycle strings
cycle(["a", "b"], `3`) -> ["a", "b", "a", "b", "a", "b"]
# Zero cycles
cycle([1, 2], `0`) -> []
# Empty array
cycle([], `5`) -> []

dedupe¶

Remove consecutive duplicate values (unlike unique, allows non-adjacent duplicates)

Signature: array -> array

Examples:

# Remove adjacent duplicates
dedupe([1, 1, 2, 2, 1, 1]) -> [1, 2, 1]
# String values
dedupe(['a', 'a', 'b', 'a']) -> ['a', 'b', 'a']
# No consecutive duplicates
dedupe([1, 2, 3]) -> [1, 2, 3]
# Empty array unchanged
dedupe([]) -> []

difference¶

Elements in first array not in second

Signature: array, array -> array

Examples:

# Remove matching elements
difference([1, 2, 3], [2]) -> [1, 3]
# No overlap
difference([1, 2, 3], [4, 5]) -> [1, 2, 3]
# All removed
difference([1, 2], [1, 2]) -> []

drop¶

Drop first n elements

Signature: array, number -> array

Examples:

# Drop first 2
drop([1, 2, 3, 4], `2`) -> [3, 4]
# Drop none
drop([1, 2, 3], `0`) -> [1, 2, 3]
# Drop more than length
drop([1, 2], `5`) -> []

fill¶

Replace elements in the range [start, end) with a value (start/end optional, negative indices supported)

Signature: array, any, number -> array

Examples:

# Fill entire array
fill([1, 2, 3, 4], `0`) -> [0, 0, 0, 0]
# Fill range [1, 3)
fill([1, 2, 3, 4], `0`, `1`, `3`) -> [1, 0, 0, 4]

find_index¶

Find index of value in array

Signature: array, any -> number | null

Examples:

# Find existing value
find_index([1, 2, 3], `2`) -> 1
# Find string
find_index(['a', 'b', 'c'], 'b') -> 1
# Value not found
find_index([1, 2, 3], `99`) -> null

first¶

Get first element of array

Signature: array -> any

Examples:

# Get first number
first([1, 2, 3]) -> 1
# Get first string
first(['a', 'b']) -> 'a'
# Empty array returns null
first([]) -> null

flatten¶

Flatten array one level deep

Signature: array -> array

Examples:

# Flatten nested arrays
flatten([[1, 2], [3]]) -> [1, 2, 3]
# Only one level deep
flatten([[1, [2]], [3]]) -> [1, [2], 3]
# Already flat
flatten([1, 2, 3]) -> [1, 2, 3]

flatten_deep¶

Recursively flatten nested arrays

Signature: array -> array

Examples:

# Deeply nested
flatten_deep([[1, [2]], [3]]) -> [1, 2, 3]
# Multiple levels
flatten_deep([[[1]], [[2]], [[3]]]) -> [1, 2, 3]
# Already flat
flatten_deep([1, 2, 3]) -> [1, 2, 3]

frequencies¶

Count occurrences of each value

Signature: array -> object

Examples:

# Count strings
frequencies(['a', 'b', 'a']) -> {a: 2, b: 1}
# Count numbers
frequencies([1, 2, 1, 1]) -> {1: 3, 2: 1}
# Empty array
frequencies([]) -> {}

group_by¶

Group array elements by expression or field name

Signature: array, expression|string -> object

Examples:

# Group by field (expref)
group_by([{t: 'a'}, {t: 'b'}, {t: 'a'}], &t) -> {a: [{t:'a'}, {t:'a'}], b: [{t:'b'}]}
# Group by field (string, legacy)
group_by([{t: 'a'}, {t: 'b'}, {t: 'a'}], 't') -> {a: [{t:'a'}, {t:'a'}], b: [{t:'b'}]}
# Group by condition
group_by([1, 2, 3, 4], &@ > `2`) -> {true: [3, 4], false: [1, 2]}
# Empty array returns empty object
group_by([], &key) -> {}

includes¶

Check if array contains value

Signature: array, any -> boolean

Examples:

# Value found
includes([1, 2, 3], `2`) -> true
# Value not found
includes([1, 2, 3], `99`) -> false
# String value
includes(['a', 'b'], 'a') -> true

index_at¶

Get element at index (supports negative)

Signature: array, number -> any

Examples:

# First element
index_at([1, 2, 3], `0`) -> 1
# Last element (negative index)
index_at([1, 2, 3], `-1`) -> 3
# Out of bounds
index_at([1, 2, 3], `99`) -> null

index_by¶

Create lookup map from array using expression or key field (last value wins for duplicates)

Signature: array, expression|string -> object

Examples:

# Index by id (expref)
index_by([{id: 1, name: "alice"}, {id: 2, name: "bob"}], &id) -> {"1": {id: 1, name: "alice"}, "2": {id: 2, name: "bob"}}
# Index by id (string, legacy)
index_by([{id: 1, name: "alice"}, {id: 2, name: "bob"}], "id") -> {"1": {id: 1, name: "alice"}, "2": {id: 2, name: "bob"}}
# Last value wins for duplicates
index_by([{t: "a", v: 1}, {t: "a", v: 2}], &t) -> {"a": {t: "a", v: 2}}
# Empty array returns empty object
index_by([], &id) -> {}

indices_array¶

Find all indices where a value appears in an array (jq parity)

Signature: array, any -> array

Examples:

# Find all occurrences
indices_array([1, 2, 3, 2, 4, 2], `2`) -> [1, 3, 5]
# String values
indices_array(['a', 'b', 'a', 'c'], `'a'`) -> [0, 2]
# Not found returns empty
indices_array([1, 2, 3], `5`) -> []

inside_array¶

Check if all elements of first array are contained in second array (inverse of contains, jq parity)

Signature: array, array -> boolean

Examples:

# Subset check
inside_array([1, 2], [1, 2, 3, 4]) -> true
# Not a subset
inside_array([1, 5], [1, 2, 3, 4]) -> false
# Empty is subset of any
inside_array([], [1, 2, 3]) -> true

interleave¶

Alternate elements from two arrays; remaining elements of the longer array are appended

Signature: array, array -> array

Examples:

# Equal-length interleave
interleave([1, 2, 3], [4, 5, 6]) -> [1, 4, 2, 5, 3, 6]
# Trailing elements appended
interleave([1, 2], [3, 4, 5, 6]) -> [1, 3, 2, 4, 5, 6]

interpose¶

Insert separator value between each element of array

Signature: array, any -> array

Examples:

# Insert zeros between numbers
interpose([1, 2, 3], `0`) -> [1, 0, 2, 0, 3]
# Insert separator strings
interpose(['a', 'b', 'c'], `"-"`) -> ['a', '-', 'b', '-', 'c']
# Single element unchanged
interpose([1], `0`) -> [1]
# Empty array unchanged
interpose([], `0`) -> []

intersection¶

Elements common to both arrays

Signature: array, array -> array

Examples:

# Common elements
intersection([1, 2], [2, 3]) -> [2]
# No overlap
intersection([1, 2], [3, 4]) -> []
# Identical arrays
intersection([1, 2, 3], [1, 2, 3]) -> [1, 2, 3]

lag¶

Shift array by n positions forward, prepending nulls

Signature: array, number -> array

Examples:

# Lag by 1
lag([1, 2, 3], `1`) -> [null, 1, 2]
# Lag by 2
lag([1, 2, 3], `2`) -> [null, null, 1]
# Lag by 0
lag([1, 2, 3], `0`) -> [1, 2, 3]

last¶

Get last element of array

Signature: array -> any

Examples:

# Get last number
last([1, 2, 3]) -> 3
# Get last string
last(['a', 'b']) -> 'b'
# Empty array returns null
last([]) -> null

lead¶

Shift array by n positions backward, appending nulls

Signature: array, number -> array

Examples:

# Lead by 1
lead([1, 2, 3], `1`) -> [2, 3, null]
# Lead by 2
lead([1, 2, 3], `2`) -> [3, null, null]
# Lead by 0
lead([1, 2, 3], `0`) -> [1, 2, 3]

nth¶

Take every nth element starting from the first (step, not index)

Signature: array, number -> array

Examples:

# Every 2nd element
nth([1, 2, 3, 4, 5, 6], `2`) -> [1, 3, 5]
# Step 1 returns all
nth([10, 20, 30, 40], `1`) -> [10, 20, 30, 40]
# Step of 0 returns null
nth([1, 2, 3], `0`) -> null

pairwise¶

Return adjacent pairs from array

Signature: array -> array

Examples:

# Adjacent pairs
pairwise([1, 2, 3]) -> [[1, 2], [2, 3]]
# Single pair
pairwise([1, 2]) -> [[1, 2]]
# Too few elements
pairwise([1]) -> []

partition¶

Split array into n contiguous parts as evenly as possible (earlier parts get the remainder)

Signature: array, number -> array

Examples:

# Even split into 3
partition([1, 2, 3, 4, 5, 6], `3`) -> [[1, 2], [3, 4], [5, 6]]
# Uneven split
partition([1, 2, 3, 4, 5], `3`) -> [[1, 2], [3, 4], [5]]

partition_by¶

Split array into partitions when expression or field value changes (preserves order unlike group_by)

Signature: array, expression|string -> array

Examples:

# Split on field change (expref)
partition_by([{t: "a"}, {t: "a"}, {t: "b"}, {t: "a"}], &t) -> [[{t: "a"}, {t: "a"}], [{t: "b"}], [{t: "a"}]]
# Split on field change (string, legacy)
partition_by([{t: "a"}, {t: "a"}, {t: "b"}, {t: "a"}], "t") -> [[{t: "a"}, {t: "a"}], [{t: "b"}], [{t: "a"}]]
# Partition by condition
partition_by([1, 1, 2, 2, 1], &@ > `1`) -> [[1, 1], [2, 2], [1]]
# Empty array returns empty
partition_by([], &type) -> []

pull_at¶

Return elements at the given indices, in the order requested (negative indices supported)

Signature: array, array -> array

Examples:

# Elements at indices 0 and 2
pull_at([10, 20, 30, 40], [0, 2]) -> [10, 30]
# Negative index from end
pull_at([10, 20, 30, 40], [-1, 0]) -> [40, 10]

range¶

Generate array of numbers

Signature: number, number -> array

Examples:

# Range 1 to 4
range(`1`, `5`) -> [1, 2, 3, 4]
# Range from zero
range(`0`, `3`) -> [0, 1, 2]
# Empty range
range(`5`, `5`) -> []

repeat_array¶

Create array with value repeated n times

Signature: any, number -> array

Examples:

# Repeat number
repeat_array(`1`, `3`) -> [1, 1, 1]
# Repeat string
repeat_array(`"x"`, `4`) -> ["x", "x", "x", "x"]
# Zero repetitions
repeat_array(`0`, `0`) -> []
# Repeat object
repeat_array(`{"a": 1}`, `2`) -> [{"a": 1}, {"a": 1}]

rotate¶

Rotate array elements left by n positions (negative rotates right)

Signature: array, number -> array

Examples:

# Rotate left by 2
rotate([1, 2, 3, 4, 5], `2`) -> [3, 4, 5, 1, 2]
# Negative rotates right
rotate([1, 2, 3, 4, 5], `-1`) -> [5, 1, 2, 3, 4]

sliding_window¶

Create overlapping windows of size n (alias for window)

Signature: array, number -> array

Aliases: window

Examples:

# Size 2 windows
sliding_window([1, 2, 3, 4], `2`) -> [[1, 2], [2, 3], [3, 4]]
# Size 3 windows
sliding_window([1, 2, 3, 4], `3`) -> [[1, 2, 3], [2, 3, 4]]
# Window larger than array
sliding_window([1, 2], `3`) -> []

tail¶

All elements except the first

Signature: array -> array

Examples:

# Drop the first element
tail([1, 2, 3, 4]) -> [2, 3, 4]
# Single-element array
tail([1]) -> []

take¶

Take first n elements

Signature: array, number -> array

Examples:

# Take first 2
take([1, 2, 3, 4], `2`) -> [1, 2]
# Take none
take([1, 2, 3], `0`) -> []
# Take more than length
take([1, 2], `5`) -> [1, 2]

transpose¶

Transpose a 2D array (swap rows and columns)

Signature: array -> array

Examples:

# Swap rows/columns
transpose([[1, 2], [3, 4]]) -> [[1, 3], [2, 4]]
# 2x3 to 3x2
transpose([[1, 2, 3], [4, 5, 6]]) -> [[1, 4], [2, 5], [3, 6]]
# Empty array
transpose([]) -> []

union¶

Unique elements from both arrays

Signature: array, array -> array

Examples:

# Combine with dedup
union([1, 2], [2, 3]) -> [1, 2, 3]
# No overlap
union([1, 2], [3, 4]) -> [1, 2, 3, 4]
# Empty first array
union([], [1, 2]) -> [1, 2]

unique¶

Remove duplicate values

Signature: array -> array

Examples:

# Basic deduplication
unique([1, 2, 1, 3]) -> [1, 2, 3]
# String values
unique(['a', 'b', 'a']) -> ['a', 'b']
# Empty array
unique([]) -> []

without¶

Remove all occurrences of the given values from the array

Signature: array, array -> array

Examples:

# Remove all 2s
without([1, 2, 3, 1, 2], [2]) -> [1, 3, 1]
# Remove multiple values
without([1, 2, 3], [2, 3]) -> [1]

xor¶

Symmetric difference: elements in exactly one of the two arrays

Signature: array, array -> array

Examples:

# Elements unique to each
xor([1, 2, 3], [2, 3, 4]) -> [1, 4]
# Identical arrays
xor([1, 2, 3], [1, 2, 3]) -> []

zip¶

Zip two arrays together

Signature: array, array -> array

JEP: JEP-013

Examples:

# Basic zip
zip([1, 2], ['a', 'b']) -> [[1, 'a'], [2, 'b']]
# Unequal lengths (truncates)
zip([1, 2, 3], ['a', 'b']) -> [[1, 'a'], [2, 'b']]
# Empty arrays
zip([], []) -> []

zipmap¶

Create object from parallel arrays of keys and values

Signature: array, array -> object

Examples:

# Basic zipmap
zipmap(["a", "b", "c"], [1, 2, 3]) -> {"a": 1, "b": 2, "c": 3}
# Uses shorter length
zipmap(["x", "y"], [10, 20, 30]) -> {"x": 10, "y": 20}
# Empty arrays return empty object
zipmap([], []) -> {}
# Mixed value types
zipmap(["name", "age"], ["alice", 30]) -> {"name": "alice", "age": 30}