@@ -4,29 +4,34 @@ module List where
44import Native.Utils (min, max)
55import Native.List as L
66
7−-- Add an element to the front of a list
8−-- a :: [b,c] = [a,b,c]
7+-- Add an element to the front of a list `(1 :: [2,3] == [1,2,3])`
98(::) : a -> [a] -> [a]
109
11−-- Appends two lists.
10+-- Puts two appendable things together:
11+--
12+-- [1,1] ++ [2,3] == [1,1,2,3]
13+-- "abc" ++ "123" == "abc123"
1214(++) : Appendable a -> Appendable a -> Appendable a
1315
1416-- Extract the first element of a list. List must be non-empty.
17+-- `(head [1,2,3] == 1)`
1518head : [a] -> a
1619
1720-- Extract the elements after the head of the list. List must be non-empty.
21+-- `(tail [1,2,3] == [2,3])`
1822tail : [a] -> [a]
1923
2024-- Extract the last element of a list. List must be non-empty.
25+-- `(last [1,2,3] == 3)`
2126last : [a] -> a
2227
23−-- Apply a function to every element of a list.
28+-- Apply a function to every element of a list: `(map sqrt [1,4,9] == [1,2,3])`
2429map : (a -> b) -> [a] -> [b]
2530
26−-- Reduce a list from the left.
31+-- Reduce a list from the left: `(foldl (::) [] "gateman" == "nametag")`
2732foldl : (a -> b -> b) -> b -> [a] -> b
2833
29−-- Reduce a list from the right.
34+-- Reduce a list from the right: `(foldr (+) 0 [1,2,3] == 6)`
3035foldr : (a -> b -> b) -> b -> [a] -> b
3136
3237-- Reduce a list from the left without a base case. List must be non-empty.
@@ -36,18 +41,22 @@ foldl1 : (a -> a -> a) -> [a] -> a
3641foldr1 : (a -> a -> a) -> [a] -> a
3742
3843-- Reduce a list from the left, building up all of the intermediate results into a list.
44+--
45+-- scanl (+) 0 [1,2,3,4] == [0,1,3,6,10]
3946scanl : (a -> b -> b) -> b -> [a] -> [b]
4047
4148-- Same as scanl but it doesn't require a base case. List must be non-empty.
49+--
50+-- scanl1 (+) [1,2,3,4] == [1,3,6,10]
4251scanl1 : (a -> a -> a) -> [a] -> [a]
4352
44−-- Filter out elements which do not satisfy the predicate.
53+-- Filter out elements which do not satisfy the predicate: `(filter isLower "AaBbCc" == "abc")`
4554filter : (a -> Bool) -> [a] -> [a]
4655
47−-- Determine the length of a list.
56+-- Determine the length of a list: `(length "innumerable" == 11)`
4857length : [a] -> Int
4958
50−-- Reverse a list.
59+-- Reverse a list. `(reverse [1..4] == [4,3,2,1])`
5160reverse : [a] -> [a]
5261
5362-- Check to see if all elements satisfy the predicate.
@@ -62,29 +71,31 @@ and : [Bool] -> Bool
6271-- Check to see if any elements are True.
6372or : [Bool] -> Bool
6473
65−-- Flatten a list of lists.
74+-- Concatenate a list of appendable things:
75+--
76+-- concat ["tree","house"] == "treehouse"
6677concat : [Appendable a] -> Appendable a
6778
6879-- Map a given function onto a list and flatten the resulting lists.
6980--
70−-- concatMap f xs == concat (map f xs)
81+-- concatMap f xs == concat (map f xs)
7182concatMap : (a -> Appendable b) -> [a] -> Appendable b
7283concatMap f = L.concat . L.map f
7384
74−-- Get the sum of the list elements.
85+-- Get the sum of the list elements. `(sum [1..4] == 10)`
7586sum : [Number a] -> Number a
7687sum = L.foldl (+) 0
7788
78−-- Get the product of the list elements.
89+-- Get the product of the list elements. `(product [1..4] == 24)`
7990product : [Number a] -> Number a
8091product = L.foldl (*) 1
8192
8293-- Find the highest number in a non-empty list.
83−maximum : [Comparable a] -> Comparable a
94+maximum : [Number a] -> Number a
8495maximum = L.foldl1 max
8596
8697-- Find the lowest number in a non-empty list.
87−minimum : [Comparable a] -> Comparable a
98+minimum : [Number a] -> Number a
8899minimum = L.foldl1 min
89100
90101-- Split a list based on the predicate.
@@ -95,13 +106,20 @@ partition pred lst =
95106 x::xs -> let (bs,cs) = partition pred xs in
96107 if pred x then (x::bs,cs) else (bs,x::cs)
97108
98−-- Combine two lists, combining them into tuples pairwise. If one input list has extra elements (it is longer), those elements are dropped.
109+-- Combine two lists, combining them into tuples pairwise.
110+-- If one list is longer, the extra elements are dropped.
111+--
112+-- zip [1,2,3] [6,7] == [(1,6),(2,7)]
113+-- zip == zipWith (,)
99114zip : [a] -> [b] -> [(a,b)]
100115
101−-- Combine two lists, combining them with the given function. If one input list has extra elements (it is longer), those elements are dropped.
116+-- Combine two lists, combining them with the given function.
117+-- If one list is longer, the extra elements are dropped.
118+--
119+-- zipWith (+) [1,2,3] [1,2,3,4] == [2,4,6]
102120zipWith : (a -> b -> c) -> [a] -> [b] -> [c]
103121
104−-- Decompose a list of tuples
122+-- Decompose a list of tuples.
105123unzip : [(a,b)] -> ([a],[b])
106124unzip pairs =
107125 case pairs of
@@ -120,6 +138,8 @@ split : [a] -> [a] -> [[a]]
120138join : Appendable a -> [Appendable a] -> Appendable a
121139
122140-- Places the given value between all members of the given list.
141+--
142+-- intersperse ' ' "INCEPTION" == "I N C E P T I O N"
123143intersperse : a -> [a] -> [a]
124144intersperse sep xs =
125145 case xs of
@@ -127,11 +147,9 @@ intersperse sep xs =
127147 [a] -> [a]
128148 [] -> []
129149
130−-- Take the first n members of a list.
131−-- take 2 [1,2,3,4]) ==> [1,2]
150+-- Take the first n members of a list: `(take 2 [1,2,3,4] == [1,2])`
132151take : Int -> [a] -> [a]
133152
134−-- Drop the first n members of a list.
135−-- drop 2 [1,2,3,4]) ==> [3,4]
153+-- Drop the first n members of a list: `(drop 2 [1,2,3,4] == [3,4])`
136154drop : Int -> [a] -> [a]
137155