Arrays
Functions for creating, transforming, querying, and modifying arrays.
append
2-parameter signature
append(array, value)
Append returns a shallow copy with one additional element, retaining duplicates.
- Parameters
arrayAny[]Source array.valueAnyValue to append as one element.
- Returns
Any[]New array with the appended value.
3-parameter signature
append(array, value, unique)
Use arrays::append; compose arrays::unique to deduplicate the entire result.
Appends an element, optionally skipping it when it already exists.
Existing duplicates are preserved even when unique is true.
- Parameters
arrayAny[]Source array.valueAnyValue to append.uniqueBooleanSkip an already present value.
- Returns
Any[]New array.
first
1-parameter signature
first(arr)
first returns a first element from a given array.
- Parameters
arrAny[]Target array.
- Returns
AnyFirst element in a given array.
flatten
1-parameter signature
flatten(arr)
flatten turns an array of arrays into a flat array.
All array elements in array will be expanded in the result array.
Non-array elements are added as they are.
The function will recurse into sub-arrays up to the specified depth.
Duplicates will not be removed.
- Parameters
arrAny[]Target array.
- Returns
Any[]Flat array.
2-parameter signature
flatten(arr, depth)
flatten turns an array of arrays into a flat array.
All array elements in array will be expanded in the result array.
Non-array elements are added as they are.
The function will recurse into sub-arrays up to the specified depth.
Duplicates will not be removed.
- Parameters
arrAny[]Target array.depthIntDepth level.
- Returns
Any[]Flat array.
intersection
Variadic signature
intersection(arrays...)
Intersection returns distinct values present in every input, in first-input order.
- Parameters
arraysAny[], repeatedAt least two arrays.
- Signature
- Variadic
- Returns
Any[]Common values, retaining their first representatives.
last
1-parameter signature
last(array)
last returns the last element of an array.
- Parameters
arrayAny[]The target array.
- Returns
AnyLast element of an array.
minus
Variadic signature
minus(arrays...)
Difference returns distinct values from the first array absent from every later array.
- Parameters
arraysAny[], repeatedAt least two arrays.
- Signature
- Variadic
- Returns
Any[]Remaining values in first-input order.
nth
2-parameter signature
nth(array, index)
At returns the element of an array at a given position.
It is the same as anyArray[position] for positive positions, but does not support negative positions.
If position is negative or beyond the upper bound of the array, then NONE will be returned.
- Parameters
arrayAny[]An array with elements of arbitrary type.indexIntPosition of desired element in array, positions start at 0.
- Returns
AnyThe array element at the given position.
outersection
Variadic signature
outersection(arrays...)
Use arrays::symmetric_difference for set XOR; it differs for three or more arrays.
Returns values present in exactly one input array, ignoring duplicates within each input.
Results follow first-encounter order. Unlike XOR, presence in three inputs is excluded.
- Parameters
arraysAny[], repeatedAt least two arrays.
- Signature
- Variadic
- Returns
Any[]Values present in exactly one source array.
pop
1-parameter signature
pop(array)
Use arrays::slice with a nonnegative length.
pop returns a new array without last element.
- Parameters
arrayAny[]Target array.
- Returns
Any[]Copy of an array without last element.
position
2-parameter signature
position(array, value)
Use arrays::contains or arrays::index_of.
Reports whether an element is contained in the array.
- Parameters
arrayAny[]The source array.valueAnyThe target value.
- Returns
BooleanWhether an equal value is present.
3-parameter signature
position(array, value, position)
Use arrays::contains or arrays::index_of.
position returns a value indicating whether an element is contained in array. Optionally returns its position.
- Parameters
arrayAny[]The source array.valueAnyThe target value.positionBooleanBoolean value which indicates whether to return item's position.
- Returns
Boolean | IntA value indicating whether an element is contained in array.
push
2-parameter signature
push(array, value)
Append returns a shallow copy with one additional element, retaining duplicates.
- Parameters
arrayAny[]Source array.valueAnyValue to append as one element.
- Returns
Any[]New array with the appended value.
3-parameter signature
push(array, value, unique)
Use arrays::append; compose arrays::unique to deduplicate the entire result.
Appends an element, optionally skipping it when it already exists.
Existing duplicates are preserved even when unique is true.
- Parameters
arrayAny[]Source array.valueAnyValue to append.uniqueBooleanSkip an already present value.
- Returns
Any[]New array.
range
2-parameter signature
range(start, end)
Use arrays::range instead.
range returns an array of numbers in the specified range, optionally with increments other than 1.
- Parameters
startInt | FloatThe value to start the range at (inclusive).endInt | FloatThe value to end the range with (inclusive).
- Returns
Float[]Numbers in the inclusive range, using a default step of one.
3-parameter signature
range(start, end, step)
Use arrays::range instead.
range returns an array of numbers in the specified range, optionally with increments other than 1.
- Parameters
startInt | FloatThe value to start the range at (inclusive).endInt | FloatThe value to end the range with (inclusive).stepInt | FloatHow much to change the value in every step. Positive steps ascend, negative steps descend, and zero is invalid.
- Returns
Float[]Numbers in the inclusive range, using a default step of one.
remove_nth
2-parameter signature
remove_nth(array, index)
Use arrays::remove_at for bounds-checked removal.
Removes an indexed value from a copy, preserving the host list's removal policy.
- Parameters
arrayAny[]Source array.indexIntPosition to remove.
- Returns
Any[]New array without the indexed element.
remove_value
2-parameter signature
remove_value(array, value)
Remove returns a shallow copy without any values equal to the target.
- Parameters
arrayAny[]Source array.valueAnyValue whose occurrences are removed.
- Returns
Any[]Remaining elements in their original order.
3-parameter signature
remove_value(array, value, limit)
Use arrays::remove to remove all matches. Limits remain legacy-only.
Removes equal values, optionally limiting the number of removals.
- Parameters
arrayAny[]Source array.valueAnyValue to remove.limitIntMaximum removals; negative is unlimited and zero removes nothing.
- Returns
Any[]New array retaining the other elements in order.
remove_values
2-parameter signature
remove_values(array, values)
RemoveAny removes all occurrences of values in the second array.
Other duplicates and the original element order are preserved.
- Parameters
arrayAny[]Source array.valuesAny[]Values whose occurrences are removed.
- Returns
Any[]Remaining elements in their original order.
shift
1-parameter signature
shift(array)
Use arrays::slice(array, 1).
shift returns a new array without the first element.
- Parameters
arrayAny[]Target array.
- Returns
Any[]Copy of an array without the first element.
slice
2-parameter signature
slice(array, start)
slice returns a new sliced array.
- Parameters
arrayAny[]Source array.startIntStart position of extraction.
- Returns
Any[]Sliced array.
3-parameter signature
slice(array, start, length)
slice returns a new sliced array.
- Parameters
arrayAny[]Source array.startIntStart position of extraction.lengthIntRead indicating how many elements to extract.
- Returns
Any[]Sliced array.
sorted
1-parameter signature
sorted(array)
sorted sorts all elements in the given list.
The function will use the default comparison order for FQL value types.
- Parameters
arrayAny[]Target array.
- Returns
Any[]Sorted array.
sorted_unique
1-parameter signature
sorted_unique(array)
Use arrays::sorted(arrays::unique(array)).
sorted_unique sorts all elements in a array.
The function will use the default comparison order for FQL value types.
Additionally, the values in the result array will be made unique
- Parameters
arrayAny[]Target array.
- Returns
Any[]Sorted array.
union
Variadic signature
union(arrays...)
Concat concatenates arrays in input order, retaining duplicates.
- Parameters
arraysAny[], repeatedList of arrays to combine.
- Signature
- Variadic
- Returns
Any[]All array elements combined in input order.
union_distinct
Variadic signature
union_distinct(arrays...)
Union returns distinct values in first-encounter order.
- Parameters
arraysAny[], repeatedList of arrays to combine.
- Signature
- Variadic
- Returns
Any[]Distinct elements in first-encounter order.
unique
1-parameter signature
unique(array)
unique returns all unique elements from a given array.
- Parameters
arrayAny[]Target array.
- Returns
Any[]New array without duplicates.
unshift
2-parameter signature
unshift(array, value)
Use arrays::concat([value], array) and arrays::remove as needed.
unshift prepends value to a given array.
- Parameters
arrayAny[]Target array.valueAnyTarget value to prepend.
- Returns
Any[]New array with prepended value.
3-parameter signature
unshift(array, value, unique)
Use arrays::concat([value], array) and arrays::remove as needed.
unshift prepends value to a given array.
- Parameters
arrayAny[]Target array.valueAnyTarget value to prepend.uniqueBooleanOptional value indicating whether a value must be unique to be prepended. Default is false.
- Returns
Any[]New array with prepended value.
arrays::append
2-parameter signature
arrays::append(array, value)
Append returns a shallow copy with one additional element, retaining duplicates.
- Parameters
arrayAny[]Source array.valueAnyValue to append as one element.
- Returns
Any[]New array with the appended value.
arrays::at
2-parameter signature
arrays::at(array, index)
At returns the element of an array at a given position.
It is the same as anyArray[position] for positive positions, but does not support negative positions.
If position is negative or beyond the upper bound of the array, then NONE will be returned.
- Parameters
arrayAny[]An array with elements of arbitrary type.indexIntPosition of desired element in array, positions start at 0.
- Returns
AnyThe array element at the given position.
arrays::concat
Variadic signature
arrays::concat(arrays...)
Concat concatenates arrays in input order, retaining duplicates.
- Parameters
arraysAny[], repeatedList of arrays to combine.
- Signature
- Variadic
- Returns
Any[]All array elements combined in input order.
arrays::contains
2-parameter signature
arrays::contains(array, value)
Contains reports whether an equal value exists in the array.
- Parameters
arrayAny[]Source array.valueAnyValue to find.
- Returns
BooleanWhether the value exists.
arrays::difference
Variadic signature
arrays::difference(arrays...)
Difference returns distinct values from the first array absent from every later array.
- Parameters
arraysAny[], repeatedAt least two arrays.
- Signature
- Variadic
- Returns
Any[]Remaining values in first-input order.
arrays::first
1-parameter signature
arrays::first(arr)
first returns a first element from a given array.
- Parameters
arrAny[]Target array.
- Returns
AnyFirst element in a given array.
arrays::flatten
1-parameter signature
arrays::flatten(arr)
flatten turns an array of arrays into a flat array.
All array elements in array will be expanded in the result array.
Non-array elements are added as they are.
The function will recurse into sub-arrays up to the specified depth.
Duplicates will not be removed.
- Parameters
arrAny[]Target array.
- Returns
Any[]Flat array.
2-parameter signature
arrays::flatten(arr, depth)
flatten turns an array of arrays into a flat array.
All array elements in array will be expanded in the result array.
Non-array elements are added as they are.
The function will recurse into sub-arrays up to the specified depth.
Duplicates will not be removed.
- Parameters
arrAny[]Target array.depthIntDepth level.
- Returns
Any[]Flat array.
arrays::index_of
2-parameter signature
arrays::index_of(array, value)
IndexOf finds the first equal value, returning -1 when it is absent.
- Parameters
arrayAny[]Source array.valueAnyValue to find.
- Returns
IntFirst matching index, or -1.
arrays::intersection
Variadic signature
arrays::intersection(arrays...)
Intersection returns distinct values present in every input, in first-input order.
- Parameters
arraysAny[], repeatedAt least two arrays.
- Signature
- Variadic
- Returns
Any[]Common values, retaining their first representatives.
arrays::last
1-parameter signature
arrays::last(array)
last returns the last element of an array.
- Parameters
arrayAny[]The target array.
- Returns
AnyLast element of an array.
arrays::range
2-parameter signature
arrays::range(start, end)
range returns an array of numbers in the specified range, optionally with increments other than 1.
- Parameters
startInt | FloatThe value to start the range at (inclusive).endInt | FloatThe value to end the range with (inclusive).
- Returns
Float[]Numbers in the inclusive range, using a default step of one.
3-parameter signature
arrays::range(start, end, step)
range returns an array of numbers in the specified range, optionally with increments other than 1.
- Parameters
startInt | FloatThe value to start the range at (inclusive).endInt | FloatThe value to end the range with (inclusive).stepInt | FloatHow much to change the value in every step. Positive steps ascend, negative steps descend, and zero is invalid.
- Returns
Float[]Numbers in the inclusive range, using a default step of one.
arrays::remove
2-parameter signature
arrays::remove(array, value)
Remove returns a shallow copy without any values equal to the target.
- Parameters
arrayAny[]Source array.valueAnyValue whose occurrences are removed.
- Returns
Any[]Remaining elements in their original order.
arrays::remove_any
2-parameter signature
arrays::remove_any(array, values)
RemoveAny removes all occurrences of values in the second array.
Other duplicates and the original element order are preserved.
- Parameters
arrayAny[]Source array.valuesAny[]Values whose occurrences are removed.
- Returns
Any[]Remaining elements in their original order.
arrays::remove_at
2-parameter signature
arrays::remove_at(array, position)
RemoveAt returns a new array without an element by a given position.
Negative and out-of-range positions return an unchanged shallow copy.
- Parameters
arrayAny[]Source array.positionIntTarget element position.
- Returns
Any[]A new array without an element by a given position.
arrays::slice
2-parameter signature
arrays::slice(array, start)
slice returns a new sliced array.
- Parameters
arrayAny[]Source array.startIntStart position of extraction.
- Returns
Any[]Sliced array.
3-parameter signature
arrays::slice(array, start, length)
slice returns a new sliced array.
- Parameters
arrayAny[]Source array.startIntStart position of extraction.lengthIntRead indicating how many elements to extract.
- Returns
Any[]Sliced array.
arrays::sorted
1-parameter signature
arrays::sorted(array)
sorted sorts all elements in the given list.
The function will use the default comparison order for FQL value types.
- Parameters
arrayAny[]Target array.
- Returns
Any[]Sorted array.
arrays::symmetric_difference
Variadic signature
arrays::symmetric_difference(arrays...)
SymmetricDifference returns values present in an odd number of input arrays.
Duplicates within one input count once. Results follow first-encounter order.
- Parameters
arraysAny[], repeatedAt least two arrays.
- Signature
- Variadic
- Returns
Any[]Odd-presence values, retaining their first representatives.
arrays::union
Variadic signature
arrays::union(arrays...)
Union returns distinct values in first-encounter order.
- Parameters
arraysAny[], repeatedList of arrays to combine.
- Signature
- Variadic
- Returns
Any[]Distinct elements in first-encounter order.
arrays::unique
1-parameter signature
arrays::unique(array)
unique returns all unique elements from a given array.
- Parameters
arrayAny[]Target array.
- Returns
Any[]New array without duplicates.
arrays::mut::clear
1-parameter signature
arrays::mut::clear(array)
ClearMutable removes all elements from the original array without closing them.
- Parameters
arrayAny[]Array to mutate.
- Returns
Any[]The original array.
arrays::mut::insert
3-parameter signature
arrays::mut::insert(array, index, value)
InsertMutable inserts an element, allowing index equal to length.
Invalid indexes fail before mutation.
- Parameters
arrayAny[]Array to mutate.indexIntZero-based insertion index.valueAnyValue to insert as one element.
- Returns
Any[]The original array.
arrays::mut::pop
1-parameter signature
arrays::mut::pop(array)
PopMutable removes and returns the last element, or none when empty.
- Parameters
arrayAny[]Array to mutate.
- Returns
AnyRemoved value, or none for an empty array.
arrays::mut::push
2-parameter signature
arrays::mut::push(array, value)
PushMutable appends one value to the original array, retaining duplicates.
- Parameters
arrayAny[]Array to mutate.valueAnyValue to insert as one element.
- Returns
Any[]The original array.
arrays::mut::remove
2-parameter signature
arrays::mut::remove(array, value)
RemoveMutable removes all equal values from the original array, preserving survivor order.
Errors may leave earlier writes or removals applied.
- Parameters
arrayAny[]Array to mutate.valueAnyValue whose occurrences are removed.
- Returns
Any[]The original array.
arrays::mut::remove_at
2-parameter signature
arrays::mut::remove_at(array, index)
RemoveAtMutable removes and returns an existing element.
Negative and missing indexes fail before mutation.
- Parameters
arrayAny[]Array to mutate.indexIntZero-based element index.
- Returns
AnyRemoved value.
arrays::mut::set
3-parameter signature
arrays::mut::set(array, index, value)
SetMutable replaces an existing element without growing the array.
Invalid indexes fail before mutation.
- Parameters
arrayAny[]Array to mutate.indexIntZero-based element index.valueAnyValue to insert as one element.
- Returns
Any[]The original array.
arrays::mut::shift
1-parameter signature
arrays::mut::shift(array)
ShiftMutable removes and returns the first element, or none when empty.
- Parameters
arrayAny[]Array to mutate.
- Returns
AnyRemoved value, or none for an empty array.
arrays::mut::sort
1-parameter signature
arrays::mut::sort(array)
SortMutable stably sorts the original array in ascending FQL order.
It uses the same ordering as arrays::sorted; errors may leave a partial sort.
- Parameters
arrayAny[]Array to mutate.
- Returns
Any[]The original array.
arrays::mut::unshift
2-parameter signature
arrays::mut::unshift(array, value)
UnshiftMutable inserts one value at the beginning of the original array.
- Parameters
arrayAny[]Array to mutate.valueAnyValue to insert as one element.
- Returns
Any[]The original array.