diff --git a/reference/spl/functions/iterator-count.xml b/reference/spl/functions/iterator-count.xml
index d839324d21..d2b117416a 100644
--- a/reference/spl/functions/iterator-count.xml
+++ b/reference/spl/functions/iterator-count.xml
@@ -14,6 +14,8 @@
   </methodsynopsis>
   <para>
    Count the elements in an iterator.
+   <function>iterator_count</function> is not guaranteed to retain the current
+   position of the <parameter>iterator</parameter>.
   </para>
  </refsect1>
 
@@ -57,6 +59,45 @@ var_dump(iterator_count($iterator));
     <screen>
 <![CDATA[
 int(4)
+]]>
+    </screen>
+   </example>
+   <example>
+    <title><function>iterator_count</function> modifies position</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new ArrayIterator(['one', 'two', 'three']);
+var_dump($iterator->current());
+var_dump(iterator_count($iterator));
+var_dump($iterator->current());
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+string(3) "one"
+int(3)
+NULL
+]]>
+    </screen>
+   </example>
+   <example>
+    <title><function>iterator_count</function> in &foreach; loops</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new ArrayIterator(['one', 'two', 'three']);
+foreach ($iterator as $key => $value) {
+    echo "$key: $value (", iterator_count($iterator), ")\n";
+}?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+0: one (3)
 ]]>
     </screen>
    </example>