From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/array.xml | 482 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 482 insertions(+) create mode 100644 lib/stdlib/doc/src/array.xml (limited to 'lib/stdlib/doc/src/array.xml') diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml new file mode 100644 index 0000000000..5c3ac6a2a9 --- /dev/null +++ b/lib/stdlib/doc/src/array.xml @@ -0,0 +1,482 @@ + + + +
+ + 20072009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + +array + + +1 + + + +A +array.xml
+array +Functional, extendible arrays. + +

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.

+ +
+ + +default(Array::array()) -> term() +Get the value used for uninitialized entries. + + + +

Get the value used for uninitialized entries. +

+

See also: new/2.

+ + +fix(Array::array()) -> array() +Fix the size of the 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::term(), Array::array()) -> term() +Fold the elements of the array using the given function and + initial accumulator value. + +Function = (Index::integer(), Value::term(), Acc::term()) -> term() + + +

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::term(), Array::array()) -> term() +Fold the elements of the array right-to-left using the given + function and initial accumulator value. + +Function = (Index::integer(), Value::term(), Acc::term()) -> term() + + +

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). + + + +

Equivalent to from_list(List, undefined).

+ + +from_list(List::list(), Default::term()) -> array() +Convert a list to an extendible 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::list()) -> array() +Equivalent to from_orddict(Orddict, undefined). + + + +

Equivalent to from_orddict(Orddict, undefined).

+ + +from_orddict(List::list(), Default::term()) -> array() +Convert an ordered list of pairs {Index, Value} to a + corresponding extendible 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 List 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::integer(), Array::array()) -> term() +Get the value of entry I. + + + +

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()) -> bool() +Returns true if X appears to be an array, otherwise false. + + + +

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()) -> bool() +Check if the array has fixed size. + + + +

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() +Map the given function onto each element of the array. + +Function = (Index::integer(), 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. + + + +

Create a new, extendible array with initial size zero.

+

See also: new/1, new/2.

+ + +new(Options::term()) -> array() +Create a new array according to the given options. + + + +

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() or {size, N::integer()} +

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(), Options::term()) -> array() +Create a new array according to the given size and options. + + + +

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

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

+

See also: fix/1.

+ + +reset(I::integer(), Array::array()) -> array() +Reset entry I to the default value for the 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. + + + +

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(), Array::array()) -> array() +Change the size of the 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::integer(), Value::term(), Array::array()) -> array() +Set entry I of the array to Value. + + + +

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() +Get the number of entries in the array. + + + +

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::term(), Array::array()) -> term() +Fold the elements of the array using the given function and + initial accumulator value, skipping default-valued entries. + +Function = (Index::integer(), Value::term(), Acc::term()) -> term() + + +

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::term(), Array::array()) -> term() +Fold the elements of the array right-to-left using the given + function and initial accumulator value, skipping default-valued + entries. + +Function = (Index::integer(), Value::term(), Acc::term()) -> term() + + +

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() +Map the given function onto each element of the array, skipping + default-valued entries. + +Function = (Index::integer(), 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(A::array()) -> integer() +Get the number of entries in the array up until the last + non-default valued entry. + + + +

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

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

+

See also: to_list/1.

+ + +sparse_to_orddict(Array::array()) -> [{Index::integer(), Value::term()}] +Convert the array to an ordered list of pairs {Index, Value}, + skipping default-valued entries. + + + +

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

Converts the array to a list. +

+

See also: from_list/2, sparse_to_list/1.

+ + +to_orddict(Array::array()) -> [{Index::integer(), Value::term()}] +Convert the array to an ordered list of pairs {Index, Value}. + + + +

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

+

See also: from_orddict/2, sparse_to_orddict/1.

+ + + + -- cgit v1.2.3