philip Thu Oct 17 07:25:32 2002 EDT
Modified files:
/phpdoc/en/reference/array/functions array-walk.xml
Log:
Fixed typo; rewrote most of docs; see also foreach() and call_user_func_array().
Index: phpdoc/en/reference/array/functions/array-walk.xml
diff -u phpdoc/en/reference/array/functions/array-walk.xml:1.4
phpdoc/en/reference/array/functions/array-walk.xml:1.5
--- phpdoc/en/reference/array/functions/array-walk.xml:1.4 Sun May 12 04:19:28
2002
+++ phpdoc/en/reference/array/functions/array-walk.xml Thu Oct 17 07:25:32 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<refentry id="function.array-walk">
<refnamediv>
@@ -17,62 +17,68 @@
<methodparam
choice="opt"><type>mixed</type><parameter>userdata</parameter></methodparam>
</methodsynopsis>
<simpara>
- Applies the user-defined function named by <parameter>func</parameter>
- to each element of <parameter>array</parameter>.
- <parameter>func</parameter> will be passed array value as the
- first parameter and array key as the second parameter. If
- <parameter>userdata</parameter> is supplied, it will be passed as
- the third parameter to the user function. <parameter>func</parameter>
- must be a user-defined function, and can't be a native PHP function.
- Thus, you can't use <function>array_walk</function> straight with
- <function>str2lower</function>, you must build a user-defined function
- with it first, and pass this function as argument.
+ Applies the user-defined function <parameter>func</parameter> to each
+ element of the <parameter>array</parameter> array. Typically,
+ <parameter>func</parameter> takes on two parameters.
+ The <parameter>array</parameter> parameter's value being the first, and
+ the key/index second. If the optional <parameter>userdata</parameter>
+ parameter is supplied, it will be passed as the third parameter to
+ function <parameter>func</parameter>.
+ </simpara>
+ <simpara>
+ <parameter>func</parameter> must be a user-defined function, not a
+ built-in PHP function such as <function>strtolower</function> or
+ <function>stripslashes</function>. The user-defined function can
+ use built-in PHP functions.
</simpara>
¬e.func-callback;
<simpara>
- If <parameter>func</parameter> requires more than two or three
- arguments, depending on <parameter>userdata</parameter>, a
- warning will be generated each time
- <function>array_walk</function> calls
- <parameter>func</parameter>. These warnings may be suppressed by
- prepending the '@' sign to the <function>array_walk</function>
- call, or by using <function>error_reporting</function>.
+ If function <parameter>func</parameter> requires more parameters than
+ given to it, an error of level <link linkend="errorfunc.constants">
+ E_WARNING</link> will be generated each time <function>array_walk</function>
+ calls <parameter>func</parameter>. These warnings may be suppressed by
+ prepending the PHP error operator
+ <link linkend="language.operators.errorcontrol">@</link> to the
+ <function>array_walk</function> call, or by using
+ <function>error_reporting</function>.
</simpara>
<note>
<para>
If <parameter>func</parameter> needs to be working with the
- actual values of the array, specify that the first parameter of
- <parameter>func</parameter> should be passed by reference. Then
- any changes made to those elements will be made in the array
- itself.
- </para>
- <para>
- Modifying the array from inside <parameter>func</parameter>
- may cause unpredictable behavior.
+ actual values of the array, specify the first parameter of
+ <parameter>func</parameter> as a
+ <link linkend="language.references">reference</link>. Then,
+ any changes made to those elements will be made in the
+ original array itself.
</para>
</note>
<note>
<para>
Passing the key and userdata to <parameter>func</parameter> was
- added in 4.0.
- </para>
- <para>
- In PHP 4 <function>reset</function> needs to be called as
- necessary since <function>array_walk</function> does not reset
- the array by default.
- </para>
- <para>
- Users may not change the array itself from the callback
- function. e.g. Add/delete element, unset the array that
- <function>array_walk</function> is applied to. If the array is
- changed, the behavior of this function is undefined.
+ added in 4.0.0
</para>
</note>
<para>
+ <function>array_walk</function> is not affected by the internal
+ array pointer of <parameter>array</parameter>. <function>
+ array_walk</function> will walk through the entire array
+ regardless of pointer position. To reset the pointer, use
+ <function>reset</function>. In PHP 3,
+ <function>array_walk</function> resets the pointer.
+ </para>
+ <para>
+ Users may not change the array itself from the callback
+ function. e.g. Add/delete elements, unset elements, etc. If
+ the array that <function>array_walk</function> is applied to
+ is changed, the behavior of this function is undefined, and
+ unpredictable.
+ </para>
+ <para>
<example>
<title><function>array_walk</function> example</title>
<programlisting role="php">
<![CDATA[
+<?php
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
function test_alter (&$item1, $key, $prefix) {
@@ -82,13 +88,15 @@
function test_print ($item2, $key) {
echo "$key. $item2<br>\n";
}
+
echo "Before ...:\n";
array_walk ($fruits, 'test_print');
-reset ($fruits);
+
array_walk ($fruits, 'test_alter', 'fruit');
echo "... and after:\n";
-reset ($fruits);
+
array_walk ($fruits, 'test_print');
+?>
]]>
</programlisting>
<para>
@@ -111,7 +119,8 @@
</example>
</para>
<simpara>
- See also <function>each</function> and <function>list</function>.
+ See also <function>list</function>, <link
+linkend="control-structures.foreach">foreach</link>,
+ <function>each</function>, and <function>call_user_func_array</function>.
</simpara>
</refsect1>
</refentry>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
