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

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 uses zero based 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 atom
       undefined. 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 index I has 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 calling resize/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() >= 0

       array_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.

              See also: new/2.

       fix(Array :: array()) -> array()

              Fix  the  size  of  the  array.  This  prevents  it from growing automatically upon
              insertion; see also set/3.

              See also: relax/1.

       foldl(Function, InitialAcc :: A, Array :: array()) -> B

              Types:

                 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. If
              Function is not a function, the call fails with reason badarg.

              See also: foldr/3, map/2, sparse_foldl/3.

       foldr(Function, InitialAcc :: A, Array :: array()) -> B

              Types:

                 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. If Function is not a function, the call fails with reason badarg.

              See also: foldl/3, map/2.

       from_list(List :: list()) -> array()

              Equivalent to from_list(List, undefined).

       from_list(List :: list(), Default :: term()) -> array()

              Convert a  list  to  an  extendible  array.  Default  is  used  as  the  value  for
              uninitialized  entries  of  the array. If List is not a proper list, the call fails
              with reason badarg.

              See also: new/2, to_list/1.

       from_orddict(Orddict :: indx_pairs()) -> array()

              Equivalent to from_orddict(Orddict, undefined).

       from_orddict(Orddict :: indx_pairs(), Default :: term()) ->
                       array()

              Convert an ordered list of pairs  {Index,  Value}  to  a  corresponding  extendible
              array.  Default  is  used  as  the value for uninitialized entries of the array. If
              Orddict is not a proper, ordered list of pairs whose first elements are nonnegative
              integers, the call fails with reason badarg.

              See also: new/2, to_orddict/1.

       get(I :: array_indx(), Array :: array()) -> term()

              Get  the  value  of entry I. If I is not a nonnegative integer, or if the array has
              fixed size and I is larger than the maximum  index,  the  call  fails  with  reason
              badarg.

              If  the array does not have fixed size, this function will return the default value
              for any index I greater than size(Array)-1.

              See also: set/3.

       is_array(X :: term()) -> boolean()

              Returns true if X appears to be an array, otherwise false. Note that the  check  is
              only  shallow;  there  is no guarantee that X is a well-formed array representation
              even if this function returns true.

       is_fix(Array :: array()) -> boolean()

              Check if the array has fixed size. Returns true if the array  is  fixed,  otherwise
              false.

              See also: 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. If Function is not a function, the call
              fails with reason badarg.

              See also: foldl/3, foldr/3, sparse_map/2.

       new() -> array()

              Create a new, extendible array with initial size zero.

              See also: 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.

              Options is a single term or a list of terms, selected from the following:

                N::integer() >= 0 or {size, N::integer() >= 0}:
                  Specifies the initial size of the array; this also implies {fixed, true}. If  N
                  is not a nonnegative integer, the call fails with reason badarg.

                fixed or {fixed, true}:
                  Creates a fixed-size array; see also fix/1.

                {fixed, false}:
                  Creates an extendible (non fixed-size) array.

                {default, Value}:
                  Sets the default value for the array to Value.

              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.

              See also: 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. If Size is not a
              nonnegative integer, the call fails with reason badarg. By default, the  array  has
              fixed  size.  Note  that  any size specifications in Options will override the Size
              parameter.

              If Options is a list, this is simply equivalent to new([{size,  Size}  |  Options],
              otherwise  it  is equivalent to new([{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.

              See also: new/1.

       relax(Array :: array()) -> array()

              Make the array resizable. (Reverses the effects of fix/1.)

              See also: fix/1.

       reset(I :: array_indx(), Array :: array()) -> array()

              Reset entry I to the default value for the array. If the value of entry  I  is  the
              default value the array will be returned unchanged. Reset will never change size of
              the array. Shrinking can be done explicitly by calling resize/2.

              If I is not a nonnegative integer, or if the array has fixed size and I  is  larger
              than the maximum index, the call fails with reason badarg; cf. set/3

              See also: new/2, set/3.

       resize(Array :: array()) -> array()

              Change  the size of the array to that reported by sparse_size/1. If the given array
              has fixed size, the resulting array will also have fixed size.

              See also: resize/2, sparse_size/1.

       resize(Size :: integer() >= 0, Array :: array()) -> array()

              Change the size of the array. If Size is not a nonnegative integer, the call  fails
              with  reason  badarg.  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 entry I of the array to Value. If I is not a nonnegative  integer,  or  if  the
              array  has  fixed  size and I is larger than the maximum index, the call fails with
              reason badarg.

              If the array does not have fixed size, and I is  greater  than  size(Array)-1,  the
              array will grow to size I+1.

              See also: get/2, reset/2.

       size(Array :: array()) -> integer() >= 0

              Get  the  number  of  entries  in  the  array.  Entries  are  numbered  from  0  to
              size(Array)-1; hence, this is also the index of the first entry that is  guaranteed
              to not have been previously set.

              See also: set/3, sparse_size/1.

       sparse_foldl(Function, InitialAcc :: A, Array :: array()) -> B

              Types:

                 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. If Function is not a function, the call fails with
              reason badarg.

              See also: foldl/3, sparse_foldr/3.

       sparse_foldr(Function, InitialAcc :: A, Array :: array()) -> B

              Types:

                 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. If Function is not a function, the call
              fails with reason badarg.

              See also: 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. If
              Function is not a function, the call fails with reason badarg.

              See also: map/2.

       sparse_size(Array :: array()) -> integer() >= 0

              Get  the number of entries in the array up until the last non-default valued entry.
              In other words, returns I+1 if I is the last non-default valued entry in the array,
              or zero if no such entry exists.

              See also: resize/1, size/1.

       sparse_to_list(Array :: array()) -> list()

              Converts the array to a list, skipping default-valued entries.

              See also: 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.

              See also: to_orddict/1.

       to_list(Array :: array()) -> list()

              Converts the array to a list.

              See also: from_list/2, sparse_to_list/1.

       to_orddict(Array :: array()) -> indx_pairs()

              Convert the array to an ordered list of pairs {Index, Value}.

              See also: from_orddict/2, sparse_to_orddict/1.