CVS update: phpdoc/functions

Date: Sunday June 27, 1999 @ 22:07 Author: jim Update of /repository/phpdoc/functions In directory php:/tmp/cvs-serv29767/functions Modified Files: array.sgml Log Message: Minor cleanups. Index: phpdoc/functions/array.sgml diff -u phpdoc/functions/array.sgml:1.3 phpdoc/functions/array.sgml:1.4 --- phpdoc/functions/array.sgml:1.3 Wed Jun 23 17:56:02 1999 +++ phpdoc/functions/array.sgml Sun Jun 27 22:07:12 1999 @@ -20,10 +20,12 @@ Returns an array of the parameters. The parameters can be given an index with the <literal>=&gt;</literal> operator. - <para> - Note that <function>array</function> really is a language - construct used to represent literal arrays, and not a regular - function. + <note> + <para> + <function>array</function> is a language construct used to represent + literal arrays, and not a regular function. + </para> + </note> <para> The following example demonstrates how to create a @@ -74,10 +76,13 @@ prepending the '@' sign to the <function>array_walk</function> call, or by using <function>error_reporting</function>. - <para> - Note that <parameter>func</parameter> will actually be working - with the elements of <parameter>arr</parameter>, so any changes - made to those elements will actually be made in the array itself. + <note> + <para> + <parameter>func</parameter> will actually be working with the + elements of <parameter>arr</parameter>, so any changes made to + those elements will be made in the array itself. + </para> + </note> <para> <example> @@ -105,8 +110,6 @@ </refsect1> </refentry> - - <refentry id="function.arsort"> <refnamediv> <refname>arsort</refname> @@ -204,10 +207,18 @@ Returns the number of elements in <parameter>var</parameter>, which is typically an array (since anything else will have one element). <para> - Returns 0 if the variable is not set. - <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. + </para> + </warning> + <para> See also: <function>sizeof</function>, <function>isset</function>, and <function>is_array</function>. @@ -217,7 +228,7 @@ <refentry id="function.current"> <refnamediv> <refname>current</refname> - <refpurpose>return the current element in an array</refpurpose> + <refpurpose>Return the current element in an array</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -226,12 +237,9 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <para> - Each array variable has an internal pointer that points to one of - its elements. In addition, all of the elements in the array are - linked by a bidirectional linked list for traversing purposes. - The internal pointer points to the first element that was inserted - to the array until you run one of the functions that modify that - pointer on that array. + Every array has an internal pointer to its "current" element, + which is initialized to the first element inserted into the + array. <para> The <function>current</function> function simply returns the @@ -240,14 +248,15 @@ internal pointer points beyond the end of the elements list, <function>current</function> returns false. - <para> - <emphasis>Warning:</emphasis> if the array contains empty - elements (0 or "", the empty string) then this function - will return false for these elements as well. It is - undecideable if the current element is just a zero-value or - you have traversed beyond the end of the array. To properly - traverse an array, use the <function>each</function> - function. + <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. + </warning> <para> See also: @@ -260,7 +269,7 @@ <refentry id="function.each"> <refnamediv> <refname>each</refname> - <refpurpose>return next key/value pair from an array</refpurpose> + <refpurpose>Return the next key and value pair from an array</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -269,19 +278,22 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <para> - Returns the current key/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> each contain the key name of the array - element, and <emphasis>1</emphasis> and - <emphasis>value</emphasis> contain the data. + 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. + + <para> + If the internal pointer for the array points past the end of the + array contents, <function>each</function> returns false. <para> <example> - <title>each() examples</title> + <title><function>each</function> examples</title> <programlisting> $foo = array( "bob", "fred", "jussi", "jouni" ); $bar = each( $foo ); @@ -316,25 +328,24 @@ </example> - <para> <function>each</function> is typically used in conjunction with <function>list</function> to traverse an array; for instance, $HTTP_POST_VARS: - <example><title>Traversing $HTTP_POST_VARS with each()</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 ) ) { +while (list($key, $val) = each($HTTP_POST_VARS)) { echo "$key => $val&lt;br&gt;"; } </programlisting> </example> - <para> - After <function>each</function> has executed, the array cursor - will be left on the next element of the array, or on the last - element if it hits the end of the array. + <para> + After <function>each</function> has executed, the array cursor + will be left on the next element of the array, or on the last + element if it hits the end of the array. <para> See also <function>key</function>, <function>list</function>, @@ -348,7 +359,7 @@ <refentry id="function.end"> <refnamediv> <refname>end</refname> - <refpurpose>set internal pointer of array to last element</refpurpose> + <refpurpose>Set the internal pointer of an array to its last element</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -369,7 +380,7 @@ <refentry id="function.key"> <refnamediv> <refname>key</refname> - <refpurpose>fetch a key from an associative array</refpurpose> + <refpurpose>Fetch a key from an associative array</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -391,7 +402,7 @@ <refentry id="function.ksort"> <refnamediv> <refname>ksort</refname> - <refpurpose>Sort an array by key.</refpurpose> + <refpurpose>Sort an array by key</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -433,7 +444,7 @@ <refnamediv> <refname>list</refname> <refpurpose> - assign variables as if they were an array + Assign variables as if they were an array </refpurpose> </refnamediv> <refsect1> @@ -469,16 +480,14 @@ </programlisting></example> <para> - See also: - <function>each</function>, - <function>array</function>. + See also: <function>each</function>, <function>array</function>. </refsect1> </refentry> <refentry id="function.next"> <refnamediv> <refname>next</refname> - <refpurpose>advance the internal array pointer</refpurpose> + <refpurpose>Advance the internal array pointer of an array</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -489,18 +498,21 @@ <para> Returns the array element in the next place that's pointed by the internal array pointer, or false if there are no more elements. - <emphasis>Warning:</emphasis> 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. + <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> See also: @@ -512,7 +524,7 @@ <refentry id="function.pos"> <refnamediv> <refname>pos</refname> - <refpurpose>return the current element in an array</refpurpose> + <refpurpose>Get the current element from an array</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -532,7 +544,7 @@ <refentry id="function.prev"> <refnamediv> <refname>prev</refname> - <refpurpose>rewind internal array pointer</refpurpose> + <refpurpose>Rewind the internal array pointer</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -542,15 +554,22 @@ </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. <emphasis>Warning:</emphasis> 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. + 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. + </para> + </warning> + <para> <function>prev</function> behaves just like <function>next</function>, except it rewinds the internal array pointer one place instead of advancing it. + <para> See also: <function>current</function>, <function>end</function> @@ -582,7 +601,9 @@ <refentry id="function.reset"> <refnamediv> <refname>reset</refname> - <refpurpose>set internal pointer of array to first element</refpurpose> + <refpurpose> + Set the internal pointer of an array to its first element + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -615,24 +636,29 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcsynopsis> <para> - This function sorts an array in reverse order (highest to lowest). - <example> + This function sorts an array in reverse order (highest to lowest). + <example> <title><function>rsort</function> example</title> <programlisting> - $fruits = array("lemon","orange","banana","apple"); - rsort($fruits); - for(reset($fruits); list($key,$value) = each($fruits); ) { - echo "fruits[$key] = ".$value."\n"; - } - </programlisting></example> - This example would display: - <computeroutput> - fruits[0] = orange - fruits[1] = lemon - fruits[2] = banana - fruits[3] = apple - </computeroutput> - The fruits have been sorted in reverse alphabetical order. +$fruits = array("lemon","orange","banana","apple"); +rsort($fruits); +for (reset($fruits); list($key,$value) = each($fruits); ) { + echo "fruits[$key] = ", $value, "\n"; +} + </programlisting> + </example> + + This example would display: + + <computeroutput> +fruits[0] = orange +fruits[1] = lemon +fruits[2] = banana +fruits[3] = apple + </computeroutput> + + 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>. @@ -660,7 +686,7 @@ srand(time()); shuffle($numbers); while (list(,$number) = each($numbers)) { - echo "$number "; + echo "$number "; } </programlisting></example> <para> @@ -673,7 +699,7 @@ <refentry id="function.sizeof"> <refnamediv> <refname>sizeof</refname> - <refpurpose>get size of array</refpurpose> + <refpurpose>Get the number of elements in an array</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -763,6 +789,7 @@ user-supplied comparison function. If the array you wish to sort needs to be sorted by some non-trivial criteria, you should use this function. + <example> <title><function>uksort</function> example</title> <programlisting> @@ -776,16 +803,21 @@ echo "$key: $value\n"; } </programlisting></example> + This example would display: + <computeroutput> 20: twenty 10: ten 4: four 3: three -</computeroutput> + </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> @@ -832,11 +864,28 @@ 3: 2 4: 1 </computeroutput> - Obviously in this trivial case the <function>rsort</function> function - would be more appropriate. + + <note> + <para> + Obviously in this trivial case the <function>rsort</function> function + would be more appropriate. + </para> + </note> + + <warning> + <para> + The underlying quicksort function in some C libraries (such as on + Solaris systems) may cause PHP to crash if the comparison function + does not return consistent values. + </para> + </warning> + <para> - See also <function>arsort</function>, <function>asort</function>, - <function>ksort</function>, <function>rsort</function> and <function>sort</function>. + See also: + <function>arsort</function>, <function>asort</function>, + <function>ksort</function>, <function>rsort</function> and + <function>sort</function>. + </refsect1> </refentry>