Array

Utilities for working with arrays.

An immutable array implementation is available in the Immutable submodule.

1

from "array" include Array

1

[> 1, 2, 3]

Values

Functions and constants included in the Array module.

Array.length

1

length : (array: Array<a>) => Number

Provides the length of the input array.

Parameters:

Returns:

Examples:

1

Array.length([> 1, 2, 3, 4, 5]) == 5

Array.make

1

make : (length: Number, item: a) => Array<a>

Creates a new array of the specified length with each element being initialized with the given value.

Parameters:

Returns:

Throws:

InvalidArgument(String)

• When length is not an integer
• When length is negative

Examples:

1

Array.make(5, "foo") == [> "foo", "foo", "foo", "foo", "foo"]

Array.init

1

init : (length: Number, fn: (Number => a)) => Array<a>

Creates a new array of the specified length where each element is initialized with the result of an initializer function. The initializer is called with the index of each array element.

Parameters:

Returns:

Throws:

InvalidArgument(String)

• When length is not an integer
• When length is negative

Examples:

1

Array.init(5, n => n + 3) == [> 3, 4, 5, 6, 7]

Array.get

1

get : (index: Number, array: Array<a>) => a

An alias for normal syntactic array access, i.e. array[n].

Retrieves the element from the array at the specified index. A negative index is treated as an offset from the end of the array.

Parameters:

Returns:

Throws:

IndexOutOfBounds

• When index is not an integer
• When index is out of bounds

Examples:

1

Array.get(1, [> 1, 2, 3, 4, 5]) == 2

Array.set

1

set : (index: Number, value: a, array: Array<a>) => Void

An alias for normal syntactic array set, i.e. array[n] = value.

Sets the element at the specified index in the array to the new value. A negative index is treated as an offset from the end of the array.

Parameters:

Throws:

IndexOutOfBounds

• When index is not an integer
• When index is out of bounds

Examples:

1
2
3

let array = [> 1, 2, 3, 4, 5]
Array.set(1, 9, array)
assert array == [> 1, 9, 3, 4, 5]

Array.append

1

append : (array1: Array<a>, array2: Array<a>) => Array<a>

Creates a new array with the elements of the first array followed by the elements of the second array. This does not modify the arguments.

Parameters:

Returns:

Throws:

InvalidArgument(String)

• When the combined length of the two arrays is not an integer

Examples:

1

Array.append([> 1, 2], [> 3, 4, 5]) == [> 1, 2, 3, 4, 5]

Array.concat

1

concat : (arrays: List<Array<a>>) => Array<a>

Creates a single array containing the elements of all arrays in the provided list. Does not modify any of the input arguments.

Parameters:

Returns:

Throws:

InvalidArgument(String)

• When the combined length of all arrays is not an integer

Examples:

1

Array.concat([[> 1, 2], [> 3, 4], [> 5, 6]]) == [> 1, 2, 3, 4, 5, 6]

Array.copy

1

copy : (array: Array<a>) => Array<a>

Produces a shallow copy of the input array. The new array contains the same elements as the original.

Parameters:

Returns:

Examples:

1

Array.copy([> 1, 2, 3]) == [> 1, 2, 3]

Array.cycle

1

cycle : (fn: (a => Void), n: Number, array: Array<a>) => Void

Iterates an array a given number of times, calling an iterator function on each element.

Parameters:

Examples:

1
2
3

let mut str = ""
Array.cycle(s => str = str ++ s, 2, [> "a", "b", "c"])
assert str == "abcabc"

Array.forEach

1

forEach : (fn: (a => Void), array: Array<a>) => Void

Iterates an array, calling an iterator function on each element.

Parameters:

Examples:

1
2
3

let mut str = ""
Array.forEach(s => str = str ++ s, [> "a", "b", "c"])
assert str == "abc"

Array.forEachi

1

forEachi : (fn: ((a, Number) => Void), array: Array<a>) => Void

Iterates an array, calling an iterator function on each element. Also passes the index as the second argument to the function.

Parameters:

Examples:

1
2
3

let mut str = ""
Array.forEachi((s, i) => str = str ++ s ++ toString(i), [> "a", "b", "c"])
assert str == "a0b1c2"

Array.map

1

map : (fn: (a => b), array: Array<a>) => Array<b>

Produces a new array initialized with the results of a mapper function called on each element of the input array.

Parameters:

Returns:

Examples:

1

Array.map(x => x * 2, [> 1, 2, 3]) == [> 2, 4, 6]

Array.mapi

1

mapi : (fn: ((a, Number) => b), array: Array<a>) => Array<b>

Produces a new array initialized with the results of a mapper function called on each element of the input array and its index.

Parameters:

Returns:

Examples:

1

Array.mapi((x, i) => (x * 2, i), [> 1, 2, 3]) == [> (2, 0), (4, 1), (6, 2)]

Array.reduce

1

reduce : (fn: ((a, b) => a), initial: a, array: Array<b>) => a

Combines all elements of an array using a reducer function, starting from the “head”, or left side, of the array.

In Array.reduce(fn, initial, array), fn is called with an accumulator and each element of the array, and returns a new accumulator. The final value is the last accumulator returned. The accumulator starts with value initial.

Parameters:

Returns:

Examples:

1

Array.reduce((acc, el) => acc + el, 0, [> 1, 2, 3]) == 6

1

Array.reduce((acc, el) => acc ++ el, "", [> "baz", "bar", "foo"]) == "bazbarfoo"

Array.reduceRight

1

reduceRight : (fn: ((a, b) => b), initial: b, array: Array<a>) => b

Combines all elements of an array using a reducer function, starting from the “end”, or right side, of the array.

In Array.reduceRight(fn, initial, array), fn is called with each element of the array and an accumulator, and returns a new accumulator. The final value is the last accumulator returned. The accumulator starts with value initial.

Parameters:

Returns:

Examples:

1

Array.reduceRight((el, acc) => acc ++ el, "", [> "baz", "bar", "foo"]) == "foobarbaz"

Array.reducei

1

reducei : (fn: ((a, b, Number) => a), initial: a, array: Array<b>) => a

Combines all elements of an array using a reducer function, starting from the “head”, or left side, of the array.

In Array.reducei(fn, initial, array), fn is called with an accumulator, each element of the array, and the index of that element, and returns a new accumulator. The final value is the last accumulator returned. The accumulator starts with value initial.

Parameters:

Returns:

Examples:

1

Array.reducei((acc, el, index) => acc + el + index, 0, [> 1, 2, 3]) == 9

1
2
3
4

let output = Array.reducei((acc, el, index) => {
  acc ++ el ++ toString(index)
}, "", [> "baz", "bar", "foo"])
assert output == "baz0bar1foo2"

Array.flatMap

1

flatMap : (fn: (b => Array<a>), array: Array<b>) => Array<a>

Produces a new array by calling a function on each element of the input array. Each iteration produces an intermediate array, which are all appended to produce a “flattened” array of all results.

Parameters:

Returns:

Throws:

InvalidArgument(String)

• When the combined length of all arrays is not an integer

Examples:

1

Array.flatMap(e => [> 1, e], [> 1, 2, 3]) == [> 1, 1, 1, 2, 1, 3]

Array.every

1

every : (fn: (a => Bool), array: Array<a>) => Bool

Checks that the given condition is satisfied for all elements in the input array.

Parameters:

Returns:

Examples:

1

Array.every(e => e % 2 == 0, [> 2, 4, 6]) == true

1

Array.every(e => e % 2 == 0, [> 2, 4, 7]) == false

Array.some

1

some : (fn: (a => Bool), array: Array<a>) => Bool

Checks that the given condition is satisfied at least once by an element in the input array.

Parameters:

Returns:

Examples:

1

Array.some(e => e % 2 == 0, [> 2, 4, 6]) == true

1

Array.some(e => e % 2 == 0, [> 2, 4, 7]) == true

1

Array.some(e => e % 2 == 0, [> 3, 5, 7]) == false

Array.fill

1

fill : (value: a, array: Array<a>) => Void

Replaces all elements in an array with the new value provided.

Parameters:

Examples:

1
2
3

let arr = [> 2, 4, 6]
Array.fill(0, arr)
assert arr == [> 0, 0, 0]

Array.fillRange

1

fillRange : (value: a, start: Number, stop: Number, array: Array<a>) => Void

Replaces all elements in the provided index range in the array with the new value provided. Fails if the index is out-of-bounds.

Parameters:

Throws:

IndexOutOfBounds

• When the start index is out of bounds
• When the start index is greater then the stop index

Examples:

1
2
3

let arr = [> 2, 4, 6, 8]
Array.fillRange(0, 1, 3, arr)
assert arr == [> 2, 0, 0, 8]

Array.reverse

1

reverse : (array: Array<a>) => Array<a>

Creates a new array with all elements in reverse order.

Parameters:

Returns:

Examples:

1

Array.reverse([> 1, 2, 3]) == [> 3, 2, 1]

Array.toList

1

toList : (array: Array<a>) => List<a>

Converts the input array to a list.

Parameters:

Returns:

Examples:

1

Array.toList([> 1, 2, 3]) == [1, 2, 3]

Array.fromList

1

fromList : (list: List<a>) => Array<a>

Converts the input list to an array.

Parameters:

Returns:

Examples:

1

Array.fromList([1, 2, 3]) == [> 1, 2, 3]

Array.contains

1

contains : (search: a, array: Array<a>) => Bool

Checks if the value is an element of the input array. Uses the generic == structural equality operator.

Parameters:

Returns:

Examples:

1

Array.contains(1, [> 1, 2, 3]) == true

1

Array.contains(0, [> 1, 2, 3]) == false

Array.find

1

find : (fn: (a => Bool), array: Array<a>) => Option<a>

Finds the first element in an array that satisfies the given condition.

Parameters:

Returns:

Examples:

1

Array.find(e => e % 2 == 0, [> 1, 4, 3]) == Some(4)

1

Array.find(e => e % 2 == 0, [> 1, 2, 3, 4]) == Some(2)

1

Array.find(e => e % 2 == 0, [> 1, 3, 5]) == None

Array.findIndex

1

findIndex : (fn: (a => Bool), array: Array<a>) => Option<Number>

Finds the first index in an array where the element satisfies the given condition.

Parameters:

Returns:

Examples:

1

Array.findIndex(e => e % 2 == 0, [> 1, 4, 3]) == Some(1)

1

Array.findIndex(e => e % 2 == 0, [> 1, 2, 3, 4]) == Some(1)

1

Array.findIndex(e => e % 2 == 0, [> 1, 3, 5]) == None

Array.product

1

product : (array1: Array<a>, array2: Array<b>) => Array<(a, b)>

Combines two arrays into a Cartesian product of tuples containing all ordered pairs (a, b).

Parameters:

Returns:

Throws:

InvalidArgument(String)

• When the multiplied array lengths are not an integer

Examples:

1

Array.product([> 1, 2], [> 3, 4]) == [> (1, 3), (1, 4), (2, 3), (2, 4)]

Array.count

1

count : (fn: (a => Bool), array: Array<a>) => Number

Counts the number of elements in an array that satisfy the given condition.

Parameters:

Returns:

Examples:

1

Array.count(e => e % 2 == 0, [> 1, 2, 3, 4]) == 2

Array.counti

1

counti : (fn: ((a, Number) => Bool), array: Array<a>) => Number

Counts the number of elements in an array that satisfy the given condition. Also passes the index to the function.

Parameters:

Returns:

Examples:

1

Array.counti((e, i) => e % 2 == 0 && i % 2 == 0, [> 1, 2, 3, 4, 5]) == 0

1

Array.counti((e, i) => e % 2 == 0 && i % 2 == 0, [> 0, 1, 2, 3, 5]) == 2

Array.filter

1

filter : (fn: (a => Bool), array: Array<a>) => Array<a>

Produces a new array by calling a function on each element of the input array and only including it in the result array if the element satisfies the condition.

Parameters:

Returns:

Examples:

1

Array.filter(e => e % 2 == 0, [> 1, 2, 3, 4]) == [> 2, 4]

Array.filteri

1

filteri : (fn: ((a, Number) => Bool), array: Array<a>) => Array<a>

Produces a new array by calling a function on each element of the input array and only including it in the result array if the element satisfies the condition. Also passes the index to the function.

Parameters:

Returns:

Examples:

1

Array.filteri((e, i) => e % 2 == 0, [> 1, 2, 3, 4]) == [> 2, 4]

1

Array.filteri((e, i) => e % 2 == 1 && i % 2 == 0, [> 1, 2, 3, 4, 5]) == [> 1, 3, 5]

Array.unique

1

unique : (array: Array<a>) => Array<a>

Produces a new array with any duplicates removed. Uses the generic == structural equality operator.

Parameters:

Returns:

Examples:

1

Array.unique([> 1, 2, 1, 2, 3, 1]) == [> 1, 2, 3]

Array.zip

1

zip : (array1: Array<a>, array2: Array<b>) => Array<(a, b)>

Produces a new array filled with tuples of elements from both given arrays. The first tuple will contain the first item of each array, the second tuple will contain the second item of each array, and so on.

Parameters:

Returns:

Throws:

IndexOutOfBounds

• When the arrays have different sizes

Examples:

1

Array.zip([> 1, 2, 3], [> 4, 5, 6]) == [> (1, 4), (2, 5), (3, 6)]

Array.zipWith

1

zipWith : (fn: ((a, b) => c), array1: Array<a>, array2: Array<b>) => Array<c>

Produces a new array filled with elements defined by applying a function on pairs from both given arrays. The first element will contain the result of applying the function to the first elements of each array, the second element will contain the result of applying the function to the second elements of each array, and so on.

Calling this function with arrays of different sizes will cause the returned array to have the length of the smaller array.

Parameters:

Returns:

Throws:

IndexOutOfBounds

• When the arrays have different sizes

Examples:

1

Array.zipWith((a, b) => a + b, [> 1, 2, 3], [> 4, 5, 6]) == [> 5, 7, 9]

1

Array.zipWith((a, b) => a * b, [> 1, 2, 3], [> 4, 5]) == [> 4, 10]

Array.unzip

1

unzip : (array: Array<(a, b)>) => (Array<a>, Array<b>)

Produces two arrays by splitting apart an array of tuples.

Parameters:

Returns:

Examples:

1

Array.unzip([> (1, 4), (2, 5), (3, 6)]) == ([> 1, 2, 3], [> 4, 5, 6])

Array.join

1

join : (separator: String, items: Array<String>) => String

Concatenates an array of strings into a single string, separated by a separator string.

Parameters:

Returns:

Examples:

1

Array.join(", ", [> "a", "b", "c"]) == "a, b, c"

Array.slice

1

slice : (start: Number, ?end: Number, array: Array<a>) => Array<a>

Slices an array given zero-based start and end indexes. The value at the end index will not be included in the result.

If either index is a negative number, it will be treated as a reverse index from the end of the array. e.g. slice(1, -1, [> 'a', 'b', 'c']) == [> 'b'].

Parameters:

Returns:

Examples:

1

Array.slice(1, end=3, [> 1, 2, 3, 4]) == [> 2, 3]

1

Array.slice(1, [> 1, 2, 3, 4]) == [> 2, 3, 4]

Array.sort

1

sort : (?compare: ((num1: a, num2: a) => Number), array: Array<a>) => Void

Sorts an array in-place.

Ordering is calculated using a comparator function which takes two array elements and must return 0 if both are equal, a positive number if the first is greater, and a negative number if the first is smaller.

Parameters:

Examples:

1
2
3

let arr = [> 3, 2, 4, 1]
Array.sort(compare=(a, b) => a - b, arr)
assert arr == [> 1, 2, 3, 4]

Array.rotate

1

rotate : (n: Number, arr: Array<a>) => Void

Rotates array elements in place by the specified amount to the left, such that the nth element becomes the first in the array.

If value is negative, array elements will be rotated by the specified amount to the right. See examples.

Parameters:

Examples:

1
2
3

let array = [> 1, 2, 3, 4, 5]
Array.rotate(2, array)
assert array == [> 3, 4, 5, 1, 2]

1
2
3

let array = [> 1, 2, 3, 4, 5]
Array.rotate(-1, array)
assert array == [> 5, 1, 2, 3, 4]

Array.chunk

1

chunk : (chunkSize: Number, arr: Array<a>) => Array<Array<a>>

Splits the given array into chunks of the provided size. If the array cannot be split evenly, the final chunk will contain the remaining elements.

Parameters:

Returns:

Throws:

InvalidArgument(String)

• When chunkSize is not an integer
• When chunkSize is less than one

Examples:

1

Array.chunk(2, [> 1, 2, 3, 4, 5]) == [> [> 1, 2], [> 3, 4], [> 5]]

1

Array.chunk(2, [> 1, 2, 3, 4]) == [> [> 1, 2], [> 3, 4]]

Array.Immutable

An immutable array implementation.

1

use Array.{ module Immutable }

1

Array.Immutable.empty

1

Immutable.fromList([1, 2, 3, 4, 5])

Types

Type declarations included in the Array.Immutable module.

Array.Immutable.ImmutableArray

1

type ImmutableArray<a>

Values

Functions and constants included in the Array.Immutable module.

Array.Immutable.empty

1

empty : ImmutableArray<a>

An empty array.

Examples:

1

Array.Immutable.empty == Array.Immutable.fromList([])

Array.Immutable.isEmpty

1

isEmpty : (array: ImmutableArray<a>) => Bool

Determines if the array contains no elements.

Parameters:

Returns:

Examples:

1
2

use Array.{ module Immutable }
assert Immutable.isEmpty(Immutable.fromList([1, 2, 3])) == false

1
2

use Array.{ module Immutable }
assert Immutable.isEmpty(Immutable.fromList([])) == true

Array.Immutable.length

1

length : (array: ImmutableArray<a>) => Number

Provides the length of the input array.

Parameters:

Returns:

Examples:

1
2

use Array.{ module Immutable }
assert Immutable.length(Immutable.fromList([1, 2, 3, 4, 5])) == 5

Array.Immutable.get

1

get : (index: Number, array: ImmutableArray<a>) => a

Retrieves the element from the array at the specified index. A negative index is treated as an offset from the end of the array.

Parameters:

Returns:

Throws:

IndexOutOfBounds

• When the index being accessed is outside the array’s bounds

Examples:

1
2

use Array.{ module Immutable }
assert Immutable.get(1, Immutable.fromList([1, 2, 3, 4])) == 2

1
2

use Array.{ module Immutable }
assert Immutable.get(-1, Immutable.fromList([1, 2, 3, 4])) == 4

Array.Immutable.set

1
2

set :
  (index: Number, value: a, array: ImmutableArray<a>) => ImmutableArray<a>

Creates a new array in which the element at the specified index is set to a new value. A negative index is treated as an offset from the end of the array.

Parameters:

Returns:

Throws:

IndexOutOfBounds

• When the index being updated is outside the array’s bounds

Examples:

1
2
3
4
5

use Array.{ module Immutable }
let arr = Immutable.fromList([1, 2, 3, 4, 5])
let array = Immutable.set(1, 9, arr)
assert arr == Immutable.fromList([1, 2, 3, 4, 5])
assert array == Immutable.fromList([1, 9, 3, 4, 5])