[doc-en] master: Document the MultipleIterator methods (#6075)
| From: | Asish Kumar via GitHub | Date: | Fri, 13 Nov 2026 10:32:54 +0000 |
| Subject: | [doc-en] master: Document the MultipleIterator methods (#6075) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23950@lists.php.net to get a copy of this message | ||
Author: Asish Kumar (officialasishkumar)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-11-13T11:32:51+01:00
Commit: https://github.com/php/doc-en/commit/5f12cb58d98c9843cdcbee9f22b05f77038432db
Raw diff: https://github.com/php/doc-en/commit/5f12cb58d98c9843cdcbee9f22b05f77038432db.diff
Document the MultipleIterator methods (#6075)
* Document the MultipleIterator methods
Eleven MultipleIterator pages only had a one-line purpose and
&warn.undocumented.func;, and several statements on them were wrong.
This writes them out based on ext/spl/spl_observer.c:
- class intro: the iterators are iterated over in parallel, not
"sequentially" as the intro said.
- attachIterator(): what info is used for, that attaching an iterator
again replaces its information, and the InvalidArgumentException for
duplicate information (the page named a non-existent
IllegalValueException and had "Description..." as return value).
- detachIterator(), containsIterator(), countIterators(): fix the return
value of containsIterator(), which claimed "true on success or false
on failure".
- getFlags(), setFlags(): MIT_NEED_ANY and MIT_KEYS_NUMERIC are 0, so
flags have to be checked with & and setFlags(MIT_KEYS_ASSOC) alone
also switches to MIT_NEED_ANY.
- rewind(), next(), valid(): how the attached iterators are called and
when the MultipleIterator is valid, including with no iterator.
- current(), key(): the shape of the returned array for each flag, null
for invalid iterators with MIT_NEED_ANY, the RuntimeException and
InvalidArgumentException cases, and correct purposes instead of
"Gets the registered iterator instances". The 8.1.0 changelog entry
now says the RuntimeException is thrown when no iterator is attached,
which is what replaced the old false return value. The note that
using key() from foreach triggers "Illegal type returned" is removed:
foreach accepts array keys from iterators.
Examples are added for getFlags(), current() and key(); each was run
on PHP 8.4 and prints the output shown.
Part of #5786
* Clarify MultipleIterator::attachIterator() info replacement
Changed paths:
M reference/spl/multipleiterator.xml
M reference/spl/multipleiterator/attachiterator.xml
M reference/spl/multipleiterator/containsiterator.xml
M reference/spl/multipleiterator/countiterators.xml
M reference/spl/multipleiterator/current.xml
M reference/spl/multipleiterator/detachiterator.xml
M reference/spl/multipleiterator/getflags.xml
M reference/spl/multipleiterator/key.xml
M reference/spl/multipleiterator/next.xml
M reference/spl/multipleiterator/rewind.xml
M reference/spl/multipleiterator/setflags.xml
M reference/spl/multipleiterator/valid.xml
Diff:
diff --git a/reference/spl/multipleiterator.xml b/reference/spl/multipleiterator.xml
index a31cb9d2366b..2a411e5db819 100644
--- a/reference/spl/multipleiterator.xml
+++ b/reference/spl/multipleiterator.xml
@@ -10,9 +10,11 @@
<!-- {{{ MultipleIterator intro -->
<section xml:id="multipleiterator.intro">
&reftitle.intro;
- <para>
- An Iterator that sequentially iterates over all attached iterators
- </para>
+ <simpara>
+ An Iterator that iterates over all attached iterators in parallel.
+ At each step, it yields an &array; containing the current element of
+ each attached iterator, and moves all of them forward together.
+ </simpara>
</section>
<!-- }}} -->
diff --git a/reference/spl/multipleiterator/attachiterator.xml
b/reference/spl/multipleiterator/attachiterator.xml
index 333a120495b0..503ad0fd8729 100644
--- a/reference/spl/multipleiterator/attachiterator.xml
+++ b/reference/spl/multipleiterator/attachiterator.xml
@@ -13,62 +13,67 @@
<methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam>
<methodparam choice="opt"><type
class="union"><type>string</type><type>int</type><type>null</type></type><parameter>info</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>
- Attaches iterator information.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Attaches an iterator, together with its associated information. Attached
+ iterators are iterated over in the order in which they were attached.
+ </simpara>
+ <simpara>
+ If <parameter>iterator</parameter> is already attached, its associated
+ information is replaced with <parameter>info</parameter>, unless
+ <parameter>info</parameter> is identical to the information it already has.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>iterator</parameter></term>
- <listitem>
- <para>
- The new iterator to attach.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>info</parameter></term>
- <listitem>
- <para>
- The associative information for the Iterator, which must be an
- <type>int</type>, a <type>string</type>, or &null;.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>iterator</parameter></term>
+ <listitem>
+ <simpara>
+ The new iterator to attach.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>info</parameter></term>
+ <listitem>
+ <simpara>
+ The associated information for the iterator, which must be an
+ <type>int</type>, a <type>string</type>, or &null;. With
+ <constant>MultipleIterator::MIT_KEYS_ASSOC</constant>, it is used as the
+ key of the iterator's values in the arrays returned by
+ <methodname>MultipleIterator::current</methodname> and
+ <methodname>MultipleIterator::key</methodname>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Description...
- </para>
+ <simpara>
+ &return.void;
+ </simpara>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
- <para>
- An <classname>IllegalValueException</classname> if the
<parameter>iterator</parameter> parameter
- is invalid, or if <parameter>info</parameter> is already associated
- information.
- </para>
+ <simpara>
+ Throws an <exceptionname>InvalidArgumentException</exceptionname> if
+ <parameter>info</parameter> is not &null; and is identical to the
+ information associated with an iterator that is already attached.
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>MultipleIterator::__construct</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+
<member><methodname>MultipleIterator::detachIterator</methodname></member>
+
<member><methodname>MultipleIterator::containsIterator</methodname></member>
+ <member><methodname>MultipleIterator::__construct</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/containsiterator.xml
b/reference/spl/multipleiterator/containsiterator.xml
index 6b022a0e2fd1..04c127420e8d 100644
--- a/reference/spl/multipleiterator/containsiterator.xml
+++ b/reference/spl/multipleiterator/containsiterator.xml
@@ -12,44 +12,40 @@
<modifier>public</modifier>
<type>bool</type><methodname>MultipleIterator::containsIterator</methodname>
<methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam>
</methodsynopsis>
- <para>
+ <simpara>
Checks if an iterator is attached or not.
- </para>
-
- &warn.undocumented.func;
-
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>iterator</parameter></term>
- <listitem>
- <para>
- The iterator to check.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>iterator</parameter></term>
+ <listitem>
+ <simpara>
+ The iterator to check.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- &return.success;
- </para>
+ <simpara>
+ Returns &true; if <parameter>iterator</parameter> is attached, &false;
+ otherwise.
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>MultipleIterator::valid</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+
<member><methodname>MultipleIterator::attachIterator</methodname></member>
+
<member><methodname>MultipleIterator::detachIterator</methodname></member>
+
<member><methodname>MultipleIterator::countIterators</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/countiterators.xml
b/reference/spl/multipleiterator/countiterators.xml
index 5f9940602060..68d04f841bad 100644
--- a/reference/spl/multipleiterator/countiterators.xml
+++ b/reference/spl/multipleiterator/countiterators.xml
@@ -12,12 +12,9 @@
<modifier>public</modifier>
<type>int</type><methodname>MultipleIterator::countIterators</methodname>
<void/>
</methodsynopsis>
- <para>
+ <simpara>
Gets the number of attached iterator instances.
- </para>
-
- &warn.undocumented.func;
-
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,18 +24,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
The number of attached iterator instances (as an <type>int</type>).
- </para>
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
-
<member><methodname>MultipleIterator::containsIterator</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+
<member><methodname>MultipleIterator::containsIterator</methodname></member>
+
<member><methodname>MultipleIterator::attachIterator</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/current.xml b/reference/spl/multipleiterator/current.xml
index b63927244260..f88a2a77da17 100644
--- a/reference/spl/multipleiterator/current.xml
+++ b/reference/spl/multipleiterator/current.xml
@@ -3,7 +3,7 @@
<refentry xml:id="multipleiterator.current" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MultipleIterator::current</refname>
- <refpurpose>Gets the registered iterator instances</refpurpose>
+ <refpurpose>Gets the current elements of the attached iterators</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,12 +12,17 @@
<modifier>public</modifier>
<type>array</type><methodname>MultipleIterator::current</methodname>
<void/>
</methodsynopsis>
- <para>
- Get the registered iterator instances current() result.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Gets the current elements of all attached iterators, by calling
+ <methodname>Iterator::current</methodname> on each valid one.
+ </simpara>
+ <simpara>
+ With <constant>MultipleIterator::MIT_KEYS_NUMERIC</constant>, the elements
+ are listed in the order in which the iterators were attached. With
+ <constant>MultipleIterator::MIT_KEYS_ASSOC</constant>, they are keyed by
+ the information associated with each iterator by
+ <methodname>MultipleIterator::attachIterator</methodname>.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,22 +32,27 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- An <type>array</type> containing the current values of each attached iterator.
- </para>
+ <simpara>
+ An <type>array</type> containing the current elements of each attached
+ iterator. With <constant>MultipleIterator::MIT_NEED_ANY</constant>, &null;
+ is used for the iterators that are not valid.
+ </simpara>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
- <para>
- A <classname>RuntimeException</classname> if the iterator is invalid (as of PHP
8.1.0),
- or mode <constant>MIT_NEED_ALL</constant> is set and at least one attached iterator
is
- not valid. Or an <classname>IllegalValueException</classname> if a key is &null;
and
- <constant>MIT_KEYS_ASSOC</constant> is set.
- </para>
+ <simpara>
+ Throws a <exceptionname>RuntimeException</exceptionname> if no iterator is
+ attached, or if <constant>MultipleIterator::MIT_NEED_ALL</constant> is set
+ and at least one attached iterator is not valid.
+ </simpara>
+ <simpara>
+ Throws an <exceptionname>InvalidArgumentException</exceptionname> if
+ <constant>MultipleIterator::MIT_KEYS_ASSOC</constant> is set and an
+ iterator was attached without associated information.
+ </simpara>
</refsect1>
-
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
@@ -57,9 +67,9 @@
<row>
<entry>8.1.0</entry>
<entry>
- A <classname>RuntimeException</classname> is now thrown if
- <methodname>MultipleIterator::current</methodname> is called on an
- invalid iterator. Previously, &false; was returned.
+ A <exceptionname>RuntimeException</exceptionname> is now thrown if
+ <methodname>MultipleIterator::current</methodname> is called when no
+ iterator is attached. Previously, &false; was returned.
</entry>
</row>
</tbody>
@@ -67,13 +77,51 @@
</informaltable>
</refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>MultipleIterator::current</methodname>
example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new MultipleIterator(MultipleIterator::MIT_NEED_ANY |
MultipleIterator::MIT_KEYS_ASSOC);
+$iterator->attachIterator(new ArrayIterator(['a' => 'apple',
'b' => 'banana']), 'fruit');
+$iterator->attachIterator(new ArrayIterator(['x' => 'red']),
'color');
+
+$iterator->rewind();
+while ($iterator->valid()) {
+ var_dump($iterator->current());
+ $iterator->next();
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+array(2) {
+ ["fruit"]=>
+ string(5) "apple"
+ ["color"]=>
+ string(3) "red"
+}
+array(2) {
+ ["fruit"]=>
+ string(6) "banana"
+ ["color"]=>
+ NULL
+}
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>MultipleIterator::valid</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>MultipleIterator::key</methodname></member>
+ <member><methodname>MultipleIterator::valid</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/detachiterator.xml
b/reference/spl/multipleiterator/detachiterator.xml
index e3e1cb3bfaef..901c54fd1104 100644
--- a/reference/spl/multipleiterator/detachiterator.xml
+++ b/reference/spl/multipleiterator/detachiterator.xml
@@ -12,44 +12,39 @@
<modifier>public</modifier>
<type>void</type><methodname>MultipleIterator::detachIterator</methodname>
<methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam>
</methodsynopsis>
- <para>
- Detaches an iterator.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Detaches an iterator, together with its associated information. Nothing
+ happens if <parameter>iterator</parameter> is not attached.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>iterator</parameter></term>
- <listitem>
- <para>
- The iterator to detach.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>iterator</parameter></term>
+ <listitem>
+ <simpara>
+ The iterator to detach.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
-
<member><methodname>MultipleIterator::attachIterator</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+
<member><methodname>MultipleIterator::attachIterator</methodname></member>
+
<member><methodname>MultipleIterator::containsIterator</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/getflags.xml
b/reference/spl/multipleiterator/getflags.xml
index 45934f85b08f..0baea6b4cb1e 100644
--- a/reference/spl/multipleiterator/getflags.xml
+++ b/reference/spl/multipleiterator/getflags.xml
@@ -12,12 +12,9 @@
<modifier>public</modifier>
<type>int</type><methodname>MultipleIterator::getFlags</methodname>
<void/>
</methodsynopsis>
- <para>
- Gets information about the flags.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Gets the flags that control how the attached iterators are iterated over.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,20 +24,49 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Information about the flags, as an <type>int</type>.
- </para>
+ <simpara>
+ Returns a bitmask of the
+ <link linkend="multipleiterator.constants">MultipleIterator
+ constants</link>. As <constant>MultipleIterator::MIT_NEED_ANY</constant>
+ and <constant>MultipleIterator::MIT_KEYS_NUMERIC</constant> are
+ <literal>0</literal>, use the bitwise
+ <link linkend="language.operators.bitwise">&</link> operator to
check
+ for <constant>MultipleIterator::MIT_NEED_ALL</constant> and
+ <constant>MultipleIterator::MIT_KEYS_ASSOC</constant>.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Checking the flags</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new MultipleIterator(MultipleIterator::MIT_NEED_ANY |
MultipleIterator::MIT_KEYS_ASSOC);
+
+var_dump((bool) ($iterator->getFlags() & MultipleIterator::MIT_NEED_ALL));
+var_dump((bool) ($iterator->getFlags() & MultipleIterator::MIT_KEYS_ASSOC));
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+bool(false)
+bool(true)
+]]>
+ </screen>
+ </example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><link linkend="multipleiterator.constants">Flag
Constants</link></member>
- <member><methodname>MultipleIterator::__construct</methodname></member>
- <member><methodname>MultipleIterator::setFlags</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><link linkend="multipleiterator.constants">Flag
Constants</link></member>
+ <member><methodname>MultipleIterator::__construct</methodname></member>
+ <member><methodname>MultipleIterator::setFlags</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/key.xml b/reference/spl/multipleiterator/key.xml
index d1ad244bdf44..73089da69e58 100644
--- a/reference/spl/multipleiterator/key.xml
+++ b/reference/spl/multipleiterator/key.xml
@@ -3,7 +3,7 @@
<refentry xml:id="multipleiterator.key" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MultipleIterator::key</refname>
- <refpurpose>Gets the registered iterator instances</refpurpose>
+ <refpurpose>Gets the keys of the attached iterators</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,12 +12,17 @@
<modifier>public</modifier>
<type>array</type><methodname>MultipleIterator::key</methodname>
<void/>
</methodsynopsis>
- <para>
- Get the registered iterator instances key() result.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Gets the current keys of all attached iterators, by calling
+ <methodname>Iterator::key</methodname> on each valid one.
+ </simpara>
+ <simpara>
+ With <constant>MultipleIterator::MIT_KEYS_NUMERIC</constant>, the keys are
+ listed in the order in which the iterators were attached. With
+ <constant>MultipleIterator::MIT_KEYS_ASSOC</constant>, they are keyed by
+ the information associated with each iterator by
+ <methodname>MultipleIterator::attachIterator</methodname>.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,21 +32,25 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- An <type>array</type> of all registered iterator instances.
- </para>
+ <simpara>
+ An <type>array</type> containing the current keys of each attached
+ iterator. With <constant>MultipleIterator::MIT_NEED_ANY</constant>, &null;
+ is used for the iterators that are not valid.
+ </simpara>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
- <para>
- A <classname>RuntimeException</classname> if the iterator is invalid (as of PHP
8.1.0), or
- mode <constant>MIT_NEED_ALL</constant> is set, and at least one attached iterator is
not valid.
- </para>
- <para>
- Calling this method from <xref linkend="control-structures.foreach"/>
- triggers warning "Illegal type returned".
- </para>
+ <simpara>
+ Throws a <exceptionname>RuntimeException</exceptionname> if no iterator is
+ attached, or if <constant>MultipleIterator::MIT_NEED_ALL</constant> is set
+ and at least one attached iterator is not valid.
+ </simpara>
+ <simpara>
+ Throws an <exceptionname>InvalidArgumentException</exceptionname> if
+ <constant>MultipleIterator::MIT_KEYS_ASSOC</constant> is set and an
+ iterator was attached without associated information.
+ </simpara>
</refsect1>
<refsect1 role="changelog">
@@ -58,9 +67,9 @@
<row>
<entry>8.1.0</entry>
<entry>
- A <classname>RuntimeException</classname> is now thrown if
- <methodname>MultipleIterator::key</methodname> is called on an
- invalid iterator. Previously, &false; was returned.
+ A <exceptionname>RuntimeException</exceptionname> is now thrown if
+ <methodname>MultipleIterator::key</methodname> is called when no
+ iterator is attached. Previously, &false; was returned.
</entry>
</row>
</tbody>
@@ -68,13 +77,51 @@
</informaltable>
</refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>MultipleIterator::key</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new MultipleIterator(MultipleIterator::MIT_NEED_ANY |
MultipleIterator::MIT_KEYS_ASSOC);
+$iterator->attachIterator(new ArrayIterator(['a' => 'apple',
'b' => 'banana']), 'fruit');
+$iterator->attachIterator(new ArrayIterator(['x' => 'red']),
'color');
+
+$iterator->rewind();
+while ($iterator->valid()) {
+ var_dump($iterator->key());
+ $iterator->next();
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+array(2) {
+ ["fruit"]=>
+ string(1) "a"
+ ["color"]=>
+ string(1) "x"
+}
+array(2) {
+ ["fruit"]=>
+ string(1) "b"
+ ["color"]=>
+ NULL
+}
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>MultipleIterator::current</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>MultipleIterator::current</methodname></member>
+ <member><methodname>MultipleIterator::valid</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/next.xml b/reference/spl/multipleiterator/next.xml
index fc15b7fae6fb..2e12fd38a11b 100644
--- a/reference/spl/multipleiterator/next.xml
+++ b/reference/spl/multipleiterator/next.xml
@@ -12,12 +12,11 @@
<modifier>public</modifier>
<type>void</type><methodname>MultipleIterator::next</methodname>
<void/>
</methodsynopsis>
- <para>
- Moves all attached iterator instances forward.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Moves all attached iterator instances forward, by calling
+ <methodname>Iterator::next</methodname> on each of them in the order in
+ which they were attached.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,18 +26,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>MultipleIterator::rewind</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>MultipleIterator::rewind</methodname></member>
+ <member><methodname>MultipleIterator::valid</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/rewind.xml b/reference/spl/multipleiterator/rewind.xml
index 39616c04150c..d929a8ccd580 100644
--- a/reference/spl/multipleiterator/rewind.xml
+++ b/reference/spl/multipleiterator/rewind.xml
@@ -12,12 +12,11 @@
<modifier>public</modifier>
<type>void</type><methodname>MultipleIterator::rewind</methodname>
<void/>
</methodsynopsis>
- <para>
- Rewinds all attached iterator instances.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Rewinds all attached iterator instances, by calling
+ <methodname>Iterator::rewind</methodname> on each of them in the order in
+ which they were attached.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,18 +26,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>MultipleIterator::next</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>MultipleIterator::next</methodname></member>
+ <member><methodname>MultipleIterator::valid</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/setflags.xml
b/reference/spl/multipleiterator/setflags.xml
index 10df626472d9..4cb89f0d2f24 100644
--- a/reference/spl/multipleiterator/setflags.xml
+++ b/reference/spl/multipleiterator/setflags.xml
@@ -12,47 +12,53 @@
<modifier>public</modifier>
<type>void</type><methodname>MultipleIterator::setFlags</methodname>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
- <para>
- Sets flags.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Replaces the flags that control how the attached iterators are iterated
+ over.
+ </simpara>
+ <simpara>
+ As <constant>MultipleIterator::MIT_NEED_ANY</constant> and
+ <constant>MultipleIterator::MIT_KEYS_NUMERIC</constant> are
+ <literal>0</literal>, a flag that is not given falls back to them: for
+ example, passing only <constant>MultipleIterator::MIT_KEYS_ASSOC</constant>
+ also switches the iterator to
+ <constant>MultipleIterator::MIT_NEED_ANY</constant>.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>
- The flags to set, according to the
- <link linkend="multipleiterator.constants">Flag Constants</link>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <simpara>
+ A bitmask of the
+ <link linkend="multipleiterator.constants">MultipleIterator
+ constants</link>: <constant>MultipleIterator::MIT_NEED_ALL</constant> or
+ <constant>MultipleIterator::MIT_NEED_ANY</constant>, combined with
+ <constant>MultipleIterator::MIT_KEYS_NUMERIC</constant> or
+ <constant>MultipleIterator::MIT_KEYS_ASSOC</constant>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><link linkend="multipleiterator.constants">Flag
Constants</link></member>
- <member><methodname>MultipleIterator::__construct</methodname></member>
- <member><methodname>MultipleIterator::getFlags</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><link linkend="multipleiterator.constants">Flag
Constants</link></member>
+ <member><methodname>MultipleIterator::__construct</methodname></member>
+ <member><methodname>MultipleIterator::getFlags</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/multipleiterator/valid.xml b/reference/spl/multipleiterator/valid.xml
index 170c7de59aea..d26adc2dbfa3 100644
--- a/reference/spl/multipleiterator/valid.xml
+++ b/reference/spl/multipleiterator/valid.xml
@@ -12,12 +12,12 @@
<modifier>public</modifier>
<type>bool</type><methodname>MultipleIterator::valid</methodname>
<void/>
</methodsynopsis>
- <para>
- Checks the validity of sub iterators.
- </para>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Checks the validity of the attached iterators. With
+ <constant>MultipleIterator::MIT_NEED_ALL</constant>, all of them must be
+ valid; with <constant>MultipleIterator::MIT_NEED_ANY</constant>, at least
+ one of them must be valid.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,19 +27,21 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Returns &true; if one or all sub iterators are valid depending on flags,
- otherwise &false;
- </para>
+ <simpara>
+ Returns &true; if all attached iterators are valid
+ (<constant>MultipleIterator::MIT_NEED_ALL</constant>) or at least one is
+ valid (<constant>MultipleIterator::MIT_NEED_ANY</constant>), otherwise
+ &false;. If no iterator is attached, &false; is returned.
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>MultipleIterator::__construct</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>MultipleIterator::__construct</methodname></member>
+ <member><methodname>MultipleIterator::setFlags</methodname></member>
+ <member><methodname>MultipleIterator::current</methodname></member>
+ </simplelist>
</refsect1>
</refentry>