

Arrays¶

A collection of functions that operate specifically on arrays, defined as tables with just keys 1..n.

-- Examples of valid arrays:
{}
{"red", "green", "blue"}
{"winter", {is = "coming"}, [3] = "again"}
{1966, nil, nil}
-- Examples of invalid arrays:
{1994, nil, 2002}
{you = {"know", "nothing"}}
{[5] = "gold rings"}
42

These functions can iterate over any Ordered values.

Functions¶

append¶

function dash.append(target, ...) --> T[]

Inserts into the target array the elements from all subsequent arguments in order.

Type

<T>(mut T[], ...Ordered<T> -> T[])

Generics

T - any - the primary type (extends any value)

Parameters

target - mut T[] - an array (of the primary type) (which can be mutated)

... - ...Ordered<T> - Ordereds (of the primary type) - any number of other arrays

Returns

T[] - an array (of the primary type)

Examples

dash.append({}, {1, 2, 3}, {4, 5, 6}) --> {1, 2, 3, 4, 5, 6}

dash.append({1, 2, 3}) --> {1, 2, 3}

local list = {"cheese"}
dash.append(list, {"nachos"}, {}, {"chillies"})
list --> {"cheese", "nachos", "chillies"}

defaultComparator¶

function dash.defaultComparator(a, b) --> bool

Given two values a and b, this function return true if a is typically considered lower than b.

The default comparator is used by dash.sort and can sort elements of different types, in the order: boolean, number, string, function, CFunction, userdata, and table.

Elements which cannot be sorted naturally will be sorted by their string value.

Type

<T>((T, T) -> bool)

Generics

T - any - the primary type (extends any value)

Parameters

a - T - the primary type

b - T - the primary type

Returns

bool - a boolean

See

dash.sort

first¶

function dash.first(source, predicate) --> V?

Returns the earliest value from the array that predicate returns true for.

If the predicate is not specified, dash.first simply returns the first element of the array.

Type

<T: Iterable<K,V>>(T, (element: V, key: K -> bool) -> V?)

Generics

T - Iterable<K, V> - the primary type (extends an Iterable (of the primary key type and the primary value type))

Parameters

source - T - the primary type

predicate - (element: V, key: K) -> bool - a function (taking element (the primary value type) and key (the primary key type), and returning a boolean) - (default = dash.returns(true))

Returns

V? - the primary value type (optional)

Examples

local names = {
    "Boromir",
    "Frodo",
    "Bilbo"
}

dash.first(names) --> "Boromir", 1

-- Find a particular value:
local firstNameWithF = dash.first(names, function(name)
    return dash.startsWith(name, "F")
end)
firstNameWithF --> "Frodo", 2

-- What about a value which doesn't exist?
local firstNameWithC = dash.first(names, function(name)
    return dash.startsWith(name, "C")
end)
firstNameWithC --> nil

-- Find the index of a value:
local _, index = dash.first(names, dash.fn:matches("Bilbo"))
index --> 2

Usage

If you need to find a value in a table which isn't an array, use dash.find.

See

dash.find

last¶

function dash.last(source, predicate) --> V?

Returns the last value from the array that predicate returns true for.

If the predicate is not specified, dash.last simply returns the last element of the array.

Type

<T: Iterable<K,V>>(T, (element: V, key: K -> bool) -> V?)

Generics

T - Iterable<K, V> - the primary type (extends an Iterable (of the primary key type and the primary value type))

Parameters

source - T - the primary type

predicate - (element: V, key: K) -> bool - a function (taking element (the primary value type) and key (the primary key type), and returning a boolean) - (default = dash.returns(true))

Returns

V? - the primary value type (optional)

Examples

local names = {
    "Boromir",
    "Frodo",
    "Bilbo"
}

dash.last(names) --> "Bilbo", 3

local lastNameWithB = dash.last(names, dash.fn:startsWith("B"))
lastNameWithB --> "Bilbo", 3

local _, key = dash.last(names, dash.fn:matches("Frodo"))
key --> 2

See

reduce¶

function dash.reduce(source, handler, initial) --> R

Runs the handler on each element of source in turn, passing the result of the previous call (or initial for the first element) as the first argument, and the current element as a value and key as subsequent arguments.

Type

<T, R>(Ordered<T>, (result: R, value: T, key: int -> R), R) -> R

Generics

T - any - the primary type (extends any value)

R - any - the result type (extends any value)

Parameters

source - Ordered<T> - an Ordered (of the primary type)

handler - (result: R, value: T, key: int) -> R - a function (taking result (the result type), value (the primary type) and key (an integer), and returning the result type)

initial - R - the result type

Returns

R - the result type

Examples

local sum = dash.reduce({1, 2, 3}, function(result, value)
    return result + value
end, 0)
sum --> 6

local recipe = {first = "cheese", second = "nachos", third = "chillies"}
local unzipRecipe = dash.reduce(recipe, function(result, value, key)
    table.insert(result[1], key)
    table.insert(result[2], value)
    return result
end, {{}, {}})
-- (in some order)
unzipRecipe --> {{"first", "third", "second"}, {"cheese", "chillies", "nachos"}}

reverse¶

function dash.reverse(source) --> T[]

Swaps the order of elements in source.

Type

<T>(T[] -> T[])

Generics

T - any - the primary type (extends any value)

Parameters

source - T[] - an array (of the primary type)

Returns

T[] - an array (of the primary type)

Examples

dash.reverse({1, 2, 4, 3, 5}) --> {5, 3, 4, 2, 1}

shuffle¶

function dash.shuffle(source) --> T[]

Returns a new array with the order of the values from source randomized.

Type

<T>(T[] -> T[])

Generics

T - any - the primary type (extends any value)

Parameters

source - T[] - an array (of the primary type)

Returns

T[] - an array (of the primary type)

Examples

local teamColors = {"red", "red", "red", "blue", "blue", "blue"}
-- (in some order)
dash.shuffle(teamColors) --> {"blue", "blue", "red", "blue", "red", "red"}

slice¶

function dash.slice(source, first, last, step) --> T[]

Returns a copied portion of the source, between the first and last elements inclusive and jumping step each time if provided.

Type

<T>(T[], int?, int?, int? -> T[])

Generics

T - any - the primary type (extends any value)

Parameters

source - T[] - an array (of the primary type)

first - int? - an integer (optional) - (default = 1) The index of the first element to include.

last - int? - an integer (optional) - (default = #source) The index of the last element to include.

step - int? - an integer (optional) - (default = 1) What amount to step the index by during iteration.

Returns

T[] - an array (of the primary type)

Examples

dash.slice({10, 20, 30, 40}) --> {10, 20, 30, 40}

dash.slice({10, 20, 30, 40}, 2) --> {20, 30, 40}

dash.slice({10, 20, 30, 40}, 2, 3) --> {20, 30}

dash.slice({10, 20, 30, 40}, 2, 4, 2) --> {20, 40}

sort¶

function dash.sort(input, comparator) --> T[]

Returns a sorted array from the input array, based on a comparator function.

Unlike dash.sort, the comparator to dash.sort is optional, but if defined it can also return a numeric weight or nil as well as a boolean to provide an ordering of the elements.

Type

<T>(T[], (T -> bool | number | nil)? -> T[])

Generics

T - any - the primary type (extends any value)

Parameters

input - T[] - an array (of the primary type)

comparator - (T) -> bool | number | nil? - a function (taking the primary type, and returning a boolean or a number or nil) (optional) - should return true or n < 0 if the first element should be before the second in the resulting array, or 0 or nil if the elements have the same order.

Returns

T[] - an array (of the primary type)

Examples

dash.sort({2, 5, 3}) --> {2, 3, 5}

dash.sort({"use", "the", "force", "Luke"}) --> {"Luke", "force", "the", "use"}

dash.sort({
    name = "Luke",
    health = 50
}, {
    name = "Yoda",
    health = 9001
}, {
    name = "Jar Jar Binks",
    health = 0
}, function(a, b)
    return a.health < b.health
end) --> the characters sorted in ascending order by their health

sum¶

function dash.sum(source) --> number

Sums all the values in the source array.

Type

Ordered<number> -> number

Parameters

source - Ordered<number> - an Ordered (of a number)

Returns

number - a number

Examples

dash.sum({1, 2, 3}) --> 6