[doc-en] master: Document the CachingIterator and RecursiveCachingIterator methods (#6073)

From: Date: Fri, 13 Nov 2026 10:16:03 +0000
Subject: [doc-en] master: Document the CachingIterator and RecursiveCachingIterator methods (#6073)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23948@lists.php.net to get a copy of this message
Author: Asish Kumar (officialasishkumar) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-11-13T11:15:59+01:00 Commit: https://github.com/php/doc-en/commit/311705fd828e1a14ea539394ec7230f3a78c8f39 Raw diff: https://github.com/php/doc-en/commit/311705fd828e1a14ea539394ec7230f3a78c8f39.diff Document the CachingIterator and RecursiveCachingIterator methods (#6073) Fifteen CachingIterator pages and all three RecursiveCachingIterator pages only had a synopsis and &warn.undocumented.func;, and the RecursiveCachingIterator class intro was a literal "...". This writes them out based on ext/spl/spl_iterators.c: - class intros: explain that a CachingIterator stays one element ahead of its inner iterator, which is what makes hasNext() possible, and what FULL_CACHE adds. - __construct(): what the flags do, that only one string conversion flag may be given (ValueError as of 8.0.0, InvalidArgumentException before), and a caution that the default CALL_TOSTRING converts every element while iterating, so arrays raise a warning and objects without __toString() throw an Error. - current(), key(), next(), rewind(), valid(), hasNext(): describe the look-ahead behaviour; fix the return value of valid() and hasNext(), which claimed "true on success or false on failure", and the return type of key(), which was "scalar" instead of mixed. - getFlags(), setFlags(): the bitmask, which flags cannot be unset (InvalidArgumentException), and that turning FULL_CACHE on empties the cache. - __toString(): what each string conversion flag returns, and the BadMethodCallException when none is set. - offsetGet(), offsetSet(), offsetUnset(), offsetExists(), count(): they work on the cache, not the inner iterator, require FULL_CACHE, and replace the placeholder purposes such as "The offsetGet purpose". - RecursiveCachingIterator: how children are wrapped with the same flags, what CATCH_GET_CHILD does, and the TypeError for an iterator that is not a RecursiveIterator. Examples are added for hasNext(), getFlags(), setFlags(), __toString(), offsetGet(), count() and getChildren(). Every example was run on PHP 8.4 and prints the output shown. Part of #5786 Changed paths: M reference/spl/cachingiterator.xml M reference/spl/cachingiterator/construct.xml M reference/spl/cachingiterator/count.xml M reference/spl/cachingiterator/current.xml M reference/spl/cachingiterator/getflags.xml M reference/spl/cachingiterator/hasnext.xml M reference/spl/cachingiterator/key.xml M reference/spl/cachingiterator/next.xml M reference/spl/cachingiterator/offsetexists.xml M reference/spl/cachingiterator/offsetget.xml M reference/spl/cachingiterator/offsetset.xml M reference/spl/cachingiterator/offsetunset.xml M reference/spl/cachingiterator/rewind.xml M reference/spl/cachingiterator/setflags.xml M reference/spl/cachingiterator/tostring.xml M reference/spl/cachingiterator/valid.xml M reference/spl/recursivecachingiterator.xml M reference/spl/recursivecachingiterator/construct.xml M reference/spl/recursivecachingiterator/getchildren.xml M reference/spl/recursivecachingiterator/haschildren.xml Diff: diff --git a/reference/spl/cachingiterator.xml b/reference/spl/cachingiterator.xml index af9b6a3189f1..8e62c41bdbe7 100644 --- a/reference/spl/cachingiterator.xml +++ b/reference/spl/cachingiterator.xml @@ -9,9 +9,22 @@ <!-- {{{ CachingIterator intro --> <section xml:id="cachingiterator.intro"> &reftitle.intro; - <para> + <simpara> This object supports cached iteration over another iterator. - </para> + </simpara> + <simpara> + A <classname>CachingIterator</classname> is always one element ahead of + its inner iterator: when it moves to an element, it stores the key and + value of that element, and then moves the inner iterator forward. + This makes it possible to know whether the current element is the last + one, with <methodname>CachingIterator::hasNext</methodname>. + </simpara> + <simpara> + With the <constant>CachingIterator::FULL_CACHE</constant> flag, it also + keeps every element that has been iterated over, which can then be + accessed with array syntax or retrieved with + <methodname>CachingIterator::getCache</methodname>. + </simpara> </section> <!-- }}} --> diff --git a/reference/spl/cachingiterator/construct.xml b/reference/spl/cachingiterator/construct.xml index 3f67e0201f62..edab20cebb82 100644 --- a/reference/spl/cachingiterator/construct.xml +++ b/reference/spl/cachingiterator/construct.xml @@ -13,34 +13,112 @@ <methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>CachingIterator::CALL_TOSTRING</constant></initializer></methodparam> </constructorsynopsis> - - &warn.undocumented.func; - + <simpara> + Creates a <classname>CachingIterator</classname> that iterates over + <parameter>iterator</parameter>, staying one element ahead of it. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>iterator</parameter></term> - <listitem> - <para> - Iterator to cache - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para> - Bitmask of flags. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + <variablelist> + <varlistentry> + <term><parameter>iterator</parameter></term> + <listitem> + <simpara> + The iterator to cache. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <simpara> + A bitmask of the + <link linkend="cachingiterator.constants">CachingIterator constants</link>. + </simpara> + <simpara> + At most one of <constant>CachingIterator::CALL_TOSTRING</constant>, + <constant>CachingIterator::TOSTRING_USE_KEY</constant>, + <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and + <constant>CachingIterator::TOSTRING_USE_INNER</constant> may be given. + It selects what <methodname>CachingIterator::__toString</methodname> + returns; if none of them is given, calling it throws an exception. + </simpara> + <simpara> + <constant>CachingIterator::FULL_CACHE</constant> keeps every element + that has been iterated over, so that it can be accessed with + <link linkend="language.types.array.syntax.accessing">array syntax</link> + or retrieved with <methodname>CachingIterator::getCache</methodname>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if + <parameter>flags</parameter> contains more than one of + <constant>CachingIterator::CALL_TOSTRING</constant>, + <constant>CachingIterator::TOSTRING_USE_KEY</constant>, + <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and + <constant>CachingIterator::TOSTRING_USE_INNER</constant>. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if + <parameter>flags</parameter> contains more than one of the string + conversion flags; previously, an + <exceptionname>InvalidArgumentException</exceptionname> was thrown. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <caution> + <simpara> + With <constant>CachingIterator::CALL_TOSTRING</constant>, which is the + default, each element is converted to a &string; as soon as the iterator + moves to it, whether or not + <methodname>CachingIterator::__toString</methodname> is ever called. + An element that is an &array; raises an <constant>E_WARNING</constant>, + and an object that does not implement + <link linkend="object.tostring">__toString()</link> throws an + <exceptionname>Error</exceptionname>. + To iterate over such elements, pass <parameter>flags</parameter> that do + not contain <constant>CachingIterator::CALL_TOSTRING</constant>, such as + <literal>0</literal>. + </simpara> + </caution> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::setFlags</methodname></member> + <member><methodname>CachingIterator::__toString</methodname></member> + <member><methodname>RecursiveCachingIterator::__construct</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/count.xml b/reference/spl/cachingiterator/count.xml index 2219682c72b9..4674e5990a35 100644 --- a/reference/spl/cachingiterator/count.xml +++ b/reference/spl/cachingiterator/count.xml @@ -3,7 +3,7 @@ <refentry xml:id="cachingiterator.count" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>CachingIterator::count</refname> - <refpurpose>The number of elements in the iterator</refpurpose> + <refpurpose>Return the number of elements in the cache</refpurpose> </refnamediv> <refsect1 role="description"> @@ -12,12 +12,15 @@ <modifier>public</modifier> <type>int</type><methodname>CachingIterator::count</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - May return the number of elements in the iterator. - </para> + <simpara> + Returns the number of elements in the cache. + This is the number of elements iterated over so far, not the number of + elements of the inner iterator. Elements are stored in the cache by key, + so an element replaces any earlier element with the same key. + </simpara> + <simpara> + The <constant>CachingIterator::FULL_CACHE</constant> flag must be set. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -27,9 +30,53 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - The count of the elements iterated over. - </para> + <simpara> + Returns the number of elements in the cache. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>BadMethodCallException</exceptionname> if the + <constant>CachingIterator::FULL_CACHE</constant> flag is not set. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><methodname>CachingIterator::count</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$iterator = new CachingIterator( + new ArrayIterator(['a', 'b', 'c']), + CachingIterator::FULL_CACHE +); + +foreach ($iterator as $value) { + echo $value, ': ', count($iterator), "\n"; +} +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +a: 1 +b: 2 +c: 3 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::getCache</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/current.xml b/reference/spl/cachingiterator/current.xml index 3727875494b4..089d72129327 100644 --- a/reference/spl/cachingiterator/current.xml +++ b/reference/spl/cachingiterator/current.xml @@ -11,14 +11,16 @@ &reftitle.description; <methodsynopsis role="CachingIterator"> <modifier>public</modifier> <type>mixed</type><methodname>CachingIterator::current</methodname> - <void /> + <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - May return the current element in the iteration. - </para> + <simpara> + Returns the current element. + </simpara> + <simpara> + As the <classname>CachingIterator</classname> is one element ahead of its + inner iterator, this is the element that was stored when the iterator last + moved, not the current element of the inner iterator. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -28,18 +30,19 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - Mixed - </para> + <simpara> + Returns the current element, or &null; if the iterator is not + <link linkend="cachingiterator.valid">valid</link>. + </simpara> </refsect1> <refsect1 role="seealso"> &reftitle.seealso; - <para> - <simplelist> - <member><methodname>Iterator::current</methodname></member> - </simplelist> - </para> + <simplelist> + <member><methodname>CachingIterator::key</methodname></member> + <member><methodname>CachingIterator::valid</methodname></member> + <member><methodname>Iterator::current</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/getflags.xml b/reference/spl/cachingiterator/getflags.xml index b114bf91d928..bfa6c685d920 100644 --- a/reference/spl/cachingiterator/getflags.xml +++ b/reference/spl/cachingiterator/getflags.xml @@ -12,12 +12,10 @@ <modifier>public</modifier> <type>int</type><methodname>CachingIterator::getFlags</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - Get the bitmask of the flags used for this CachingIterator instance. - </para> + <simpara> + Gets the bitmask of the flags used for this + <classname>CachingIterator</classname> instance. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -27,9 +25,47 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - Description... - </para> + <simpara> + Returns a bitmask of the + <link linkend="cachingiterator.constants">CachingIterator constants</link>. + Use the bitwise <link linkend="language.operators.bitwise">&amp;</link> + operator to check whether a given flag is set. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Checking whether a flag is set</title> + <programlisting role="php"> +<![CDATA[ +<?php +$iterator = new CachingIterator( + new ArrayIterator(['a', 'b', 'c']), + CachingIterator::TOSTRING_USE_KEY | CachingIterator::FULL_CACHE +); + +var_dump((bool) ($iterator->getFlags() & CachingIterator::FULL_CACHE)); +var_dump((bool) ($iterator->getFlags() & CachingIterator::CALL_TOSTRING)); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +bool(true) +bool(false) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::setFlags</methodname></member> + <member><methodname>CachingIterator::__construct</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/hasnext.xml b/reference/spl/cachingiterator/hasnext.xml index b4c71f974a69..37647a31dfb0 100644 --- a/reference/spl/cachingiterator/hasnext.xml +++ b/reference/spl/cachingiterator/hasnext.xml @@ -12,9 +12,15 @@ <modifier>public</modifier> <type>bool</type><methodname>CachingIterator::hasNext</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - + <simpara> + Checks whether there is an element after the current one. + </simpara> + <simpara> + As the <classname>CachingIterator</classname> is one element ahead of its + inner iterator, this checks whether the inner iterator is valid, which + makes it possible to tell whether the current element is the last one + before moving past it. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -24,9 +30,46 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - &return.success; - </para> + <simpara> + Returns &true; if there is an element after the current one, + &false; otherwise. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Detecting the last element</title> + <programlisting role="php"> +<![CDATA[ +<?php +$fruits = new CachingIterator(new ArrayIterator(['apple', 'banana', 'cherry'])); + +foreach ($fruits as $fruit) { + echo $fruit; + + if ($fruits->hasNext()) { + echo ', '; + } +} +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +apple, banana, cherry +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::valid</methodname></member> + <member><methodname>CachingIterator::next</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/key.xml b/reference/spl/cachingiterator/key.xml index a427e0f5c2d4..de0f4b9a127f 100644 --- a/reference/spl/cachingiterator/key.xml +++ b/reference/spl/cachingiterator/key.xml @@ -10,15 +10,17 @@ <refsect1 role="description"> &reftitle.description; <methodsynopsis role="CachingIterator"> - <modifier>public</modifier> <type>scalar</type><methodname>CachingIterator::key</methodname> - <void /> + <modifier>public</modifier> <type>mixed</type><methodname>CachingIterator::key</methodname> + <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - This method may return a key for the current element. - </para> + <simpara> + Returns the key of the current element. + </simpara> + <simpara> + As the <classname>CachingIterator</classname> is one element ahead of its + inner iterator, this is the key that was stored when the iterator last + moved, not the current key of the inner iterator. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -26,6 +28,23 @@ &no.function.parameters; </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns the key of the current element, or &null; if the iterator is not + <link linkend="cachingiterator.valid">valid</link>. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::current</methodname></member> + <member><methodname>CachingIterator::valid</methodname></member> + <member><methodname>Iterator::key</methodname></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/reference/spl/cachingiterator/next.xml b/reference/spl/cachingiterator/next.xml index 3b68e5f6aa39..bab31b950b52 100644 --- a/reference/spl/cachingiterator/next.xml +++ b/reference/spl/cachingiterator/next.xml @@ -12,12 +12,17 @@ <modifier>public</modifier> <type>void</type><methodname>CachingIterator::next</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - Move the iterator forward. - </para> + <simpara> + Moves the iterator forward. + </simpara> + <simpara> + If the inner iterator is valid, its current key and element become the + current key and element of the <classname>CachingIterator</classname>, + and are added to the cache if + <constant>CachingIterator::FULL_CACHE</constant> is set. + The inner iterator is then moved forward. + Otherwise, the <classname>CachingIterator</classname> is no longer valid. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -27,9 +32,18 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> &return.void; - </para> + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::rewind</methodname></member> + <member><methodname>CachingIterator::hasNext</methodname></member> + <member><methodname>CachingIterator::valid</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/offsetexists.xml b/reference/spl/cachingiterator/offsetexists.xml index 859b271b0958..92ee3c0738bc 100644 --- a/reference/spl/cachingiterator/offsetexists.xml +++ b/reference/spl/cachingiterator/offsetexists.xml @@ -3,7 +3,7 @@ <refentry xml:id="cachingiterator.offsetexists" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>CachingIterator::offsetExists</refname> - <refpurpose>The offsetExists purpose</refpurpose> + <refpurpose>Check whether an element exists in the cache</refpurpose> </refnamediv> <refsect1 role="description"> @@ -12,33 +12,54 @@ <modifier>public</modifier> <type>bool</type><methodname>CachingIterator::offsetExists</methodname> <methodparam><type>string</type><parameter>key</parameter></methodparam> </methodsynopsis> - - &warn.undocumented.func; - + <simpara> + Checks whether an element is stored under <parameter>key</parameter> in + the cache. + This method is called when <function>isset</function> or <function>empty</function> is used on the + <classname>CachingIterator</classname> with array syntax, such as + <code>isset($iterator['key'])</code>. + </simpara> + <simpara> + The <constant>CachingIterator::FULL_CACHE</constant> flag must be set. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>key</parameter></term> - <listitem> - <para> - The index being checked. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - + <variablelist> + <varlistentry> + <term><parameter>key</parameter></term> + <listitem> + <simpara> + The key being checked. + </simpara> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - Returns &true; if an entry referenced by the offset exists, &false; otherwise. - </para> + <simpara> + Returns &true; if an element is stored under <parameter>key</parameter> + in the cache, &false; otherwise. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>BadMethodCallException</exceptionname> if the + <constant>CachingIterator::FULL_CACHE</constant> flag is not set. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::offsetGet</methodname></member> + <member><methodname>CachingIterator::getCache</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/offsetget.xml b/reference/spl/cachingiterator/offsetget.xml index 711a659af549..3d155bf79111 100644 --- a/reference/spl/cachingiterator/offsetget.xml +++ b/reference/spl/cachingiterator/offsetget.xml @@ -3,7 +3,7 @@ <refentry xml:id="cachingiterator.offsetget" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>CachingIterator::offsetGet</refname> - <refpurpose>The offsetGet purpose</refpurpose> + <refpurpose>Return an element from the cache</refpurpose> </refnamediv> <refsect1 role="description"> @@ -12,33 +12,92 @@ <modifier>public</modifier> <type>mixed</type><methodname>CachingIterator::offsetGet</methodname> <methodparam><type>string</type><parameter>key</parameter></methodparam> </methodsynopsis> - - &warn.undocumented.func; - + <simpara> + Returns the element stored under <parameter>key</parameter> in the cache. + This method is called when the <classname>CachingIterator</classname> is + read with <link linkend="language.types.array.syntax.accessing">array syntax</link>, + such as <code>$iterator['key']</code>. + </simpara> + <simpara> + The <constant>CachingIterator::FULL_CACHE</constant> flag must be set. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>key</parameter></term> - <listitem> - <para> - Description... - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - + <variablelist> + <varlistentry> + <term><parameter>key</parameter></term> + <listitem> + <simpara> + The key of the element to retrieve. + </simpara> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - Description... - </para> + <simpara> + Returns the cached element, or &null; if there is no element with the + given <parameter>key</parameter> in the cache. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>BadMethodCallException</exceptionname> if the + <constant>CachingIterator::FULL_CACHE</constant> flag is not set. + </simpara> + <simpara> + Emits an <constant>E_WARNING</constant> if there is no element with the + given <parameter>key</parameter> in the cache. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Accessing elements that have been iterated over</title> + <programlisting role="php"> +<![CDATA[ +<?php +$iterator = new CachingIterator( + new ArrayIterator(['apple' => 3, 'banana' => 5, 'cherry' => 7]), + CachingIterator::FULL_CACHE +); + +foreach ($iterator as $fruit => $count) { + if ($fruit === 'banana') { + break; + } +} + +var_dump($iterator['apple']); +var_dump(isset($iterator['cherry'])); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(3) +bool(false) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::offsetExists</methodname></member> + <member><methodname>CachingIterator::offsetSet</methodname></member> + <member><methodname>CachingIterator::offsetUnset</methodname></member> + <member><methodname>CachingIterator::getCache</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/offsetset.xml b/reference/spl/cachingiterator/offsetset.xml index 5708f2f5d870..98d4c946b04c 100644 --- a/reference/spl/cachingiterator/offsetset.xml +++ b/reference/spl/cachingiterator/offsetset.xml @@ -3,7 +3,7 @@ <refentry xml:id="cachingiterator.offsetset" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>CachingIterator::offsetSet</refname> - <refpurpose>The offsetSet purpose</refpurpose> + <refpurpose>Set an element in the cache</refpurpose> </refnamediv> <refsect1 role="description"> @@ -13,41 +13,63 @@ <methodparam><type>string</type><parameter>key</parameter></methodparam> <methodparam><type>mixed</type><parameter>value</parameter></methodparam> </methodsynopsis> - - &warn.undocumented.func; - + <simpara> + Stores <parameter>value</parameter> under <parameter>key</parameter> in + the cache. + This method is called when a value is assigned to the + <classname>CachingIterator</classname> with array syntax, such as + <code>$iterator['key'] = $value</code>. + The inner iterator is not modified. + </simpara> + <simpara> + The <constant>CachingIterator::FULL_CACHE</constant> flag must be set. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>key</parameter></term> - <listitem> - <para> - The index of the element to be set. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>value</parameter></term> - <listitem> - <para> - The new value for the <parameter>key</parameter>. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - + <variablelist> + <varlistentry> + <term><parameter>key</parameter></term> + <listitem> + <simpara> + The key of the element to be set. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter></term> + <listitem> + <simpara> + The new value for the <parameter>key</parameter>. + </simpara> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> &return.void; - </para> + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>BadMethodCallException</exceptionname> if the + <constant>CachingIterator::FULL_CACHE</constant> flag is not set. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::offsetGet</methodname></member> + <member><methodname>CachingIterator::offsetUnset</methodname></member> + <member><methodname>CachingIterator::getCache</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/offsetunset.xml b/reference/spl/cachingiterator/offsetunset.xml index 74874aefec18..4df093dec32b 100644 --- a/reference/spl/cachingiterator/offsetunset.xml +++ b/reference/spl/cachingiterator/offsetunset.xml @@ -3,7 +3,7 @@ <refentry xml:id="cachingiterator.offsetunset" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>CachingIterator::offsetUnset</refname> - <refpurpose>The offsetUnset purpose</refpurpose> + <refpurpose>Remove an element from the cache</refpurpose> </refnamediv> <refsect1 role="description"> @@ -12,33 +12,54 @@ <modifier>public</modifier> <type>void</type><methodname>CachingIterator::offsetUnset</methodname> <methodparam><type>string</type><parameter>key</parameter></methodparam> </methodsynopsis> - - &warn.undocumented.func; - + <simpara> + Removes the element stored under <parameter>key</parameter> from the cache. + This method is called when <function>unset</function> is used on the + <classname>CachingIterator</classname> with array syntax, such as + <code>unset($iterator['key'])</code>. + The inner iterator is not modified. + </simpara> + <simpara> + The <constant>CachingIterator::FULL_CACHE</constant> flag must be set. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>key</parameter></term> - <listitem> - <para> - The index of the element to be unset. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - + <variablelist> + <varlistentry> + <term><parameter>key</parameter></term> + <listitem> + <simpara> + The key of the element to be removed. + </simpara> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> &return.void; - </para> + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>BadMethodCallException</exceptionname> if the + <constant>CachingIterator::FULL_CACHE</constant> flag is not set. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::offsetExists</methodname></member> + <member><methodname>CachingIterator::offsetSet</methodname></member> + <member><methodname>CachingIterator::getCache</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/rewind.xml b/reference/spl/cachingiterator/rewind.xml index e38ec7d010e0..e171a031fdca 100644 --- a/reference/spl/cachingiterator/rewind.xml +++ b/reference/spl/cachingiterator/rewind.xml @@ -12,12 +12,10 @@ <modifier>public</modifier> <type>void</type><methodname>CachingIterator::rewind</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - Rewind the iterator. - </para> + <simpara> + Rewinds the inner iterator, empties the cache, and then moves to the first + element as <methodname>CachingIterator::next</methodname> does. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -27,9 +25,17 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> &return.void; - </para> + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::next</methodname></member> + <member><methodname>CachingIterator::getCache</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/setflags.xml b/reference/spl/cachingiterator/setflags.xml index d975b5e6d72b..d0929c2802dc 100644 --- a/reference/spl/cachingiterator/setflags.xml +++ b/reference/spl/cachingiterator/setflags.xml @@ -3,7 +3,7 @@ <refentry xml:id="cachingiterator.setflags" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>CachingIterator::setFlags</refname> - <refpurpose>The setFlags purpose</refpurpose> + <refpurpose>Set the flags for the CachingIterator object</refpurpose> </refnamediv> <refsect1 role="description"> @@ -12,36 +12,126 @@ <modifier>public</modifier> <type>void</type><methodname>CachingIterator::setFlags</methodname> <methodparam><type>int</type><parameter>flags</parameter></methodparam> </methodsynopsis> - - &warn.undocumented.func; - - <para> - Set the flags for the CachingIterator object. - </para> + <simpara> + Replaces the flags of the <classname>CachingIterator</classname> with + <parameter>flags</parameter>. + </simpara> + <simpara> + Turning <constant>CachingIterator::FULL_CACHE</constant> on empties the + cache; elements are added to it from the next move of the iterator onwards. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para> - Bitmask of the flags to set. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - + <variablelist> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <simpara> + A bitmask of the + <link linkend="cachingiterator.constants">CachingIterator constants</link>. + At most one of <constant>CachingIterator::CALL_TOSTRING</constant>, + <constant>CachingIterator::TOSTRING_USE_KEY</constant>, + <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and + <constant>CachingIterator::TOSTRING_USE_INNER</constant> may be given. + </simpara> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> &return.void; - </para> + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if + <parameter>flags</parameter> contains more than one of + <constant>CachingIterator::CALL_TOSTRING</constant>, + <constant>CachingIterator::TOSTRING_USE_KEY</constant>, + <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and + <constant>CachingIterator::TOSTRING_USE_INNER</constant>. + </simpara> + <simpara> + Throws an <exceptionname>InvalidArgumentException</exceptionname> if + <constant>CachingIterator::CALL_TOSTRING</constant> or + <constant>CachingIterator::TOSTRING_USE_INNER</constant> is currently set + and <parameter>flags</parameter> does not contain it, as these flags + cannot be unset. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if + <parameter>flags</parameter> contains more than one of the string + conversion flags; previously, an + <exceptionname>InvalidArgumentException</exceptionname> was thrown. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Turning on the full cache</title> + <programlisting role="php"> +<![CDATA[ +<?php +$iterator = new CachingIterator(new ArrayIterator(['a', 'b', 'c']), 0); +$iterator->setFlags(CachingIterator::FULL_CACHE); + +foreach ($iterator as $value) { + // ... +} + +var_dump($iterator->getCache()); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +array(3) { + [0]=> + string(1) "a" + [1]=> + string(1) "b" + [2]=> + string(1) "c" +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::getFlags</methodname></member> + <member><methodname>CachingIterator::__construct</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/tostring.xml b/reference/spl/cachingiterator/tostring.xml index 8e906df6e598..b1e1703aa8c9 100644 --- a/reference/spl/cachingiterator/tostring.xml +++ b/reference/spl/cachingiterator/tostring.xml @@ -12,12 +12,49 @@ <modifier>public</modifier> <type>string</type><methodname>CachingIterator::__toString</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - Get the string representation of the current element. - </para> + <simpara> + Gets the string representation of the current element. + What is returned depends on the flags of the + <classname>CachingIterator</classname>: + </simpara> + <variablelist> + <varlistentry> + <term><constant>CachingIterator::CALL_TOSTRING</constant></term> + <listitem> + <simpara> + The current element converted to a &string;. + The conversion is done when the iterator moves to the element. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>CachingIterator::TOSTRING_USE_KEY</constant></term> + <listitem> + <simpara> + The key of the current element converted to a &string;. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>CachingIterator::TOSTRING_USE_CURRENT</constant></term> + <listitem> + <simpara> + The current element converted to a &string;. + The conversion is done when this method is called. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>CachingIterator::TOSTRING_USE_INNER</constant></term> + <listitem> + <simpara> + The inner iterator converted to a &string;. + The conversion is done when the iterator moves to the element, before + the inner iterator is moved forward. + </simpara> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1 role="parameters"> @@ -27,9 +64,56 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> The <type>string</type> representation of the current element. - </para> + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>BadMethodCallException</exceptionname> if none of + <constant>CachingIterator::CALL_TOSTRING</constant>, + <constant>CachingIterator::TOSTRING_USE_KEY</constant>, + <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and + <constant>CachingIterator::TOSTRING_USE_INNER</constant> is set. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Using the keys as the string representation</title> + <programlisting role="php"> +<![CDATA[ +<?php +$iterator = new CachingIterator( + new ArrayIterator(['apple' => 3, 'banana' => 5]), + CachingIterator::TOSTRING_USE_KEY +); + +foreach ($iterator as $count) { + echo $iterator, ': ', $count, "\n"; +} +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +apple: 3 +banana: 5 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::__construct</methodname></member> + <member><methodname>CachingIterator::setFlags</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/cachingiterator/valid.xml b/reference/spl/cachingiterator/valid.xml index ae90d208da04..118b95cd20e4 100644 --- a/reference/spl/cachingiterator/valid.xml +++ b/reference/spl/cachingiterator/valid.xml @@ -12,12 +12,14 @@ <modifier>public</modifier> <type>bool</type><methodname>CachingIterator::valid</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - - <para> - Check whether the current element is valid. - </para> + <simpara> + Checks whether the current element is valid. + </simpara> + <simpara> + A <classname>CachingIterator</classname> has no current element until + <methodname>CachingIterator::rewind</methodname> is called, which + &foreach; does automatically. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -27,9 +29,17 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - &return.success; - </para> + <simpara> + Returns &true; if the current element is valid, &false; otherwise. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>CachingIterator::hasNext</methodname></member> + <member><methodname>CachingIterator::rewind</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/recursivecachingiterator.xml b/reference/spl/recursivecachingiterator.xml index 47d0b80c542d..0f7ee9bca004 100644 --- a/reference/spl/recursivecachingiterator.xml +++ b/reference/spl/recursivecachingiterator.xml @@ -9,9 +9,13 @@ <!-- {{{ RecursiveCachingIterator intro --> <section xml:id="recursivecachingiterator.intro"> &reftitle.intro; - <para> - ... - </para> + <simpara> + This object supports cached iteration over a + <interfacename>RecursiveIterator</interfacename>. + The children of each element are also iterated over by a + <classname>RecursiveCachingIterator</classname>, created with the same + flags. + </simpara> </section> <!-- }}} --> diff --git a/reference/spl/recursivecachingiterator/construct.xml b/reference/spl/recursivecachingiterator/construct.xml index f1cc3c85b855..18ef9b1a906f 100644 --- a/reference/spl/recursivecachingiterator/construct.xml +++ b/reference/spl/recursivecachingiterator/construct.xml @@ -13,48 +13,98 @@ <methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>RecursiveCachingIterator::CALL_TOSTRING</constant></initializer></methodparam> </constructorsynopsis> - <para> + <simpara> Constructs a new <classname>RecursiveCachingIterator</classname>, which consists of a passed in <parameter>iterator</parameter>. - </para> - - &warn.undocumented.func; - + </simpara> + <simpara> + Whether the current element has children is checked when the iterator + moves to it. If it does, its children are wrapped in a new + <classname>RecursiveCachingIterator</classname> created with the same + <parameter>flags</parameter>, which + <methodname>RecursiveCachingIterator::getChildren</methodname> returns. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>iterator</parameter></term> - <listitem> - <para> - The iterator being used. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para> - The flags. Use <constant>CALL_TOSTRING</constant> to call - <methodname>RecursiveCachingIterator::__toString</methodname> for every element (the default), - and/or <constant>CATCH_GET_CHILD</constant> to catch exceptions when trying to get children. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + <variablelist> + <varlistentry> + <term><parameter>iterator</parameter></term> + <listitem> + <simpara> + The iterator being used. It must be a + <interfacename>RecursiveIterator</interfacename>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <simpara> + A bitmask of the + <link linkend="cachingiterator.constants">CachingIterator constants</link>, + as for <methodname>CachingIterator::__construct</methodname>. + </simpara> + <simpara> + With <constant>CachingIterator::CATCH_GET_CHILD</constant>, an exception + thrown by the <methodname>RecursiveIterator::hasChildren</methodname> or + <methodname>RecursiveIterator::getChildren</methodname> method of the + inner iterator is discarded, and the current element is treated as + having no children. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>TypeError</exceptionname> if + <parameter>iterator</parameter> is not a + <interfacename>RecursiveIterator</interfacename>. + </simpara> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if + <parameter>flags</parameter> contains more than one of + <constant>CachingIterator::CALL_TOSTRING</constant>, + <constant>CachingIterator::TOSTRING_USE_KEY</constant>, + <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and + <constant>CachingIterator::TOSTRING_USE_INNER</constant>. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if + <parameter>flags</parameter> contains more than one of the string + conversion flags; previously, an + <exceptionname>InvalidArgumentException</exceptionname> was thrown. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </refsect1> <refsect1 role="seealso"> &reftitle.seealso; - <para> - <simplelist> - <member><methodname>CachingIterator::__construct</methodname></member> - </simplelist> - </para> + <simplelist> + <member><methodname>CachingIterator::__construct</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/recursivecachingiterator/getchildren.xml b/reference/spl/recursivecachingiterator/getchildren.xml index 2ae0feaa6326..dc0058031e70 100644 --- a/reference/spl/recursivecachingiterator/getchildren.xml +++ b/reference/spl/recursivecachingiterator/getchildren.xml @@ -11,9 +11,12 @@ <modifier>public</modifier> <type class="union"><type>RecursiveCachingIterator</type><type>null</type></type><methodname>RecursiveCachingIterator::getChildren</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - + <simpara> + Returns the children of the current element, wrapped in a + <classname>RecursiveCachingIterator</classname> that has the same flags. + The children are retrieved from the inner iterator when the iterator moves + to the element, so the same object is returned until the iterator moves on. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -23,9 +26,59 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - The inner iterator's children, as a RecursiveCachingIterator; or &null; if there is no children. - </para> + <simpara> + The children of the current element, as a + <classname>RecursiveCachingIterator</classname>; + or &null; if the current element has no children. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Iterating over children</title> + <programlisting role="php"> +<![CDATA[ +<?php +$iterator = new RecursiveCachingIterator( + new RecursiveArrayIterator(['a' => 1, 'b' => ['c' => 2, 'd' => 3], 'e' => 4]), + 0 +); + +foreach ($iterator as $key => $value) { + if (!$iterator->hasChildren()) { + echo $key, ' = ', $value, "\n"; + continue; + } + + echo $key, ":\n"; + $children = $iterator->getChildren(); + foreach ($children as $childKey => $childValue) { + echo ' ', $childKey, ' = ', $childValue, $children->hasNext() ? '' : ' (last)', "\n"; + } +} +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +a = 1 +b: + c = 2 + d = 3 (last) +e = 4 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>RecursiveCachingIterator::hasChildren</methodname></member> + <member><methodname>RecursiveIterator::getChildren</methodname></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/spl/recursivecachingiterator/haschildren.xml b/reference/spl/recursivecachingiterator/haschildren.xml index 4dbd0d85340a..bb0a18837cae 100644 --- a/reference/spl/recursivecachingiterator/haschildren.xml +++ b/reference/spl/recursivecachingiterator/haschildren.xml @@ -11,12 +11,13 @@ <modifier>public</modifier> <type>bool</type><methodname>RecursiveCachingIterator::hasChildren</methodname> <void/> </methodsynopsis> - - &warn.undocumented.func; - + <simpara> + Checks whether the current element has children. + The inner iterator is asked when the iterator moves to the element, so + this method returns the result that was stored at that time. + </simpara> </refsect1> - <refsect1 role="parameters"> &reftitle.parameters; &no.function.parameters; @@ -24,9 +25,17 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - &true; if the inner iterator has children, otherwise &false; - </para> + <simpara> + Returns &true; if the current element has children, &false; otherwise. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>RecursiveCachingIterator::getChildren</methodname></member> + <member><methodname>RecursiveIterator::hasChildren</methodname></member> + </simplelist> </refsect1> </refentry>

« previous php.doc.cvs (#23948) next »