From 964d208b1fce2e332fc0777f8dbe1b026e133179 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Mon, 24 Aug 2015 18:15:02 +0000
Subject: [PATCH] iterator_count() may wind iterator beyond its end (fixes
 #70346)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@337605 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/spl/functions/iterator-count.xml | 41 ++++++++++++++++++++++
 1 file changed, 41 insertions(+)

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>