cvs: /phpdoc/functions array.sgml

eschmid Tue Sep 7 16:26:09 1999 EDT Modified files: /phpdoc/functions array.sgml Log: Made a lot of line breaks. It's easy with emacs psgml-mode. Index: phpdoc/functions/array.sgml diff -u phpdoc/functions/array.sgml:1.20 phpdoc/functions/array.sgml:1.21 --- phpdoc/functions/array.sgml:1.20 Tue Sep 7 15:00:28 1999 +++ phpdoc/functions/array.sgml Tue Sep 7 16:25:39 1999 @@ -21,8 +21,8 @@ <note> <para> - <function>array</function> is a language construct used to represent - literal arrays, and not a regular function. + <function>array</function> is a language construct used to + represent literal arrays, and not a regular function. </para> </note> @@ -63,10 +63,13 @@ </funcsynopsis> <para> - <function>array_keys</function> returns the keys, numeric and string, from the <parameter>input</parameter> array. + <function>array_keys</function> returns the keys, numeric and + string, from the <parameter>input</parameter> array. <para> - If the optional <parameter>search_value</parameter> is specified, then only the keys for that value are returned. Otherwise, all the keys from the <parameter>input</parameter> are returned. + If the optional <parameter>search_value</parameter> is specified, + then only the keys for that value are returned. Otherwise, all + the keys from the <parameter>input</parameter> are returned. <para> <example> @@ -112,7 +115,10 @@ the end of the previous one. It returns the resulting array. <para> - If the input arrays had the same string keys, then the later value for that key will overwrite previous one. If, however, the arrays have the same numeric key, this does not happen since the values are appended. + If the input arrays had the same string keys, then the later + value for that key will overwrite previous one. If, however, the + arrays have the same numeric key, this does not happen since the + values are appended. <para> <example> @@ -123,7 +129,8 @@ array_merge($array1, $array2); </programlisting> <para> - Resulting array will be array("color" => "green", 2, 4, "a", "b", "shape" => "trapezoid"). + Resulting array will be array("color" => "green", 2, 4, "a", + "b", "shape" => "trapezoid"). </example> <note> @@ -177,7 +184,9 @@ <refentry id="function.array-push"> <refnamediv> <refname>array_push</refname> - <refpurpose>Push one or more elements onto the end of array</refpurpose> + <refpurpose> + Push one or more elements onto the end of array + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -210,10 +219,12 @@ array_push($stack, "+", 3); </programlisting> </example> - This example would result in $stack having 4 elements: 1, 2, "+", and 3. + This example would result in $stack having 4 elements: 1, 2, "+", + and 3. <para> - See also <function>array_pop</function>, + See also: + <function>array_pop</function>, <function>array_shift</function>, and <function>array_unshift</function>. @@ -330,7 +341,10 @@ <refentry id="function.array-splice"> <refnamediv> <refname>array_splice</refname> - <refpurpose>Remove a portion of the array and replace it with something else</refpurpose> + <refpurpose> + Remove a portion of the array and replace it with something + else + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -350,7 +364,8 @@ by <parameter>offset</parameter> and <parameter>length</parameter> from the <parameter>input</parameter> array, and replaces them with the - elements of the <parameter>replacement</parameter> array, if supplied. + elements of the <parameter>replacement</parameter> array, if + supplied. <para> If <parameter>offset</parameter> is positive then the start of @@ -374,7 +389,14 @@ <para> If <parameter>replacement</parameter> array is specified, then - the removed elements are replaced with elements from this array. If <parameter>offset</parameter> and <parameter>length</parameter> are such that nothing is removed, then the elements from the <parameter>replacement</parameter> array are inserted in the place specified by the <parameter>offset</parameter>. Tip: if the replacement is just one element it is not necessary to put <literal>array()</literal> around it, unless the element is an array itself. + the removed elements are replaced with elements from this array. + If <parameter>offset</parameter> and + <parameter>length</parameter> are such that nothing is removed, + then the elements from the <parameter>replacement</parameter> + array are inserted in the place specified by the + <parameter>offset</parameter>. Tip: if the replacement is just + one element it is not necessary to put <literal>array()</literal> + around it, unless the element is an array itself. <para> The following equivalences hold: @@ -397,8 +419,11 @@ array_splice($input, 2); // $input is now array("red", "green") array_splice($input, 1, -1); // $input is now array("red", "yellow") -array_splice($input, 1, count($input), "orange"); // $input is now array("red", "orange") -array_splice($input, -1, 1, array("black", "maroon")); // $input is now array("red", "green", "blue", "black", "maroon") +array_splice($input, 1, count($input), "orange"); + // $input is now array("red", "orange") +array_splice($input, -1, 1, array("black", "maroon")); + // $input is now array("red", "green", + // "blue", "black", "maroon") </programlisting> </example> @@ -475,7 +500,8 @@ </funcsynopsis> <para> - <function>array_values</function> returns all the values from the <parameter>input</parameter> array. + <function>array_values</function> returns all the values from the + <parameter>input</parameter> array. <para> <example> @@ -576,10 +602,10 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <para> - This function sorts an array such that array indices maintain their - correlation with the array elements they are associated with. This is - used mainly when sorting associative arrays where the actual element - order is significant. + This function sorts an array such that array indices maintain + their correlation with the array elements they are associated + with. This is used mainly when sorting associative arrays where + the actual element order is significant. <example> <title><function>arsort</function> example</title> <programlisting> @@ -616,10 +642,10 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <para> - This function sorts an array such that array indices maintain their - correlation with the array elements they are associated with. This is - used mainly when sorting associative arrays where the actual element - order is significant. + This function sorts an array such that array indices maintain + their correlation with the array elements they are associated + with. This is used mainly when sorting associative arrays where + the actual element order is significant. <example> <title><function>asort</function> example</title> <programlisting> @@ -647,7 +673,9 @@ <refentry id="function.compact"> <refnamediv> <refname>compact</refname> - <refpurpose>Create array containing variables and their values</refpurpose> + <refpurpose> + Create array containing variables and their values + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -687,7 +715,8 @@ </programlisting> <para> - After this, $result will be array("event" => "SIGGRAPH", "city" => "San Francisco", "state" => "CA"). + After this, $result will be array("event" => "SIGGRAPH", "city" + => "San Francisco", "state" => "CA"). </example> <para> @@ -712,18 +741,19 @@ <paramdef>mixed <parameter>var</parameter></paramdef> </funcsynopsis> <para> - Returns the number of elements in <parameter>var</parameter>, which is - typically an array (since anything else will have one element). + Returns the number of elements in <parameter>var</parameter>, + which is typically an array (since anything else will have one + element). <para> Returns 1 if the variable is not an array. <para> Returns 0 if the variable is not set. <warning> <para> - <function>count</function> may return 0 for a variable that isn't - set, but it may also return 0 for a variable that has been initialized - with an empty array. Use <function>isset</function> to test if a - variable is set. + <function>count</function> may return 0 for a variable that + isn't set, but it may also return 0 for a variable that has been + initialized with an empty array. Use <function>isset</function> + to test if a variable is set. </para> </warning> <para> @@ -757,13 +787,13 @@ <function>current</function> returns false. <warning> - <para> - If the array contains empty elements (0 or "", the empty string) - then this function will return false for these elements as well. - This makes it impossible to determine if you are really at the - end of the list in such an array using <function>current</function>. - To properly traverse an array that may contain empty elements, - use the <function>each</function> function. + <para> If the array contains empty elements (0 or "", the empty + string) then this function will return false for these elements + as well. This makes it impossible to determine if you are really + at the end of the list in such an array using + <function>current</function>. To properly traverse an array that + may contain empty elements, use the <function>each</function> + function. </warning> <para> @@ -776,8 +806,10 @@ <refentry id="function.each"> <refnamediv> - <refname>each</refname> - <refpurpose>Return the next key and value pair from an array</refpurpose> + <refname>each</refname> + <refpurpose> + Return the next key and value pair from an array + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -787,13 +819,14 @@ </funcsynopsis> <para> Returns the current key and value pair from the array - <parameter>array</parameter> and advances the array - cursor. This pair is returned in a four-element array, - with the keys <emphasis>0</emphasis>, <emphasis>1</emphasis>, - <emphasis>key</emphasis>, and <emphasis>value</emphasis>. Elements - <emphasis>0</emphasis> and <emphasis>key</emphasis> contain - the key name of the array element, and <emphasis>1</emphasis> - and <emphasis>value</emphasis> contain the data. + <parameter>array</parameter> and advances the array cursor. This + pair is returned in a four-element array, with the keys + <emphasis>0</emphasis>, <emphasis>1</emphasis>, + <emphasis>key</emphasis>, and + <emphasis>value</emphasis>. Elements <emphasis>0</emphasis> and + <emphasis>key</emphasis> contain the key name of the array + element, and <emphasis>1</emphasis> and + <emphasis>value</emphasis> contain the data. <para> If the internal pointer for the array points past the end of the @@ -803,7 +836,7 @@ <example> <title><function>each</function> examples</title> <programlisting> -$foo = array( "bob", "fred", "jussi", "jouni" ); +$foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese"); $bar = each( $foo ); </programlisting> @@ -841,7 +874,10 @@ <function>list</function> to traverse an array; for instance, $HTTP_POST_VARS: - <example><title>Traversing $HTTP_POST_VARS with <function>each</function></title> + <example> + <title> + Traversing $HTTP_POST_VARS with <function>each</function> + </title> <programlisting> echo "Values submitted via POST method:&lt;br&gt;"; while (list($key, $val) = each($HTTP_POST_VARS)) { @@ -867,7 +903,9 @@ <refentry id="function.end"> <refnamediv> <refname>end</refname> - <refpurpose>Set the internal pointer of an array to its last element</refpurpose> + <refpurpose> + Set the internal pointer of an array to its last element + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -880,23 +918,32 @@ internal pointer to the last element. <para> See also: - <function>current</function>, <function>each</function>, <function>end</function> - <function>next</function> and <function>reset</function> + <function>current</function>, + <function>each</function>, + <function>end</function>, + <function>next</function>, and + <function>reset</function>. </refsect1> </refentry> <refentry id="function.extract"> <refnamediv> <refname>extract</refname> - <refpurpose>Import variables into the symbol table from an array</refpurpose> + <refpurpose> + Import variables into the symbol table from an array + </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcdef>void <function>extract</function></funcdef> - <paramdef>array <parameter>var_array</parameter></paramdef> - <paramdef>int <parameter><optional>extract_type</optional></parameter></paramdef> - <paramdef>string <parameter><optional>prefix</optional></parameter></paramdef> + <paramdef>array <parameter>var_array</parameter></paramdef> + <paramdef>int + <parameter><optional>extract_type</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>prefix</optional></parameter> + </paramdef> </funcsynopsis> <para> This function is used to import variables from an array into the @@ -906,51 +953,57 @@ will create a variable in the current symbol table, subject to <parameter>extract_type</parameter> and <parameter>prefix</parameter> parameters. - <para> - <function>extract</function> checks for colissions with existing variables. - The way collisions are treated is determined by + <para> + <function>extract</function> checks for colissions with existing + variables. The way collisions are treated is determined by <parameter>extract_type</parameter>. It can be one of the following values: - <variablelist> - <varlistentry> - <term>EXTR_OVERWRITE</term> - <listitem> - <simpara>If there is a collision, overwrite the existing variable.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>EXTR_SKIP</term> - <listitem> - <simpara>If there is a collision, don't overwrite the existing variable.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>EXTR_PREFIX_SAME</term> - <listitem> - <simpara>If there is a collision, prefix the new variable with - <parameter>prefix</parameter>. - </simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>EXTR_PREFIX_ALL</term> - <listitem> - <simpara>Prefix all variables with <parameter>prefix</parameter>.</simpara> - </listitem> - </varlistentry> - </variablelist> - <para> - If <parameter>extract_type</parameter> is not specified, - it is assumed to be EXTR_OVERWRITE. - <para> + <variablelist> + <varlistentry> + <term>EXTR_OVERWRITE</term> + <listitem> + <simpara> + If there is a collision, overwrite the existing variable. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_SKIP</term> + <listitem> + <simpara> + If there is a collision, don't overwrite the existing variable. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_SAME</term> + <listitem> + <simpara>If there is a collision, prefix the new variable with + <parameter>prefix</parameter>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_ALL</term> + <listitem> + <simpara> + Prefix all variables with <parameter>prefix</parameter>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <para> + If <parameter>extract_type</parameter> is not specified, it is + assumed to be EXTR_OVERWRITE. + <para> Note that <parameter>prefix</parameter> is only required if <parameter>extract_type</parameter> is EXTR_PREFIX_SAME or EXTR_PREFIX_ALL. - <para> + <para> <function>extract</function> checks each key to see if it constitues a valid variable name, and if it does only then does it proceed to import it. - <para> + <para> A possible use for extract is to import into symbol table variables contained in an associative array returned by <function>wddx_deserialize</function>. @@ -980,7 +1033,7 @@ blue, large, sphere, medium </programlisting> - <para> + <para> The $size wasn't overwritten, becaus we specified EXTR_PREFIX_SAME, which resulted in $wddx_size being created. If EXTR_SKIP was specified, then $wddx_size wouldn't even have @@ -1135,7 +1188,9 @@ <refentry id="function.next"> <refnamediv> <refname>next</refname> - <refpurpose>Advance the internal array pointer of an array</refpurpose> + <refpurpose> + Advance the internal array pointer of an array + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1147,19 +1202,20 @@ Returns the array element in the next place that's pointed by the internal array pointer, or false if there are no more elements. <para> - <function>next</function> behaves like <function>current</function>, - with one difference. It advances the internal array pointer one - place forward before returning the element. That means it returns - the next array element and advances the internal array pointer by - one. If advancing the internal array pointer results in going beyond - the end of the element list, <function>next</function> returns false. - <warning> - <para> - If the array contains empty elements then this function will return - false for these elements as well. To properly traverse an array - which may contain empty elements see the <function>each</function> - function. - </para> + <function>next</function> behaves like + <function>current</function>, with one difference. It advances + the internal array pointer one place forward before returning the + element. That means it returns the next array element and + advances the internal array pointer by one. If advancing the + internal array pointer results in going beyond the end of the + element list, <function>next</function> returns false. + <warning> + <para> + If the array contains empty elements then this function will + return false for these elements as well. To properly traverse + an array which may contain empty elements see the + <function>each</function> function. + </para> </warning> <para> @@ -1181,7 +1237,7 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <simpara> - This is an alias for <function>current</function>. + This is an alias for <function>current</function>. <para> See also: <function>end</function>, <function>next</function>, @@ -1202,14 +1258,15 @@ </funcsynopsis> <para> Returns the array element in the previous place that's pointed by - the internal array pointer, or false if there are no more elements. + the internal array pointer, or false if there are no more + elements. <warning> <para> - If the array contains empty elements then this function will return - false for these elements as well. To properly traverse an array - which may contain empty elements see the <function>each</function> - function. + If the array contains empty elements then this function will + return false for these elements as well. To properly traverse + an array which may contain empty elements see the + <function>each</function> function. </para> </warning> @@ -1228,7 +1285,9 @@ <refentry id="function.range"> <refnamediv> <refname>range</refname> - <refpurpose>Create an array containing a range of integers</refpurpose> + <refpurpose> + Create an array containing a range of integers + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1266,9 +1325,12 @@ <function>reset</function> returns the value of the first array element. <para> - See also: - <function>current</function>, <function>each</function>, <function>next</function> - <function>prev</function> and <function>reset</function> + See also: + <function>current</function>, + <function>each</function>, + <function>next</function>, + <function>prev</function>, and + <function>reset</function>. </refsect1> </refentry> @@ -1308,8 +1370,12 @@ The fruits have been sorted in reverse alphabetical order. <para> - See also <function>arsort</function>, <function>asort</function>, - <function>ksort</function>, <function>sort</function> and <function>usort</function>. + See also: + <function>arsort</function>, + <function>asort</function>, + <function>ksort</function>, + <function>sort</function>, and + <function>usort</function>. </refsect1> </refentry> @@ -1325,7 +1391,7 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <para> - This function shuffles (randomizes the order of the elements in) + This function shuffles (randomizes the order of the elements in) an array. <example> <title><function>shuffle</function> example</title> @@ -1375,8 +1441,8 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <para> - This function sorts an array. Elements will be arranged from lowest to - highest when this function has completed. + This function sorts an array. Elements will be arranged from + lowest to highest when this function has completed. <example> <title><function>sort</function> example</title> <programlisting> @@ -1395,15 +1461,22 @@ </computeroutput> The fruits have been sorted in alphabetical order. <para> - See also <function>arsort</function>, <function>asort</function>, - <function>ksort</function>, <function>rsort</function>, and <function>usort</function>. + See also: + <function>arsort</function>, + <function>asort</function>, + <function>ksort</function>, + <function>rsort</function>, and + <function>usort</function>. </refsect1> </refentry> <refentry id="function.uasort"> <refnamediv> <refname>uasort</refname> - <refpurpose>Sort an array with a user-defined comparison function and maintain index association</refpurpose> + <refpurpose> + Sort an array with a user-defined comparison function and + maintain index association + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1413,17 +1486,20 @@ <paramdef>function <parameter>cmp_function</parameter></paramdef> </funcsynopsis> <para> - This function sorts an array such that array indices maintain their - correlation with the array elements they are associated with. This is - used mainly when sorting associative arrays where the actual element - order is significant. The comparison function is user-defined. + This function sorts an array such that array indices maintain + their correlation with the array elements they are associated + with. This is used mainly when sorting associative arrays where + the actual element order is significant. The comparison function + is user-defined. </refsect1> </refentry> <refentry id="function.uksort"> <refnamediv> <refname>uksort</refname> - <refpurpose>Sort an array by keys using a user-defined comparison function</refpurpose> + <refpurpose> + Sort an array by keys using a user-defined comparison function + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1462,9 +1538,13 @@ </computeroutput> <para> - See also <function>arsort</function>, <function>asort</function>, - <function>uasort</function>, <function>ksort</function>, - <function>rsort</function> and <function>sort</function>. + See also: + <function>arsort</function>, + <function>asort</function>, + <function>uasort</function>, + <function>ksort</function>, + <function>rsort</function>, and + <function>sort</function>. </refsect1> </refentry> @@ -1472,7 +1552,9 @@ <refentry id="function.usort"> <refnamediv> <refname>usort</refname> - <refpurpose>Sort an array by values using a user-defined comparison function</refpurpose> + <refpurpose> + Sort an array by values using a user-defined comparison function + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1487,10 +1569,11 @@ needs to be sorted by some non-trivial criteria, you should use this function. <para> - The comparison function must return an integer less than, equal to, or - greater than zero if the first argument is considered to be respectively - less than, equal to, or greater than the second. If two members compare - as equal, their order in the sorted array is undefined. + The comparison function must return an integer less than, equal + to, or greater than zero if the first argument is considered to + be respectively less than, equal to, or greater than the + second. If two members compare as equal, their order in the + sorted array is undefined. <example> <title><function>usort</function> example</title> <programlisting> @@ -1515,8 +1598,8 @@ <note> <para> - Obviously in this trivial case the <function>rsort</function> function - would be more appropriate. + Obviously in this trivial case the <function>rsort</function> + function would be more appropriate. </para> </note>