replay reverted r313182 with fixed examples sections

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@313199 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Peter Cowburn 2011-07-13 09:39:04 +00:00
parent 8dcd90b377
commit a1e4712d6a
6 changed files with 222 additions and 18 deletions

View file

@ -60,6 +60,66 @@
</section>
<!-- {{{ examples -->
<section xml:id="callbackfilteriterator.examples">
&reftitle.examples;
<para>
The callback should accept up to three arguments:
the current item, the current key and the iterator, respectively.
</para>
<example xml:id="callbackfilteriterator.examples.args">
<title>Available callback arguments</title>
<programlisting role="php">
<![CDATA[
<?php
/**
* Callback for CallbackFilterIterator
*
* @param $current Current item's value
* @param $key Current item's key
* @param $iterator Iterator being filtered
* @return boolean TRUE to accept the current item, FALSE otherwise
*/
function my_callback($current, $key, $iterator) {
// Your filtering code here
}
?>
]]>
</programlisting>
</example>
<para>
Any <type>callback</type> may be used; such as a string containing a
function name, an array for a method, or an anonymous function.
</para>
<example xml:id="callbackfilteriterator.examples.basic">
<title>Callback basic examples</title>
<programlisting role="php">
<![CDATA[
<?php
$dir = new FilesystemIterator(__DIR__);
// Filter large files ( > 100MB)
function is_large_file($current) {
return $current->isFile() && $current->getSize() > 104857600;
}
$large_files = new CallbackFilterIterator($dir, 'is_large_file');
// Filter directories
$files = new CallbackFilterIterator($dir, function ($current, $key, $iterator) {
return $current->isDir() && ! $iterator->isDot();
});
?>
]]>
</programlisting>
</example>
</section>
<!-- }}} -->
</partintro>
&reference.spl.entities.callbackfilteriterator;

View file

@ -64,6 +64,74 @@
</section>
<!-- {{{ examples -->
<section xml:id="recursivecallbackfilteriterator.examples">
&reftitle.examples;
<para>
The callback should accept up to three arguments:
the current item, the current key and the iterator, respectively.
</para>
<example xml:id="recursivecallbackfilteriterator.examples.args">
<title>Available callback arguments</title>
<programlisting role="php">
<![CDATA[
<?php
/**
* Callback for RecursiveCallbackFilterIterator
*
* @param $current Current item's value
* @param $key Current item's key
* @param $iterator Iterator being filtered
* @return boolean TRUE to accept the current item, FALSE otherwise
*/
function my_callback($current, $key, $iterator) {
// Your filtering code here
}
?>
]]>
</programlisting>
</example>
<para>
Filtering a recursive iterator generally involves two conditions.
The first is that, to allow recursion, the callback function should return &true;
if the current iterator item has children.
The second is the normal filter condition, such as a file size or extension
check as in the example below.
</para>
<example xml:id="recursivecallbackfilteriterator.examples.basic">
<title>Recursive callback basic example</title>
<programlisting role="php">
<![CDATA[
<?php
$dir = new FilesystemIterator(__DIR__);
// Filter large files ( > 100MB)
$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
// Allow recursion
if ($iterator->hasChildren()) {
return TRUE;
}
// Check for large file
if ($current->isFile() && $current->getSize() > 104857600) {
return TRUE;
}
return FALSE;
});
foreach (new RecursiveIteratorIterator($files) as $file) {
echo $file->getPathname() . PHP_EOL;
}
?>
]]>
</programlisting>
</example>
</section>
<!-- }}} -->
</partintro>
&reference.spl.entities.recursivecallbackfilteriterator;

View file

@ -9,17 +9,17 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<constructorsynopsis role="oop">
<modifier>public</modifier>
<methodname>RecursiveCallbackFilterIterator::__construct</methodname>
<methodparam><type>RecursiveIterator</type><parameter>iterator</parameter></methodparam>
<methodparam><type>string</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
</constructorsynopsis>
<para>
Creates a filtered iterator from a <interfacename>RecursiveIterator</interfacename>
using the <parameter>callback</parameter> to determine which
items are accepted or rejected.
</para>
&warn.undocumented.func;
</refsect1>
<refsect1 role="parameters">
@ -29,7 +29,7 @@
<term><parameter>iterator</parameter></term>
<listitem>
<para>
The recursive iterator to be filtered.
</para>
</listitem>
</varlistentry>
@ -37,7 +37,12 @@
<term><parameter>callback</parameter></term>
<listitem>
<para>
The callback, which should return &true; to accept the current item
or &false; otherwise.
See <link linkend="recursivecallbackfilteriterator.examples">Examples</link>.
</para>
<para>
May be any valid <type>callback</type> value.
</para>
</listitem>
</varlistentry>
@ -47,10 +52,20 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.void;
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="recursivecallbackfilteriterator.examples">RecursiveCallbackFilterIterator Examples</link></member>
<member><methodname>RecursiveCallbackFilterIterator::getChildren</methodname></member>
<member><methodname>RecursiveCallbackFilteriterator::hasChildren</methodname></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -14,11 +14,12 @@
<void />
</methodsynopsis>
<para>
Fetches the filtered children of the inner iterator.
</para>
<para>
<methodname>RecursiveCallbackFilterIterator::hasChildren</methodname> should be used
to determine if there are children to be fetched.
</para>
&warn.undocumented.func;
</refsect1>
<refsect1 role="parameters">
@ -29,7 +30,19 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a <classname>RecursiveCallbackFilterIterator</classname> containing
the children.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="recursivecallbackfilteriterator.examples">RecursiveCallbackFilterIterator Examples</link></member>
<member><methodname>RecursiveCallbackFilterIterator::__construct</methodname></member>
<member><methodname>RecursiveCallbackFilteriterator::hasChildren</methodname></member>
</simplelist>
</para>
</refsect1>

View file

@ -14,11 +14,8 @@
<void />
</methodsynopsis>
<para>
Returns &true; if the current element has children, &false; otherwise.
</para>
&warn.undocumented.func;
</refsect1>
<refsect1 role="parameters">
@ -29,10 +26,51 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; if the current element has children, &false; otherwise.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example xml:id="recursivecallbackfilteriterator.haschildren.examples.basic">
<title><methodname>RecursiveCallbackFilterIterator::hasChildren</methodname> basic usage</title>
<programlisting role="php">
<![CDATA[
<?php
$dir = new FilesystemIterator(__DIR__);
// Recursively iterate over XML files
$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
// Allow recursion into directories
if ($iterator->hasChildren()) {
return TRUE;
}
// Check for XML file
if (!strcasecmp($current->getExtension(), 'xml')) {
return TRUE;
}
return FALSE;
});
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="recursivecallbackfilteriterator.examples">RecursiveCallbackFilterIterator Examples</link></member>
<member><methodname>RecursiveCallbackFilterIterator::__construct</methodname></member>
<member><methodname>RecursiveCallbackFilteriterator::getChildren</methodname></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1020,6 +1020,16 @@
<function name='multipleiterator::key' from='PHP 5 &gt;= 5.3.0'/>
<function name='multipleiterator::current' from='PHP 5 &gt;= 5.3.0'/>
<function name='multipleiterator::next' from='PHP 5 &gt;= 5.3.0'/>
<function name='callbackfilteriterator' from='PHP 5 &gt;= 5.4.0'/>
<function name='callbackfilteriterator::__construct' from='PHP 5 &gt;= 5.4.0'/>
<function name='callbackfilteriterator::accept' from='PHP 5 &gt;= 5.4.0'/>
<function name='recursivecallbackfilteriterator' from='PHP 5 &gt;= 5.4.0'/>
<function name='recursivecallbackfilteriterator::__construct' from='PHP 5 &gt;= 5.4.0'/>
<function name='recursivecallbackfilteriterator::getchildren' from='PHP 5 &gt;= 5.4.0'/>
<function name='recursivecallbackfilteriterator::haschildren' from='PHP 5 &gt;= 5.4.0'/>
</versions>
<!-- Keep this comment at the end of the file