Array

You can create an Array using the [1, 2, 3] syntax. This module has a bunch of functions to help you work with them.

type Array

An Array is an ordered collection of elements.

Create

empty : Array a

An empty array.

singleton : a -> Array a

Create an array containing a single value.

initialize : Int -> Int -> (Int -> a) -> Array a

Create an array of n elements, containing the elements resulting from calling fn with offset + index.

initialize 3 5 identity == [ 5, 6, 7 ]

In the above example, we create an array containing 3 integers starting at 5.

repeat : Int -> a -> Array a

Create an array with n copies of a value:

repeat 5 3 == [ 3, 3, 3, 3, 3 ]
range : Int -> Int -> Array Int

Create a list of numbers, every element increasing by one. You give the lowest and highest number that should be in the list.

range 3 6 == [3, 4, 5, 6]
range 3 3 == [3]
range 6 3 == []

Transform

map : (a -> b) -> Array a -> Array b

Apply a function on every element in an array.

map negate [ 1, 4, 9 ] == [ -1, -4, -9 ]

So map func [ a, b, c ] is the same as [ func a, func b, func c ]

indexedMap : (Int -> a -> b) -> Array a -> Array b

Same as map but the function is also applied to the index of each element.

indexedMap (\idx val -> [idx, val]) [ 3, 3, 3 ] == [ [ 0, 3 ], [ 1, 3 ], [ 2, 3 ] ]
foldl : (a -> b -> b) -> b -> Array a -> b

Reduce the array from the left.

foldl (+) 0 [ 1, 2, 3 ] == 6

So `foldl step state [ 1, 2, 3 ] is like saying:

state
    |> step 1
    |> step 2
    |> step 3
foldr : (a -> b -> b) -> b -> Array a -> b

Reduce the array from the right. Same as foldl but the execution order is reversed.

filter : (a -> Bool) -> Array a -> Array a

Keep values that pass the test.

filter (\n -> n < 3) [ 1, 2, 3, 4 ] == [ 1, 2 ]
filterMap : (a -> Maybe b) -> Array a -> Array b

Filter out unwanted results of a map operation.

filterMap String.toInt [ "3", "not a number", "-5" ] == [ 3, -5 ]
filterMap identity [ Just 1, Nothing ] == [ 1 ]
reverse : Array a -> Array a

Reverse an array.

reverse [ 1, 2, 3 ] == [ 3, 2, 1 ]

Query

isEmpty : Array a -> Bool

Check if an array is empty.

isEmpty [] == True
isEmpty [ 1, 2, 3 ] == False
length : Array a -> Int

Return the length of an array.

length [ 1, 2, 3 ] == 3
get : Int -> Array a -> Maybe a

Retrieve the element at a given index, or Nothing if the index is out of bounds.

get 1 [ 1, 2, 3 ] == Just 2
get 10 [ 1, 2, 3 ] == Nothing
findFirst : (a -> Bool) -> Array a -> Maybe a

Find the first value that passes the test.

find (\n -> n > 0) [ -1, 0, 1, 2 ] == Just 1
findLast : (a -> Bool) -> Array a -> Maybe a

Find the last value that passes the test.

find (\n -> n > 0) [ -1, 0, 1, 2 ] == Just 2
member : a -> Array a -> Bool

Figure out whether an array contains a value.

member 9 [1,2,3,4] == False
member 4 [1,2,3,4] == True
any : (a -> Bool) -> Array a -> Bool

Determine if any elements pass the test.

any isEven [2,3] == True
any isEven [1,3] == False
any isEven [] == False
all : (a -> Bool) -> Array a -> Bool

Determine if all elements pass the test.

all isEven [2,4] == True
all isEven [2,3] == False
all isEven [] == True
minimum : Array comparable -> Maybe comparable

Find the minimum element in a non-empty list.

minimum [3,2,1] == Just 1
minimum []      == Nothing
maximum : Array comparable -> Maybe comparable

Find the maximum element in a non-empty list.

maximum [3,2,1] == Just 3
maximum []      == Nothing

Modify

set : Int -> a -> Array a -> Array a

Replaces the element at the given index, or returns the array unmodified if the index is out of bounds.

set 1 10 [ 1, 2, 3 ] == [ 1, 10, 3 ]
set 10 10 [ 1, 2, 3 ] == [ 1, 2, 3 ]
update : Int -> (a -> a) -> Array a -> Array a

Update a value at the given index using a function. If the index is out of bounds, nothing happens.

update 1 (\n -> n + 1) [ 1, 2, 3 ] == [ 1, 3, 3 ]
update 10 (\n -> n + 1) [ 1, 2, 3 ] == [ 1, 2, 3 ]
pushFirst : a -> Array a -> Array a

Add a value to the start of the array.

pushFirst 1 []          == [ 1 ]
pushFirst 5 [ 1, 4, 9 ] == [ 5, 1, 4, 9 ]
pushLast : a -> Array a -> Array a

Add a value to the end of the array.

pushLast 1 []          == [ 1 ]
pushLast 5 [ 1, 4, 9 ] == [ 1, 4, 9, 5 ]

Combine

prefix : Array a -> Array a -> Array a

Combine two arrays so that the first array becomes the prefix, and the second array becomes the postfix of the resulting array.

prefix [ 1, 2, 3 ] [ 4, 5, 6 ] == [ 1, 2, 3, 4, 5, 6 ] 

You can also use the ++ operator for this purpose.

[ 1, 2, 3 ] ++ [ 4, 5, 6 ] == [ 1, 2, 3, 4, 5, 6 ]
postfix : Array a -> Array a -> Array a

Combine two arrays so that the first array becomes the postfix, and the second array becomes the prefix of the resulting array.

postfix [ 1, 2, 3 ] [ 4, 5, 6 ] == [ 4, 5, 6, 1, 2, 3 ]
flatten : Array (Array a) -> Array a

Combine a bunch of arrays into a single array.

flatten [ [ 1 ], [ 2 ], [ 4, 5 ] ] == [ 1, 2, 4, 5 ]
flatMap : (a -> Array b) -> Array a -> Array b

Map a given function onto an array, then flatten the resulting array.

flatMap f xs == flatten (map f xs)
intersperse : a -> Array a -> Array a

Places the given value between all members of the given list.

intersperse "on" [ "turtles", "turtles", "turtles"] == [ "turtles", "on", "turtles", "on", "turtles"]
map2 : (a -> b -> result) -> Array a -> Array b -> Array result

Combine two arrays, combining them with the given function. If one array is longer, the extra elements are dropped.

map2 (\x y -> { x = x, y = y }) [ 1 ] [ 2 ] == [ { x = 1, y = 2 } ]
map3 : (a -> b -> c -> result) -> Array a -> Array b -> Array c -> Array result

Combine three arrays, combining them with the given function. If one array is longer, the extra elements are dropped.

map3 (\x y z -> { x = x, y = y, z = z }) [ 1 ] [ 2 ] [ 3 ] == [ { x = 1, y = 2, z = 3 } ]

Deconstruct

slice : Int -> Int -> Array a -> Array a

Get a sub section of an array: (slice start end array).

The start is a zero-based index where we will start our slice. The end is a zero-based index that indicates the end of the slice. The slice extracts up to, but no including, the end.

Both start and end can be negative, indicating an offset from the end of the array. Removing the last element of the array can be expressed as:

`slice 0 -1 arr`.

In the case of an impossible slice, the empty array is returned.

dropFirst : Int -> Array a -> Array a

Remove the first n elements of the array.

dropFirst 5 [ 1 ] == []
dropFirst 1 [ 1, 2, 3 ] == [ 2, 3 ]
dropLast : Int -> Array a -> Array a

Remove the last n elements of the array.

dropLast 1 [ 1, 2, 3 ] == [ 1, 2 ]
takeFirst : Int -> Array a -> Array a

Take the first n elements from the array.

takeFirst 2 [ 1, 2, 3 ] == [ 1, 2 ]
takeLast : Int -> Array a -> Array a

Take the last n elements from the array.

takeLast 2 [ 1, 2, 3 ] == [ 2, 3 ]
popFirst : Array a -> Maybe { first : a, rest : Array a }

Split an array into its first element, and its remaining elements, if possible.

popFirst [ 1, 2, 3 ] == Just { first = 1, rest = [ 2, 3 ] }
popLast : Array a -> Maybe { last : a, initial : Array a }

Split an array into its last element, and its remaining elements, if possible.

popFirst [ 1, 2, 3 ] == Just { last = 3, initial = [ 1, 2 ] }
first : Array a -> Maybe a

Retrieve the first element of the array, if it exists.

first [ 1, 2, 3 ] == Just 1
last : Array a -> Maybe a

Retrieve the last element of the array, if it exists.

last [ 1, 2, 3 ] == Just 3
partition : (a -> Bool) -> Array a -> { trues : Array a, falses : Array a }

Divide elements into two arrays based on the result of a boolean test.

partition (\x -> x < 3) [ 0, 1, 2, 3, 4, 5 ] == { trues = [ 0, 1, 2 ], falses = [ 3, 4, 5 ] }

Sort

sort : Array comparable -> Array comparable

Sort values from lowest to highest

sort [ 3, 1, 5 ] == [ 1, 3, 5 ]
sortBy : (a -> comparable) -> Array a -> Array a

Sort values by a derived property.

sortBy String.length [ "mouse", "cat" ] == [ "cat", "mouse" ]
sortWith : (a -> a -> Order) -> Array a -> Array a

Sort values with a custom comparison function.

sortWith flippedComparison [1,2,3,4,5] == [5,4,3,2,1]

flippedComparison a b =
    case compare a b of
      LT -> GT
      EQ -> EQ
      GT -> LT

This is also the most general sort function, allowing you to define any other: sort == sortWith compare