Update documentation

1 files changed, 16 insertions, 78 deletions

diff --git a/ext/spl/README b/ext/spl/README
index 60c6d97425..99f34af679 100755
--- a/ext/spl/README
+++ b/ext/spl/README
@@ -1,88 +1,26 @@
 This is an extension that aims to implement some efficient data access 
 interfaces and classes. You'll find the classes documented using php
-code in the file spl.php.
+code in the file spl.php or in the corresponding .inc file in the examples
+subdirectory. Based on the internal implementations or the files in the 
+examples subdirectory there are also some .php files to experiment with.
 
-There are special SPL interfaces that provides the ability to hook into 
-foreach and array reading/writng. By inheriting these interfaces, instances 
-of the resulting classes can be iterated using the foreach construct or
-use array read write notation.
-
-Look into the examples subdirectory for some basic examples which will
-demonstracte this.
-
-Also some classes of extensions like SQLite inherit SPL interfaces so that
-they take advantage of the foreach or array overloading.
+The .inc files are not included automatically because the are sooner or 
+later intergrated into the extension. That means that you either need to 
+put the code of examples/autoload into your autoprepend file or that you
+have to point your ini setting auto_prepend_file to this file.
 
 1) Iterators
 
-Iterator is design pattern that allows to enumerate and list all elements of 
-a collection whatsoever using an oo protocol. The minimalistic Iterator needs
-a method that returns the current value, a method that moves to the next value
-and a method that checks whether or not the Iterator can provide more elements.
-
-In SPL this basich Iterator is defined by the interface spl_forward:
-
-interface spl_forward {
-	function current();
-	function next();
-	function has_more();
-}
-
-This basic Iterator does not allow to rewind itself nor does it in anyway 
-support to name the values by some kind association as key/value mappings
-provided by the standard PHP arrays. All these additions to the basic Iterator
-are done in specialized interfaces as described in detail in the file spl.php.
-
-SPL allows to hook into the engine opcodes that realize the foreach construct.
-This construct normally works on arrays the following way. First it rewinds 
-the current array position to the beginning. Then it loops through the whole
-array by first checking whether or not the end of the array is reached and
-if not returning the current array value and or key. After that it move the
-current array pointer forward and does starts the loop process again. As you 
-can see this perfectly maps to the interface spl_forward. So the foreach
-hooking simply checks whether or not the variable passed to foreach is an
-object of a class implementing the interface spl_forward. The foreach hook
-can be activated by --enable-spl-foreach which is on by default.
-
-class it implements spl_forward...
-$obj = new it();
-foreach($obj as $value) ...
-
-2) Arrays
-
-Arrays in general, not specifically PHP arrays, provide a collection of pairs
-normally referred to as key and value. A PHP object consists of properties and
-a class type specifing the methods available for the object. SPL now allows
-this to be combined using the spl_array_<xy> interfaces.
-
-The minimalistic array interface is spl_array_read which only support reading:
-
-interface spl_array_read {
-	function exists($key);
-	function get($key);
-}
-
-Any instance of a class that implements spl_array_read can be used with array
-read notation when the corresponding hook is activated --enable-spl-array-read.
-
-class ar implements spl_array_read...
-$obj = new ar();
-$value = $obj[$key];
-
-SPL also supports the write notation by the interface spl_array_access:
+SPL offers some advanced iterator algorythmns:
 
-interface spl_array_access extends spl_array_read {
-	function set($value, $index);
-}
+interface RecursiveIterator implements Iterator
+class RecursiveIteratorIterator implements Iterator
+abstract class FilterIterator implements Iterator
+class ParentIterator extends FilterIterator implements RecursiveIterator
 
-When the array write hook is activated by --enable-spl-array-write the 
-following can be done:
+2) Directories
 
-class ar implements spl_array_access...
-$obj = new ar();
-$value = $obj[$key];
-$obj[$key] = $value;
+SPL offers two advanced directory classes.
 
-However this hook should only be activated when it is made use of, since it 
-slows down noticeable. That is the case because first there is some not used
-overhead and second the overhead is in one the most often used opcodes.
\ No newline at end of file
+class DirectoryIterator implements Iterator
+class RecursiveDirectoryIterator extends DirectoryIterator implements RecursiveIterator