@@ -1,23 +1,23 @@
1module Array where
1module Array where
3−{-| A library for immutable arrays. The elements in an array must have the same
3+{-| A library for fast immutable arrays. The elements in an array must have the
4−type. The arrays are implemented in Relaxed Radix Balanced-Trees for fast
4+same type. The arrays are implemented in Relaxed Radix Balanced-Trees for fast
5−reads, updates, and concatenation.
5+reads, updates, and appends.
7−If you use more then one map or zip function on an array, consider turning it
7+# Creating Arrays
8−into a list before operating on it, and then turning it back into an array.
8+@docs empty, repeat, initialize, fromList
11−@docs empty, length, get, getMaybe, getSafe
11+@docs length, push, append
13−# Putting Arrays Together
13+# Get and Set
14−@docs fill, fromList, concat, set, updates, push
14+@docs get, getMaybe, getWithDefault, set
16# Taking Arrays Apart
16# Taking Arrays Apart
17−@docs toList, toIndexedList, indices, slice
17+@docs toList, toIndexedList, slice
19−# Mapping, folding, zipping
19+# Mapping and Folding
20−@docs map, indexedMap, foldl, foldr, zip, zipWith
20+@docs map, indexedMap, foldl, foldr
23import Native.Array
23import Native.Array
@@ -27,17 +27,29 @@ import List
28data Array a = Array
28data Array a = Array
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)`.
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]
34−fill : Int -> a -> Array a
37+initialize : Int -> (Int -> a) -> Array a
35−fill len e = fromList <| List.map (always e) [1..len]
38+initialize = Native.Array.initialize
40+{-| Creates an array with a given length, filled with a default element.
42+ repeat 5 0 == fromList [0,0,0,0,0]
43+ repeat 3 "cat" == fromList ["cat","cat","cat"]
45+Notice that `repeat 3 x` is the same as `initialize 3 (always x)`.
47+repeat : Int -> a -> Array a
48+repeat n e = initialize n (always e)
37−-- TODO: make this a native function.
38{-| Create an array from a list. -}
50{-| Create an array from a list. -}
39fromList : [a] -> Array a
51fromList : [a] -> Array a
40−fromList = List.foldl (Native.Array.push) Native.Array.empty
52+fromList = Native.Array.fromList
42{-| Create a list of elements from an array.
54{-| Create a list of elements from an array.
@@ -46,24 +58,19 @@ fromList = List.foldl (Native.Array.push) Native.Array.empty
46toList : Array a -> [a]
58toList : Array a -> [a]
47toList = Native.Array.toList
59toList = Native.Array.toList
49−{-| Create a list of the possible indices of an array.
51− indices (fromList [3,5,8] == [0,1,2])
53−indices : Array a -> [Int]
54−indices a = [0..Native.Array.length a - 1]
56-- TODO: make this a native function.
61-- 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.
59− toIndexedList (fromList [3,5,8]) == [(0,3), (1,5), (2,8)]
65+ toIndexedList (fromList ["cat","dog"]) == [(0,"cat"), (1,"dog")]
61toIndexedList : Array a -> [(Int, a)]
67toIndexedList : Array a -> [(Int, a)]
62−toIndexedList a = List.zip (indices a) (Native.Array.toList a)
69+ List.zip [ 0 .. Native.Array.length array - 1 ] (Native.Array.toList array)
64{-| Apply a function on every element in an array.
71{-| Apply a function on every element in an array.
66− map (\x -> x*x) (fromList [1,2,3]) == fromList [1,4,9]
73+ map sqrt (fromList [1,4,9]) == fromList [1,2,3]
68map : (a -> b) -> Array a -> Array b
75map : (a -> b) -> Array a -> Array b
69map = Native.Array.map
76map = Native.Array.map
@@ -77,35 +84,18 @@ indexedMap = Native.Array.indexedMap
78{-| Reduce an array from the left.
85{-| Reduce an array from the left.
80− foldl (+) 0 (fill 3 5) == 15
87+ foldl (::) [] (fromList [1,2,3]) == [3,2,1]
82foldl : (a -> b -> b) -> b -> Array a -> b
89foldl : (a -> b -> b) -> b -> Array a -> b
83foldl = Native.Array.foldl
90foldl = Native.Array.foldl
85{-| Reduce an array from the right.
92{-| Reduce an array from the right.
87− foldr (::) [] (fromList [1,2,3]) == [3,2,1]
94+ foldr (+) 0 (repeat 3 5) == 15
89foldr : (a -> b -> b) -> b -> Array a -> b
96foldr : (a -> b -> b) -> b -> Array a -> b
90foldr = Native.Array.foldr
97foldr = Native.Array.foldr
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.
95− zip (fromList [1,2,3,4]) (fromList [0,0,0]) = fromList [(1,0), (2,0), (3,0)]
97−zip : Array a -> Array b -> Array (a,b)
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.
103− zipWith (+) (fill 3 5) (fill 5 8) == fill 3 13
105−zipWith : (a -> b -> c) -> Array a -> Array b -> Array c
107− fromList <| List.zipWith f (Native.Array.toList a) (Native.Array.toList b)
109{-| Return an empty array.
99{-| Return an empty array.
111 length empty == 0
101 length empty == 0
@@ -121,7 +111,7 @@ push : a -> Array a -> Array a
121push = Native.Array.push
111push = Native.Array.push
123{-| Return the element at the index. Breaks, if index is out of range. If the
113{-| 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.
126 get 2 (A.fromList [3,2,1]) == 1
116 get 2 (A.fromList [3,2,1]) == 1
@@ -130,46 +120,42 @@ get = Native.Array.get
131{-| Return Just the element at the index or Nothing if the index is out of range.
121{-| Return Just the element at the index or Nothing if the index is out of range.
133− getMaybe 2 (A.fromList [3,2,1]) == Just 2
123+ getMaybe 2 (fromList [3,2,1]) == Just 2
134− getMaybe 5 (A.fromList [3,2,1]) == Nothing
124+ getMaybe 5 (fromList [3,2,1]) == Nothing
125+ getMaybe -1 (fromList [3,2,1]) == Nothing
136getMaybe : Int -> Array a -> Maybe a
127getMaybe : Int -> Array a -> Maybe a
137−getMaybe i array = if Native.Array.length array > i
129+ if 0 <= i && i < Native.Array.length array
138− then Just (Native.Array.get i array)
130+ then Just (Native.Array.get i array)
139− else Nothing
131+ else Nothing
141{-| Get the element at the index. If the index is out of range, the given default
133{-| Get the element at the index. If the index is out of range, the given default
142element is returned.
134element is returned.
144− getSafe 0 2 (A.fromList [3,2,1]) == 1
136+ getWithDefault 0 2 (fromList [3,2,1]) == 1
145− getSafe 0 5 (A.fromList [3,2,1]) == 0
137+ getWithDefault 0 5 (fromList [3,2,1]) == 0
147−getSafe : a -> Int -> Array a -> a
139+getWithDefault : a -> Int -> Array a -> a
140+getWithDefault default i array =
148−getSafe default i array = if Native.Array.length array > i
141+ if 0 <= i && i < Native.Array.length array
149− then Native.Array.get i array else default
142+ then Native.Array.get i array
151−{-| Set the element at the index. Returns the updated array, or if the index is
145+{-| Set the element at a particular index. Returns an updated array.
152−out of range, the unaltered array.
146+If the index is out of range, the array is unaltered.
154 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
148 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
156set : Int -> a -> Array a -> Array a
150set : Int -> a -> Array a -> Array a
157set = Native.Array.set
151set = Native.Array.set
159−{-| Update an array with a a list tuples, wherein the first Int is the index.
161− updates [(1,7),(2,8)] (fill 3 1) == fromList [1,7,8]
163−updates : [(Int, a)] -> Array a -> Array a
164−updates us array = List.foldl (uncurry Native.Array.set) array us
166{-| Slice an array given a range. The selection is inclusive, so the last
153{-| Slice an array given a range. The selection is inclusive, so the last
167element in the selection will also be in the new array. This may change in the
154element in the selection will also be in the new array. This may change in the
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.
171− slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
157+ 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]
158+ slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
173 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
159 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
175slice : Int -> Int -> Array a -> Array a
161slice : Int -> Int -> Array a -> Array a
@@ -182,9 +168,9 @@ slice = Native.Array.slice
182length : Array a -> Int
168length : Array a -> Int
183length = Native.Array.length
169length = Native.Array.length
185−{-| Concat two arrays to a new one.
171+{-| Append two arrays to a new one.
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]
189−concat : Array a -> Array a -> Array a
175+append : Array a -> Array a -> Array a
190−concat = Native.Array.concat
176+append = Native.Array.append