git.iko.soy/elk
on dcba223 help sign in
elk/libraries/Array.elm
184 lines 5.3 kB history raw
1module Array where
3{-| A library for manipulating arrays of elements. The elements in an
4array must have the same type. The arrays are implemented in Relaxed
5Radix Balanced-Trees for fast updating and concating.
7If you use more then one map or zip function on an array, consider turning it
8first into a list, 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 Basic
25import List
27data Array a = Array
29{-| Fills an array with a given length and a default element.
31 fill 3 5 == fromList [5,5,5]
32-}
33fill : Int -> a -> Array a
34fill len e = fromList <| List.map (always e) [1..len]
36{-| Create an array from a list. -}
37fromList : [a] -> Array a
38fromList = List.foldl (Native.Array.push) Native.Array.empty
40{-| Create a list of elements from an array.
42 elements (fromList [3,5,8]) == [3,5,8]
43-}
44elements : Array a -> [a]
45elements = Native.Array.toList
47{-| Create a list of the possible indices of an array.
49 indices (fromList [3,5,8] == [0,1,2])
50-}
51indices : Array a -> [Int]
52indices a = [0..Native.Array.length a - 1]
54{-| Create a list of tuples (Index, Element) from an array.
56 assocs (fromList [3,5,8]) == [(0,3), (1,5), (2,8)]
57-}
58assocs : Array a -> [(Int, a)]
59assocs a = List.zip (indices a) (Native.Array.elements a)
61{-| Apply a function on every element in an array.
63 map (\x -> x*x) (fromList [1,2,3]) == fromList [1,4,9]
64-}
65map : (a -> b) -> Array a -> Array b
66map = Native.Array.map
68{-| Apply a function with an index on every element in an array.
70 assocMap (*) (fromList [5,5,5]) == fromList [0,5,10]
71-}
72assocMap : (Int -> a -> b) -> Array a -> Array b
73assocMap = Native.Array.assocMap
75{-| Reduce an array from the left.
77 foldl (+) 0 (fill 3 5) == 15
78-}
79foldl : (a -> b -> b) -> b -> Array a -> b
80foldl = Native.Array.foldl
82{-| Reduce an array from the right.
84 foldr (::) [] (fromList [1,2,3]) == [3,2,1]
85-}
86foldr : (a -> b -> b) -> b -> Array a -> b
87foldr = Native.Array.foldr
89{-| Zip the elements of two arrays via a tuple into a new array. If one array is
90longer, the extra elements are dropped.
92 zip (fromList [1,2,3,4]) (fromList [0,0,0]) = fromList [(1,0), (2,0), (3,0)]
93-}
94zip : Array a -> Array b -> Array (a,b)
95zip = zipWith (,)
97{-| Zips the elements of two arrays via a function into a new array. If one array
98is longer, the extra elements are dropped.
100 zipWith (+) (fill 3 5) (fill 5 8) == fill 3 13
101-}
102zipWith : (a -> b -> c) -> Array a -> Array b -> Array c
103zipWith f a b =
104 fromList <| List.zipWith f (Native.Array.elements a) (Native.Array.elements b)
106{-| Return an empty array.
108 length empty == 0
109-}
110empty : Array a
111empty = Native.Array.empty
113{-| Push an item to the end of an array. -}
114push : a -> Array a -> Array a
115push = Native.Array.push
117{-| Return the value at the index. Breaks, if index is out of range. If the
118array length is unkown, use safeGet oder getWithDefault.
120 get 2 (A.fromList [3,2,1]) == 1
121-}
122get : Int -> Array a -> a
123get = Native.Array.get
125{-| Return Just the element at the index or Nothing.
127 safeGet 2 (A.fromList [3,2,1]) == Just 2
128 safeGet 5 (A.fromList [3,2,1]) == Nothing
129-}
130safeGet : Int -> Array a -> Maybe a
131safeGet i array = 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
136elementis returned.
138 getWithDefault 0 2 (A.fromList [3,2,1]) == 1
139 getWithDefault 0 5 (A.fromList [3,2,1]) == 0
140-}
141getWithDefault : a -> Int -> Array a -> a
142getWithDefault default i array = if Native.Array.length array > i
143 then Native.Array.get i array else default
145{-| Set the element at the index. Returns the updated array, or if the index is
146out of range, the unaltered array.
148 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
149-}
150set : Int -> a -> Array a -> Array a
151set = Native.Array.set
153{-| Update an array with a a list tuples, wherein the first Int is the index.
155 updates [(1,7),(2,8)] (fill 3 1) == fromList [1,7,8]
156-}
157updates : [(Int, a)] -> Array a -> Array a
158updates assocs array = List.foldl (Basic.uncurry Native.Array.set) array assocs
160{-| Slice an array given a range. The selection is inclusive, so the last
161element in the selection will also be in the new array. This may change in the
162future.
163You can select from the end by giving a negative Int.
165 slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
166 slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
167 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
168-}
169slice : Int -> Int -> Array a -> Array a
170slice = Native.Array.slice
172{-| Return the length of an array.
174 length (fromList [1,2,3]) == 3
175-}
176length : Array a -> Int
177length = Native.Array.length
179{-| Concat two arrays to a new one.
181 concat (fill 3 1) (fill 4 2) == fromList [1,1,1,2,2,2,2]
182-}
183concat : Array a -> Array a -> Array a
184concat = Native.Array.concat