List

A library for manipulating lists of values. Every value in a list must have the same type.

Basics

isEmpty : List a -> Bool

Determine if a list is empty.

isEmpty [] == True

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..4] == [4,3,2,1]

member : a -> List a -> Bool

Sub-lists

head : List a -> a

Extract the first element of a list. List must be non-empty.

head [1,2,3] == 1

tail : List a -> List a

Extract the elements after the head of the list. List must be non-empty.

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

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

Keep only elements that satisfy the predicate.

filter isEven [1..6] == [2,4,6]

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]

Putting Lists Together

repeat : Int -> a -> List a

Create a list with n copies of a value:

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

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

Add an element to the front of a list. Pronounced cons.

1 :: [2,3] == [1,2,3]
1 :: [] == [1]

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']

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]

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"]

Taking Lists Apart

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

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

partition (\x -> x < 3) [0..5] == ([0,1,2], [3,4,5])
partition isEven        [0..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])

Mapping

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]

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.

map2 (+) [1,2,3] [1,2,3,4] == [2,4,6]


map2 (,) [1,2,3] ['a','b'] == [ (1,'a'), (2,'b') ]


pairs : List a -> List b -> List (a,b)
pairs lefts rights =
    map2 (,) lefts rights

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

map4 :

(a -> b -> c -> d -> result)

-> List a

-> List b

-> List c

-> List d

-> List result

map5 :

(a -> b -> c -> d -> e -> result)

-> List a

-> List b

-> List c

-> List d

-> List e

-> List result

If you can think of a legitimate use of mapN where N is 6 or more, please let us know on the list. The current sentiment is that it is already quite error prone once you get to 4 and possibly should be approached another way.

Special Maps

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

Apply a function that may succeed to all values in the list, but only keep the successes.

String.toInt : String -> Maybe Int


filterMap String.toInt ["3", "4.0", "5", "hats"] == [3,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)

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 (,) ["Tom","Sue","Bob"] == [ (0,"Tom"), (1,"Sue"), (2,"Bob") ]

Folding

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

Reduce a list from the right.

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

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

Reduce a list from the left.

foldl (::) [] [1,2,3] == [3,2,1]

Special Folds

sum : List number -> number

Get the sum of the list elements.

sum [1..4] == 10

product : List number -> number

Get the product of the list elements.

product [1..4] == 24

maximum : List comparable -> comparable

Find the maximum element in a non-empty list.

maximum [1,4,2] == 4

minimum : List comparable -> comparable

Find the minimum element in a non-empty list.

minimum [3,2,1] == 1

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

Determine if all elements satisfy the predicate.

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

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

Determine if any elements satisfy the predicate.

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

foldr1 : (a -> a -> a) -> List a -> a

Reduce a list from the right without a base case. List must be non-empty.

foldl1 : (a -> a -> a) -> List a -> a

Reduce a list from the left without a base case. List must be non-empty.

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

Reduce a list from the left, building up all of the intermediate results into a list.

scanl (+) 0 [1,2,3,4] == [0,1,3,6,10]

scanl1 : (a -> a -> a) -> List a -> List a

Same as scanl but it doesn't require a base case. List must be non-empty.

scanl1 (+) [1,2,3,4] == [1,3,6,10]

Sorting

sort : List comparable -> List comparable

Sort values from lowest to highest

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

sortBy : (a -> comparable) -> 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 -> Order) -> List a -> List a

Sort values with a custom comparison function.

sortWith flippedComparison [1..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

elm-lang/core/1.1.1