List

You can create a List in Elm with the [1,2,3] syntax, so lists are used all over the place. This module has a bunch of functions to help you work with them!

Documentation

type List a = [a]

In Haskell a list type is defined using square brackets. This alias allows us to alternatively write the type like we would in Elm.

Create

singleton :: a -> List a

Create a list with only one element:

singleton 1234 == [1234]
singleton "hi" == ["hi"]

repeat :: Int -> a -> List a

Create a list with *n* copies of a value:

repeat 3 (0,0) == [(0,0),(0,0),(0,0)]

range :: Int -> Int -> List 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) -> List a -> List b

Apply a function to every element of a list.

map sqrt [1,4,9] == [1,2,3]
map not [True,False,True] == [False,True,False]

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

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

Same as map but the function is also applied to the index of each element (starting at zero).

indexedMap Tuple.pair ["Tom","Sue","Bob"] == [ (0,"Tom"), (1,"Sue"), (2,"Bob") ]

foldl :: (a -> b -> b) -> b -> List a -> b

Reduce a list from the left.

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

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

state
  |> step 1
  |> step 2
  |> step 3

Note: This function is implemented using fold' to eagerly evaluate the accumulator, preventing space leaks.

foldr :: (a -> b -> b) -> b -> List a -> b

Reduce a list from the right.

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

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

state
  |> step 3
  |> step 2
  |> step 1

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

Keep elements that satisfy the test.

filter isEven [1,2,3,4,5,6] == [2,4,6]

filterMap :: (a -> Maybe b) -> List a -> List b

Filter out certain values. For example, maybe you have a bunch of strings from an untrusted source and you want to turn them into numbers:

numbers : List Int
numbers =
  filterMap String.toInt ["3", "hi", "12", "4th", "May"]
-- numbers == [3, 12]

Utilities

length :: List a -> Int

Determine the length of a list.

length [1,2,3] == 3

reverse :: List a -> List a

Reverse a list. > reverse [1,2,3,4] == [4,3,2,1]

member :: Eq a => a -> List a -> Bool

Figure out whether a list contains a value.

member 9 [1,2,3,4] == False
member 4 [1,2,3,4] == True

all :: (a -> Bool) -> List a -> Bool

Determine if all elements satisfy some test.

all isEven [2,4] == True
all isEven [2,3] == False
all isEven [] == True

any :: (a -> Bool) -> List a -> Bool

Determine if any elements satisfy some test.

any isEven [2,3] == True
any isEven [1,3] == False
any isEven [] == False

maximum :: Ord a => List a -> Maybe a

Find the maximum element in a non-empty list.

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

minimum :: Ord a => List a -> Maybe a

Find the minimum element in a non-empty list.

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

sum :: Num a => List a -> a

Get the sum of the list elements.

sum [1,2,3,4] == 10

product :: Num a => List a -> a

Get the product of the list elements.

product [1,2,3,4] == 24

Combine

append :: List a -> List a -> List a

Put two lists together.

append [1,1,2] [3,5,8] == [1,1,2,3,5,8]
append ['a','b'] ['c'] == ['a','b','c']

You can also use the (++) operator to append lists.

concat :: List (List a) -> List a

Concatenate a bunch of lists into a single list:

concat [[1,2],[3],[4,5]] == [1,2,3,4,5]

concatMap :: (a -> List b) -> List a -> List b

Map a given function onto a list and flatten the resulting lists.

concatMap f xs == concat (map f xs)

intersperse :: a -> List a -> List 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) -> List a -> List b -> List result

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

totals : List Int -> List Int -> List Int
totals xs ys =
  List.map2 (+) xs ys

-- totals [1,2,3] [4,5,6] == [5,7,9]

pairs : List a -> List b -> List (a,b)
pairs xs ys =
  List.map2 Tuple.pair xs ys

-- pairs ["alice","bob","chuck"] [2,5,7,8]
--   == [("alice",2),("bob",5),("chuck",7)]

Note: This behaves differently than map2, which produces all combinations of elements from both lists.

map3 :: (a -> b -> c -> result) -> List a -> List b -> List c -> List result

Note: This behaves differently than map3, which produces all combinations of elements from all lists.

map4 :: (a -> b -> c -> d -> result) -> List a -> List b -> List c -> List d -> List result

Note: This behaves differently than map4, which produces all combinations of elements from all lists.

map5 :: (a -> b -> c -> d -> e -> result) -> List a -> List b -> List c -> List d -> List e -> List result

Note: This behaves differently than map5, which produces all combinations of elements from all lists.

Sort

sort :: Ord a => List a -> List a

Sort values from lowest to highest

sort [3,1,5] == [1,3,5]

sortBy :: Ord b => (a -> b) -> List a -> List a

Sort values by a derived property.

alice = { name="Alice", height=1.62 }
bob   = { name="Bob"  , height=1.85 }
chuck = { name="Chuck", height=1.76 }

sortBy .name   [chuck,alice,bob] == [alice,bob,chuck]
sortBy .height [chuck,alice,bob] == [alice,chuck,bob]

sortBy String.length ["mouse","cat"] == ["cat","mouse"]

sortWith :: (a -> a -> Ordering) -> List a -> List 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

Deconstruct

isEmpty :: List a -> Bool

Determine if a list is empty.

isEmpty [] == True

Note: It is usually preferable to use a case to test this so you do not forget to handle the (x :: xs) case as well!

head :: List a -> Maybe a

Extract the first element of a list.

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

Note: It is usually preferable to use a case to deconstruct a List because it gives you (x :: xs) and you can work with both subparts.

tail :: List a -> Maybe (List a)

Extract the rest of the list.

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

Note: It is usually preferable to use a case to deconstruct a List because it gives you (x :: xs) and you can work with both subparts.

take :: Int -> List a -> List a

Take the first *n* members of a list.

take 2 [1,2,3,4] == [1,2]

drop :: Int -> List a -> List a

Drop the first *n* members of a list.

drop 2 [1,2,3,4] == [3,4]

partition :: (a -> Bool) -> List a -> (List a, List a)

Partition a list based on some test. The first list contains all values that satisfy the test, and the second list contains all the value that do not.

partition (\x -> x < 3) [0,1,2,3,4,5] == ([0,1,2], [3,4,5])
partition isEven        [0,1,2,3,4,5] == ([0,2,4], [1,3,5])

unzip :: List (a, b) -> (List a, List b)

Decompose a list of tuples into a tuple of lists.

unzip [(0, True), (17, False), (1337, True)] == ([0,17,1337], [True,False,True])