git.iko.soy/elk
on ef6a2d6 help sign in
elk/libraries/Array.elm
179 lines 5.0 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 getMaybe -1 (fromList [3,2,1]) == Nothing
129-}
130getMaybe : Int -> Array a -> Maybe a
131getMaybe i array =
132 if 0 <= i && i < Native.Array.length array
133 then Just (Native.Array.get i array)
134 else Nothing
136{-| Get the element at the index. If the index is out of range, the given default
137element is returned.
139 getWithDefault 0 2 (fromList [3,2,1]) == 1
140 getWithDefault 0 5 (fromList [3,2,1]) == 0
141-}
142getWithDefault : a -> Int -> Array a -> a
143getWithDefault default i array =
144 if 0 <= i && i < Native.Array.length array
145 then Native.Array.get i array
146 else default
148{-| Set the element at a particular index. Returns an updated array.
149If the index is out of range, the array is unaltered.
151 set 1 7 (fromList [1,2,3]) == fromList [1,7,3]
152-}
153set : Int -> a -> Array a -> Array a
154set = Native.Array.set
156{-| Slice an array given a range. The selection is inclusive, so the last
157element in the selection will also be in the new array. This may change in the
158future. You can select from the end by giving a negative Int.
160 slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
161 slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
162 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
163-}
164slice : Int -> Int -> Array a -> Array a
165slice = Native.Array.slice
167{-| Return the length of an array.
169 length (fromList [1,2,3]) == 3
170-}
171length : Array a -> Int
172length = Native.Array.length
174{-| Append two arrays to a new one.
176 append (array 2 42) (array 3 81) == fromList [42,42,81,81,81]
177-}
178append : Array a -> Array a -> Array a
179append = Native.Array.append