xref: /PHP-5.6/ext/spl/spl.php (revision 4dc99457)
1<?php
2
3/** @file spl.php
4 * @ingroup SPL
5 * @brief Documentation of internal classes and interfaces
6 *
7 * SPL - Standard PHP Library
8 *
9 * (c) Marcus Boerger, 2003 - 2008
10 */
11
12/** @mainpage SPL - Standard PHP Library
13 *
14 * SPL - Standard PHP Library
15 *
16 * SPL is a collection of interfaces and classes that are meant to solve
17 * standard problems and implements some efficient data access interfaces
18 * and classes. You'll find the classes documented using php code in the
19 * file spl.php or in corresponding .inc files in subdirectories examples
20 * and internal. Based on the internal implementations or the files in the
21 * examples subdirectory there are also some .php files to experiment with.
22 *
23 * The .inc files are not included automatically because they are sooner or
24 * later integrated into the extension. That means that you either need to
25 * put the code of examples/autoload.inc into your autoprepend file or that
26 * you have to point your ini setting auto_prepend_file to that file.
27 *
28 * Below is a list of interfaces/classes already availabel natively through
29 * the SPL extension grouped by category.
30 *
31 * 1) Iterators
32 *
33 * SPL offers some advanced iterator algorithms:
34 *
35 * - interface RecursiveIterator extends Iterator
36 * - interface OuterIterator extends Iterator
37 * - class RecursiveIteratorIterator implements OuterIterator
38 * - class RecursiveTreeIterator extends RecursiveIteratorIterator
39 * - abstract class FilterIterator implements OuterIterator
40 * - class ParentIterator extends FilterIterator implements RecursiveIterator
41 * - interface SeekableIterator extends Iterator
42 * - class LimitIterator implements OuterIterator
43 * - class CachingIterator implements OuterIterator
44 * - class RecursiveCachingIterator extends CachingIterator implements RecursiveIterator
45 * - class IteratorIterator implements OuterIterator
46 * - class NoRewindIterator implements OuterIterator
47 * - class EmptyIterator implements Iterator
48 * - class InfiniteIterator extends IteratorIterator
49 * - class AppendIterator implements OuterIterator
50 * - class RegexIterator extends FilterIterator
51 * - class RecursiveRegexIterator extends RegexIterator implements RecursiveIterator
52 * - class MultipleIterator extends Iterator
53 *
54 * 2) Directories and Files
55 *
56 * SPL offers two advanced directory and file handling classes:
57 *
58 * - class SplFileInfo
59 * - class DirectoryIterator extends SplFileInfo implements Iterator
60 * - class FilesystemIterator extends DirectoryIterator
61 * - class RecursiveDirectoryIterator extends FilesystemIterator implements RecursiveIterator
62 * - class GlobIterator extends FilesystemIterator implements Countable
63 * - class SplFileObject extends SplFileInfo implements RecursiveIterator, SeekableIterator
64 * - class SplTempFileObject extends SplFileObject
65 *
66 * 3) XML
67 *
68 * SPL offers an advanced XML handling class:
69 *
70 * - class SimpleXMLIterator extends simplexml_element implements RecursiveIterator
71 *
72 * 4) Array Overloading
73 *
74 * SPL offers advanced Array overloading:
75 *
76 * - class ArrayObject implements IteratorAggregate, ArrayAccess, Countable
77 * - class ArrayIterator implements Iterator, ArrayAccess, Countable, SeekableIterator
78 * - class RecursiveArrayIterator extends ArrayIterator implements RecursiveIterator
79 * - class SplFixedArray implements Iterator, ArrayAccess, Countable
80 *
81 * As the above suggest an ArrayObject creates an ArrayIterator when it comes to
82 * iteration (e.g. ArrayObject instance used inside foreach).
83 *
84 * 5) Counting
85 *
86 * - interface Countable allows to hook into the standard array function count().
87 *
88 * 6) Exception%s
89 *
90 * SPL provides a set of standard Exception classes each meant to indicate a
91 * certain problem type.
92 *
93 * - class LogicException           extends Exception
94 * - class BadFunctionCallException extends LogicException
95 * - class BadMethodCallException   extends BadFunctionCallException
96 * - class DomainException          extends LogicException
97 * - class InvalidArgumentException extends LogicException
98 * - class LengthException          extends LogicException
99 * - class OutOfRangeException      extends LogicException
100 * - class RuntimeException         extends Exception
101 * - class OutOfBoundsException     extends RuntimeException
102 * - class OverflowException        extends RuntimeException
103 * - class RangeException           extends RuntimeException
104 * - class UnderflowException       extends RuntimeException
105 *
106 * 7) Observer
107 *
108 * SPL suggests a standard way of implementing the observer pattern.
109 *
110 * - interface SplObserver
111 * - interface SplSubject
112 * - class SplObjectStorage
113 *
114 * 8) Datastructures
115 *
116 * SPL proposes a set of datastructures implemented internally.
117 *
118 * - class SplDoublyLinkedList
119 * - class SplStack                 extends SplDoublyLinkedList
120 * - class SplQueue                 extends SplDoublyLinkedList
121 *
122 * 9) @ref Examples
123 *
124 * The classes and interfaces in this group are contained as PHP code in the
125 * examples subdirectory of ext/SPL. Sooner or later they will be moved to
126 * c-code.
127 *
128 * 10) Some articles about SPL:
129 * - <a href="http://www.phpro.org/tutorials/Introduction-to-SPL.html">Introduction to Standard PHP Library (SPL)</a>
130 * - <a href="http://www.sitepoint.com/article/php5-standard-library/1">Introducing PHP 5's Standard Library</a>
131 * - <a href="http://www.ramikayyali.com/archives/2005/02/25/iterators">Iterators in PHP5</a>
132 * - <a href="http://www.phpriot.com/d/articles/php/oop/oop-with-spl-php-5-1/index.html">Advanced OOP with SPL in PHP 5</a>
133 * - <a href="http://www.devshed.com/c/a/PHP/The-Standard-PHP-Library-Part-1/">The Standard PHP Library, Part 1</a>
134 * - <a href="http://www.devshed.com/c/a/PHP/The-Standard-PHP-Library-Part-2/">The Standard PHP Library, Part 2</a>
135 * - <a href="http://www.professionelle-softwareentwicklung-mit-php5.de/erste_auflage/oop.iterators.spl.html">Die Standard PHP Library (SPL) [german]</a>
136 *
137 * 11) Talks on SPL:
138 * - SPL Update <a href="http://talks.somabo.de/200702_vancouver_spl_update.pps">[pps]</a>, <a href="http://talks.somabo.de/200702_vancouver_spl_update.pdf">[pdf]</a>
139 * - Happy SPLing <a href="http://talks.somabo.de/200509_toronto_happy_spling.pps">[pps]</a>, <a href="http://talks.somabo.de/200509_toronto_happy_spling.pdf">[pdf]</a>
140 * - From engine overloading to SPL <a href="http://talks.somabo.de/200505_cancun_from_engine_overloading_to_spl.pps">[pps]</a>, <a href="http://talks.somabo.de/200505_cancun_from_engine_overloading_to_spl.pdf">[pdf]</a>
141 * - SPL for the masses <a href="http://talks.somabo.de/200504_php_quebec_spl_for_the_masses.pps">[pps]</a>, <a href="http://talks.somabo.de/200504_php_quebec_spl_for_the_masses.pdf">[pdf]</a>
142 *
143 * 12) Debug sessions:
144 * - Debug session 1 <a href="200407_oscon_introduction_to_iterators_debug.pps">[pps]</a>, <a href="200407_oscon_introduction_to_iterators_debug.pdf">[pdf]</a>
145 * - Debug session 2 <a href="http://talks.somabo.de/200509_toronto_iterator_debug_session_1.pps">[pps]</a>, <a href="http://talks.somabo.de/200509_toronto_iterator_debug_session_1.pdf">[pdf]</a>, <a href="http://taks.somabo.de/200411_php_conference_frankfrurt_iterator_debug_session.swf">[swf]</a>
146 * - Debug session 3 <a href="http://talks.somabo.de/200509_toronto_iterator_debug_session_2.pps">[pps]</a>, <a href="http://talks.somabo.de/200509_toronto_iterator_debug_session_2.pdf">[pdf]</a>
147 *
148 * (c) Marcus Boerger, 2003 - 2007
149 */
150
151/** @defgroup ZendEngine Zend engine classes
152 *
153 * The classes and interfaces in this group are contained in the c-code of
154 * PHP's Zend engine.
155 */
156
157/** @defgroup SPL Internal classes
158 *
159 * The classes and interfaces in this group are contained in the c-code of
160 * ext/SPL.
161 */
162
163/** @defgroup Examples Example classes
164 *
165 * The classes and interfaces in this group are contained as PHP code in the
166 * examples subdirectory of ext/SPL. Sooner or later they will be moved to
167 * c-code.
168 */
169
170/** @ingroup SPL
171 * @brief Default implementation for __autoload()
172 * @since PHP 5.1
173 *
174 * @param class_name        name of class to load
175 * @param file_extensions   file extensions (use defaults if NULL)
176 */
177function spl_autoload(string $class_name, string $file_extensions = NULL) {/**/};
178
179/** @ingroup SPL
180 * @brief Manual invocation of all registerd autoload functions
181 * @since PHP 5.1
182 *
183 * @param class_name        name of class to load
184 */
185function spl_autoload_call(string $class_name) {/**/};
186
187/** @ingroup SPL
188 * @brief Register and return default file extensions for spl_autoload
189 * @since PHP 5.1
190 *
191 * @param file_extensions optional comma separated list of extensions to use in
192 *        default autoload function. If not given just return the current list.
193 * @return comma separated list of file extensions to use in default autoload
194 *        function.
195 */
196function spl_autoload_extensions($file_extensions) {/**/};
197
198/** @ingroup SPL
199 * @brief Return all registered autoload functionns
200 * @since PHP 5.1
201 *
202 * @return array of all registered autoload functions or false
203 */
204function spl_autoload_functions() {/**/};
205
206/** @ingroup SPL
207 * @brief Register given function as autoload implementation
208 * @since PHP 5.1
209 *
210 * @param autoload_function  name of function or array of object/class and
211 *                           function name to register as autoload function.
212 * @param throw              whether to throw or issue an error on failure.
213 */
214function spl_autoload_register(string $autoload_function = "spl_autoload", $throw = true) {/**/};
215
216/** @ingroup SPL
217 * @brief Unregister given function as autoload implementation
218 * @since PHP 5.1
219 *
220 * @param autoload_function  name of function or array of object/class and
221 *                           function name to unregister as autoload function.
222 */
223function spl_autoload_unregister(string $autoload_function = "spl_autoload") {/**/};
224
225/** @ingroup SPL
226 * @brief Return an array of classes and interfaces in SPL
227 *
228 * @return array containing the names of all clsses and interfaces defined in
229 *         extension SPL
230 */
231function spl_classes() {/**/};
232
233/** @ingroup SPL
234 * @brief Count the elements in an iterator
235 * @since PHP 5.1
236 *
237 * @return number of elements in an iterator
238 */
239function iterator_count(Traversable $it) {/**/};
240
241/** @ingroup SPL
242 * @brief Copy iterator elements into an array
243 * @since PHP 5.1
244 *
245 * @param it  iterator to copy
246 * @param use_keys whether touse the keys
247 * @return array with elements copied from the iterator
248 */
249function iterator_to_array(Traversable $it, $use_keys = true) {/**/};
250
251/** @ingroup ZendEngine
252 * @brief Basic Exception class.
253 * @since PHP 5.0
254 */
255class Exception
256{
257	/** The exception message */
258	protected $message;
259
260	/** The string representations as generated during construction */
261	private $string;
262
263	/** The code passed to the constructor */
264	protected $code;
265
266	/** The file name where the exception was instantiated */
267	protected $file;
268
269	/** The line number where the exception was instantiated */
270	protected $line;
271
272	/** The stack trace */
273	private $trace;
274
275	/** Prevent clone
276	 */
277	final private function __clone() {}
278
279	/** Construct an exception
280	 *
281	 * @param $message Some text describing the exception
282	 * @param $code    Some code describing the exception
283	 */
284	function __construct($message = NULL, $code = 0) {
285		if (func_num_args()) {
286			$this->message = $message;
287		}
288		$this->code = $code;
289		$this->file = __FILE__; // of throw clause
290		$this->line = __LINE__; // of throw clause
291		$this->trace = debug_backtrace();
292		$this->string = StringFormat($this);
293	}
294
295	/** @return the message passed to the constructor
296	 */
297	final public function getMessage()
298	{
299		return $this->message;
300	}
301
302	/** @return the code passed to the constructor
303	 */
304	final public function getCode()
305	{
306		return $this->code;
307	}
308
309	/** @return the name of the file where the exception was thrown
310	 */
311	final public function getFile()
312	{
313		return $this->file;
314	}
315
316	/** @return the line number where the exception was thrown
317	 */
318	final public function getLine()
319	{
320		return $this->line;
321	}
322
323	/** @return the stack trace as array
324	 */
325	final public function getTrace()
326	{
327		return $this->trace;
328	}
329
330	/** @return the stack trace as string
331	 */
332	final public function getTraceAsString()
333	{
334	}
335
336	/** @return string representation of exception
337	 */
338	public function __toString()
339	{
340		return $this->string;
341	}
342}
343
344/** @ingroup SPL
345 * @brief Exception that represents error in the program logic.
346 * @since PHP 5.1
347 *
348 * This kind of exceptions should directly leed to a fix in your code.
349 */
350class LogicException extends Exception
351{
352}
353
354/** @ingroup SPL
355 * @brief Exception thrown when a function call was illegal.
356 * @since PHP 5.1
357 */
358class BadFunctionCallException extends LogicException
359{
360}
361
362/** @ingroup SPL
363 * @brief Exception thrown when a method call was illegal.
364 * @since PHP 5.1
365 */
366class BadMethodCallException extends BadFunctionCallException
367{
368}
369
370/** @ingroup SPL
371 * @brief Exception that denotes a value not in the valid domain was used.
372 * @since PHP 5.1
373 *
374 * This kind of exception should be used to inform about domain erors in
375 * mathematical sense.
376 *
377 * @see RangeException
378 */
379class DomainException extends LogicException
380{
381}
382
383/** @ingroup SPL
384 * @brief Exception that denotes invalid arguments were passed.
385 * @since PHP 5.1
386 *
387 * @see UnexpectedValueException
388 */
389class InvalidArgumentException extends LogicException
390{
391}
392
393/** @ingroup SPL
394 * @brief Exception thrown when a parameter exceeds the allowed length.
395 * @since PHP 5.1
396 *
397 * This can be used for strings length, array size, file size, number of
398 * elements read from an Iterator and so on.
399 */
400class LengthException extends LogicException
401{
402}
403
404/** @ingroup SPL
405 * @brief Exception thrown when an illegal index was requested.
406 * @since PHP 5.1
407 *
408 * This represents errors that should be detected at compile time.
409 *
410 * @see OutOfBoundsException
411 */
412class OutOfRangeException extends LogicException
413{
414}
415
416/** @ingroup SPL
417 * @brief Exception thrown for errors that are only detectable at runtime.
418 * @since PHP 5.1
419 */
420class RuntimeException extends Exception
421{
422}
423
424/** @ingroup SPL
425 * @brief Exception thrown when an illegal index was requested.
426 * @since PHP 5.1
427 *
428 * This represents errors that cannot be detected at compile time.
429 *
430 * @see OutOfRangeException
431 */
432class OutOfBoundsException extends RuntimeException
433{
434}
435
436/** @ingroup SPL
437 * @brief Exception thrown to indicate arithmetic/buffer overflow.
438 * @since PHP 5.1
439 */
440class OverflowException extends RuntimeException
441{
442}
443
444/** @ingroup SPL
445 * @brief Exception thrown to indicate range errors during program execution.
446 * @since PHP 5.1
447 *
448 * Normally this means there was an arithmetic error other than under/overflow.
449 * This is the runtime version of DomainException.
450 *
451 * @see DomainException
452 */
453class RangeException extends RuntimeException
454{
455}
456
457/** @ingroup SPL
458 * @brief Exception thrown to indicate arithmetic/buffer underflow.
459 * @since PHP 5.1
460 */
461class UnderflowException extends RuntimeException
462{
463}
464
465/** @ingroup SPL
466 * @brief Exception thrown to indicate an unexpected value.
467 * @since PHP 5.1
468 *
469 * Typically this happens when a function calls another function and espects
470 * the return value to be of a certain type or value not including arithmetic
471 * or buffer related errors.
472 *
473 * @see InvalidArgumentException
474 */
475class UnexpectedValueException extends RuntimeException
476{
477}
478
479/** @ingroup ZendEngine
480 * @brief Interface to override array access of objects.
481 * @since PHP 5.0
482 */
483interface ArrayAccess
484{
485	/** @param $offset to modify
486	 * @param $value new value
487	 */
488	function offsetSet($offset, $value);
489
490	/** @param $offset to retrieve
491	 * @return value at given offset
492	 */
493	function offsetGet($offset);
494
495	/** @param $offset to delete
496	 */
497	function offsetUnset($offset);
498
499	/** @param $offset to check
500	 * @return whether the offset exists.
501	 */
502	function offsetExists($offset);
503}
504
505/** @ingroup ZendEngine
506 * @brief Interface to detect a class is traversable using foreach.
507 * @since PHP 5.0
508 *
509 * Abstract base interface that cannot be implemented alone. Instead it
510 * must be implemented by either IteratorAggregate or Iterator.
511 *
512 * @note Internal classes that implement this interface can be used in a
513 * foreach construct and do not need to implement IteratorAggregate or
514 * Iterator.
515 *
516 * @note This is an engine internal interface which cannot be implemented
517 * in PHP scripts. Either IteratorAggregate or Iterator must be used
518 * instead.
519 */
520interface Traversable
521{
522}
523
524/** @ingroup ZendEngine
525 * @brief Interface to create an external Iterator.
526 * @since PHP 5.0
527 *
528 * @note This is an engine internal interface.
529 */
530interface IteratorAggregate extends Traversable
531{
532	/** @return an Iterator for the implementing object.
533	 */
534	function getIterator();
535}
536
537/** @ingroup ZendEngine
538 * @brief Basic iterator
539 * @since PHP 5.0
540 *
541 * Interface for external iterators or objects that can be iterated
542 * themselves internally.
543 *
544 * @note This is an engine internal interface.
545 */
546interface Iterator extends Traversable
547{
548	/** Rewind the Iterator to the first element.
549	 */
550	function rewind();
551
552	/** Return the current element.
553	 */
554	function current();
555
556	/** Return the key of the current element.
557	 */
558	function key();
559
560	/** Move forward to next element.
561	 */
562	function next();
563
564	/** Check if there is a current element after calls to rewind() or next().
565	 */
566	function valid();
567}
568
569/** @ingroup SPL
570 * @brief This Interface allows to hook into the global count() function.
571 * @since PHP 5.1
572 */
573interface Countable
574{
575	/** @return the number the global function count() should show
576	 */
577	function count();
578}
579
580/** @ingroup ZendEngine
581 * @brief Interface for customized serializing
582 * @since 5.1
583 *
584 * Classes that implement this interface no longer support __sleep() and
585 * __wakeup(). The method serialized is called whenever an instance needs to
586 * be serialized. This does not invoke __destruct() or has any other side
587 * effect unless programmed inside the method. When the data is unserialized
588 * the class is known and the appropriate unserialize() method is called as a
589 * constructor instead of calling __construct(). If you need to execute the
590 * standard constructor you may do so in the method.
591 */
592interface Serializable
593{
594	/**
595	 * @return string representation of the instance
596	 */
597	function serialize();
598
599	/**
600	 * @note This is a constructor
601	 *
602	 * @param $serialized data read from stream to construct the instance
603	 */
604	function unserialize($serialized);
605}
606
607/** @ingroup SPL
608 * @brief An Array wrapper
609 * @since PHP 5.0
610 * @version 1.2
611 *
612 * This array wrapper allows to recursively iterate over Arrays and public
613 * Object properties.
614 *
615 * @see ArrayIterator
616 */
617class ArrayObject implements IteratorAggregate, ArrayAccess, Countable
618{
619	/** Properties of the object have their normal functionality
620	 * when accessed as list (var_dump, foreach, etc.) */
621	const STD_PROP_LIST     = 0x00000001;
622	/** Array indices can be accessed as properties in read/write */
623	const ARRAY_AS_PROPS    = 0x00000002;
624
625	/** Construct a new array iterator from anything that has a hash table.
626	 * That is any Array or Object.
627	 *
628	 * @param $array the array to use.
629	 * @param $flags see setFlags().
630	 * @param $iterator_class class used in getIterator()
631	 */
632	function __construct($array, $flags = 0, $iterator_class = "ArrayIterator") {/**/}
633
634	/** Set behavior flags.
635	 *
636	 * @param $flags bitmask as follows:
637	 *        0 set: properties of the object have their normal functionality
638	 *               when accessed as list (var_dump, foreach, etc.)
639	 *        1 set: array indices can be accessed as properties in read/write
640	 */
641	function setFlags($flags) {/**/}
642
643	/** @return current flags
644	 */
645	function getFlags() {/**/}
646
647	/** Sort the entries by values.
648	 */
649	function asort() {/**/}
650
651	/** Sort the entries by key.
652	 */
653	function ksort() {/**/}
654
655	/** Sort the entries by values using user defined function.
656	 */
657	function uasort(mixed cmp_function) {/**/}
658
659	/** Sort the entries by key using user defined function.
660	 */
661	function uksort(mixed cmp_function) {/**/}
662
663	/** Sort the entries by values using "natural order" algorithm.
664	 */
665	function natsort() {/**/}
666
667	/** Sort the entries by values using case insensitive "natural order" algorithm.
668	 */
669	function natcasesort() {/**/}
670
671	/** @param $array new array or object
672	 */
673	function exchangeArray($array) {/**/}
674
675	/** @return the iterator which is an ArrayIterator object connected to
676	 * this object.
677	 */
678	function getIterator() {/**/}
679
680	/** @param $index offset to inspect
681	 * @return whetehr offset $index esists
682	 */
683	function offsetExists($index) {/**/}
684
685	/** @param $index offset to return value for
686	 * @return value at offset $index
687	 */
688	function offsetGet($index) {/**/}
689
690	/** @param $index index to set
691	 * @param $newval new value to store at offset $index
692	 */
693	function offsetSet($index, $newval) {/**/}
694
695	/** @param $index offset to unset
696	 */
697	function offsetUnset($index) {/**/}
698
699	/** @param $value is appended as last element
700	 * @warning this method cannot be called when the ArrayObject refers to
701	 *          an object.
702	 */
703	function append($value) {/**/}
704
705	/** @return a \b copy of the array
706	 * @note when the ArrayObject refers to an object then this method
707	 *       returns an array of the public properties.
708	 */
709	function getArrayCopy() {/**/}
710
711	/** @return the number of elements in the array or the number of public
712	 * properties in the object.
713	 */
714	function count() {/**/}
715
716	/* @param $iterator_class new class used in getIterator()
717	 */
718	function setIteratorClass($itertor_class) {/**/}
719
720	/* @return class used in getIterator()
721	 */
722	function getIteratorClass() {/**/}
723}
724
725/** @ingroup SPL
726 * @brief An Array iterator
727 * @since PHP 5.0
728 * @version 1.2
729 *
730 * This iterator allows to unset and modify values and keys while iterating
731 * over Arrays and Objects.
732 *
733 * When you want to iterate over the same array multiple times you need to
734 * instanciate ArrayObject and let it create ArrayIterator instances that
735 * refer to it either by using foreach or by calling its getIterator()
736 * method manually.
737 */
738class ArrayIterator implements SeekableIterator, ArrayAccess, Countable
739{
740	/** Properties of the object have their normal functionality
741	 * when accessed as list (var_dump, foreach, etc.) */
742	const STD_PROP_LIST  = 0x00000001;
743	/** Array indices can be accessed as properties in read/write */
744	const ARRAY_AS_PROPS = 0x00000002;
745
746	/** Construct a new array iterator from anything that has a hash table.
747	 * That is any Array or Object.
748	 *
749	 * @param $array the array to use.
750	 * @param $flags see setFlags().
751	 */
752	function __construct($array, $flags = 0) {/**/}
753
754	/** Set behavior flags.
755	 *
756	 * @param $flags bitmask as follows:
757	 *        0 set: properties of the object have their normal functionality
758	 *               when accessed as list (var_dump, foreach, etc.)
759	 *        1 set: array indices can be accessed as properties in read/write
760	 */
761	function setFlags($flags) {/**/}
762
763	/**
764	 * @return current flags
765	 */
766	function getFlags() {/**/}
767
768	/** Sort the entries by values.
769	 */
770	function asort() {/**/}
771
772	/** Sort the entries by key.
773	 */
774	function ksort() {/**/}
775
776	/** Sort the entries by values using user defined function.
777	 */
778	function uasort(mixed cmp_function) {/**/}
779
780	/** Sort the entries by key using user defined function.
781	 */
782	function uksort(mixed cmp_function) {/**/}
783
784	/** Sort the entries by values using "natural order" algorithm.
785	 */
786	function natsort() {/**/}
787
788	/** Sort the entries by values using case insensitive "natural order" algorithm.
789	 */
790	function natcasesort() {/**/}
791
792	/** @param $index offset to inspect
793	 * @return whetehr offset $index esists
794	 */
795	function offsetExists($index) {/**/}
796
797	/** @param $index offset to return value for
798	 * @return value at offset $index
799	 */
800	function offsetGet($index) {/**/}
801
802	/** @param $index index to set
803	 * @param $newval new value to store at offset $index
804	 */
805	function offsetSet($index, $newval) {/**/}
806
807	/** @param $index offset to unset
808	 */
809	function offsetUnset($index) {/**/}
810
811	/** @param $value is appended as last element
812	 * @warning this method cannot be called when the ArrayIterator refers to
813	 *          an object.
814	 */
815	function append($value) {/**/}
816
817	/** @return a \b copy of the array
818	 * @note when the ArrayIterator refers to an object then this method
819	 *       returns an array of the public properties.
820	 */
821	function getArrayCopy() {/**/}
822
823	/** @param $position offset to seek to
824	 * @throw OutOfBoundsException if $position is invalid
825	 */
826	function seek($position) {/**/}
827
828	/** @return the number of elements in the array or the number of public
829	 * properties in the object.
830	 */
831	function count() {/**/}
832
833	/** @copydoc Iterator::rewind */
834	function rewind() {/**/}
835
836	/** @copydoc Iterator::valid */
837	function valid() {/**/}
838
839	/** @copydoc Iterator::current */
840	function current() {/**/}
841
842	/** @copydoc Iterator::key */
843	function key() {/**/}
844
845	/** @copydoc Iterator::next */
846	function next() {/**/}
847}
848
849/** @ingroup SPL
850 * @brief File info class
851 * @since PHP 5.1.3
852 */
853class SplFileInfo
854{
855	/** Construct a file info object
856	 *
857	 * @param $file_name path or file name
858	 */
859	function __construct($file_name) {/**/}
860
861	/** @return the path part only.
862	 */
863	function getPath() {/**/}
864
865	/** @return the filename only.
866	 */
867	function getFilename() {/**/}
868
869	/** @return SplFileInfo created for the file
870	 * @param class_name name of class to instantiate
871	 * @see SplFileInfo::setInfoClass()
872	 */
873	function getFileInfo(string class_name = NULL) {/**/}
874
875	/** @return The current entries path and file name.
876	 */
877	function getPathname() {/**/}
878
879	/** @return SplFileInfo created for the path
880	 * @param class_name name of class to instantiate
881	 * @see SplFileInfo::setInfoClass()
882	 */
883	function getPathInfo(string class_name = NULL) {/**/}
884
885	/** @return The current entry's permissions.
886	 */
887	function getPerms() {/**/}
888
889	/** @return The current entry's inode.
890	 */
891	function getInode() {/**/}
892
893	/** @return The current entry's size in bytes .
894	 */
895	function getSize() {/**/}
896
897	/** @return The current entry's owner name.
898	 */
899	function getOwner() {/**/}
900
901	/** @return The current entry's group name.
902	 */
903	function getGroup() {/**/}
904
905	/** @return The current entry's last access time.
906	 */
907	function getATime() {/**/}
908
909	/** @return The current entry's last modification time.
910	 */
911	function getMTime() {/**/}
912
913	/** @return The current entry's last change time.
914	 */
915	function getCTime() {/**/}
916
917	/** @return The current entry's file type.
918	 */
919	function getType() {/**/}
920
921	/** @return Whether the current entry is writeable.
922	 */
923	function isWritable() {/**/}
924
925	/** @return Whether the current entry is readable.
926	 */
927	function isReadable() {/**/}
928
929	/** @return Whether the current entry is executable.
930	 */
931	function isExecutable() {/**/}
932
933	/** @return Whether the current entry is .
934	 */
935	function isFile() {/**/}
936
937	/** @return Whether the current entry is a directory.
938	 */
939	function isDir() {/**/}
940
941	/** @return whether the current entry is a link.
942	 */
943	function isLink() {/**/}
944
945	/** @return target of link.
946	 */
947	function getLinkTarget() {/**/}
948
949	/** @return The resolved path
950	 */
951	function getRealPath() {/**/}
952
953	/** @return getPathname()
954	 */
955	function __toString() {/**/}
956
957	/** Open the current file as a SplFileObject instance
958	 *
959	 * @param mode              open mode
960	 * @param use_include_path  whether to search include paths (don't use)
961	 * @param context           resource context to passed to open function
962	 * @throw RuntimeException  if file cannot be opened (e.g. insufficient
963	 *                          access rights).
964	 * @return The opened file as a SplFileObject instance
965	 *
966	 * @see SplFileObject
967	 * @see SplFileInfo::setFileClass()
968	 * @see file()
969	 */
970	function openFile($mode = 'r', $use_include_path = false, $context = NULL) {/**/}
971
972	/** @param class_name name of class used with openFile(). Must be derived
973	 * from SPLFileObject.
974	 */
975	function setFileClass(string class_name = "SplFileObject") {/**/}
976
977	/** @param class_name name of class used with getFileInfo(), getPathInfo().
978	 *                     Must be derived from SplFileInfo.
979	 */
980	function setInfoClass(string class_name = "SplFileInfo") {/**/}
981}
982
983/** @ingroup SPL
984 * @brief Directory iterator
985 * @version 1.1
986 * @since PHP 5.0
987 */
988class DirectoryIterator extends SplFileInfo implements Iterator
989{
990	/** Construct a directory iterator from a path-string.
991	 *
992	 * @param $path directory to iterate.
993	 */
994	function __construct($path) {/**/}
995
996	/** @copydoc Iterator::rewind */
997	function rewind() {/**/}
998
999	/** @copydoc Iterator::valid */
1000	function valid() {/**/}
1001
1002	/** @return index of entry
1003	 */
1004	function key() {/**/}
1005
1006	/** @return $this
1007	 */
1008	function current() {/**/}
1009
1010	/** @copydoc Iterator::next */
1011	function next() {/**/}
1012
1013	/** @return Whether the current entry is either '.' or '..'.
1014	 */
1015	function isDot() {/**/}
1016
1017	/** @return whether the current entry is a link.
1018	 */
1019	function isLink() {/**/}
1020
1021	/** @return getFilename()
1022	 */
1023	function __toString() {/**/}
1024}
1025
1026/** @ingroup SPL
1027 * @brief recursive directory iterator
1028 * @version 1.1
1029 * @since PHP 5.0
1030 */
1031class RecursiveDirectoryIterator extends DirectoryIterator implements RecursiveIterator
1032{
1033	const CURRENT_AS_FILEINFO   0x00000000; /* make RecursiveDirectoryTree::current() return SplFileInfo */
1034	const CURRENT_AS_SELF       0x00000010; /* make RecursiveDirectoryTree::current() return getSelf() */
1035	const CURRENT_AS_PATHNAME   0x00000020; /* make RecursiveDirectoryTree::current() return getPathname() */
1036
1037	const KEY_AS_PATHNAME       0x00000000; /* make RecursiveDirectoryTree::key() return getPathname() */
1038	const KEY_AS_FILENAME       0x00000100; /* make RecursiveDirectoryTree::key() return getFilename() */
1039
1040	const NEW_CURRENT_AND_KEY   0x00000100; /* CURRENT_AS_FILEINFO + KEY_AS_FILENAME */
1041
1042	/** Construct a directory iterator from a path-string.
1043	 *
1044	 * @param $path   directory to iterate.
1045	 * @param $flags  open flags
1046	 * - CURRENT_AS_FILEINFO
1047	 * - CURRENT_AS_SELF
1048	 * - CURRENT_AS_PATHNAME
1049	 * - KEY_AS_PATHNAME
1050	 * - KEY_AS_FILENAME
1051	 * - NEW_CURRENT_AND_KEY
1052	 */
1053	function __construct($path, $flags = 0) {/**/}
1054
1055	/** @return getPathname() or getFilename() depending on flags
1056	 */
1057	function key() {/**/}
1058
1059	/** @return getFilename() or getFileInfo() depending on flags
1060	 */
1061	function current() {/**/}
1062
1063	/** @return whether the current is a directory (not '.' or '..').
1064	 */
1065	function hasChildren() {/**/}
1066
1067	/** @return a RecursiveDirectoryIterator for the current entry.
1068	 */
1069	function getChildren() {/**/}
1070
1071	/** @return sub path only (without main path)
1072	 */
1073	function getSubPath() {/**/}
1074
1075	/** @return the current sub path
1076	 */
1077	function getSubPathname() {/**/}
1078}
1079
1080/** @ingroup SPL
1081 * @brief recursive SimpleXML_Element iterator
1082 * @since PHP 5.0
1083 *
1084 * The SimpleXMLIterator implements the RecursiveIterator interface. This
1085 * allows iteration over all elements using foreach or an appropriate while
1086 * construct, just like SimpleXMLElement does. When using the foreach construct,
1087 * you will also iterate over the subelements. For every element which
1088 * has subelements, hasChildren() returns true.  This will trigger a call to
1089 * getChildren() which returns the iterator for that sub element.
1090 */
1091class SimpleXMLIterator extends SimpleXMLElement implements RecursiveIterator, Countable
1092{
1093	/** @return whether the current node has sub nodes.
1094	 */
1095	function hasChildren() {/**/}
1096
1097	/** @return a SimpleXMLIterator for the current node.
1098	 */
1099	function getChildren() {/**/}
1100
1101	/** @return number of elements/attributes seen with foreach()
1102	 */
1103	function count() {/**/}
1104
1105	/** @copydoc Iterator::rewind */
1106	function rewind() {/**/}
1107
1108	/** @copydoc Iterator::valid */
1109	function valid() {/**/}
1110
1111	/** @copydoc Iterator::current */
1112	function current() {/**/}
1113
1114	/** @copydoc Iterator::key */
1115	function key() {/**/}
1116
1117	/** @copydoc Iterator::next */
1118	function next() {/**/}
1119}
1120
1121/** @ingroup SPL
1122 * @brief Observer of the observer pattern
1123 * @since PHP 5.1
1124 *
1125 * For a detailed explanation see Observer pattern in
1126 * <em>
1127 * Gamma, Helm, Johnson, Vlissides<br />
1128 * Design Patterns
1129 * </em>
1130 */
1131interface SplObserver
1132{
1133	/** Called from the subject (i.e. when it's value has changed).
1134	 * @param $subject the callee
1135	 */
1136	function update(SplSubject $subject);
1137}
1138
1139/** @ingroup SPL
1140 * @brief Subject to the observer pattern
1141 * @since PHP 5.1
1142 * @see Observer
1143 */
1144interface SplSubject
1145{
1146	/** @param $observer new observer to attach
1147	 */
1148	function attach(SplObserver $observer);
1149
1150	/** @param $observer existing observer to detach
1151	 * @note a non attached observer shouldn't result in a warning or similar
1152	 */
1153	function detach(SplObserver $observer);
1154
1155	/** Notify all observers
1156	 */
1157	function notify();
1158}
1159
1160?>
1161