diff options
Diffstat (limited to 'lib/stdlib/doc/src/array.xml')
| -rw-r--r-- | lib/stdlib/doc/src/array.xml | 177 |
1 files changed, 90 insertions, 87 deletions
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 @@ <erlref> <header> <copyright> - <year>2007</year><year>2009</year> + <year>2007</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -82,19 +82,35 @@ the default value cannot be confused with the values of set entries.</p> %% allow accesses beyond the last set entry {'EXIT',{badarg,_}} = (catch array:set(18, true, A3)). {'EXIT',{badarg,_}} = (catch array:get(18, A3)).</pre></description> -<section><title>DATA TYPES</title><marker id="types"/> - -<taglist> -<tag><c>array()</c></tag> -<item><marker id="type-array"/> -<p>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.</p> -</item> -</taglist></section> +<datatypes> + <datatype> + <name><marker id="type-array">array()</marker></name> + <desc> + <p>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.</p> + </desc> + </datatype> + <datatype> + <name name="array_indx"/> + </datatype> + <datatype> + <name name="array_opts"/> + </datatype> + <datatype> + <name name="array_opt"/> + </datatype> + <datatype> + <name name="indx_pairs"/> + </datatype> + <datatype> + <name name="indx_pair"/> + </datatype> +</datatypes> + <funcs> <func> -<name>default(Array::array()) -> term()</name> +<name name="default" arity="1"/> <fsummary>Get the value used for uninitialized entries.</fsummary> <desc><marker id="default-1"/> @@ -104,7 +120,7 @@ the default value cannot be confused with the values of set entries.</p> <p><em>See also:</em> <seealso marker="#new-2">new/2</seealso>.</p> </desc></func> <func> -<name>fix(Array::array()) -> array()</name> +<name name="fix" arity="1"/> <fsummary>Fix the size of the array.</fsummary> <desc><marker id="fix-1"/> @@ -114,105 +130,100 @@ the default value cannot be confused with the values of set entries.</p> <p><em>See also:</em> <seealso marker="#relax-1">relax/1</seealso>.</p> </desc></func> <func> -<name>foldl(Function, InitialAcc::term(), Array::array()) -> term()</name> +<name name="foldl" arity="3"/> <fsummary>Fold the elements of the array using the given function and initial accumulator value.</fsummary> -<type> -<v>Function = (Index::integer(), Value::term(), Acc::term()) -> term()</v></type> <desc><marker id="foldl-3"/> - <p>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 <c>Function</c> is not a function, the + lowest index to the highest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#foldr-3">foldr/3</seealso>, <seealso marker="#map-2">map/2</seealso>, <seealso marker="#sparse_foldl-3">sparse_foldl/3</seealso>.</p> </desc></func> <func> -<name>foldr(Function, InitialAcc::term(), Array::array()) -> term()</name> +<name name="foldr" arity="3"/> <fsummary>Fold the elements of the array right-to-left using the given function and initial accumulator value.</fsummary> -<type> -<v>Function = (Index::integer(), Value::term(), Acc::term()) -> term()</v></type> <desc><marker id="foldr-3"/> <p>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 <c>Function</c> is not a + order from the highest index to the lowest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#foldl-3">foldl/3</seealso>, <seealso marker="#map-2">map/2</seealso>.</p> </desc></func> <func> -<name>from_list(List::list()) -> array()</name> +<name name="from_list" arity="1"/> <fsummary>Equivalent to from_list(List, undefined). </fsummary> <desc><marker id="from_list-1"/> -<p>Equivalent to <seealso marker="#from_list-2">from_list(List, undefined)</seealso>.</p> +<p>Equivalent to <seealso marker="#from_list-2">from_list(<anno>List</anno>, undefined)</seealso>.</p> </desc></func> <func> -<name>from_list(List::list(), Default::term()) -> array()</name> +<name name="from_list" arity="2"/> <fsummary>Convert a list to an extendible array.</fsummary> <desc><marker id="from_list-2"/> -<p>Convert a list to an extendible array. <c>Default</c> is used as the value - for uninitialized entries of the array. If <c>List</c> is not a proper list, +<p>Convert a list to an extendible array. <c><anno>Default</anno></c> is used as the value + for uninitialized entries of the array. If <c><anno>List</anno></c> is not a proper list, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#new-2">new/2</seealso>, <seealso marker="#to_list-1">to_list/1</seealso>.</p> </desc></func> <func> -<name>from_orddict(Orddict::list()) -> array()</name> +<name name="from_orddict" arity="1"/> <fsummary>Equivalent to from_orddict(Orddict, undefined). </fsummary> <desc><marker id="from_orddict-1"/> -<p>Equivalent to <seealso marker="#from_orddict-2">from_orddict(Orddict, undefined)</seealso>.</p> +<p>Equivalent to <seealso marker="#from_orddict-2">from_orddict(<anno>Orddict</anno>, undefined)</seealso>.</p> </desc></func> <func> -<name>from_orddict(List::list(), Default::term()) -> array()</name> +<name name="from_orddict" arity="2"/> <fsummary>Convert an ordered list of pairs {Index, Value} to a corresponding extendible array.</fsummary> <desc><marker id="from_orddict-2"/> <p>Convert an ordered list of pairs <c>{Index, Value}</c> to a - corresponding extendible array. <c>Default</c> is used as the value for - uninitialized entries of the array. If <c>List</c> is not a proper, + corresponding extendible array. <c><anno>Default</anno></c> is used as the value for + uninitialized entries of the array. If <c><anno>Orddict</anno></c> is not a proper, ordered list of pairs whose first elements are nonnegative integers, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#new-2">new/2</seealso>, <seealso marker="#to_orddict-1">to_orddict/1</seealso>.</p> </desc></func> <func> -<name>get(I::integer(), Array::array()) -> term()</name> +<name name="get" arity="2"/> <fsummary>Get the value of entry I.</fsummary> <desc><marker id="get-2"/> -<p>Get the value of entry <c>I</c>. If <c>I</c> is not a nonnegative - integer, or if the array has fixed size and <c>I</c> is larger than the +<p>Get the value of entry <c><anno>I</anno></c>. If <c><anno>I</anno></c> is not a nonnegative + integer, or if the array has fixed size and <c><anno>I</anno></c> is larger than the maximum index, the call fails with reason <c>badarg</c>.</p> <p>If the array does not have fixed size, this function will return the - default value for any index <c>I</c> greater than <c>size(Array)-1</c>.</p> + default value for any index <c><anno>I</anno></c> greater than <c>size(<anno>Array</anno>)-1</c>.</p> <p><em>See also:</em> <seealso marker="#set-3">set/3</seealso>.</p> </desc></func> <func> -<name>is_array(X::term()) -> bool()</name> +<name name="is_array" arity="1"/> <fsummary>Returns true if X appears to be an array, otherwise false.</fsummary> <desc><marker id="is_array-1"/> -<p>Returns <c>true</c> if <c>X</c> appears to be an array, otherwise <c>false</c>. - Note that the check is only shallow; there is no guarantee that <c>X</c> +<p>Returns <c>true</c> if <c><anno>X</anno></c> appears to be an array, otherwise <c>false</c>. + Note that the check is only shallow; there is no guarantee that <c><anno>X</anno></c> is a well-formed array representation even if this function returns <c>true</c>.</p> </desc></func> <func> -<name>is_fix(Array::array()) -> bool()</name> +<name name="is_fix" arity="1"/> <fsummary>Check if the array has fixed size.</fsummary> <desc><marker id="is_fix-1"/> @@ -222,20 +233,18 @@ the default value cannot be confused with the values of set entries.</p> <p><em>See also:</em> <seealso marker="#fix-1">fix/1</seealso>.</p> </desc></func> <func> -<name>map(Function, Array::array()) -> array()</name> +<name name="map" arity="2"/> <fsummary>Map the given function onto each element of the array.</fsummary> -<type> -<v>Function = (Index::integer(), Value::term()) -> term()</v></type> <desc><marker id="map-2"/> <p>Map the given function onto each element of the array. The elements are visited in order from the lowest index to the highest. - If <c>Function</c> is not a function, the call fails with reason <c>badarg</c>. + If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#foldl-3">foldl/3</seealso>, <seealso marker="#foldr-3">foldr/3</seealso>, <seealso marker="#sparse_map-2">sparse_map/2</seealso>.</p> </desc></func> <func> -<name>new() -> array()</name> +<name name="new" arity="0"/> <fsummary>Create a new, extendible array with initial size zero.</fsummary> <desc><marker id="new-0"/> @@ -244,7 +253,7 @@ the default value cannot be confused with the values of set entries.</p> <p><em>See also:</em> <seealso marker="#new-1">new/1</seealso>, <seealso marker="#new-2">new/2</seealso>.</p> </desc></func> <func> -<name>new(Options::term()) -> array()</name> +<name name="new" arity="1"/> <fsummary>Create a new array according to the given options.</fsummary> <desc><marker id="new-1"/> @@ -253,10 +262,10 @@ the default value cannot be confused with the values of set entries.</p> the array is extendible and has initial size zero. Array indices start at 0.</p> - <p><c>Options</c> is a single term or a list of terms, selected from the + <p><c><anno>Options</anno></c> is a single term or a list of terms, selected from the following: </p><taglist> - <tag><c>N::integer()</c> or <c>{size, N::integer()}</c></tag> + <tag><c>N::integer() >= 0</c> or <c>{size, N::integer() >= 0}</c></tag> <item><p>Specifies the initial size of the array; this also implies <c>{fixed, true}</c>. If <c>N</c> is not a nonnegative integer, the call fails with reason <c>badarg</c>.</p></item> @@ -283,19 +292,19 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#fix-1">fix/1</seealso>, <seealso marker="#from_list-2">from_list/2</seealso>, <seealso marker="#get-2">get/2</seealso>, <seealso marker="#new-0">new/0</seealso>, <seealso marker="#new-2">new/2</seealso>, <seealso marker="#set-3">set/3</seealso>.</p> </desc></func> <func> -<name>new(Size::integer(), Options::term()) -> array()</name> +<name name="new" arity="2"/> <fsummary>Create a new array according to the given size and options.</fsummary> <desc><marker id="new-2"/> <p>Create a new array according to the given size and options. If - <c>Size</c> is not a nonnegative integer, the call fails with reason + <c><anno>Size</anno></c> is not a nonnegative integer, the call fails with reason <c>badarg</c>. By default, the array has fixed size. Note that any size - specifications in <c>Options</c> will override the <c>Size</c> parameter.</p> + specifications in <c><anno>Options</anno></c> will override the <c><anno>Size</anno></c> parameter.</p> - <p>If <c>Options</c> is a list, this is simply equivalent to <c>new([{size, - Size} | Options]</c>, otherwise it is equivalent to <c>new([{size, Size} | - [Options]]</c>. However, using this function directly is more efficient.</p> + <p>If <c><anno>Options</anno></c> is a list, this is simply equivalent to <c>new([{size, + <anno>Size</anno>} | <anno>Options</anno>]</c>, otherwise it is equivalent to <c>new([{size, <anno>Size</anno>} | + [<anno>Options</anno>]]</c>. However, using this function directly is more efficient.</p> <p>Example: </p><pre> array:new(100, {default,0})</pre><p> creates a fixed-size array of size @@ -304,7 +313,7 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#new-1">new/1</seealso>.</p> </desc></func> <func> -<name>relax(Array::array()) -> array()</name> +<name name="relax" arity="1"/> <fsummary>Make the array resizable.</fsummary> <desc><marker id="relax-1"/> @@ -313,24 +322,24 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#fix-1">fix/1</seealso>.</p> </desc></func> <func> -<name>reset(I::integer(), Array::array()) -> array()</name> +<name name="reset" arity="2"/> <fsummary>Reset entry I to the default value for the array.</fsummary> <desc><marker id="reset-2"/> -<p>Reset entry <c>I</c> to the default value for the array. - If the value of entry <c>I</c> is the default value the array will be +<p>Reset entry <c><anno>I</anno></c> to the default value for the array. + If the value of entry <c><anno>I</anno></c> 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 <seealso marker="#resize-2">resize/2</seealso>.</p> - <p>If <c>I</c> is not a nonnegative integer, or if the array has fixed size - and <c>I</c> is larger than the maximum index, the call fails with reason + <p>If <c><anno>I</anno></c> is not a nonnegative integer, or if the array has fixed size + and <c><anno>I</anno></c> is larger than the maximum index, the call fails with reason <c>badarg</c>; cf. <seealso marker="#set-3">set/3</seealso> </p> <p><em>See also:</em> <seealso marker="#new-2">new/2</seealso>, <seealso marker="#set-3">set/3</seealso>.</p> </desc></func> <func> -<name>resize(Array::array()) -> array()</name> +<name name="resize" arity="1"/> <fsummary>Change the size of the array to that reported by sparse_size/1.</fsummary> <desc><marker id="resize-1"/> @@ -340,90 +349,84 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#resize-2">resize/2</seealso>, <seealso marker="#sparse_size-1">sparse_size/1</seealso>.</p> </desc></func> <func> -<name>resize(Size::integer(), Array::array()) -> array()</name> +<name name="resize" arity="2"/> <fsummary>Change the size of the array.</fsummary> <desc><marker id="resize-2"/> -<p>Change the size of the array. If <c>Size</c> is not a nonnegative +<p>Change the size of the array. If <c><anno>Size</anno></c> is not a nonnegative integer, the call fails with reason <c>badarg</c>. If the given array has fixed size, the resulting array will also have fixed size.</p> </desc></func> <func> -<name>set(I::integer(), Value::term(), Array::array()) -> array()</name> +<name name="set" arity="3"/> <fsummary>Set entry I of the array to Value.</fsummary> <desc><marker id="set-3"/> -<p>Set entry <c>I</c> of the array to <c>Value</c>. If <c>I</c> is not a - nonnegative integer, or if the array has fixed size and <c>I</c> is larger +<p>Set entry <c><anno>I</anno></c> of the array to <c><anno>Value</anno></c>. If <c><anno>I</anno></c> is not a + nonnegative integer, or if the array has fixed size and <c><anno>I</anno></c> is larger than the maximum index, the call fails with reason <c>badarg</c>.</p> - <p>If the array does not have fixed size, and <c>I</c> is greater than - <c>size(Array)-1</c>, the array will grow to size <c>I+1</c>. + <p>If the array does not have fixed size, and <c><anno>I</anno></c> is greater than + <c>size(<anno>Array</anno>)-1</c>, the array will grow to size <c><anno>I</anno>+1</c>. </p> <p><em>See also:</em> <seealso marker="#get-2">get/2</seealso>, <seealso marker="#reset-2">reset/2</seealso>.</p> </desc></func> <func> -<name>size(Array::array()) -> integer()</name> +<name name="size" arity="1"/> <fsummary>Get the number of entries in the array.</fsummary> <desc><marker id="size-1"/> <p>Get the number of entries in the array. Entries are numbered - from 0 to <c>size(Array)-1</c>; hence, this is also the index of the first + from 0 to <c>size(<anno>Array</anno>)-1</c>; hence, this is also the index of the first entry that is guaranteed to not have been previously set.</p> <p><em>See also:</em> <seealso marker="#set-3">set/3</seealso>, <seealso marker="#sparse_size-1">sparse_size/1</seealso>.</p> </desc></func> <func> -<name>sparse_foldl(Function, InitialAcc::term(), Array::array()) -> term()</name> +<name name="sparse_foldl" arity="3"/> <fsummary>Fold the elements of the array using the given function and initial accumulator value, skipping default-valued entries.</fsummary> -<type> -<v>Function = (Index::integer(), Value::term(), Acc::term()) -> term()</v></type> <desc><marker id="sparse_foldl-3"/> <p>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 <c>Function</c> is not a function, the call fails with reason <c>badarg</c>. + If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#foldl-3">foldl/3</seealso>, <seealso marker="#sparse_foldr-3">sparse_foldr/3</seealso>.</p> </desc></func> <func> -<name>sparse_foldr(Function, InitialAcc::term(), Array::array()) -> term()</name> +<name name="sparse_foldr" arity="3"/> <fsummary>Fold the elements of the array right-to-left using the given function and initial accumulator value, skipping default-valued entries.</fsummary> -<type> -<v>Function = (Index::integer(), Value::term(), Acc::term()) -> term()</v></type> <desc><marker id="sparse_foldr-3"/> <p>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 <c>Function</c> is not a function, the call fails with + the lowest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#foldr-3">foldr/3</seealso>, <seealso marker="#sparse_foldl-3">sparse_foldl/3</seealso>.</p> </desc></func> <func> -<name>sparse_map(Function, Array::array()) -> array()</name> +<name name="sparse_map" arity="2"/> <fsummary>Map the given function onto each element of the array, skipping default-valued entries.</fsummary> -<type> -<v>Function = (Index::integer(), Value::term()) -> term()</v></type> <desc><marker id="sparse_map-2"/> <p>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 <c>Function</c> is not a function, the + lowest index to the highest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>. </p> <p><em>See also:</em> <seealso marker="#map-2">map/2</seealso>.</p> </desc></func> <func> -<name>sparse_size(A::array()) -> integer()</name> +<name name="sparse_size" arity="1"/> <fsummary>Get the number of entries in the array up until the last non-default valued entry.</fsummary> @@ -436,7 +439,7 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#resize-1">resize/1</seealso>, <seealso marker="#size-1">size/1</seealso>.</p> </desc></func> <func> -<name>sparse_to_list(Array::array()) -> list()</name> +<name name="sparse_to_list" arity="1"/> <fsummary>Converts the array to a list, skipping default-valued entries.</fsummary> <desc><marker id="sparse_to_list-1"/> @@ -446,7 +449,7 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#to_list-1">to_list/1</seealso>.</p> </desc></func> <func> -<name>sparse_to_orddict(Array::array()) -> [{Index::integer(), Value::term()}]</name> +<name name="sparse_to_orddict" arity="1"/> <fsummary>Convert the array to an ordered list of pairs {Index, Value}, skipping default-valued entries.</fsummary> @@ -458,7 +461,7 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#to_orddict-1">to_orddict/1</seealso>.</p> </desc></func> <func> -<name>to_list(Array::array()) -> list()</name> +<name name="to_list" arity="1"/> <fsummary>Converts the array to a list.</fsummary> <desc><marker id="to_list-1"/> @@ -468,7 +471,7 @@ cannot be changed once the array has been created.</p> <p><em>See also:</em> <seealso marker="#from_list-2">from_list/2</seealso>, <seealso marker="#sparse_to_list-1">sparse_to_list/1</seealso>.</p> </desc></func> <func> -<name>to_orddict(Array::array()) -> [{Index::integer(), Value::term()}]</name> +<name name="to_orddict" arity="1"/> <fsummary>Convert the array to an ordered list of pairs {Index, Value}.</fsummary> <desc><marker id="to_orddict-1"/> |