Updated iterator_apply docs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@289185 c90b9560-bf6c-de11-be94-00142212c4b1

reference/spl/functions/iterator-apply.xml

@@ -4,7 +4,7 @@
 <refentry xml:id="function.iterator-apply" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>iterator_apply</refname>
-  <refpurpose>Apply a user function to every element of an iterator</refpurpose>
+  <refpurpose>Call a function for every element in an iterator</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -28,7 +28,7 @@
      <term><parameter>iterator</parameter></term>
      <listitem>
       <para>
-       The class to walk through.
+       The class to iterate over.
       </para>
      </listitem>
     </varlistentry>
@@ -37,6 +37,12 @@
      <listitem>
       <para>
        The callback function to call on every element.
+       <note>
+        <simpara>
+         The function must return &true; in order to
+         continue iterating over the <parameter>iterator</parameter>.
+        </simpara>
+       </note>
       </para>
      </listitem>
     </varlistentry>
@@ -60,6 +66,36 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>iterator_apply</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function print_caps(Iterator $iterator) {
+    echo strtoupper($iterator->current()) . "\n";
+    return TRUE;
+}
+
+$it = new ArrayIterator(array("Apples", "Bananas", "Cherries"));
+iterator_apply($it, "print_caps", array($it));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+APPLES
+BANANAS
+CHERRIES
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
 <!--
  <refsect1 role="errors">
   &reftitle.errors;