git.iko.soy/elk
on 3d40a4f help sign in
elk/libraries/Array.elm
191 lines 5.3 kB history raw
1module Array where
3{-| A library for immutable arrays. The elements in an array must have the same
4type. The arrays are implemented in Relaxed Radix Balanced-Trees for fast
5reads, updates, and concatenation.
7If you use more then one map or zip function on an array, consider turning it
8into a list before operating on it, and then turning it back into an array.
10# Basics
11@docs empty, length, get, safeGet, getWithDefault
13# Putting Arrays Together
14@docs fill, fromList, concat, set, updates, push
16# Taking Arrays Apart
17@docs elements, indices, assocs, slice
19# Mapping, folding, zipping
20@docs map, assocMap, foldl, foldr, zip, zipWith
21-}
23import Native.Array
24import Basics (..)
25import Maybe (..)
26import List
28data Array a = Array
30{-| Fills an array with a given length and a default element.
32 fill 3 5 == fromList [5,5,5]
33-}
34fill : Int -> a -> Array a
35fill len e = fromList <| List.map (always e) [1..len]
37{-| Create an array from a list. -}
38fromList : [a] -> Array a
39fromList = List.foldl (Native.Array.push) Native.Array.empty
41{-| Create a list of elements from an array.
43 elements (fromList [3,5,8]) == [3,5,8]
44-}
45elements : Array a -> [a]
46elements = Native.Array.toList
48{-| Create a list of the possible indices of an array.
50 indices (fromList [3,5,8] == [0,1,2])
51-}
52indices : Array a -> [Int]
53indices a = [0..Native.Array.length a - 1]
55{-| Create a list of tuples (Index, Element) from an array.
57 assocs (fromList [3,5,8]) == [(0,3), (1,5), (2,8)]
58-}
59assocs : Array a -> [(Int, a)]
60assocs a = List.zip (indices a) (Native.Array.elements a)
62{-| Apply a function on every element in an array.
64 map (\x -> x*x) (fromList [1,2,3]) == fromList [1,4,9]
65-}
66map : (a -> b) -> Array a -> Array b
67map = Native.Array.map
69{-| Apply a function with an index on every element in an array.
71 assocMap (*) (fromList [5,5,5]) == fromList [0,5,10]
72-}
73assocMap : (Int -> a -> b) -> Array a -> Array b
74assocMap = Native.Array.assocMap
76{-| Reduce an array from the left.
78 foldl (+) 0 (fill 3 5) == 15
79-}
80foldl : (a -> b -> b) -> b -> Array a -> b
81foldl = Native.Array.foldl
83{-| Reduce an array from the right.
85 foldr (::) [] (fromList [1,2,3]) == [3,2,1]
86-}
87foldr : (a -> b -> b) -> b -> Array a -> b
88foldr = Native.Array.foldr
90{-| Zip the elements of two arrays via a tuple into a new array. If one array is
91longer, the extra elements are dropped.
93 zip (fromList [1,2,3,4]) (fromList [0,0,0]) = fromList [(1,0), (2,0), (3,0)]
94-}
95zip : Array a -> Array b -> Array (a,b)
96zip = zipWith (,)
98{-| Zips the elements of two arrays via a function into a new array. If one array
99is longer, the extra elements are dropped.
101 zipWith (+) (fill 3 5) (fill 5 8) == fill 3 13
102-}
103zipWith : (a -> b -> c) -> Array a -> Array b -> Array c
104zipWith f a b =
105 fromList <| List.zipWith f (Native.Array.elements a) (Native.Array.elements b)
107{-| Return an empty array.
109 length empty == 0
110-}
111empty : Array a
112empty = Native.Array.empty
114{-| Push an element to the end of an array.
116 push 3 (fromList [1,2]) == fromList [1,2,3]
117-}
118push : a -> Array a -> Array a
119push = Native.Array.push
121{-| Return the element at the index. Breaks, if index is out of range. If the
122array length is unkown, use safeGet oder getWithDefault.
124 get 2 (A.fromList [3,2,1]) == 1
125-}
126get : Int -> Array a -> a
127get = Native.Array.get
129{-| Return Just the element at the index or Nothing.
131 safeGet 2 (A.fromList [3,2,1]) == Just 2
132 safeGet 5 (A.fromList [3,2,1]) == Nothing
133-}
134safeGet : Int -> Array a -> Maybe a
135safeGet i array =
136 if i < Native.Array.length array
137 then Just (Native.Array.get i array)
138 else Nothing
140{-| Get the element at the index. If the index is out of range, the given default
141elementis returned.
143 getWithDefault 0 2 (A.fromList [3,2,1]) == 1
144 getWithDefault 0 5 (A.fromList [3,2,1]) == 0
145-}
146getWithDefault : a -> Int -> Array a -> a
147getWithDefault default i array =
148 if i < Native.Array.length array
149 then Native.Array.get i array
150 else default
152{-| Set the element at the index. Returns the updated array, or if the index is
153out of range, the unaltered array.
155 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
156-}
157set : Int -> a -> Array a -> Array a
158set = Native.Array.set
160{-| Update an array with a a list tuples, wherein the first Int is the index.
162 updates [(1,7),(2,8)] (fill 3 1) == fromList [1,7,8]
163-}
164updates : [(Int, a)] -> Array a -> Array a
165updates assocs array = List.foldl (uncurry Native.Array.set) array assocs
167{-| Slice an array given a range. The selection is inclusive, so the last
168element in the selection will also be in the new array. This may change in the
169future.
170You can select from the end by giving a negative Int.
172 slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
173 slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
174 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
175-}
176slice : Int -> Int -> Array a -> Array a
177slice = Native.Array.slice
179{-| Return the length of an array.
181 length (fromList [1,2,3]) == 3
182-}
183length : Array a -> Int
184length = Native.Array.length
186{-| Concat two arrays to a new one.
188 concat (fill 3 1) (fill 4 2) == fromList [1,1,1,2,2,2,2]
189-}
190concat : Array a -> Array a -> Array a
191concat = Native.Array.concat