archived-doc-zh/reference/array/functions/array-walk.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5faa7a6747bca628b3bdcc9f93aec5603b65581f Maintainer: HonestQiao Status: ready -->
<!-- Reviewed: no Maintainer: HonestQiao -->
<refentry xml:id="function.array-walk" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_walk</refname>
  <refpurpose>对数组中的每个成员应用用户函数</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>array_walk</methodname>
   <methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
   <methodparam><type>callback</type><parameter>funcname</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>userdata</parameter></methodparam>
  </methodsynopsis>
  <simpara>
   &return.success;
  </simpara>
  <simpara>
   将用户自定义函数 <parameter>funcname</parameter> 应用到
   <parameter>array</parameter> 数组中的每个单元。典型情况下
   <parameter>funcname</parameter> 接受两个参数。<parameter>array</parameter>
   参数的值作为第一个，键名作为第二个。如果提供了可选参数
   <parameter>userdata</parameter>，将被作为第三个参数传递给
   callback <parameter>funcname</parameter>。
  </simpara>
  <simpara>
   如果 <parameter>funcname</parameter> 函数需要的参数比给出的多，则每次
   <function>array_walk</function> 调用 <parameter>funcname</parameter>
   时都会产生一个 <link linkend="errorfunc.constants">E_WARNING</link>
   级的错误。这些警告可以通过在 <function>array_walk</function> 调用前加上
   PHP 的错误操作符 <link linkend="language.operators.errorcontrol">@</link>
   来抑制，或者用 <function>error_reporting</function>。
  </simpara>
  <note>
   <para>
    如果 <parameter>funcname</parameter> 需要直接作用于数组中的值，则给
    <parameter>funcname</parameter> 的第一个参数指定为<link
    linkend="language.references">引用</link>。这样任何对这些单元的改变也将会改变原始数组本身。
   </para>
  </note>
  <note>
   <para>
    将键名和 userdata 传递到 <parameter>funcname</parameter> 中是 PHP 4.0 新增加的。
   </para>
  </note>
  <para>
   <function>array_walk</function> 不会受到 <parameter>array</parameter>
   内部数组指针的影响。<function>array_walk</function>
   会遍历整个数组而不管指针的位置。
  </para>
  <para>
   用户不应在回调函数中改变该数组本身。例如增加/删除单元，unset
   单元等等。如果 <function>array_walk</function>
   作用的数组改变了，则此函数的的行为未经定义，且不可预期。
  </para>
  <para>
   <example>
    <title><function>array_walk</function> 例子</title>
    <programlisting role="php">
<![CDATA[
<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");

function test_alter(&$item1, $key, $prefix)
{
    $item1 = "$prefix: $item1";
}

function test_print($item2, $key)
{
    echo "$key. $item2<br />\n";
}

echo "Before ...:\n";
array_walk($fruits, 'test_print');

array_walk($fruits, 'test_alter', 'fruit');
echo "... and after:\n";

array_walk($fruits, 'test_print');
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Before ...:
d. lemon
a. orange
b. banana
c. apple
... and after:
d. fruit: lemon
a. fruit: orange
b. fruit: banana
c. fruit: apple
]]>
    </screen>
   </example>
  </para>
  <simpara>
   参见 <function>array_walk_recursive</function>，<function>create_function</function>，<function>list</function>，<link
   linkend="control-structures.foreach">foreach</link>，<function>each</function>，<function>call_user_func_array</function>，<function>array_map</function>
   和&seealso.callback;。
  </simpara>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       The input array.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>funcname</parameter></term>
     <listitem>
      <para>
       Typically, <parameter>funcname</parameter> takes on two parameters.
       The <parameter>array</parameter> parameter's value being the first, and
       the key/index second.
      </para>
      <note>
       <para>
        If <parameter>funcname</parameter> needs to be working with the
        actual values of the array, specify the first parameter of
        <parameter>funcname</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>
          Many internal functions (for example <function>strtolower</function>)
          will throw a warning if more than the expected number of argument
          are passed in and are not usable directly as
          <parameter>funcname</parameter>.
        </para>
      </note>
      <para>
       Only the values of the <parameter>array</parameter> may potentially be
       changed; its structure cannot be altered, i.e., the programmer cannot
       add, unset or reorder elements. If the callback does not respect this
       requirement, the behavior of this function is undefined, and      
       unpredictable.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>userdata</parameter></term>
     <listitem>
      <para>
       If the optional <parameter>userdata</parameter> parameter is supplied,
       it will be passed as the third parameter to the callback
       <parameter>funcname</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   If function <parameter>funcname</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>funcname</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>.
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <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)
{
    $item1 = "$prefix: $item1";
}

function test_print($item2, $key)
{
    echo "$key. $item2<br />\n";
}

echo "Before ...:\n";
array_walk($fruits, 'test_print');

array_walk($fruits, 'test_alter', 'fruit');
echo "... and after:\n";

array_walk($fruits, 'test_print');
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Before ...:
d. lemon
a. orange
b. banana
c. apple
... and after:
d. fruit: lemon
a. fruit: orange
b. fruit: banana
c. fruit: apple
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>array_walk_recursive</function></member>
    <member><function>iterator_apply</function></member>
    <member><function>create_function</function></member>
    <member><function>list</function></member>
    <member><function>each</function></member>
    <member><function>call_user_func_array</function></member>
    <member><function>array_map</function></member>
    <member>&seealso.callback;</member>
    <member>&foreach;</member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->