diff options
Diffstat (limited to 'lib/stdlib/doc/src/array.xml')
| -rw-r--r-- | lib/stdlib/doc/src/array.xml | 1003 |
1 files changed, 538 insertions, 465 deletions
diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml index bff98245bf..db0ab42372 100644 --- a/lib/stdlib/doc/src/array.xml +++ b/lib/stdlib/doc/src/array.xml @@ -1,7 +1,8 @@ <?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> + <erlref> -<header> + <header> <copyright> <year>2007</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> @@ -21,469 +22,541 @@ </legalnotice> -<title>array</title> -<prepared></prepared> -<responsible></responsible> -<docno>1</docno> -<approved></approved> -<checked></checked> -<date></date> -<rev>A</rev> -<file>array.xml</file></header> -<module>array</module> -<modulesummary>Functional, extendible arrays.</modulesummary> -<description> -<p>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.</p> - - <p>Arrays uses <em>zero</em> based indexing. This is a deliberate design -choice and differs from other erlang datastructures, e.g. tuples.</p> - - <p>Unless specified by the user when the array is created, the default - value is the atom <c>undefined</c>. 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. <seealso marker="#reset-2">reset/2</seealso>). 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.</p> - - <p>The array never shrinks automatically; if an index <c>I</c> has been used - successfully to set an entry, all indices in the range [0,<c>I</c>] will - stay accessible unless the array size is explicitly changed by - calling <seealso marker="#resize-2">resize/2</seealso>.</p> - - <p>Examples: - </p><pre> %% 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)).</pre></description> -<datatypes> - <datatype> - <name name="array" n_vars="1"/> - <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" n_vars="0"/> - </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 name="default" arity="1"/> -<fsummary>Get the value used for uninitialized entries.</fsummary> - -<desc><marker id="default-1"/> - -<p>Get the value used for uninitialized entries. - </p> -<p><em>See also:</em> <seealso marker="#new-2">new/2</seealso>.</p> -</desc></func> -<func> -<name name="fix" arity="1"/> -<fsummary>Fix the size of the array.</fsummary> - -<desc><marker id="fix-1"/> - -<p>Fix the size of the array. This prevents it from growing - automatically upon insertion; see also <seealso marker="#set-3">set/3</seealso>.</p> -<p><em>See also:</em> <seealso marker="#relax-1">relax/1</seealso>.</p> -</desc></func> -<func> -<name name="foldl" arity="3"/> -<fsummary>Fold the elements of the array using the given function and - initial accumulator value.</fsummary> -<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><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 name="foldr" arity="3"/> -<fsummary>Fold the elements of the array right-to-left using the given - function and initial accumulator value.</fsummary> -<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><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 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(<c><anno>List</anno></c>, undefined)</seealso>.</p> -</desc></func> -<func> -<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><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 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(<c><anno>Orddict</anno></c>, undefined)</seealso>.</p> -</desc></func> -<func> -<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, <anno>Value</anno>}</c> to a - 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 name="get" arity="2"/> -<fsummary>Get the value of entry I.</fsummary> - -<desc><marker id="get-2"/> - -<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><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 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><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 name="is_fix" arity="1"/> -<fsummary>Check if the array has fixed size.</fsummary> - -<desc><marker id="is_fix-1"/> - -<p>Check if the array has fixed size. - Returns <c>true</c> if the array is fixed, otherwise <c>false</c>.</p> -<p><em>See also:</em> <seealso marker="#fix-1">fix/1</seealso>.</p> -</desc></func> -<func> -<name name="map" arity="2"/> -<fsummary>Map the given function onto each element of the array.</fsummary> -<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><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 name="new" arity="0"/> -<fsummary>Create a new, extendible array with initial size zero.</fsummary> - -<desc><marker id="new-0"/> - -<p>Create a new, extendible array with initial size zero.</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 name="new" arity="1"/> -<fsummary>Create a new array according to the given options.</fsummary> - -<desc><marker id="new-1"/> - -<p>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.</p> - - <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() >= 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> - <tag><c>fixed</c> or <c>{fixed, true}</c></tag> - <item><p>Creates a fixed-size array; see also <seealso marker="#fix-1">fix/1</seealso>.</p></item> - <tag><c>{fixed, false}</c></tag> - <item><p>Creates an extendible (non fixed-size) array.</p></item> - <tag><c>{default, Value}</c></tag> - <item><p>Sets the default value for the array to <c>Value</c>.</p></item> - </taglist><p> -Options are processed in the order they occur in the list, i.e., -later options have higher precedence.</p> - - <p>The default value is used as the value of uninitialized entries, and -cannot be changed once the array has been created.</p> - - <p>Examples: - </p><pre> array:new(100)</pre><p> creates a fixed-size array of size 100. - </p><pre> array:new({default,0})</pre><p> creates an empty, extendible array - whose default value is 0. - </p><pre> array:new([{size,10},{fixed,false},{default,-1}])</pre><p> creates an - extendible array with initial size 10 whose default value is -1. - </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 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><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><anno>Options</anno></c> will override the <c><anno>Size</anno></c> parameter.</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 - 100, whose default value is 0. - </p> -<p><em>See also:</em> <seealso marker="#new-1">new/1</seealso>.</p> -</desc></func> -<func> -<name name="relax" arity="1"/> -<fsummary>Make the array resizable.</fsummary> - -<desc><marker id="relax-1"/> - -<p>Make the array resizable. (Reverses the effects of <seealso marker="#fix-1">fix/1</seealso>.)</p> -<p><em>See also:</em> <seealso marker="#fix-1">fix/1</seealso>.</p> -</desc></func> -<func> -<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><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><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 name="resize" arity="1"/> -<fsummary>Change the size of the array to that reported by sparse_size/1.</fsummary> - -<desc><marker id="resize-1"/> - -<p>Change the size of the array to that reported by <seealso marker="#sparse_size-1">sparse_size/1</seealso>. If the given array has fixed size, the resulting - array will also have fixed size.</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 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><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 name="set" arity="3"/> -<fsummary>Set entry I of the array to Value.</fsummary> - -<desc><marker id="set-3"/> - -<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><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 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(<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 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> -<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><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 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> -<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><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 name="sparse_map" arity="2"/> -<fsummary>Map the given function onto each element of the array, skipping - default-valued entries.</fsummary> -<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><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 name="sparse_size" arity="1"/> -<fsummary>Get the number of entries in the array up until the last - non-default valued entry.</fsummary> - -<desc><marker id="sparse_size-1"/> - -<p>Get the number of entries in the array up until the last - non-default valued entry. In other words, returns <c>I+1</c> if <c>I</c> is the - last non-default valued entry in the array, or zero if no such entry - exists.</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 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"/> - -<p>Converts the array to a list, skipping default-valued entries. - </p> -<p><em>See also:</em> <seealso marker="#to_list-1">to_list/1</seealso>.</p> -</desc></func> -<func> -<name name="sparse_to_orddict" arity="1"/> -<fsummary>Convert the array to an ordered list of pairs {Index, Value}, - skipping default-valued entries.</fsummary> - -<desc><marker id="sparse_to_orddict-1"/> - -<p>Convert the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>, - skipping default-valued entries. - </p> -<p><em>See also:</em> <seealso marker="#to_orddict-1">to_orddict/1</seealso>.</p> -</desc></func> -<func> -<name name="to_list" arity="1"/> -<fsummary>Converts the array to a list.</fsummary> - -<desc><marker id="to_list-1"/> - -<p>Converts the array to a list. - </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 name="to_orddict" arity="1"/> -<fsummary>Convert the array to an ordered list of pairs {Index, Value}.</fsummary> - -<desc><marker id="to_orddict-1"/> - -<p>Convert the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>. - </p> -<p><em>See also:</em> <seealso marker="#from_orddict-2">from_orddict/2</seealso>, <seealso marker="#sparse_to_orddict-1">sparse_to_orddict/1</seealso>.</p> -</desc></func></funcs> - + <title>array</title> + <prepared></prepared> + <responsible></responsible> + <docno>1</docno> + <approved></approved> + <checked></checked> + <date></date> + <rev>A</rev> + <file>array.xml</file> + </header> + <module>array</module> + <modulesummary>Functional, extendible arrays.</modulesummary> + <description> + <p>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.</p> + + <p>Arrays uses <em>zero</em>-based indexing. This is a deliberate design + choice and differs from other Erlang data structures, for example, + tuples.</p> + + <p>Unless specified by the user when the array is created, the default + value is the atom <c>undefined</c>. There is no difference between an + unset entry and an entry that has been explicitly set to the same value + as the default one (compare + <seealso marker="#reset-2"><c>reset/2</c></seealso>). If you need to + differentiate between unset and set entries, ensure that the default value + cannot be confused with the values of set entries.</p> + + <p>The array never shrinks automatically. If an index <c>I</c> has been used + to set an entry successfully, all indices in the range [0,<c>I</c>] stay + accessible unless the array size is explicitly changed by calling + <seealso marker="#resize-2"><c>resize/2</c></seealso>.</p> + + <p><em>Examples:</em></p> + + <p>Create a fixed-size array with entries 0-9 set to <c>undefined</c>:</p> + + <pre> +A0 = array:new(10). +10 = array:size(A0).</pre> + + <p>Create an extendible array and set entry 17 to <c>true</c>, causing the + array to grow automatically:</p> + + <pre> +A1 = array:set(17, true, array:new()). +18 = array:size(A1).</pre> + + <p>Read back a stored value:</p> + + <pre> +true = array:get(17, A1).</pre> + + <p>Accessing an unset entry returns default value:</p> + + <pre> +undefined = array:get(3, A1)</pre> + + <p>Accessing an entry beyond the last set entry also returns the default + value, if the array does not have fixed size:</p> + + <pre> +undefined = array:get(18, A1).</pre> + + <p>"Sparse" functions ignore default-valued entries:</p> + + <pre> +A2 = array:set(4, false, A1). +[{4, false}, {17, true}] = array:sparse_to_orddict(A2).</pre> + + <p>An extendible array can be made fixed-size later:</p> + + <pre> +A3 = array:fix(A2).</pre> + + <p>A fixed-size array does not grow automatically and does not allow + accesses beyond the last set entry:</p> + + <pre> +{'EXIT',{badarg,_}} = (catch array:set(18, true, A3)). +{'EXIT',{badarg,_}} = (catch array:get(18, A3)).</pre> + </description> + + <datatypes> + <datatype> + <name name="array" n_vars="1"/> + <desc> + <p>A functional, extendible array. The representation is not documented + and is subject to change without notice. Notice that arrays cannot be + directly compared for equality.</p> + </desc> + </datatype> + <datatype> + <name name="array" n_vars="0"/> + </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 name="default" arity="1"/> + <fsummary>Get the value used for uninitialized entries.</fsummary> + <desc><marker id="default-1"/> + <p>Gets the value used for uninitialized entries.</p> + <p>See also <seealso marker="#new-2"><c>new/2</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="fix" arity="1"/> + <fsummary>Fix the array size.</fsummary> + <desc><marker id="fix-1"/> + <p>Fixes the array size. This prevents it from growing automatically + upon insertion.</p> + <p>See also <seealso marker="#set-3"><c>set/3</c></seealso> and + <seealso marker="#relax-1"><c>relax/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="foldl" arity="3"/> + <fsummary>Fold the array elements using the specified function and initial + accumulator value.</fsummary> + <desc><marker id="foldl-3"/> + <p>Folds the array elements using the specified function and initial + accumulator value. The elements are visited in order from 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>See also <seealso marker="#foldr-3"><c>foldr/3</c></seealso>, + <seealso marker="#map-2"><c>map/2</c></seealso>, + <seealso marker="#sparse_foldl-3"><c>sparse_foldl/3</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="foldr" arity="3"/> + <fsummary>Fold the array elements right-to-left using the specified + function and initial accumulator value.</fsummary> + <desc><marker id="foldr-3"/> + <p>Folds the array elements right-to-left using the specified function + and initial accumulator value. The elements are visited in 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>See also <seealso marker="#foldl-3"><c>foldl/3</c></seealso>, + <seealso marker="#map-2"><c>map/2</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="from_list" arity="1"/> + <fsummary>Equivalent to <c>from_list(List, undefined)</c>.</fsummary> + <desc><marker id="from_list-1"/> + <p>Equivalent to + <seealso marker="#from_list-2"><c>from_list(<anno>List</anno>, undefined)</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="from_list" arity="2"/> + <fsummary>Convert a list to an extendible array.</fsummary> + <desc><marker id="from_list-2"/> + <p>Converts 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>See also <seealso marker="#new-2"><c>new/2</c></seealso>, + <seealso marker="#to_list-1"><c>to_list/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="from_orddict" arity="1"/> + <fsummary>Equivalent to <c>from_orddict(Orddict, undefined)</c>. + </fsummary> + <desc><marker id="from_orddict-1"/> + <p>Equivalent to + <seealso marker="#from_orddict-2"><c>from_orddict(<anno>Orddict</anno>, undefined)</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="from_orddict" arity="2"/> + <fsummary>Convert an ordered list of pairs <c>{Index, Value}</c> to a + corresponding extendible array.</fsummary> + <desc><marker id="from_orddict-2"/> + <p>Converts an ordered list of pairs <c>{Index, <anno>Value</anno>}</c> + to a 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 non-negative integers, the call fails with + reason <c>badarg</c>.</p> + <p>See also <seealso marker="#new-2"><c>new/2</c></seealso>, + <seealso marker="#to_orddict-1"><c>to_orddict/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="get" arity="2"/> + <fsummary>Get the value of entry <c>I</c>.</fsummary> + <desc><marker id="get-2"/> + <p>Gets the value of entry <c><anno>I</anno></c>. If + <c><anno>I</anno></c> is not a non-negative 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, the default value for any + index <c><anno>I</anno></c> greater than + <c>size(<anno>Array</anno>)-1</c> is returned.</p> + <p>See also <seealso marker="#set-3"><c>set/3</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="is_array" arity="1"/> + <fsummary>Returns <c>true</c> if <c>X</c> is an array, otherwise + <c>false</c>.</fsummary> + <desc><marker id="is_array-1"/> + <p>Returns <c>true</c> if <c><anno>X</anno></c> is an array, otherwise + <c>false</c>. Notice that the check is only shallow, as 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 name="is_fix" arity="1"/> + <fsummary>Check if the array has fixed size.</fsummary> + <desc><marker id="is_fix-1"/> + <p>Checks if the array has fixed size. Returns <c>true</c> if the array + is fixed, otherwise <c>false</c>.</p> + <p>See also <seealso marker="#fix-1"><c>fix/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="map" arity="2"/> + <fsummary>Map the specified function onto each array element.</fsummary> + <desc><marker id="map-2"/> + <p>Maps the specified function onto each array element. The elements are + visited in order from 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>See also <seealso marker="#foldl-3"><c>foldl/3</c></seealso>, + <seealso marker="#foldr-3"><c>foldr/3</c></seealso>, + <seealso marker="#sparse_map-2"><c>sparse_map/2</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="new" arity="0"/> + <fsummary>Create a new, extendible array with initial size zero. + </fsummary> + <desc><marker id="new-0"/> + <p>Creates a new, extendible array with initial size zero.</p> + <p>See also <seealso marker="#new-1"><c>new/1</c></seealso>, + <seealso marker="#new-2"><c>new/2</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="new" arity="1"/> + <fsummary>Create a new array according to the specified options. + </fsummary> + <desc><marker id="new-1"/> + <p>Creates a new array according to the specified otions. By default, + the array is extendible and has initial size zero. Array indices + start at <c>0</c>.</p> + <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() >= 0</c> or <c>{size, N::integer() >= 0}</c> + </tag> + <item><p>Specifies the initial array size; this also implies + <c>{fixed, true}</c>. If <c>N</c> is not a non-negative integer, the + call fails with reason <c>badarg</c>.</p></item> + <tag><c>fixed</c> or <c>{fixed, true}</c></tag> + <item><p>Creates a fixed-size array. See also + <seealso marker="#fix-1"><c>fix/1</c></seealso>.</p></item> + <tag><c>{fixed, false}</c></tag> + <item><p>Creates an extendible (non-fixed-size) array.</p></item> + <tag><c>{default, Value}</c></tag> + <item><p>Sets the default value for the array to <c>Value</c>.</p> + </item> + </taglist> + <p>Options are processed in the order they occur in the list, that is, + later options have higher precedence.</p> + <p>The default value is used as the value of uninitialized entries, and + cannot be changed once the array has been created.</p> + <p><em>Examples:</em></p> + <pre> +array:new(100)</pre> + <p>creates a fixed-size array of size 100.</p> + <pre> +array:new({default,0})</pre> + <p>creates an empty, extendible array whose default value is <c>0</c>. + </p> + <pre> +array:new([{size,10},{fixed,false},{default,-1}])</pre> + <p>creates an extendible array with initial size 10 whose default value + is <c>-1</c>.</p> + <p>See also <seealso marker="#fix-1"><c>fix/1</c></seealso>, + <seealso marker="#from_list-2"><c>from_list/2</c></seealso>, + <seealso marker="#get-2"><c>get/2</c></seealso>, + <seealso marker="#new-0"><c>new/0</c></seealso>, + <seealso marker="#new-2"><c>new/2</c></seealso>, + <seealso marker="#set-3"><c>set/3</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="new" arity="2"/> + <fsummary>Create a new array according to the specified size and options. + </fsummary> + <desc><marker id="new-2"/> + <p>Creates a new array according to the specified size and options. If + <c><anno>Size</anno></c> is not a non-negative integer, the call fails + with reason <c>badarg</c>. By default, the array has fixed size. + Notice that any size specifications in <c><anno>Options</anno></c> + override parameter <c><anno>Size</anno></c>.</p> + <p>If <c><anno>Options</anno></c> is a list, this is 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><em>Example:</em></p> + <pre> +array:new(100, {default,0})</pre> + <p>creates a fixed-size array of size 100, whose default value is + <c>0</c>.</p> + <p>See also <seealso marker="#new-1"><c>new/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="relax" arity="1"/> + <fsummary>Make the array resizable.</fsummary> + <desc><marker id="relax-1"/> + <p>Makes the array resizable. (Reverses the effects of + <seealso marker="#fix-1"><c>fix/1</c></seealso>.)</p> + <p>See also <seealso marker="#fix-1"><c>fix/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="reset" arity="2"/> + <fsummary>Reset entry <c>I</c> to the default value for the array. + </fsummary> + <desc><marker id="reset-2"/> + <p>Resets 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 is returned unchanged. Reset never changes the array + size. Shrinking can be done explicitly by calling + <seealso marker="#resize-2"><c>resize/2</c></seealso>.</p> + <p>If <c><anno>I</anno></c> is not a non-negative 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>; compare + <seealso marker="#set-3"><c>set/3</c></seealso></p> + <p>See also <seealso marker="#new-2"><c>new/2</c></seealso>, + <seealso marker="#set-3"><c>set/3</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="resize" arity="1"/> + <fsummary>Change the array size to that reported by <c>sparse_size/1</c>. + </fsummary> + <desc><marker id="resize-1"/> + <p>Changes the array size to that reported by + <seealso marker="#sparse_size-1"><c>sparse_size/1</c></seealso>. If + the specified array has fixed size, also the resulting array has fixed + size.</p> + <p>See also <seealso marker="#resize-2"><c>resize/2</c></seealso>, + <seealso marker="#sparse_size-1"><c>sparse_size/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="resize" arity="2"/> + <fsummary>Change the array size.</fsummary> + <desc><marker id="resize-2"/> + <p>Change the array size. If <c><anno>Size</anno></c> is not a + non-negative integer, the call fails with reason <c>badarg</c>. If + the specified array has fixed size, also the resulting array has fixed + size.</p> + </desc> + </func> + + <func> + <name name="set" arity="3"/> + <fsummary>Set entry <c>I</c> of the array to <c>Value</c>.</fsummary> + <desc><marker id="set-3"/> + <p>Sets entry <c><anno>I</anno></c> of the array to + <c><anno>Value</anno></c>. If <c><anno>I</anno></c> is not a + non-negative 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><anno>I</anno></c> is + greater than <c>size(<anno>Array</anno>)-1</c>, the array grows to + size <c><anno>I</anno>+1</c>.</p> + <p>See also <seealso marker="#get-2"><c>get/2</c></seealso>, + <seealso marker="#reset-2"><c>reset/2</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="size" arity="1"/> + <fsummary>Get the number of entries in the array.</fsummary> + <desc><marker id="size-1"/> + <p>Gets the number of entries in the array. Entries are numbered from + <c>0</c> 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>See also <seealso marker="#set-3"><c>set/3</c></seealso>, + <seealso marker="#sparse_size-1"><c>sparse_size/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="sparse_foldl" arity="3"/> + <fsummary>Fold the array elements using the specified function and initial + accumulator value, skipping default-valued entries.</fsummary> + <desc><marker id="sparse_foldl-3"/> + <p>Folds the array elements using the specified function and initial + accumulator value, skipping default-valued entries. The elements are + visited in order from 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>See also <seealso marker="#foldl-3"><c>foldl/3</c></seealso>, + <seealso marker="#sparse_foldr-3"><c>sparse_foldr/3</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="sparse_foldr" arity="3"/> + <fsummary>Fold the array elements right-to-left using the specified + function and initial accumulator value, skipping default-valued + entries.</fsummary> + <desc><marker id="sparse_foldr-3"/> + <p>Folds the array elements right-to-left using the specified + function and initial accumulator value, skipping default-valued + entries. The elements are visited in 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>See also <seealso marker="#foldr-3"><c>foldr/3</c></seealso>, + <seealso marker="#sparse_foldl-3"><c>sparse_foldl/3</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="sparse_map" arity="2"/> + <fsummary>Map the specified function onto each array element, skipping + default-valued entries.</fsummary> + <desc><marker id="sparse_map-2"/> + <p>Maps the specified function onto each array element, skipping + default-valued entries. The elements are visited in order from 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>See also <seealso marker="#map-2"><c>map/2</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="sparse_size" arity="1"/> + <fsummary>Get the number of entries in the array up until the last + non-default-valued entry.</fsummary> + <desc><marker id="sparse_size-1"/> + <p>Gets the number of entries in the array up until the last + non-default-valued entry. That is, returns <c>I+1</c> if <c>I</c> is + the last non-default-valued entry in the array, or zero if no such + entry exists.</p> + <p>See also <seealso marker="#resize-1"><c>resize/1</c></seealso>, + <seealso marker="#size-1"><c>size/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="sparse_to_list" arity="1"/> + <fsummary>Convert the array to a list, skipping default-valued entries. + </fsummary> + <desc><marker id="sparse_to_list-1"/> + <p>Converts the array to a list, skipping default-valued entries.</p> + <p>See also <seealso marker="#to_list-1"><c>to_list/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="sparse_to_orddict" arity="1"/> + <fsummary>Convert the array to an ordered list of pairs <c>{Index, + Value}</c>, skipping default-valued entries.</fsummary> + <desc><marker id="sparse_to_orddict-1"/> + <p>Converts the array to an ordered list of pairs <c>{Index, + <anno>Value</anno>}</c>, skipping default-valued entries.</p> + <p>See also + <seealso marker="#to_orddict-1"><c>to_orddict/1</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="to_list" arity="1"/> + <fsummary>Convert the array to a list.</fsummary> + <desc><marker id="to_list-1"/> + <p>Converts the array to a list.</p> + <p>See also <seealso marker="#from_list-2"><c>from_list/2</c></seealso>, + <seealso marker="#sparse_to_list-1"><c>sparse_to_list/1</c></seealso>. + </p> + </desc> + </func> + + <func> + <name name="to_orddict" arity="1"/> + <fsummary>Convert the array to an ordered list of pairs <c>{Index, + Value}</c>.</fsummary> + <desc><marker id="to_orddict-1"/> + <p>Converts the array to an ordered list of pairs <c>{Index, + <anno>Value</anno>}</c>.</p> + <p>See also + <seealso marker="#from_orddict-2"><c>from_orddict/2</c></seealso>, + <seealso marker="#sparse_to_orddict-1"><c>sparse_to_orddict/1</c></seealso>. + </p> + </desc> + </func> + </funcs> </erlref> |