1array(3) Erlang Module Definition array(3)
2
6 array - Functional, extendible arrays.
7
9 Functional, extendible arrays. Arrays can have fixed size, or can grow
10 automatically as needed. A default value is used for entries that have
11 not been explicitly set.
12 Arrays uses zero-based indexing. This is a deliberate design choice and
14 differs from other Erlang data structures, for example, tuples.
15 Unless specified by the user when the array is created, the default
17 value is the atom undefined. There is no difference between an unset
18 entry and an entry that has been explicitly set to the same value as
19 the default one (compare reset/2). If you need to differentiate between
20 unset and set entries, ensure that the default value cannot be confused
21 with the values of set entries.
22 The array never shrinks automatically. If an index I has been used to
24 set an entry successfully, all indices in the range [0,I] stay accessi‐
25 ble unless the array size is explicitly changed by calling resize/2.
26 Examples:
28 Create a fixed-size array with entries 0-9 set to undefined:
30 A0 = array:new(10).
32 10 = array:size(A0).
33 Create an extendible array and set entry 17 to true, causing the array
35 to grow automatically:
36 A1 = array:set(17, true, array:new()).
38 18 = array:size(A1).
39 Read back a stored value:
41 true = array:get(17, A1).
43 Accessing an unset entry returns default value:
45 undefined = array:get(3, A1)
47 Accessing an entry beyond the last set entry also returns the default
49 value, if the array does not have fixed size:
50 undefined = array:get(18, A1).
52 "Sparse" functions ignore default-valued entries:
54 A2 = array:set(4, false, A1).
56 [{4, false}, {17, true}] = array:sparse_to_orddict(A2).
57 An extendible array can be made fixed-size later:
59 A3 = array:fix(A2).
61 A fixed-size array does not grow automatically and does not allow
63 accesses beyond the last set entry:
64 {'EXIT',{badarg,_}} = (catch array:set(18, true, A3)).
66 {'EXIT',{badarg,_}} = (catch array:get(18, A3)).
67
69 array(Type)
70 A functional, extendible array. The representation is not docu‐
72 mented and is subject to change without notice. Notice that
73 arrays cannot be directly compared for equality.
74 array() = array(term())
76 array_indx() = integer() >= 0
78 array_opts() = array_opt() | [array_opt()]
80 array_opt() =
82 {fixed, boolean()} |
83 fixed |
84 {default, Type :: term()} |
85 {size, N :: integer() >= 0} |
86 (N :: integer() >= 0)
87 indx_pairs(Type) = [indx_pair(Type)]
89 indx_pair(Type) = {Index :: array_indx(), Type}
91
93 default(Array :: array(Type)) -> Value :: Type
94 Gets the value used for uninitialized entries.
96 See also new/2.
98 fix(Array :: array(Type)) -> array(Type)
100 Fixes the array size. This prevents it from growing automati‐
102 cally upon insertion.
103 See also set/3 and relax/1.
105 foldl(Function, InitialAcc :: A, Array :: array(Type)) -> B
107 Types:
109 Function =
111 fun((Index :: array_indx(), Value :: Type, Acc :: A) ->
112 B)
113 Folds the array elements using the specified function and ini‐
115 tial accumulator value. The elements are visited in order from
116 the lowest index to the highest. If Function is not a function,
117 the call fails with reason badarg.
118 See also foldr/3, map/2, sparse_foldl/3.
120 foldr(Function, InitialAcc :: A, Array :: array(Type)) -> B
122 Types:
124 Function =
126 fun((Index :: array_indx(), Value :: Type, Acc :: A) ->
127 B)
128 Folds the array elements right-to-left using the specified func‐
130 tion and initial accumulator value. The elements are visited in
131 order from the highest index to the lowest. If Function is not a
132 function, the call fails with reason badarg.
133 See also foldl/3, map/2.
135 from_list(List :: [Value :: Type]) -> array(Type)
137 Equivalent to from_list(List, undefined).
139 from_list(List :: [Value :: Type], Default :: term()) ->
141 array(Type)
142 Converts a list to an extendible array. Default is used as the
144 value for uninitialized entries of the array. If List is not a
145 proper list, the call fails with reason badarg.
146 See also new/2, to_list/1.
148 from_orddict(Orddict :: indx_pairs(Value :: Type)) -> array(Type)
150 Equivalent to from_orddict(Orddict, undefined).
152 from_orddict(Orddict :: indx_pairs(Value :: Type),
154 Default :: Type) ->
155 array(Type)
156 Converts an ordered list of pairs {Index, Value} to a corre‐
158 sponding extendible array. Default is used as the value for
159 uninitialized entries of the array. If Orddict is not a proper,
160 ordered list of pairs whose first elements are non-negative
161 integers, the call fails with reason badarg.
162 See also new/2, to_orddict/1.
164 get(I :: array_indx(), Array :: array(Type)) -> Value :: Type
166 Gets the value of entry I. If I is not a non-negative integer,
168 or if the array has fixed size and I is larger than the maximum
169 index, the call fails with reason badarg.
170 If the array does not have fixed size, the default value for any
172 index I greater than size(Array)-1 is returned.
173 See also set/3.
175 is_array(X :: term()) -> boolean()
177 Returns true if X is an array, otherwise false. Notice that the
179 check is only shallow, as there is no guarantee that X is a
180 well-formed array representation even if this function returns
181 true.
182 is_fix(Array :: array()) -> boolean()
184 Checks if the array has fixed size. Returns true if the array is
186 fixed, otherwise false.
187 See also fix/1.
189 map(Function, Array :: array(Type1)) -> array(Type2)
191 Types:
193 Function = fun((Index :: array_indx(), Type1) -> Type2)
195 Maps the specified function onto each array element. The ele‐
197 ments are visited in order from the lowest index to the highest.
198 If Function is not a function, the call fails with reason
199 badarg.
200 See also foldl/3, foldr/3, sparse_map/2.
202 new() -> array()
204 Creates a new, extendible array with initial size zero.
206 See also new/1, new/2.
208 new(Options :: array_opts()) -> array()
210 Creates a new array according to the specified otions. By
212 default, the array is extendible and has initial size zero.
213 Array indices start at 0.
214 Options is a single term or a list of terms, selected from the
216 following:
217 N::integer() >= 0 or {size, N::integer() >= 0}:
219 Specifies the initial array size; this also implies {fixed,
220 true}. If N is not a non-negative integer, the call fails
221 with reason badarg.
222 fixed or {fixed, true}:
224 Creates a fixed-size array. See also fix/1.
225 {fixed, false}:
227 Creates an extendible (non-fixed-size) array.
228 {default, Value}:
230 Sets the default value for the array to Value.
231 Options are processed in the order they occur in the list, that
233 is, later options have higher precedence.
234 The default value is used as the value of uninitialized entries,
236 and cannot be changed once the array has been created.
237 Examples:
239 array:new(100)
241 creates a fixed-size array of size 100.
243 array:new({default,0})
245 creates an empty, extendible array whose default value is 0.
247 array:new([{size,10},{fixed,false},{default,-1}])
249 creates an extendible array with initial size 10 whose default
251 value is -1.
252 See also fix/1, from_list/2, get/2, new/0, new/2, set/3.
254 new(Size :: integer() >= 0, Options :: array_opts()) -> array()
256 Creates a new array according to the specified size and options.
258 If Size is not a non-negative integer, the call fails with rea‐
259 son badarg. By default, the array has fixed size. Notice that
260 any size specifications in Options override parameter Size.
261 If Options is a list, this is equivalent to new([{size, Size} |
263 Options], otherwise it is equivalent to new([{size, Size} |
264 [Options]]. However, using this function directly is more effi‐
265 cient.
266 Example:
268 array:new(100, {default,0})
270 creates a fixed-size array of size 100, whose default value is
272 0.
273 See also new/1.
275 relax(Array :: array(Type)) -> array(Type)
277 Makes the array resizable. (Reverses the effects of fix/1.)
279 See also fix/1.
281 reset(I :: array_indx(), Array :: array(Type)) -> array(Type)
283 Resets entry I to the default value for the array. If the value
285 of entry I is the default value, the array is returned
286 unchanged. Reset never changes the array size. Shrinking can be
287 done explicitly by calling resize/2.
288 If I is not a non-negative integer, or if the array has fixed
290 size and I is larger than the maximum index, the call fails with
291 reason badarg; compare set/3
292 See also new/2, set/3.
294 resize(Array :: array(Type)) -> array(Type)
296 Changes the array size to that reported by sparse_size/1. If the
298 specified array has fixed size, also the resulting array has
299 fixed size.
300 See also resize/2, sparse_size/1.
302 resize(Size :: integer() >= 0, Array :: array(Type)) ->
304 array(Type)
305 Change the array size. If Size is not a non-negative integer,
307 the call fails with reason badarg. If the specified array has
308 fixed size, also the resulting array has fixed size.
309 set(I :: array_indx(), Value :: Type, Array :: array(Type)) ->
311 array(Type)
312 Sets entry I of the array to Value. If I is not a non-negative
314 integer, or if the array has fixed size and I is larger than the
315 maximum index, the call fails with reason badarg.
316 If the array does not have fixed size, and I is greater than
318 size(Array)-1, the array grows to size I+1.
319 See also get/2, reset/2.
321 size(Array :: array()) -> integer() >= 0
323 Gets the number of entries in the array. Entries are numbered
325 from 0 to size(Array)-1. Hence, this is also the index of the
326 first entry that is guaranteed to not have been previously set.
327 See also set/3, sparse_size/1.
329 sparse_foldl(Function, InitialAcc :: A, Array :: array(Type)) -> B
331 Types:
333 Function =
335 fun((Index :: array_indx(), Value :: Type, Acc :: A) ->
336 B)
337 Folds the array elements using the specified function and ini‐
339 tial accumulator value, skipping default-valued entries. The
340 elements are visited in order from the lowest index to the high‐
341 est. If Function is not a function, the call fails with reason
342 badarg.
343 See also foldl/3, sparse_foldr/3.
345 sparse_foldr(Function, InitialAcc :: A, Array :: array(Type)) -> B
347 Types:
349 Function =
351 fun((Index :: array_indx(), Value :: Type, Acc :: A) ->
352 B)
353 Folds the array elements right-to-left using the specified func‐
355 tion and initial accumulator value, skipping default-valued
356 entries. The elements are visited in order from the highest
357 index to the lowest. If Function is not a function, the call
358 fails with reason badarg.
359 See also foldr/3, sparse_foldl/3.
361 sparse_map(Function, Array :: array(Type1)) -> array(Type2)
363 Types:
365 Function = fun((Index :: array_indx(), Type1) -> Type2)
367 Maps the specified function onto each array element, skipping
369 default-valued entries. The elements are visited in order from
370 the lowest index to the highest. If Function is not a function,
371 the call fails with reason badarg.
372 See also map/2.
374 sparse_size(Array :: array()) -> integer() >= 0
376 Gets the number of entries in the array up until the last non-
378 default-valued entry. That is, returns I+1 if I is the last non-
379 default-valued entry in the array, or zero if no such entry
380 exists.
381 See also resize/1, size/1.
383 sparse_to_list(Array :: array(Type)) -> [Value :: Type]
385 Converts the array to a list, skipping default-valued entries.
387 See also to_list/1.
389 sparse_to_orddict(Array :: array(Type)) ->
391 indx_pairs(Value :: Type)
392 Converts the array to an ordered list of pairs {Index, Value},
394 skipping default-valued entries.
395 See also to_orddict/1.
397 to_list(Array :: array(Type)) -> [Value :: Type]
399 Converts the array to a list.
401 See also from_list/2, sparse_to_list/1.
403 to_orddict(Array :: array(Type)) -> indx_pairs(Value :: Type)
405 Converts the array to an ordered list of pairs {Index, Value}.
407 See also from_orddict/2, sparse_to_orddict/1.
409Ericsson AB stdlib 3.14.1 array(3)