@@ -1,131 +1,162 @@
1−
21module List where
32
3+{-| A library for manipulating lists of values. Every value in a
4+list must have the same type.
5+
6+# Basics
7+@docs (::), (++), length, reverse, map
8+
9+# Sub-lists
10+@docs head, tail, last, filter, take, drop
11+
12+# Putting Lists Together
13+@docs concat, concatMap, join, intersperse, zip, zipWith
14+
15+# Taking Lists Apart
16+@docs split, partition, unzip
17+
18+# Folds
19+@docs foldr, foldl, foldr1, foldl1, scanl, scanl1
20+
21+# Special Folds
22+@docs susm, product, maximum, minimum, all, any, and, or
23+-}
24+
425import open Basics
526import Native.List
627
7−-- Add an element to the front of a list `(1 :: [2,3] == [1,2,3])`
28+{-| Add an element to the front of a list `(1 :: [2,3] == [1,2,3])` -}
829(::) : a -> [a] -> [a]
930(::) = Native.List.cons
1031
11−-- Puts two appendable things together:
12−--
13−-- [1,1] ++ [2,3] == [1,1,2,3]
14−-- "abc" ++ "123" == "abc123"
32+{-| Puts two appendable things together:
33+
34+ [1,1] ++ [2,3] == [1,1,2,3]
35+ "abc" ++ "123" == "abc123"
36+-}
1537(++) : appendable -> appendable -> appendable
1638(++) = Native.List.append
1739
18−-- Extract the first element of a list. List must be non-empty.
19−-- `(head [1,2,3] == 1)`
40+{-| Extract the first element of a list. List must be non-empty.
41+`(head [1,2,3] == 1)`
42+-}
2043head : [a] -> a
2144head = Native.List.head
2245
23−-- Extract the elements after the head of the list. List must be non-empty.
24−-- `(tail [1,2,3] == [2,3])`
46+{-| Extract the elements after the head of the list. List must be non-empty.
47+`(tail [1,2,3] == [2,3])`
48+-}
2549tail : [a] -> [a]
2650tail = Native.List.tail
2751
28−-- Extract the last element of a list. List must be non-empty.
29−-- `(last [1,2,3] == 3)`
52+{-| Extract the last element of a list. List must be non-empty.
53+`(last [1,2,3] == 3)`
54+-}
3055last : [a] -> a
3156last = Native.List.last
3257
33−-- Check if a list is empty `(isEmpty [] == True)`
58+{-| Check if a list is empty `(isEmpty [] == True)` -}
3459isEmpty : [a] -> Bool
3560isEmpty xs =
3661 case xs of
3762 [] -> True
3863 _ -> False
3964
40−-- Apply a function to every element of a list: `(map sqrt [1,4,9] == [1,2,3])`
65+{-| Apply a function to every element of a list: `(map sqrt [1,4,9] == [1,2,3])` -}
4166map : (a -> b) -> [a] -> [b]
4267map = Native.List.map
4368
44−-- Reduce a list from the left: `(foldl (::) [] "gateman" == "nametag")`
69+{-| Reduce a list from the left: `(foldl (::) [] "gateman" == "nametag")` -}
4570foldl : (a -> b -> b) -> b -> [a] -> b
4671foldl = Native.List.foldl
4772
48−-- Reduce a list from the right: `(foldr (+) 0 [1,2,3] == 6)`
73+{-| Reduce a list from the right: `(foldr (+) 0 [1,2,3] == 6)` -}
4974foldr : (a -> b -> b) -> b -> [a] -> b
5075foldr = Native.List.foldr
5176
52−-- Reduce a list from the left without a base case. List must be non-empty.
77+{-| Reduce a list from the left without a base case. List must be non-empty. -}
5378foldl1 : (a -> a -> a) -> [a] -> a
5479foldl1 = Native.List.foldl1
5580
56−-- Reduce a list from the right without a base case. List must be non-empty.
81+{-| Reduce a list from the right without a base case. List must be non-empty. -}
5782foldr1 : (a -> a -> a) -> [a] -> a
5883foldr1 = Native.List.foldr1
5984
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]
85+{-| Reduce a list from the left, building up all of the intermediate results into a list.
86+
87+ scanl (+) 0 [1,2,3,4] == [0,1,3,6,10]
88+-}
6389scanl : (a -> b -> b) -> b -> [a] -> [b]
6490scanl = Native.List.scanl
6591
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]
92+{-| Same as scanl but it doesn't require a base case. List must be non-empty.
93+
94+ scanl1 (+) [1,2,3,4] == [1,3,6,10]
95+-}
6996scanl1 : (a -> a -> a) -> [a] -> [a]
7097scanl1 = Native.List.scanl1
7198
72−-- Filter out elements which do not satisfy the predicate: `(filter isLower "AaBbCc" == "abc")`
99+{-| Keep only elements that satisfy the predicate:
100+`(filter isLower "AaBbCc" == "abc")`
101+-}
73102filter : (a -> Bool) -> [a] -> [a]
74103filter = Native.List.filter
75104
76−-- Determine the length of a list: `(length "innumerable" == 11)`
105+{-| Determine the length of a list: `(length "innumerable" == 11)` -}
77106length : [a] -> Int
78107length = Native.List.length
79108
80−-- Reverse a list. `(reverse [1..4] == [4,3,2,1])`
109+{-| Reverse a list. `(reverse [1..4] == [4,3,2,1])` -}
81110reverse : [a] -> [a]
82111reverse = Native.List.reverse
83112
84−-- Check to see if all elements satisfy the predicate.
113+{-| Check to see if all elements satisfy the predicate. -}
85114all : (a -> Bool) -> [a] -> Bool
86115all = Native.List.all
87116
88−-- Check to see if any elements satisfy the predicate.
117+{-| Check to see if any elements satisfy the predicate. -}
89118any : (a -> Bool) -> [a] -> Bool
90119any = Native.List.any
91120
92−-- Check to see if all elements are True.
121+{-| Check to see if all elements are True. -}
93122and : [Bool] -> Bool
94123and = foldl (&&) True
95124
96−-- Check to see if any elements are True.
125+{-| Check to see if any elements are True. -}
97126or : [Bool] -> Bool
98127or = foldl (||) False
99128
100−-- Concatenate a list of appendable things:
101−--
102−-- concat ["tree","house"] == "treehouse"
129+{-| Concatenate a list of appendable things:
130+
131+ concat ["tree","house"] == "treehouse"
132+-}
103133concat : [appendable] -> appendable
104134concat = Native.List.concat
105135
106−-- Map a given function onto a list and flatten the resulting lists.
107−--
108−-- concatMap f xs == concat (map f xs)
136+{-| Map a given function onto a list and flatten the resulting lists.
137+
138+ concatMap f xs == concat (map f xs)
139+-}
109140concatMap : (a -> appendable) -> [a] -> appendable
110141concatMap f list = concat (map f list)
111142
112−-- Get the sum of the list elements. `(sum [1..4] == 10)`
143+{-| Get the sum of the list elements. `(sum [1..4] == 10)` -}
113144sum : [number] -> number
114145sum = foldl (+) 0
115146
116−-- Get the product of the list elements. `(product [1..4] == 24)`
147+{-| Get the product of the list elements. `(product [1..4] == 24)` -}
117148product : [number] -> number
118149product = foldl (*) 1
119150
120−-- Find the maximum element in a non-empty list: `maximum [1,4,2] == 4`
151+{-| Find the maximum element in a non-empty list: `maximum [1,4,2] == 4` -}
121152maximum : [comparable] -> comparable
122153maximum = foldl1 max
123154
124−-- Find the minimum element in a non-empty list: `minimum [3,2,1] == 1`
155+{-| Find the minimum element in a non-empty list: `minimum [3,2,1] == 1` -}
125156minimum : [comparable] -> comparable
126157minimum = foldl1 min
127158
128−-- Split a list based on the predicate.
159+{-| Split a list based on the predicate. -}
129160partition : (a -> Bool) -> [a] -> ([a],[a])
130161partition pred lst =
131162 case lst of
@@ -133,44 +164,49 @@ partition pred lst =
133164 x::xs -> let (bs,cs) = partition pred xs in
134165 if pred x then (x::bs,cs) else (bs,x::cs)
135166
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 (,)
167+{-| Combine two lists, combining them into tuples pairwise.
168+If one list is longer, the extra elements are dropped.
169+
170+ zip [1,2,3] [6,7] == [(1,6),(2,7)]
171+ zip == zipWith (,)
172+-}
141173zip : [a] -> [b] -> [(a,b)]
142174zip = Native.List.zip
143175
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]
176+{-| Combine two lists, combining them with the given function.
177+If one list is longer, the extra elements are dropped.
178+
179+ zipWith (+) [1,2,3] [1,2,3,4] == [2,4,6]
180+-}
148181zipWith : (a -> b -> c) -> [a] -> [b] -> [c]
149182zipWith = Native.List.zipWith
150183
151−-- Decompose a list of tuples.
184+{-| Decompose a list of tuples. -}
152185unzip : [(a,b)] -> ([a],[b])
153186unzip pairs =
154187 case pairs of
155188 [] -> ([],[])
156189 (x,y)::ps -> let (xs,ys) = (unzip ps) in (x::xs,y::ys)
157190
158−-- Split a list with a given seperator.
159−--
160−-- split "," "hello,there,friend" == ["hello", "there", "friend"]
191+{-| Split a list with a given seperator.
192+
193+ split "," "hello,there,friend" == ["hello", "there", "friend"]
194+-}
161195split : [a] -> [a] -> [[a]]
162196split = Native.List.split
163197
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"
198+{-| Places the given value between all of the lists in the second
199+argument and concatenates the result.
200+
201+ join "a" ["H","w","ii","n"] == "Hawaiian"
202+-}
168203join : appendable -> [appendable] -> appendable
169204join = Native.List.join
170205
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"
206+{-| Places the given value between all members of the given list.
207+
208+ intersperse ' ' "INCEPTION" == "I N C E P T I O N"
209+-}
174210intersperse : a -> [a] -> [a]
175211intersperse sep xs =
176212 case xs of
@@ -178,14 +214,16 @@ intersperse sep xs =
178214 [a] -> [a]
179215 [] -> []
180216
181−-- Take the first n members of a list: `(take 2 [1,2,3,4] == [1,2])`
217+{-| Take the first n members of a list: `(take 2 [1,2,3,4] == [1,2])` -}
182218take : Int -> [a] -> [a]
183219take = Native.List.take
184220
185−-- Drop the first n members of a list: `(drop 2 [1,2,3,4] == [3,4])`
221+{-| Drop the first n members of a list: `(drop 2 [1,2,3,4] == [3,4])` -}
186222drop : Int -> [a] -> [a]
187223drop = Native.List.drop
188224
189−-- Creates a list with n copies of a value: `(replicate 3 (0,0) == [(0,0),(0,0),(0,0)]`
225+{-| Creates a list with *n* copies of a value:
226+`(repeat 3 (0,0) == [(0,0),(0,0),(0,0)]`
227+-}
190228repeat : Int -> a -> [a]
191229repeat = Native.List.repeat