git.iko.soy/elk
on ea54e58 help sign in
elk/libraries/Array.elm
178 lines 4.9 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-- TODO: make this a native function
31{-| Initialize an array. `initialize n f` creates an array of length `n` with
32the element at index `i` initialized to the result of `(f i)`.
34 initialize 4 id == fromList [0,1,2,3]
35 initialize 4 (\n -> n*n) == fromList [0,1,4,9]
36 initialize 4 (always 0) == fromList [0,0,0,0]
37-}
38initialize : Int -> (Int -> a) -> Array a
39initialize n initializer =
40 fromList <| List.map initializer [ 0 .. n - 1 ]
42{-| Creates an array with a given length, filled with a default element.
44 repeat 5 0 == fromList [0,0,0,0,0]
45 repeat 3 "cat" == fromList ["cat","cat","cat"]
47Notice that `repeat 3 x` is the same as `initialize 3 (always x)`.
48-}
49repeat : Int -> a -> Array a
50repeat n e = initialize n (always e)
52-- TODO: make this a native function.
53{-| Create an array from a list. -}
54fromList : [a] -> Array a
55fromList xs = List.foldl Native.Array.push Native.Array.empty xs
57{-| Create a list of elements from an array.
59 toList (fromList [3,5,8]) == [3,5,8]
60-}
61toList : Array a -> [a]
62toList = Native.Array.toList
64-- TODO: make this a native function.
65{-| Create an indexed list from an array. Each element of the array will be
66paired with its index.
68 toIndexedList (fromList ["cat","dog"]) == [(0,"cat"), (1,"dog")]
69-}
70toIndexedList : Array a -> [(Int, a)]
71toIndexedList array =
72 List.zip [ 0 .. Native.Array.length array - 1 ] (Native.Array.toList array)
74{-| Apply a function on every element in an array.
76 map sqrt (fromList [1,4,9]) == fromList [1,2,3]
77-}
78map : (a -> b) -> Array a -> Array b
79map = Native.Array.map
81{-| Apply a function on every element with its index as first argument.
83 indexedMap (*) (fromList [5,5,5]) == fromList [0,5,10]
84-}
85indexedMap : (Int -> a -> b) -> Array a -> Array b
86indexedMap = Native.Array.indexedMap
88{-| Reduce an array from the left.
90 foldl (::) [] (fromList [1,2,3]) == [3,2,1]
91-}
92foldl : (a -> b -> b) -> b -> Array a -> b
93foldl = Native.Array.foldl
95{-| Reduce an array from the right.
97 foldr (+) 0 (repeat 3 5) == 15
98-}
99foldr : (a -> b -> b) -> b -> Array a -> b
100foldr = Native.Array.foldr
102{-| Return an empty array.
104 length empty == 0
105-}
106empty : Array a
107empty = Native.Array.empty
109{-| Push an element to the end of an array.
111 push 3 (fromList [1,2]) == fromList [1,2,3]
112-}
113push : a -> Array a -> Array a
114push = Native.Array.push
116{-| Return the element at the index. Breaks, if index is out of range. If the
117array length is unkown, use withDefaultGet oder getWithDefault.
119 get 2 (A.fromList [3,2,1]) == 1
120-}
121get : Int -> Array a -> a
122get = Native.Array.get
124{-| Return Just the element at the index or Nothing if the index is out of range.
126 getMaybe 2 (fromList [3,2,1]) == Just 2
127 getMaybe 5 (fromList [3,2,1]) == Nothing
128-}
129getMaybe : Int -> Array a -> Maybe a
130getMaybe i array =
131 if Native.Array.length array > i
132 then Just (Native.Array.get i array)
133 else Nothing
135{-| Get the element at the index. If the index is out of range, the given default
136element is returned.
138 getWithDefault 0 2 (fromList [3,2,1]) == 1
139 getWithDefault 0 5 (fromList [3,2,1]) == 0
140-}
141getWithDefault : a -> Int -> Array a -> a
142getWithDefault default i array =
143 if Native.Array.length array > i
144 then Native.Array.get i array
145 else default
147{-| Set the element at a particular index. Returns an updated array.
148If the index is out of range, the array is unaltered.
150 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
151-}
152set : Int -> a -> Array a -> Array a
153set = Native.Array.set
155{-| Slice an array given a range. The selection is inclusive, so the last
156element in the selection will also be in the new array. This may change in the
157future. You can select from the end by giving a negative Int.
159 slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
160 slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
161 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
162-}
163slice : Int -> Int -> Array a -> Array a
164slice = Native.Array.slice
166{-| Return the length of an array.
168 length (fromList [1,2,3]) == 3
169-}
170length : Array a -> Int
171length = Native.Array.length
173{-| Append two arrays to a new one.
175 append (array 2 42) (array 3 81) == fromList [42,42,81,81,81]
176-}
177append : Array a -> Array a -> Array a
178append = Native.Array.append