Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
array(3)		   Erlang Module Definition		      array(3)

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 un-
       set 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 suc-
       cessfully to set	an entry, all indices in the range [0,I] will stay ac-
       cessible	 unless	 the  array  size is explicitly	changed	by calling re-
       size/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(Type)

	      A	functional, extendible array. The representation is not	 docu-
	      mented and is subject to change without notice. Note that	arrays
	      cannot be	directly compared for equality.

       array()

	      array() is equivalent to array(term()).

       array_indx() = integer()	>= 0

       array_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 :: Type

	      Get the value used for uninitialized entries.

	      See also:	new/2.

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

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

	      See also:	relax/1.

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

	      Types:

		 Function =
		     fun((Index	 ::  array_indx(), Value :: Type, Acc :: A) ->
		 B)

	      Fold the elements	of the array using the given function and ini-
	      tial  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(Type)) -> B

	      Types:

		 Function =
		     fun((Index	 ::  array_indx(), Value :: Type, 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 :: [Value	:: Type]) -> array(Type)

	      Equivalent to from_list(List, undefined).

       from_list(List :: [Value	:: Type], Default :: term()) ->
		    array(Type)

	      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(Value	:: Type)) -> array(Type)

	      Equivalent to from_orddict(Orddict, undefined).

       from_orddict(Orddict :: indx_pairs(Value	:: Type),
		    Default :: Type) ->
		       array(Type)

	      Convert an ordered list of pairs {Index, Value} to a correspond-
	      ing extendible array. Default is used as the  value  for	unini-
	      tialized	entries	 of the	array. If Orddict is not a proper, or-
	      dered list of pairs whose	first elements are  nonnegative	 inte-
	      gers, the	call fails with	reason badarg.

	      See also:	new/2, to_orddict/1.

       get(I ::	array_indx(), Array :: array(Type)) -> Value ::	Type

	      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 in-
	      dex, 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(Type1)) -> array(Type2)

	      Types:

		 Function = fun((Index :: array_indx(),	Type1) -> Type2)

	      Map the given function onto each element of the array. The  ele-
	      ments 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(Type)) -> array(Type)

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

	      See also:	fix/1.

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

	      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 un-
	      changed. 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(Type)) -> array(Type)

	      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(Type)) ->
		 array(Type)

	      Change the size of the array. If Size is not a nonnegative inte-
	      ger, 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 :: Type, Array :: array(Type)) ->
	      array(Type)

	      Set entry	I of the array to Value. If I is not a nonnegative in-
	      teger, 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(Type)) ->	B

	      Types:

		 Function =
		     fun((Index	:: array_indx(), Value :: Type,	Acc ::	A)  ->
		 B)

	      Fold the elements	of the array using the given function and ini-
	      tial accumulator value, skipping default-valued entries. The el-
	      ements  are  visited in order from the lowest index to the high-
	      est. 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(Type)) ->	B

	      Types:

		 Function =
		     fun((Index	 ::  array_indx(), Value :: Type, 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  in-
	      dex 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(Type1)) -> array(Type2)

	      Types:

		 Function = fun((Index :: array_indx(),	Type1) -> Type2)

	      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-de-
	      fault 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(Type)) -> [Value :: Type]

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

	      See also:	to_list/1.

       sparse_to_orddict(Array :: array(Type)) ->
			    indx_pairs(Value ::	Type)

	      Convert the array	to an ordered list of  pairs  {Index,  Value},
	      skipping default-valued entries.

	      See also:	to_orddict/1.

       to_list(Array ::	array(Type)) ->	[Value :: Type]

	      Converts the array to a list.

	      See also:	from_list/2, sparse_to_list/1.

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

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

	      See also:	from_orddict/2,	sparse_to_orddict/1.

Ericsson AB			  stdlib 2.4			      array(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=array&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help