1array(3)                   Erlang Module Definition                   array(3)
2
3
4

NAME

6       array - Functional, extendible arrays.
7

DESCRIPTION

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
13       Arrays uses zero-based indexing. This is a deliberate design choice and
14       differs from other Erlang data structures, for example, tuples.
15
16       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
23       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
27       Examples:
28
29       Create a fixed-size array with entries 0-9 set to undefined:
30
31       A0 = array:new(10).
32       10 = array:size(A0).
33
34       Create  an extendible array and set entry 17 to true, causing the array
35       to grow automatically:
36
37       A1 = array:set(17, true, array:new()).
38       18 = array:size(A1).
39
40       Read back a stored value:
41
42       true = array:get(17, A1).
43
44       Accessing an unset entry returns default value:
45
46       undefined = array:get(3, A1)
47
48       Accessing an entry beyond the last set entry also returns  the  default
49       value, if the array does not have fixed size:
50
51       undefined = array:get(18, A1).
52
53       "Sparse" functions ignore default-valued entries:
54
55       A2 = array:set(4, false, A1).
56       [{4, false}, {17, true}] = array:sparse_to_orddict(A2).
57
58       An extendible array can be made fixed-size later:
59
60       A3 = array:fix(A2).
61
62       A  fixed-size  array  does  not  grow  automatically and does not allow
63       accesses beyond the last set entry:
64
65       {'EXIT',{badarg,_}} = (catch array:set(18, true, A3)).
66       {'EXIT',{badarg,_}} = (catch array:get(18, A3)).
67

DATA TYPES

69       array(Type)
70
71              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
75       array() = array(term())
76
77       array_indx() = integer() >= 0
78
79       array_opts() = array_opt() | [array_opt()]
80
81       array_opt() =
82           {fixed, boolean()} |
83           fixed |
84           {default, Type :: term()} |
85           {size, N :: integer() >= 0} |
86           (N :: integer() >= 0)
87
88       indx_pairs(Type) = [indx_pair(Type)]
89
90       indx_pair(Type) = {Index :: array_indx(), Type}
91

EXPORTS

93       default(Array :: array(Type)) -> Value :: Type
94
95              Gets the value used for uninitialized entries.
96
97              See also new/2.
98
99       fix(Array :: array(Type)) -> array(Type)
100
101              Fixes the array size. This prevents it  from  growing  automati‐
102              cally upon insertion.
103
104              See also set/3 and relax/1.
105
106       foldl(Function, InitialAcc :: A, Array :: array(Type)) -> B
107
108              Types:
109
110                 Function =
111                     fun((Index  ::  array_indx(), Value :: Type, Acc :: A) ->
112                 B)
113
114              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
119              See also foldr/3, map/2, sparse_foldl/3.
120
121       foldr(Function, InitialAcc :: A, Array :: array(Type)) -> B
122
123              Types:
124
125                 Function =
126                     fun((Index  ::  array_indx(), Value :: Type, Acc :: A) ->
127                 B)
128
129              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
134              See also foldl/3, map/2.
135
136       from_list(List :: [Value :: Type]) -> array(Type)
137
138              Equivalent to from_list(List, undefined).
139
140       from_list(List :: [Value :: Type], Default :: term()) ->
141                    array(Type)
142
143              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
147              See also new/2, to_list/1.
148
149       from_orddict(Orddict :: indx_pairs(Value :: Type)) -> array(Type)
150
151              Equivalent to from_orddict(Orddict, undefined).
152
153       from_orddict(Orddict :: indx_pairs(Value :: Type),
154                    Default :: Type) ->
155                       array(Type)
156
157              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
163              See also new/2, to_orddict/1.
164
165       get(I :: array_indx(), Array :: array(Type)) -> Value :: Type
166
167              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
171              If the array does not have fixed size, the default value for any
172              index I greater than size(Array)-1 is returned.
173
174              See also set/3.
175
176       is_array(X :: term()) -> boolean()
177
178              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
183       is_fix(Array :: array()) -> boolean()
184
185              Checks if the array has fixed size. Returns true if the array is
186              fixed, otherwise false.
187
188              See also fix/1.
189
190       map(Function, Array :: array(Type1)) -> array(Type2)
191
192              Types:
193
194                 Function = fun((Index :: array_indx(), Type1) -> Type2)
195
196              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
201              See also foldl/3, foldr/3, sparse_map/2.
202
203       new() -> array()
204
205              Creates a new, extendible array with initial size zero.
206
207              See also new/1, new/2.
208
209       new(Options :: array_opts()) -> array()
210
211              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
215              Options  is  a single term or a list of terms, selected from the
216              following:
217
218                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
223                fixed or {fixed, true}:
224                  Creates a fixed-size array. See also fix/1.
225
226                {fixed, false}:
227                  Creates an extendible (non-fixed-size) array.
228
229                {default, Value}:
230                  Sets the default value for the array to Value.
231
232              Options are processed in the order they occur in the list,  that
233              is, later options have higher precedence.
234
235              The default value is used as the value of uninitialized entries,
236              and cannot be changed once the array has been created.
237
238              Examples:
239
240              array:new(100)
241
242              creates a fixed-size array of size 100.
243
244              array:new({default,0})
245
246              creates an empty, extendible array whose default value is 0.
247
248              array:new([{size,10},{fixed,false},{default,-1}])
249
250              creates an extendible array with initial size 10  whose  default
251              value is -1.
252
253              See also fix/1, from_list/2, get/2, new/0, new/2, set/3.
254
255       new(Size :: integer() >= 0, Options :: array_opts()) -> array()
256
257              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
262              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
267              Example:
268
269              array:new(100, {default,0})
270
271              creates  a  fixed-size array of size 100, whose default value is
272              0.
273
274              See also new/1.
275
276       relax(Array :: array(Type)) -> array(Type)
277
278              Makes the array resizable. (Reverses the effects of fix/1.)
279
280              See also fix/1.
281
282       reset(I :: array_indx(), Array :: array(Type)) -> array(Type)
283
284              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
289              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
293              See also new/2, set/3.
294
295       resize(Array :: array(Type)) -> array(Type)
296
297              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
301              See also resize/2, sparse_size/1.
302
303       resize(Size :: integer() >= 0, Array :: array(Type)) ->
304                 array(Type)
305
306              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
310       set(I :: array_indx(), Value :: Type, Array :: array(Type)) ->
311              array(Type)
312
313              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
317              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
320              See also get/2, reset/2.
321
322       size(Array :: array()) -> integer() >= 0
323
324              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
328              See also set/3, sparse_size/1.
329
330       sparse_foldl(Function, InitialAcc :: A, Array :: array(Type)) -> B
331
332              Types:
333
334                 Function =
335                     fun((Index :: array_indx(), Value :: Type, Acc ::  A)  ->
336                 B)
337
338              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
344              See also foldl/3, sparse_foldr/3.
345
346       sparse_foldr(Function, InitialAcc :: A, Array :: array(Type)) -> B
347
348              Types:
349
350                 Function =
351                     fun((Index  ::  array_indx(), Value :: Type, Acc :: A) ->
352                 B)
353
354              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
360              See also foldr/3, sparse_foldl/3.
361
362       sparse_map(Function, Array :: array(Type1)) -> array(Type2)
363
364              Types:
365
366                 Function = fun((Index :: array_indx(), Type1) -> Type2)
367
368              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
373              See also map/2.
374
375       sparse_size(Array :: array()) -> integer() >= 0
376
377              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
382              See also resize/1, size/1.
383
384       sparse_to_list(Array :: array(Type)) -> [Value :: Type]
385
386              Converts the array to a list, skipping default-valued entries.
387
388              See also to_list/1.
389
390       sparse_to_orddict(Array :: array(Type)) ->
391                            indx_pairs(Value :: Type)
392
393              Converts the array to an ordered list of pairs  {Index,  Value},
394              skipping default-valued entries.
395
396              See also to_orddict/1.
397
398       to_list(Array :: array(Type)) -> [Value :: Type]
399
400              Converts the array to a list.
401
402              See also from_list/2, sparse_to_list/1.
403
404       to_orddict(Array :: array(Type)) -> indx_pairs(Value :: Type)
405
406              Converts the array to an ordered list of pairs {Index, Value}.
407
408              See also from_orddict/2, sparse_to_orddict/1.
409
410
411
412Ericsson AB                      stdlib 3.14.1                        array(3)
Impressum