From 1738cb5f71c66fabf3afc79079afa305edfcbd75 Mon Sep 17 00:00:00 2001
From: Peter Cowburn <salathe@php.net>
Date: Mon, 11 Jul 2011 15:52:02 +0000
Subject: [PATCH] AppendIterator constructor docs (patch by Gordon Oheim)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@313138 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/spl/appenditerator.xml           |   4 +-
 reference/spl/appenditerator/construct.xml | 106 +++++++++++++++++++--
 2 files changed, 99 insertions(+), 11 deletions(-)

diff --git a/reference/spl/appenditerator.xml b/reference/spl/appenditerator.xml
index 5247a0c194..600e14e1e9 100644
--- a/reference/spl/appenditerator.xml
+++ b/reference/spl/appenditerator.xml
@@ -12,7 +12,7 @@
   <section xml:id="appenditerator.intro">
    &reftitle.intro;
    <para>
-    An Iterator that iterates over several iterators one after the other.
+    Consecutively iterates over all iterators appended to this iterator.
    </para>
   </section>
 <!-- }}} -->
@@ -50,11 +50,11 @@
 <!-- }}} -->
     
     <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.appenditerator')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[1])" />
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.appenditerator')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
     
     <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.iteratoriterator')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
-
    </classsynopsis>
 <!-- }}} -->
 
diff --git a/reference/spl/appenditerator/construct.xml b/reference/spl/appenditerator/construct.xml
index 0e9b015b0e..04098856b3 100644
--- a/reference/spl/appenditerator/construct.xml
+++ b/reference/spl/appenditerator/construct.xml
@@ -6,33 +6,32 @@
   <refname>AppendIterator::__construct</refname>
   <refpurpose>Constructs an AppendIterator</refpurpose>
  </refnamediv>
-
+ 
  <refsect1 role="description">
   &reftitle.description;
-  <methodsynopsis>
+  <constructorsynopsis role="oop">
+   <modifier>public</modifier> 
+   <type>void</type>
    <methodname>AppendIterator::__construct</methodname>
    <void />
-  </methodsynopsis>
+  </constructorsynopsis>
   <para>
    Constructs an AppendIterator.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
-
+ 
  <refsect1 role="parameters">
   &reftitle.parameters;
   &no.function.parameters;
  </refsect1>
-
+ 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
    &return.void;
   </para>
  </refsect1>
-
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
@@ -41,7 +40,96 @@
    </simplelist>
   </para>
  </refsect1>
+ 
+ 
+ <refsect1 role="examples"><!-- {{{ -->
+  &reftitle.examples;
+  <para>
+   <example xml:id="appenditerator.examples.foreach"><!-- {{{ -->
+    <title>Iterating AppendIterator with foreach</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$pizzas   = new ArrayIterator(array('Margarita', 'Siciliana', 'Hawaii'));
+$toppings = new ArrayIterator(array('Cheese', 'Anchovies', 'Olives', 'Pineapple', 'Ham'));
 
+$appendIterator = new AppendIterator;
+$appendIterator->append($pizzas);
+$appendIterator->append($toppings);
+
+foreach ($appendIterator as $key => $item) {
+    echo "$key => $item", PHP_EOL;
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+0 => Margarita
+1 => Siciliana
+2 => Hawaii
+0 => Cheese
+1 => Anchovies
+2 => Olives
+3 => Pineapple
+4 => Ham
+]]>
+    </screen>
+   </example><!-- }}} -->
+   <example xml:id="appenditerator.examples.api"><!-- {{{ -->
+    <title>Iterating AppendIterator with the AppendIterator API</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$pizzas   = new ArrayIterator(array('Margarita', 'Siciliana', 'Hawaii'));
+$toppings = new ArrayIterator(array('Cheese', 'Anchovies', 'Olives', 'Pineapple', 'Ham'));
+
+$appendIterator = new AppendIterator;
+$appendIterator->append($pizzas);
+$appendIterator->append($toppings);
+
+while ($appendIterator->valid()) {
+    printf(
+        '%s => %s => %s%s',
+        $appendIterator->getIteratorIndex(),
+        $appendIterator->key(),
+        $appendIterator->current(),
+        PHP_EOL
+    );
+    $appendIterator->next();
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+0 => 0 => Margarita
+0 => 1 => Siciliana
+0 => 2 => Hawaii
+1 => 0 => Cheese
+1 => 1 => Anchovies
+1 => 2 => Olives
+1 => 3 => Pineapple
+1 => 4 => Ham
+]]>
+    </screen>
+   </example><!-- }}} --> 
+  </para>
+ </refsect1><!-- }}} --> 
+ 
+ <refsect1 role="notes"><!-- {{{ -->
+  &reftitle.notes;
+  <caution>
+   <para>
+    When using <function>iterator_to_array</function> to copy the values of the AppendIterator 
+    into an array, you have to set the optional <parameter>use_key</parameter> argument to 
+    &false;. When <parameter>use_key</parameter> is not &false; any keys reoccuring in inner 
+    iterators will get overwritten in the returned array. There is no way to preserve the original keys.
+   </para>
+  </caution>
+ </refsect1><!-- }}} --> 
 </refentry>
 
 <!-- Keep this comment at the end of the file