Provided by: erlang-manpages_22.2.7+dfsg-1_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 useszero-based indexing. This is a deliberate design choice and differs from other Erlang data structures, for example, 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 that has been explicitly set to the same value as the default one (comparereset/2). If you need to differentiate between unset and set entries, ensure that the default value cannot be confused with the values of set entries. The array never shrinks automatically. If an indexIhas been used to set an entry successfully, all indices in the range [0,I] stay accessible unless the array size is explicitly changed by callingresize/2.Examples:Create a fixed-size array with entries 0-9 set toundefined: A0 = array:new(10). 10 = array:size(A0). Create an extendible array and set entry 17 totrue, 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 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(Type)A functional, extendible array. The representation is not documented and is subject to change without notice. Notice that arrays cannot be directly compared for equality.array()=array(term())array_indx()= integer() >= 0array_opts()=array_opt()| [array_opt()]array_opt()= {fixed, boolean()} | fixed | {default, Type :: term()} | {size, N :: integer() >= 0} | (N :: integer() >= 0)indx_pairs(Type)= [indx_pair(Type)]indx_pair(Type)= {Index ::array_indx(), Type}

**EXPORTS**

default(Array::array(Type))->Value::TypeGets the value used for uninitialized entries. See alsonew/2.fix(Array::array(Type))->array(Type)Fixes the array size. This prevents it from growing automatically upon insertion. See alsoset/3andrelax/1.foldl(Function,InitialAcc::A,Array::array(Type))->BTypes: Function = fun((Index ::array_indx(), Value :: Type, Acc :: A) -> B) Folds the array elements using the specified 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. See alsofoldr/3,map/2,sparse_foldl/3.foldr(Function,InitialAcc::A,Array::array(Type))->BTypes: Function = fun((Index ::array_indx(), Value :: Type, Acc :: A) -> B) Folds the array elements right-to-left using the specified 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. See alsofoldl/3,map/2.from_list(List::[Value::Type])->array(Type)Equivalent tofrom_list(List,undefined).from_list(List::[Value::Type],Default::term())->array(Type)Converts 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. See alsonew/2,to_list/1.from_orddict(Orddict::indx_pairs(Value::Type))->array(Type)Equivalent tofrom_orddict(Orddict,undefined).from_orddict(Orddict::indx_pairs(Value::Type),Default::Type)->array(Type)Converts 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 non- negative integers, the call fails with reasonbadarg. See alsonew/2,to_orddict/1.get(I::array_indx(),Array::array(Type))->Value::TypeGets the value of entryI. IfIis not a non-negative 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, the default value for any indexIgreater thansize(Array)-1is returned. See alsoset/3.is_array(X::term())->boolean()ReturnstrueifXis an array, otherwisefalse. Notice that the check is only shallow, as there is no guarantee thatXis a well-formed array representation even if this function returnstrue.is_fix(Array::array())->boolean()Checks if the array has fixed size. Returnstrueif the array is fixed, otherwisefalse. See alsofix/1.map(Function,Array::array(Type1))->array(Type2)Types: Function = fun((Index ::array_indx(), Type1) -> Type2) Maps the specified function onto each array element. The elements are visited in order from the lowest index to the highest. IfFunctionis not a function, the call fails with reasonbadarg. See alsofoldl/3,foldr/3,sparse_map/2.new()->array()Creates a new, extendible array with initial size zero. See alsonew/1,new/2.new(Options::array_opts())->array()Creates a new array according to the specified otions. By default, the array is extendible and has initial size zero. Array indices start at0.Optionsis a single term or a list of terms, selected from the following:N::integer()>=0or{size,N::integer()>=0}: Specifies the initial array size; this also implies{fixed,true}. IfNis not a non-negative 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, that is, 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 is0. array:new([{size,10},{fixed,false},{default,-1}]) creates an extendible array with initial size 10 whose default value is-1. See alsofix/1,from_list/2,get/2,new/0,new/2,set/3.new(Size::integer()>=0,Options::array_opts())->array()Creates a new array according to the specified size and options. IfSizeis not a non-negative integer, the call fails with reasonbadarg. By default, the array has fixed size. Notice that any size specifications inOptionsoverride parameterSize. IfOptionsis a list, this is 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 is0. See alsonew/1.relax(Array::array(Type))->array(Type)Makes the array resizable. (Reverses the effects offix/1.) See alsofix/1.reset(I::array_indx(),Array::array(Type))->array(Type)Resets entryIto the default value for the array. If the value of entryIis the default value, the array is returned unchanged. Reset never changes the array size. Shrinking can be done explicitly by callingresize/2. IfIis not a non-negative integer, or if the array has fixed size andIis larger than the maximum index, the call fails with reasonbadarg; compareset/3See alsonew/2,set/3.resize(Array::array(Type))->array(Type)Changes the array size to that reported bysparse_size/1. If the specified array has fixed size, also the resulting array has fixed size. See alsoresize/2,sparse_size/1.resize(Size::integer()>=0,Array::array(Type))->array(Type)Change the array size. IfSizeis not a non-negative integer, the call fails with reasonbadarg. If the specified array has fixed size, also the resulting array has fixed size.set(I::array_indx(),Value::Type,Array::array(Type))->array(Type)Sets entryIof the array toValue. IfIis not a non-negative 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 grows to sizeI+1. See alsoget/2,reset/2.size(Array::array())->integer()>=0Gets the number of entries in the array. Entries are numbered from0tosize(Array)-1. Hence, this is also the index of the first entry that is guaranteed to not have been previously set. See alsoset/3,sparse_size/1.sparse_foldl(Function,InitialAcc::A,Array::array(Type))->BTypes: Function = fun((Index ::array_indx(), Value :: Type, Acc :: A) -> B) Folds the array elements using the specified 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. See alsofoldl/3,sparse_foldr/3.sparse_foldr(Function,InitialAcc::A,Array::array(Type))->BTypes: Function = fun((Index ::array_indx(), Value :: Type, Acc :: A) -> B) Folds the array elements right-to-left using the specified 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. See alsofoldr/3,sparse_foldl/3.sparse_map(Function,Array::array(Type1))->array(Type2)Types: Function = fun((Index ::array_indx(), Type1) -> Type2) Maps the specified function onto each array element, 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. See alsomap/2.sparse_size(Array::array())->integer()>=0Gets the number of entries in the array up until the last non-default-valued entry. That is, returnsI+1ifIis the last non-default-valued entry in the array, or zero if no such entry exists. See alsoresize/1,size/1.sparse_to_list(Array::array(Type))->[Value::Type]Converts the array to a list, skipping default-valued entries. See alsoto_list/1.sparse_to_orddict(Array::array(Type))->indx_pairs(Value::Type)Converts the array to an ordered list of pairs{Index,Value}, skipping default- valued entries. See alsoto_orddict/1.to_list(Array::array(Type))->[Value::Type]Converts the array to a list. See alsofrom_list/2,sparse_to_list/1.to_orddict(Array::array(Type))->indx_pairs(Value::Type)Converts the array to an ordered list of pairs{Index,Value}. See alsofrom_orddict/2,sparse_to_orddict/1.