git.iko.soy/elk
on 1cc3bac help sign in
elk/libraries/Array.elm
186 lines 5.3 kB history raw
1module Array where
3{-| A library for fast immutable arrays. The elements in an array must have the
4same type. The arrays are implemented in Relaxed Radix Balanced-Trees for fast
5reads, updates, and appends.
7# Creating Arrays
8@docs empty, repeat, initialize, fromList
10# Basics
11@docs length, push, append
13# Get and Set
14@docs get, getMaybe, getWithDefault, set
16# Taking Arrays Apart
17@docs toList, toIndexedList, slice
19# Mapping and Folding
20@docs map, indexedMap, foldl, foldr
21-}
23import Native.Array
24import Basics (..)
25import Maybe (..)
26import List
28data Array a = Array
30{-| Initialize an array. `initialize n f` creates an array of length `n` with
31the element at index `i` initialized to the result of `(f i)`.
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]
36-}
37initialize : Int -> (Int -> a) -> Array a
38initialize = 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"]
45Notice that `repeat 3 x` is the same as `initialize 3 (always x)`.
46-}
47repeat : Int -> a -> Array a
48repeat n e = initialize n (always e)
50{-| Create an array from a list. -}
51fromList : [a] -> Array a
52fromList = Native.Array.fromList
54{-| Create a list of elements from an array.
56 toList (fromList [3,5,8]) == [3,5,8]
57-}
58toList : Array a -> [a]
59toList = Native.Array.toList
61-- TODO: make this a native function.
62{-| Create an indexed list from an array. Each element of the array will be
63paired with its index.
65 toIndexedList (fromList ["cat","dog"]) == [(0,"cat"), (1,"dog")]
66-}
67toIndexedList : Array a -> [(Int, a)]
68toIndexedList array =
69 List.zip [ 0 .. Native.Array.length array - 1 ] (Native.Array.toList array)
71{-| Apply a function on every element in an array.
73 map sqrt (fromList [1,4,9]) == fromList [1,2,3]
74-}
75map : (a -> b) -> Array a -> Array b
76map = Native.Array.map
78{-| Apply a function on every element with its index as first argument.
80 indexedMap (*) (fromList [5,5,5]) == fromList [0,5,10]
81-}
82indexedMap : (Int -> a -> b) -> Array a -> Array b
83indexedMap = Native.Array.indexedMap
85{-| Reduce an array from the left. Read `foldl` as “fold from the left”.
87 foldl (::) [] (fromList [1,2,3]) == [3,2,1]
88-}
89foldl : (a -> b -> b) -> b -> Array a -> b
90foldl = Native.Array.foldl
92{-| Reduce an array from the right. Read `foldr` as “fold from the right”.
94 foldr (+) 0 (repeat 3 5) == 15
95-}
96foldr : (a -> b -> b) -> b -> Array a -> b
97foldr = Native.Array.foldr
99{-| Keep only elements that satisfy the predicate:
101 filter isEven (fromList [1..6]) == (fromList [2,4,6])
102-}
103filter : (a -> Bool) -> Array a -> Array a
104filter isOkay arr =
105 let update x xs = if isOkay x then Native.Array.push x xs else xs
106 in
107 Native.Array.foldl update Native.Array.empty arr
109{-| Return an empty array.
111 length empty == 0
112-}
113empty : Array a
114empty = Native.Array.empty
116{-| Push an element to the end of an array.
118 push 3 (fromList [1,2]) == fromList [1,2,3]
119-}
120push : a -> Array a -> Array a
121push = Native.Array.push
123{-| Return the element at the index. Breaks, if index is out of range. If the
124array length is unkown, use withDefaultGet oder getWithDefault.
126 get 2 (A.fromList [3,2,1]) == 1
127-}
128get : Int -> Array a -> a
129get = Native.Array.get
131{-| Return Just the element at the index or Nothing if the index is out of range.
133 getMaybe 2 (fromList [3,2,1]) == Just 2
134 getMaybe 5 (fromList [3,2,1]) == Nothing
135 getMaybe -1 (fromList [3,2,1]) == Nothing
136-}
137getMaybe : Int -> Array a -> Maybe a
138getMaybe i array =
139 if 0 <= i && i < Native.Array.length array
140 then Just (Native.Array.get i array)
141 else Nothing
143{-| Get the element at the index. If the index is out of range, the given default
144element is returned.
146 getWithDefault 0 2 (fromList [3,2,1]) == 1
147 getWithDefault 0 5 (fromList [3,2,1]) == 0
148-}
149getWithDefault : a -> Int -> Array a -> a
150getWithDefault default i array =
151 if 0 <= i && i < Native.Array.length array
152 then Native.Array.get i array
153 else default
155{-| Set the element at a particular index. Returns an updated array.
156If the index is out of range, the array is unaltered.
158 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
159-}
160set : Int -> a -> Array a -> Array a
161set = Native.Array.set
163{-| Slice an array given a range. The selection is inclusive, so the last
164element in the selection will also be in the new array. This may change in the
165future. You can select from the end by giving a negative Int.
167 slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
168 slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
169 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
170-}
171slice : Int -> Int -> Array a -> Array a
172slice = Native.Array.slice
174{-| Return the length of an array.
176 length (fromList [1,2,3]) == 3
177-}
178length : Array a -> Int
179length = Native.Array.length
181{-| Append two arrays to a new one.
183 append (array 2 42) (array 3 81) == fromList [42,42,81,81,81]
184-}
185append : Array a -> Array a -> Array a
186append = Native.Array.append