git.iko.soy/elk
on abaaf39 help sign in
elk/libraries/Array.elm
176 lines 4.8 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.
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.
94 foldr (+) 0 (repeat 3 5) == 15
95-}
96foldr : (a -> b -> b) -> b -> Array a -> b
97foldr = Native.Array.foldr
99{-| Return an empty array.
101 length empty == 0
102-}
103empty : Array a
104empty = Native.Array.empty
106{-| Push an element to the end of an array.
108 push 3 (fromList [1,2]) == fromList [1,2,3]
109-}
110push : a -> Array a -> Array a
111push = Native.Array.push
113{-| Return the element at the index. Breaks, if index is out of range. If the
114array length is unkown, use withDefaultGet oder getWithDefault.
116 get 2 (A.fromList [3,2,1]) == 1
117-}
118get : Int -> Array a -> a
119get = Native.Array.get
121{-| Return Just the element at the index or Nothing if the index is out of range.
123 getMaybe 2 (fromList [3,2,1]) == Just 2
124 getMaybe 5 (fromList [3,2,1]) == Nothing
125 getMaybe -1 (fromList [3,2,1]) == Nothing
126-}
127getMaybe : Int -> Array a -> Maybe a
128getMaybe i array =
129 if 0 <= i && i < Native.Array.length array
130 then Just (Native.Array.get i array)
131 else Nothing
133{-| Get the element at the index. If the index is out of range, the given default
134element is returned.
136 getWithDefault 0 2 (fromList [3,2,1]) == 1
137 getWithDefault 0 5 (fromList [3,2,1]) == 0
138-}
139getWithDefault : a -> Int -> Array a -> a
140getWithDefault default i array =
141 if 0 <= i && i < Native.Array.length array
142 then Native.Array.get i array
143 else default
145{-| Set the element at a particular index. Returns an updated array.
146If the index is out of range, the array is unaltered.
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{-| Slice an array given a range. The selection is inclusive, so the last
154element in the selection will also be in the new array. This may change in the
155future. You can select from the end by giving a negative Int.
157 slice 1 2 (fromList [0,1,2,3,4]) == fromList [1,2]
158 slice 1 -2 (fromList [0,1,2,3,4]) == fromList [1,2,3]
159 slice -3 -2 (fromList [0,1,2,3,4]) == fromList [2,3]
160-}
161slice : Int -> Int -> Array a -> Array a
162slice = Native.Array.slice
164{-| Return the length of an array.
166 length (fromList [1,2,3]) == 3
167-}
168length : Array a -> Int
169length = Native.Array.length
171{-| Append two arrays to a new one.
173 append (array 2 42) (array 3 81) == fromList [42,42,81,81,81]
174-}
175append : Array a -> Array a -> Array a
176append = Native.Array.append