From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/array.xml | 177 ++++++++++++++++++++++--------------------- 1 file changed, 90 insertions(+), 87 deletions(-) (limited to 'lib/stdlib/doc/src/array.xml') diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml index 5c3ac6a2a9..a79fcd487e 100644 --- a/lib/stdlib/doc/src/array.xml +++ b/lib/stdlib/doc/src/array.xml @@ -3,7 +3,7 @@
- 20072009 + 20072011 Ericsson AB. All Rights Reserved. @@ -82,19 +82,35 @@ the default value cannot be confused with the values of set entries.

%% 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() + +

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. @@ -104,7 +120,7 @@ the default value cannot be confused with the values of set entries.

See also: new/2.

 -fix(Array::array()) -> array() + Fix the size of the array. @@ -114,105 +130,100 @@ the default value cannot be confused with the values of set entries.

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

+

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

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

+

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, + 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::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 +

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.

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

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. @@ -222,20 +233,18 @@ the default value cannot be confused with the values of set entries.

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. + 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. @@ -244,7 +253,7 @@ the default value cannot be confused with the values of set entries.

See also: new/1, new/2.

 -new(Options::term()) -> array() + Create a new array according to the given options. @@ -253,10 +262,10 @@ the default value cannot be confused with the values of set entries.

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 +

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

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

 @@ -283,19 +292,19 @@ cannot be changed once the array has been created.

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

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

+

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 @@ -304,7 +313,7 @@ cannot be changed once the array has been created.

See also: new/1.

 -relax(Array::array()) -> array() + Make the array resizable. @@ -313,24 +322,24 @@ cannot be changed once the array has been created.

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 +

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 +

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. @@ -340,90 +349,84 @@ cannot be changed once the array has been created.

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 +

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 +

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

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 + 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. + 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 + 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 + 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. @@ -436,7 +439,7 @@ cannot be changed once the array has been created.

See also: resize/1, size/1.

 -sparse_to_list(Array::array()) -> list() + Converts the array to a list, skipping default-valued entries. @@ -446,7 +449,7 @@ cannot be changed once the array has been created.

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. @@ -458,7 +461,7 @@ cannot be changed once the array has been created.

See also: to_orddict/1.

 -to_list(Array::array()) -> list() + Converts the array to a list. @@ -468,7 +471,7 @@ cannot be changed once the array has been created.

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}. -- cgit v1.2.3