@@ -4,128 +4,163 @@ module List where
44import open Basics
55import Native.List
66
7−-- Add an element to the front of a list `(1 :: [2,3] == [1,2,3])`
7+{-| DOCUMENT STRUCTURE
8+
9+A library for manipulating lists of values. Every value in a list must have
10+the same type.
11+
12+# Basics
13+@docs (::), (++), length, reverse, map
14+
15+# Sub-lists
16+@docs head, tail, last, filter, take, drop
17+
18+# Putting Lists Together
19+@docs concat, concatMap, join, intersperse, zip, zipWith
20+
21+# Taking Lists Apart
22+@docs split, partition, unzip
23+
24+# Folds
25+@docs foldr, foldl, foldr1, foldl1, scanl, scanl1
26+
27+# Special Folds
28+@docs susm, product, maximum, minimum, all, any, and, or
29+
30+-}
31+
32+{-| Add an element to the front of a list `(1 :: [2,3] == [1,2,3])` -}
833(::) : a -> [a] -> [a]
934(::) = Native.List.cons
1035
11−-- Puts two appendable things together:
12−--
13−-- [1,1] ++ [2,3] == [1,1,2,3]
14−-- "abc" ++ "123" == "abc123"
36+{-| Puts two appendable things together:
37+
38+ [1,1] ++ [2,3] == [1,1,2,3]
39+ "abc" ++ "123" == "abc123"
40+-}
1541(++) : appendable -> appendable -> appendable
1642(++) = Native.List.append
1743
18−-- Extract the first element of a list. List must be non-empty.
19−-- `(head [1,2,3] == 1)`
44+{-| Extract the first element of a list. List must be non-empty.
45+`(head [1,2,3] == 1)`
46+-}
2047head : [a] -> a
2148head = Native.List.head
2249
23−-- Extract the elements after the head of the list. List must be non-empty.
24−-- `(tail [1,2,3] == [2,3])`
50+{-| Extract the elements after the head of the list. List must be non-empty.
51+`(tail [1,2,3] == [2,3])`
52+-}
2553tail : [a] -> [a]
2654tail = Native.List.tail
2755
28−-- Extract the last element of a list. List must be non-empty.
29−-- `(last [1,2,3] == 3)`
56+{-| Extract the last element of a list. List must be non-empty.
57+`(last [1,2,3] == 3)`
58+-}
3059last : [a] -> a
3160last = Native.List.last
3261
33−-- Check if a list is empty `(isEmpty [] == True)`
62+{-| Check if a list is empty `(isEmpty [] == True)` -}
3463isEmpty : [a] -> Bool
3564isEmpty xs =
3665 case xs of
3766 [] -> True
3867 _ -> False
3968
40−-- Apply a function to every element of a list: `(map sqrt [1,4,9] == [1,2,3])`
69+{-| Apply a function to every element of a list: `(map sqrt [1,4,9] == [1,2,3])` -}
4170map : (a -> b) -> [a] -> [b]
4271map = Native.List.map
4372
44−-- Reduce a list from the left: `(foldl (::) [] "gateman" == "nametag")`
73+{-| Reduce a list from the left: `(foldl (::) [] "gateman" == "nametag")` -}
4574foldl : (a -> b -> b) -> b -> [a] -> b
4675foldl = Native.List.foldl
4776
48−-- Reduce a list from the right: `(foldr (+) 0 [1,2,3] == 6)`
77+{-| Reduce a list from the right: `(foldr (+) 0 [1,2,3] == 6)` -}
4978foldr : (a -> b -> b) -> b -> [a] -> b
5079foldr = Native.List.foldr
5180
52−-- Reduce a list from the left without a base case. List must be non-empty.
81+{-| Reduce a list from the left without a base case. List must be non-empty. -}
5382foldl1 : (a -> a -> a) -> [a] -> a
5483foldl1 = Native.List.foldl1
5584
56−-- Reduce a list from the right without a base case. List must be non-empty.
85+{-| Reduce a list from the right without a base case. List must be non-empty. -}
5786foldr1 : (a -> a -> a) -> [a] -> a
5887foldr1 = Native.List.foldr1
5988
60−-- Reduce a list from the left, building up all of the intermediate results into a list.
61−--
62−-- scanl (+) 0 [1,2,3,4] == [0,1,3,6,10]
89+{-| Reduce a list from the left, building up all of the intermediate results into a list.
90+
91+ scanl (+) 0 [1,2,3,4] == [0,1,3,6,10]
92+-}
6393scanl : (a -> b -> b) -> b -> [a] -> [b]
6494scanl = Native.List.scanl
6595
66−-- Same as scanl but it doesn't require a base case. List must be non-empty.
67−--
68−-- scanl1 (+) [1,2,3,4] == [1,3,6,10]
96+{-| Same as scanl but it doesn't require a base case. List must be non-empty.
97+
98+ scanl1 (+) [1,2,3,4] == [1,3,6,10]
99+-}
69100scanl1 : (a -> a -> a) -> [a] -> [a]
70101scanl1 = Native.List.scanl1
71102
72−-- Filter out elements which do not satisfy the predicate: `(filter isLower "AaBbCc" == "abc")`
103+{-| Keep only elements that satisfy the predicate:
104+`(filter isLower "AaBbCc" == "abc")`
105+-}
73106filter : (a -> Bool) -> [a] -> [a]
74107filter = Native.List.filter
75108
76−-- Determine the length of a list: `(length "innumerable" == 11)`
109+{-| Determine the length of a list: `(length "innumerable" == 11)` -}
77110length : [a] -> Int
78111length = Native.List.length
79112
80−-- Reverse a list. `(reverse [1..4] == [4,3,2,1])`
113+{-| Reverse a list. `(reverse [1..4] == [4,3,2,1])` -}
81114reverse : [a] -> [a]
82115reverse = Native.List.reverse
83116
84−-- Check to see if all elements satisfy the predicate.
117+{-| Check to see if all elements satisfy the predicate. -}
85118all : (a -> Bool) -> [a] -> Bool
86119all = Native.List.all
87120
88−-- Check to see if any elements satisfy the predicate.
121+{-| Check to see if any elements satisfy the predicate. -}
89122any : (a -> Bool) -> [a] -> Bool
90123any = Native.List.any
91124
92−-- Check to see if all elements are True.
125+{-| Check to see if all elements are True. -}
93126and : [Bool] -> Bool
94127and = foldl (&&) True
95128
96−-- Check to see if any elements are True.
129+{-| Check to see if any elements are True. -}
97130or : [Bool] -> Bool
98131or = foldl (||) False
99132
100−-- Concatenate a list of appendable things:
101−--
102−-- concat ["tree","house"] == "treehouse"
133+{-| Concatenate a list of appendable things:
134+
135+ concat ["tree","house"] == "treehouse"
136+-}
103137concat : [appendable] -> appendable
104138concat = Native.List.concat
105139
106−-- Map a given function onto a list and flatten the resulting lists.
107−--
108−-- concatMap f xs == concat (map f xs)
140+{-| Map a given function onto a list and flatten the resulting lists.
141+
142+ concatMap f xs == concat (map f xs)
143+-}
109144concatMap : (a -> appendable) -> [a] -> appendable
110145concatMap f list = concat (map f list)
111146
112−-- Get the sum of the list elements. `(sum [1..4] == 10)`
147+{-| Get the sum of the list elements. `(sum [1..4] == 10)` -}
113148sum : [number] -> number
114149sum = foldl (+) 0
115150
116−-- Get the product of the list elements. `(product [1..4] == 24)`
151+{-| Get the product of the list elements. `(product [1..4] == 24)` -}
117152product : [number] -> number
118153product = foldl (*) 1
119154
120−-- Find the maximum element in a non-empty list: `maximum [1,4,2] == 4`
155+{-| Find the maximum element in a non-empty list: `maximum [1,4,2] == 4` -}
121156maximum : [comparable] -> comparable
122157maximum = foldl1 max
123158
124−-- Find the minimum element in a non-empty list: `minimum [3,2,1] == 1`
159+{-| Find the minimum element in a non-empty list: `minimum [3,2,1] == 1` -}
125160minimum : [comparable] -> comparable
126161minimum = foldl1 min
127162
128−-- Split a list based on the predicate.
163+{-| Split a list based on the predicate. -}
129164partition : (a -> Bool) -> [a] -> ([a],[a])
130165partition pred lst =
131166 case lst of
@@ -133,44 +168,49 @@ partition pred lst =
133168 x::xs -> let (bs,cs) = partition pred xs in
134169 if pred x then (x::bs,cs) else (bs,x::cs)
135170
136−-- Combine two lists, combining them into tuples pairwise.
137−-- If one list is longer, the extra elements are dropped.
138−--
139−-- zip [1,2,3] [6,7] == [(1,6),(2,7)]
140−-- zip == zipWith (,)
171+{-| Combine two lists, combining them into tuples pairwise.
172+If one list is longer, the extra elements are dropped.
173+
174+ zip [1,2,3] [6,7] == [(1,6),(2,7)]
175+ zip == zipWith (,)
176+-}
141177zip : [a] -> [b] -> [(a,b)]
142178zip = Native.List.zip
143179
144−-- Combine two lists, combining them with the given function.
145−-- If one list is longer, the extra elements are dropped.
146−--
147−-- zipWith (+) [1,2,3] [1,2,3,4] == [2,4,6]
180+{-| Combine two lists, combining them with the given function.
181+If one list is longer, the extra elements are dropped.
182+
183+ zipWith (+) [1,2,3] [1,2,3,4] == [2,4,6]
184+-}
148185zipWith : (a -> b -> c) -> [a] -> [b] -> [c]
149186zipWith = Native.List.zipWith
150187
151−-- Decompose a list of tuples.
188+{-| Decompose a list of tuples. -}
152189unzip : [(a,b)] -> ([a],[b])
153190unzip pairs =
154191 case pairs of
155192 [] -> ([],[])
156193 (x,y)::ps -> let (xs,ys) = (unzip ps) in (x::xs,y::ys)
157194
158−-- Split a list with a given seperator.
159−--
160−-- split "," "hello,there,friend" == ["hello", "there", "friend"]
195+{-| Split a list with a given seperator.
196+
197+ split "," "hello,there,friend" == ["hello", "there", "friend"]
198+-}
161199split : [a] -> [a] -> [[a]]
162200split = Native.List.split
163201
164−-- Places the given value between all of the lists in the second argument
165−-- and concatenates the result.
166−--
167−-- join "a" ["H","w","ii","n"] == "Hawaiian"
202+{-| Places the given value between all of the lists in the second
203+argument and concatenates the result.
204+
205+ join "a" ["H","w","ii","n"] == "Hawaiian"
206+-}
168207join : appendable -> [appendable] -> appendable
169208join = Native.List.join
170209
171−-- Places the given value between all members of the given list.
172−--
173−-- intersperse ' ' "INCEPTION" == "I N C E P T I O N"
210+{-| Places the given value between all members of the given list.
211+
212+ intersperse ' ' "INCEPTION" == "I N C E P T I O N"
213+-}
174214intersperse : a -> [a] -> [a]
175215intersperse sep xs =
176216 case xs of
@@ -178,14 +218,16 @@ intersperse sep xs =
178218 [a] -> [a]
179219 [] -> []
180220
181−-- Take the first n members of a list: `(take 2 [1,2,3,4] == [1,2])`
221+{-| Take the first n members of a list: `(take 2 [1,2,3,4] == [1,2])` -}
182222take : Int -> [a] -> [a]
183223take = Native.List.take
184224
185−-- Drop the first n members of a list: `(drop 2 [1,2,3,4] == [3,4])`
225+{-| Drop the first n members of a list: `(drop 2 [1,2,3,4] == [3,4])` -}
186226drop : Int -> [a] -> [a]
187227drop = Native.List.drop
188228
189−-- Creates a list with n copies of a value: `(replicate 3 (0,0) == [(0,0),(0,0),(0,0)]`
229+{-| Creates a list with *n* copies of a value:
230+`(repeat 3 (0,0) == [(0,0),(0,0),(0,0)]`
231+-}
190232repeat : Int -> a -> [a]
191233repeat = Native.List.repeat