diff --git a/reference/spl/callbackfilteriterator.xml b/reference/spl/callbackfilteriterator.xml index c2e714f51a..e05e738e27 100644 --- a/reference/spl/callbackfilteriterator.xml +++ b/reference/spl/callbackfilteriterator.xml @@ -12,7 +12,9 @@
&reftitle.intro; - + The CallbackFilterIterator is a concrete + FilterIterator which uses a callback + for filtering.
@@ -29,31 +31,32 @@ CallbackFilterIterator - - - extends - FilterIterator + + + extends + FilterIterator - - - Iterator - - - - Traversable - - - - OuterIterator + + + Iterator + + + + Traversable + + + + OuterIterator - - &Methods; + + &Methods; + - - &InheritedMethods; - + + &InheritedMethods; + diff --git a/reference/spl/callbackfilteriterator/accept.xml b/reference/spl/callbackfilteriterator/accept.xml index 9e5cfb863f..befadc4aa9 100644 --- a/reference/spl/callbackfilteriterator/accept.xml +++ b/reference/spl/callbackfilteriterator/accept.xml @@ -14,10 +14,13 @@ - + This method calls the callback with the current value, current key + and the inner iterator. + + + The callback is expected to return &true; if the current item is + to be accepted, or &false; otherwise. - - &warn.undocumented.func; @@ -29,10 +32,19 @@ &reftitle.returnvalues; - + Returns &true; to accept the current item, or &false; otherwise. + + &reftitle.seealso; + + + CallbackFilterIterator Examples + CallbackFilterIterator::__construct + + + diff --git a/reference/spl/callbackfilteriterator/construct.xml b/reference/spl/callbackfilteriterator/construct.xml index cc37f96055..217bdf5bec 100644 --- a/reference/spl/callbackfilteriterator/construct.xml +++ b/reference/spl/callbackfilteriterator/construct.xml @@ -4,22 +4,21 @@ CallbackFilterIterator::__construct - Create an Iterator from another iterator + Create a filtered iterator from another iterator &reftitle.description; - + + public CallbackFilterIterator::__construct Iteratoriterator - stringcallback - + callbackcallback + - + Creates a filtered iterator using the callback to + determine which items are accepted or rejected. - - &warn.undocumented.func; - @@ -29,7 +28,7 @@ iterator - + The iterator to be filtered. @@ -37,7 +36,12 @@ callback - + The callback, which should return &true; to accept the current item + or &false; otherwise. + See Examples. + + + May be any valid callback value. @@ -47,10 +51,19 @@ &reftitle.returnvalues; - + &return.void; + + &reftitle.seealso; + + + CallbackFilterIterator Examples + CallbackFilterIterator::accept + + + diff --git a/reference/spl/callbackfilteriterator/examples.xml b/reference/spl/callbackfilteriterator/examples.xml new file mode 100644 index 0000000000..a4abd79209 --- /dev/null +++ b/reference/spl/callbackfilteriterator/examples.xml @@ -0,0 +1,130 @@ + + + + CallbackFilterIterator & RecursiveCallbackFilterIterator Examples + + The main purpose of the CallbackFilterIterator and + RecursiveCallbackFilterIterator classes is to + filter the contents of an iterator using a callback rather than having + to go to the trouble of creating a bespoke class extending + the abstract FilterIterator. + + + + The callback should accept up to three arguments: + the current item, the current key and the iterator, respectively. + + + + Available callback arguments + + +]]> + + + + + Any callback may be used; such as a string containing a + function name, an array for a method, or an anonymous + function. + + + + Callback basic examples + + 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(); +}); + +?> +]]> + + + + + 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. + + + + Recursive callback basic examples + + 100MB) +$files = new CallbackFilterIterator($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; +} + +?> +]]> + + + + + + diff --git a/reference/spl/recursivecallbackfilteriterator.xml b/reference/spl/recursivecallbackfilteriterator.xml index dc66d1251f..6ab67cecb4 100644 --- a/reference/spl/recursivecallbackfilteriterator.xml +++ b/reference/spl/recursivecallbackfilteriterator.xml @@ -12,7 +12,9 @@
&reftitle.intro; - + The RecursiveCallbackFilterIterator is a concrete + RecursiveFilterIterator which uses a callback + for filtering.
@@ -29,35 +31,36 @@ RecursiveCallbackFilterIterator - - - extends - CallbackFilterIterator + + + extends + CallbackFilterIterator - - - OuterIterator - - - - Traversable - - - - Iterator - - - - RecursiveIterator + + + OuterIterator + + + + Traversable + + + + Iterator + + + + RecursiveIterator - - &Methods; + + &Methods; + - - &InheritedMethods; - + + &InheritedMethods; + diff --git a/reference/spl/recursivecallbackfilteriterator/construct.xml b/reference/spl/recursivecallbackfilteriterator/construct.xml index d9540eb5be..61feae5460 100644 --- a/reference/spl/recursivecallbackfilteriterator/construct.xml +++ b/reference/spl/recursivecallbackfilteriterator/construct.xml @@ -9,17 +9,17 @@ &reftitle.description; - + + public RecursiveCallbackFilterIterator::__construct RecursiveIteratoriterator stringcallback - + - + Creates a filtered iterator from a RecursiveIterator + using the callback to determine which + items are accepted or rejected. - - &warn.undocumented.func; - @@ -29,7 +29,7 @@ iterator - + The recursive iterator to be filtered. @@ -37,7 +37,12 @@ callback - + The callback, which should return &true; to accept the current item + or &false; otherwise. + See Examples. + + + May be any valid callback value. @@ -47,10 +52,20 @@ &reftitle.returnvalues; - + &return.void; + + &reftitle.seealso; + + + RecursiveCallbackFilterIterator Examples + RecursiveCallbackFilterIterator::getChildren + RecursiveCallbackFilteriterator::hasChildren + + + diff --git a/reference/spl/recursivecallbackfilteriterator/getchildren.xml b/reference/spl/recursivecallbackfilteriterator/getchildren.xml index de40a38739..645e4f7427 100644 --- a/reference/spl/recursivecallbackfilteriterator/getchildren.xml +++ b/reference/spl/recursivecallbackfilteriterator/getchildren.xml @@ -14,11 +14,12 @@ - + Fetches the filtered children of the inner iterator. + + + RecursiveCallbackFilterIterator::hasChildren should be used + to determine if there are children to be fetched. - - &warn.undocumented.func; - @@ -29,7 +30,19 @@ &reftitle.returnvalues; + Returns a RecursiveCallbackFilterIterator containing + the children. + + + + &reftitle.seealso; + + + RecursiveCallbackFilterIterator Examples + RecursiveCallbackFilterIterator::__construct + RecursiveCallbackFilteriterator::hasChildren + diff --git a/reference/spl/recursivecallbackfilteriterator/haschildren.xml b/reference/spl/recursivecallbackfilteriterator/haschildren.xml index 906fa3c8ea..a9b70cef99 100644 --- a/reference/spl/recursivecallbackfilteriterator/haschildren.xml +++ b/reference/spl/recursivecallbackfilteriterator/haschildren.xml @@ -14,11 +14,8 @@ - + Returns &true; if the current element has children, &false; otherwise. - - &warn.undocumented.func; - @@ -29,10 +26,51 @@ &reftitle.returnvalues; - + Returns &true; if the current element has children, &false; otherwise. + + &reftitle.examples; + + + <methodname>RecursiveCallbackFilterIterator::hasChildren</methodname> basic usage + +hasChildren()) { + return TRUE; + } + // Check for XML file + if (!strcasecmp($current->getExtension(), 'xml')) { + return TRUE; + } + return false; +}); + +?> +]]> + + + + + + + &reftitle.seealso; + + + RecursiveCallbackFilterIterator Examples + RecursiveCallbackFilterIterator::__construct + RecursiveCallbackFilteriterator::getChildren + + + diff --git a/reference/spl/versions.xml b/reference/spl/versions.xml index 71224d1bec..8c94c179be 100644 --- a/reference/spl/versions.xml +++ b/reference/spl/versions.xml @@ -1020,6 +1020,16 @@ + + + + + + + + + +