aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/array.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
committerBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
commit1280c70da91b90592ae4be88f1f045956e716de7 (patch)
tree42a0b48e54a9b5c982ce606b8c7e7ff9c564ade6 /lib/stdlib/doc/src/array.xml
parent3873cb650711342aced0036e3c2d640df8a73c4b (diff)
parent68d53c01b0b8e9a007a6a30158c19e34b2d2a34e (diff)
downloadotp-1280c70da91b90592ae4be88f1f045956e716de7.tar.gz
otp-1280c70da91b90592ae4be88f1f045956e716de7.tar.bz2
otp-1280c70da91b90592ae4be88f1f045956e716de7.zip
Merge branch 'bjorn/stdlib/doc'
* bjorn/stdlib/doc: Update STDLIB documentation
Diffstat (limited to 'lib/stdlib/doc/src/array.xml')
-rw-r--r--lib/stdlib/doc/src/array.xml1003
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>