@@ -1,23 +1,23 @@
11module Array where
22
3−{-| A library for immutable arrays. The elements in an array must have the same
4−type. The arrays are implemented in Relaxed Radix Balanced-Trees for fast
5−reads, updates, and concatenation.
3+{-| A library for fast immutable arrays. The elements in an array must have the
4+same type. The arrays are implemented in Relaxed Radix Balanced-Trees for fast
5+reads, updates, and appends.
66
7−If you use more then one map or zip function on an array, consider turning it
8−into a list before operating on it, and then turning it back into an array.
7+# Creating Arrays
8+@docs empty, repeat, initialize, fromList
99
1010# Basics
11−@docs empty, length, get, getMaybe, getSafe
11+@docs length, push, append
1212
13−# Putting Arrays Together
14−@docs fill, fromList, concat, set, updates, push
13+# Get and Set
14+@docs get, getMaybe, getWithDefault, set
1515
1616# Taking Arrays Apart
17−@docs toList, toIndexedList, indices, slice
17+@docs toList, toIndexedList, slice
1818
19−# Mapping, folding, zipping
20−@docs map, indexedMap, foldl, foldr, zip, zipWith
19+# Mapping and Folding
20+@docs map, indexedMap, foldl, foldr
2121-}
2222
2323import Native.Array
@@ -27,17 +27,29 @@ import List
2727
2828data Array a = Array
2929
30−{-| Fills an array with a given length and a default element.
30+{-| Initialize an array. `initialize n f` creates an array of length `n` with
31+the element at index `i` initialized to the result of `(f i)`.
3132
32− fill 3 5 == fromList [5,5,5]
33+ initialize 4 id == fromList [0,1,2,3]
34+ initialize 4 (\n -> n*n) == fromList [0,1,4,9]
35+ initialize 4 (always 0) == fromList [0,0,0,0]
3336-}
34−fill : Int -> a -> Array a
35−fill len e = fromList <| List.map (always e) [1..len]
37+initialize : Int -> (Int -> a) -> Array a
38+initialize = Native.Array.initialize
39+
40+{-| Creates an array with a given length, filled with a default element.
41+
42+ repeat 5 0 == fromList [0,0,0,0,0]
43+ repeat 3 "cat" == fromList ["cat","cat","cat"]
44+
45+Notice that `repeat 3 x` is the same as `initialize 3 (always x)`.
46+-}
47+repeat : Int -> a -> Array a
48+repeat n e = initialize n (always e)
3649
37−-- TODO: make this a native function.
3850{-| Create an array from a list. -}
3951fromList : [a] -> Array a
40−fromList = List.foldl (Native.Array.push) Native.Array.empty
52+fromList = Native.Array.fromList
4153
4254{-| Create a list of elements from an array.
4355
@@ -46,24 +58,19 @@ fromList = List.foldl (Native.Array.push) Native.Array.empty
4658toList : Array a -> [a]
4759toList = Native.Array.toList
4860
49−{-| Create a list of the possible indices of an array.
50−
51− indices (fromList [3,5,8] == [0,1,2])
52−-}
53−indices : Array a -> [Int]
54−indices a = [0..Native.Array.length a - 1]
55−
5661-- TODO: make this a native function.
57−{-| Create a list of tuples (Index, Element) from an array.
62+{-| Create an indexed list from an array. Each element of the array will be
63+paired with its index.
5864
59− toIndexedList (fromList [3,5,8]) == [(0,3), (1,5), (2,8)]
65+ toIndexedList (fromList ["cat","dog"]) == [(0,"cat"), (1,"dog")]
6066-}
6167toIndexedList : Array a -> [(Int, a)]
62−toIndexedList a = List.zip (indices a) (Native.Array.toList a)
68+toIndexedList array =
69+ List.zip [ 0 .. Native.Array.length array - 1 ] (Native.Array.toList array)
6370
6471{-| Apply a function on every element in an array.
6572
66− map (\x -> x*x) (fromList [1,2,3]) == fromList [1,4,9]
73+ map sqrt (fromList [1,4,9]) == fromList [1,2,3]
6774-}
6875map : (a -> b) -> Array a -> Array b
6976map = Native.Array.map
@@ -77,35 +84,18 @@ indexedMap = Native.Array.indexedMap
7784
7885{-| Reduce an array from the left.
7986
80− foldl (+) 0 (fill 3 5) == 15
87+ foldl (::) [] (fromList [1,2,3]) == [3,2,1]
8188-}
8289foldl : (a -> b -> b) -> b -> Array a -> b
8390foldl = Native.Array.foldl
8491
8592{-| Reduce an array from the right.
8693
87− foldr (::) [] (fromList [1,2,3]) == [3,2,1]
94+ foldr (+) 0 (repeat 3 5) == 15
8895-}
8996foldr : (a -> b -> b) -> b -> Array a -> b
9097foldr = Native.Array.foldr
9198
92−{-| Zip the elements of two arrays via a tuple into a new array. If one array is
93−longer, the extra elements are dropped.
94−
95− zip (fromList [1,2,3,4]) (fromList [0,0,0]) = fromList [(1,0), (2,0), (3,0)]
96−-}
97−zip : Array a -> Array b -> Array (a,b)
98−zip = zipWith (,)
99−
100−{-| Zips the elements of two arrays via a function into a new array. If one array
101−is longer, the extra elements are dropped.
102−
103− zipWith (+) (fill 3 5) (fill 5 8) == fill 3 13
104−-}
105−zipWith : (a -> b -> c) -> Array a -> Array b -> Array c
106−zipWith f a b =
107− fromList <| List.zipWith f (Native.Array.toList a) (Native.Array.toList b)
108−
10999{-| Return an empty array.
110100
111101 length empty == 0
@@ -121,7 +111,7 @@ push : a -> Array a -> Array a
121111push = Native.Array.push
122112
123113{-| Return the element at the index. Breaks, if index is out of range. If the
124−array length is unkown, use safeGet oder getWithDefault.
114+array length is unkown, use withDefaultGet oder getWithDefault.
125115
126116 get 2 (A.fromList [3,2,1]) == 1
127117-}
@@ -130,46 +120,42 @@ get = Native.Array.get
130120
131121{-| Return Just the element at the index or Nothing if the index is out of range.
132122
133− getMaybe 2 (A.fromList [3,2,1]) == Just 2
134− getMaybe 5 (A.fromList [3,2,1]) == Nothing
123+ getMaybe 2 (fromList [3,2,1]) == Just 2
124+ getMaybe 5 (fromList [3,2,1]) == Nothing
125+ getMaybe -1 (fromList [3,2,1]) == Nothing
135126-}
136127getMaybe : Int -> Array a -> Maybe a
137−getMaybe i array = if Native.Array.length array > i
138− then Just (Native.Array.get i array)
139− else Nothing
128+getMaybe i array =
129+ if 0 <= i && i < Native.Array.length array
130+ then Just (Native.Array.get i array)
131+ else Nothing
140132
141133{-| Get the element at the index. If the index is out of range, the given default
142134element is returned.
143135
144− getSafe 0 2 (A.fromList [3,2,1]) == 1
145− getSafe 0 5 (A.fromList [3,2,1]) == 0
136+ getWithDefault 0 2 (fromList [3,2,1]) == 1
137+ getWithDefault 0 5 (fromList [3,2,1]) == 0
146138-}
147−getSafe : a -> Int -> Array a -> a
148−getSafe default i array = if Native.Array.length array > i
149− then Native.Array.get i array else default
139+getWithDefault : a -> Int -> Array a -> a
140+getWithDefault default i array =
141+ if 0 <= i && i < Native.Array.length array
142+ then Native.Array.get i array
143+ else default
150144
151−{-| Set the element at the index. Returns the updated array, or if the index is
152−out of range, the unaltered array.
145+{-| Set the element at a particular index. Returns an updated array.
146+If the index is out of range, the array is unaltered.
153147
154148 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
155149-}
156150set : Int -> a -> Array a -> Array a
157151set = Native.Array.set
158152
159−{-| Update an array with a a list tuples, wherein the first Int is the index.
160−
161− updates [(1,7),(2,8)] (fill 3 1) == fromList [1,7,8]
162−-}
163−updates : [(Int, a)] -> Array a -> Array a
164−updates us array = List.foldl (uncurry Native.Array.set) array us
165−
166153{-| Slice an array given a range. The selection is inclusive, so the last
167154element in the selection will also be in the new array. This may change in the
168−future.
169−You can select from the end by giving a negative Int.
155+future. You can select from the end by giving a negative Int.
170156
171− slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
172− slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
157+ slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
158+ slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
173159 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
174160-}
175161slice : Int -> Int -> Array a -> Array a
@@ -182,9 +168,9 @@ slice = Native.Array.slice
182168length : Array a -> Int
183169length = Native.Array.length
184170
185−{-| Concat two arrays to a new one.
171+{-| Append two arrays to a new one.
186172
187− concat (fill 3 1) (fill 4 2) == fromList [1,1,1,2,2,2,2]
173+ append (array 2 42) (array 3 81) == fromList [42,42,81,81,81]
188174-}
189−concat : Array a -> Array a -> Array a
190−concat = Native.Array.concat
175+append : Array a -> Array a -> Array a
176+append = Native.Array.append