Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all

**NAME**

array - Functional, extendible arrays.

**DESCRIPTION**

Functional, extendible arrays. Arrays can have fixed size, or can grow automatically as needed. A default value is used for entries that have not been explicitly set. Arrays useszerobased indexing. This is a deliberate design choice and differs from other erlang datastructures, e.g. tuples. Unless specified by the user when the array is created, the default value is the atomundefined. There is no difference between an unset entry and an entry which has been explicitly set to the same value as the default one (cf.reset/2). If you need to differentiate between unset and set entries, you must make sure that the default value cannot be confused with the values of set entries. The array never shrinks automatically; if an indexIhas been used successfully to set an entry, all indices in the range [0,I] will stay accessible unless the array size is explicitly changed by callingresize/2. Examples: %% Create a fixed-size array with entries 0-9 set to 'undefined' A0 = array:new(10). 10 = array:size(A0). %% Create an extendible array and set entry 17 to 'true', %% causing the array to grow automatically A1 = array:set(17, true, array:new()). 18 = array:size(A1). %% Read back a stored value true = array:get(17, A1). %% Accessing an unset entry returns the default value undefined = array:get(3, A1). %% Accessing an entry beyond the last set entry also returns the %% default value, if the array does not have fixed size undefined = array:get(18, A1). %% "sparse" functions ignore default-valued entries A2 = array:set(4, false, A1). [{4, false}, {17, true}] = array:sparse_to_orddict(A2). %% An extendible array can be made fixed-size later A3 = array:fix(A2). %% A fixed-size array does not grow automatically and does not %% allow accesses beyond the last set entry {'EXIT',{badarg,_}} = (catch array:set(18, true, A3)). {'EXIT',{badarg,_}} = (catch array:get(18, A3)).

**DATA** **TYPES**

array()A functional, extendible array. The representation is not documented and is subject to change without notice. Note that arrays cannot be directly compared for equality.array_indx()= integer() >= 0array_opts()=array_opt()| [array_opt()]array_opt()= {fixed, boolean()} | fixed | {default, Value :: term()} | {size, N :: integer() >= 0} | (N :: integer() >= 0)indx_pairs()= [indx_pair()]indx_pair()= {Index ::array_indx(), Value :: term()}

**EXPORTS**

default(Array::array())->term()Get the value used for uninitialized entries.Seealso:new/2.fix(Array::array())->array()Fix the size of the array. This prevents it from growing automatically upon insertion; see alsoset/3.Seealso:relax/1.foldl(Function,InitialAcc::A,Array::array())->BTypes: Function = fun((Index ::array_indx(), Value :: term(), Acc :: A) -> B) Fold the elements of the array using the given function and initial accumulator value. The elements are visited in order from the lowest index to the highest. IfFunctionis not a function, the call fails with reasonbadarg.Seealso:foldr/3,map/2,sparse_foldl/3.foldr(Function,InitialAcc::A,Array::array())->BTypes: Function = fun((Index ::array_indx(), Value :: term(), Acc :: A) -> B) Fold the elements of the array right-to-left using the given function and initial accumulator value. The elements are visited in order from the highest index to the lowest. IfFunctionis not a function, the call fails with reasonbadarg.Seealso:foldl/3,map/2.from_list(List::list())->array()Equivalent tofrom_list(List,undefined).from_list(List::list(),Default::term())->array()Convert a list to an extendible array.Defaultis used as the value for uninitialized entries of the array. IfListis not a proper list, the call fails with reasonbadarg.Seealso:new/2,to_list/1.from_orddict(Orddict::indx_pairs())->array()Equivalent tofrom_orddict(Orddict,undefined).from_orddict(Orddict::indx_pairs(),Default::term())->array()Convert an ordered list of pairs{Index,Value}to a corresponding extendible array.Defaultis used as the value for uninitialized entries of the array. IfOrddictis not a proper, ordered list of pairs whose first elements are nonnegative integers, the call fails with reasonbadarg.Seealso:new/2,to_orddict/1.get(I::array_indx(),Array::array())->term()Get the value of entryI. IfIis not a nonnegative integer, or if the array has fixed size andIis larger than the maximum index, the call fails with reasonbadarg. If the array does not have fixed size, this function will return the default value for any indexIgreater thansize(Array)-1.Seealso:set/3.is_array(X::term())->boolean()ReturnstrueifXappears to be an array, otherwisefalse. Note that the check is only shallow; there is no guarantee thatXis a well-formed array representation even if this function returnstrue.is_fix(Array::array())->boolean()Check if the array has fixed size. Returnstrueif the array is fixed, otherwisefalse.Seealso:fix/1.map(Function,Array::array())->array()Types: Function = fun((Index ::array_indx(), Value :: term()) -> term()) Map the given function onto each element of the array. The elements are visited in order from the lowest index to the highest. IfFunctionis not a function, the call fails with reasonbadarg.Seealso:foldl/3,foldr/3,sparse_map/2.new()->array()Create a new, extendible array with initial size zero.Seealso:new/1,new/2.new(Options::array_opts())->array()Create a new array according to the given options. By default, the array is extendible and has initial size zero. Array indices start at 0.Optionsis a single term or a list of terms, selected from the following:N::integer()>=0or{size,N::integer()>=0}: Specifies the initial size of the array; this also implies{fixed,true}. IfNis not a nonnegative integer, the call fails with reasonbadarg.fixedor{fixed,true}: Creates a fixed-size array; see alsofix/1.{fixed,false}: Creates an extendible (non fixed-size) array.{default,Value}: Sets the default value for the array toValue. Options are processed in the order they occur in the list, i.e., later options have higher precedence. The default value is used as the value of uninitialized entries, and cannot be changed once the array has been created. Examples: array:new(100) creates a fixed-size array of size 100. array:new({default,0}) creates an empty, extendible array whose default value is 0. array:new([{size,10},{fixed,false},{default,-1}]) creates an extendible array with initial size 10 whose default value is -1.Seealso:fix/1,from_list/2,get/2,new/0,new/2,set/3.new(Size::integer()>=0,Options::array_opts())->array()Create a new array according to the given size and options. IfSizeis not a nonnegative integer, the call fails with reasonbadarg. By default, the array has fixed size. Note that any size specifications inOptionswill override theSizeparameter. IfOptionsis a list, this is simply equivalent tonew([{size,Size}|Options], otherwise it is equivalent tonew([{size,Size}|[Options]]. However, using this function directly is more efficient. Example: array:new(100, {default,0}) creates a fixed-size array of size 100, whose default value is 0.Seealso:new/1.relax(Array::array())->array()Make the array resizable. (Reverses the effects offix/1.)Seealso:fix/1.reset(I::array_indx(),Array::array())->array()Reset entryIto the default value for the array. If the value of entryIis the default value the array will be returned unchanged. Reset will never change size of the array. Shrinking can be done explicitly by callingresize/2. IfIis not a nonnegative integer, or if the array has fixed size andIis larger than the maximum index, the call fails with reasonbadarg; cf.set/3Seealso:new/2,set/3.resize(Array::array())->array()Change the size of the array to that reported bysparse_size/1. If the given array has fixed size, the resulting array will also have fixed size.Seealso:resize/2,sparse_size/1.resize(Size::integer()>=0,Array::array())->array()Change the size of the array. IfSizeis not a nonnegative integer, the call fails with reasonbadarg. If the given array has fixed size, the resulting array will also have fixed size.set(I::array_indx(),Value::term(),Array::array())->array()Set entryIof the array toValue. IfIis not a nonnegative integer, or if the array has fixed size andIis larger than the maximum index, the call fails with reasonbadarg. If the array does not have fixed size, andIis greater thansize(Array)-1, the array will grow to sizeI+1.Seealso:get/2,reset/2.size(Array::array())->integer()>=0Get the number of entries in the array. Entries are numbered from 0 tosize(Array)-1; hence, this is also the index of the first entry that is guaranteed to not have been previously set.Seealso:set/3,sparse_size/1.sparse_foldl(Function,InitialAcc::A,Array::array())->BTypes: Function = fun((Index ::array_indx(), Value :: term(), Acc :: A) -> B) Fold the elements of the array using the given function and initial accumulator value, skipping default-valued entries. The elements are visited in order from the lowest index to the highest. IfFunctionis not a function, the call fails with reasonbadarg.Seealso:foldl/3,sparse_foldr/3.sparse_foldr(Function,InitialAcc::A,Array::array())->BTypes: Function = fun((Index ::array_indx(), Value :: term(), Acc :: A) -> B) Fold the elements of the array right-to-left using the given function and initial accumulator value, skipping default-valued entries. The elements are visited in order from the highest index to the lowest. IfFunctionis not a function, the call fails with reasonbadarg.Seealso:foldr/3,sparse_foldl/3.sparse_map(Function,Array::array())->array()Types: Function = fun((Index ::array_indx(), Value :: term()) -> term()) Map the given function onto each element of the array, skipping default-valued entries. The elements are visited in order from the lowest index to the highest. IfFunctionis not a function, the call fails with reasonbadarg.Seealso:map/2.sparse_size(Array::array())->integer()>=0Get the number of entries in the array up until the last non-default valued entry. In other words, returnsI+1ifIis the last non-default valued entry in the array, or zero if no such entry exists.Seealso:resize/1,size/1.sparse_to_list(Array::array())->list()Converts the array to a list, skipping default-valued entries.Seealso:to_list/1.sparse_to_orddict(Array::array())->indx_pairs()Convert the array to an ordered list of pairs{Index,Value}, skipping default- valued entries.Seealso:to_orddict/1.to_list(Array::array())->list()Converts the array to a list.Seealso:from_list/2,sparse_to_list/1.to_orddict(Array::array())->indx_pairs()Convert the array to an ordered list of pairs{Index,Value}.Seealso:from_orddict/2,sparse_to_orddict/1.