helly Mon Nov 1 12:05:45 2004 EDT Modified files: /php-src/ext/spl spl.php Log: - Update docu
http://cvs.php.net/diff.php/php-src/ext/spl/spl.php?r1=1.35&r2=1.36&ty=u Index: php-src/ext/spl/spl.php diff -u php-src/ext/spl/spl.php:1.35 php-src/ext/spl/spl.php:1.36 --- php-src/ext/spl/spl.php:1.35 Mon Nov 1 11:31:19 2004 +++ php-src/ext/spl/spl.php Mon Nov 1 12:05:45 2004 @@ -1,15 +1,15 @@ <?php -/** \file spl.php - * \ingroup SPL - * \brief Documentation of internal classes and interfaces +/** @file spl.php + * @ingroup SPL + * @brief Documentation of internal classes and interfaces * * SPL - Standard PHP Library * * (c) Marcus Boerger, 2003 - 2004 */ -/** \mainpage SPL - Standard PHP Library +/** @mainpage SPL - Standard PHP Library * * SPL - Standard PHP Library * @@ -224,42 +224,42 @@ { } -/** \ingroup ZendEngine - * \brief Interface to override array access of objects. +/** @ingroup ZendEngine + * @brief Interface to override array access of objects. */ interface ArrayAccess { - /** \param $offset to modify - * \param $value new value + /** @param $offset to modify + * @param $value new value */ function offsetSet($offset, $value); - /** \param $offset to retrieve - * \return value at given offset + /** @param $offset to retrieve + * @return value at given offset */ function offsetGet($offset); - /** \param $offset to delete + /** @param $offset to delete */ function offsetUnset($offset); - /** \param $offset to check - *\return whether the offset exists. + /** @param $offset to check + * @return whether the offset exists. */ function offsetExists($offset); } -/** \ingroup ZendEngine - * \brief Interface to detect a class is traversable using foreach. +/** @ingroup ZendEngine + * @brief Interface to detect a class is traversable using foreach. * * Abstract base interface that cannot be implemented alone. Instead it * must be implemented by either IteratorAggregate or Iterator. * - * \note Internal classes that implement this interface can be used in a + * @note Internal classes that implement this interface can be used in a * foreach construct and do not need to implement IteratorAggregate or * Iterator. * - * \note This is an engine internal interface which cannot be implemented + * @note This is an engine internal interface which cannot be implemented * in PHP scripts. Either IteratorAggregate or Iterator must be used * instead. */ @@ -267,25 +267,25 @@ { } -/** \ingroup ZendEngine - * \brief Interface to create an external Iterator. +/** @ingroup ZendEngine + * @brief Interface to create an external Iterator. * - * \note This is an engine internal interface. + * @note This is an engine internal interface. */ interface IteratorAggregate extends Traversable { - /** \return an Iterator for the implementing object. + /** @return an Iterator for the implementing object. */ function getIterator(); } -/** \ingroup ZendEngine - * \brief Basic iterator +/** @ingroup ZendEngine + * @brief Basic iterator * * Interface for external iterators or objects that can be iterated * themselves internally. * - * \note This is an engine internal interface. + * @note This is an engine internal interface. */ interface Iterator extends Traversable { @@ -310,26 +310,26 @@ function valid(); } -/** \ingroup SPL - * \brief Recursive iterator +/** @ingroup SPL + * @brief Recursive iterator * * Interface for recursive traversal to be used with * RecursiveIteratorIterator. */ interface RecursiveIterator extends Iterator { - /** \return whether current element can be iterated itself. + /** @return whether current element can be iterated itself. */ function hasChildren(); - /** \return an object that recursively iterates the current element. + /** @return an object that recursively iterates the current element. * This object must implement RecursiveIterator. */ function getChildren(); } -/** \ingroup SPL - * \brief Class for recursive traversal. +/** @ingroup SPL + * @brief Class for recursive traversal. * * The objects of this class are created by instances of RecursiveIterator. * Elements of those iterators may be traversable themselves. If so these @@ -339,23 +339,23 @@ { /** Construct an instance form a RecursiveIterator. * - * \param $iterator inner root iterator - * \param $mode one of + * @param $iterator inner root iterator + * @param $mode one of * - RIT_LEAVES_ONLY do not return elements that can be recursed. * - RIT_SELF_FIRST show elements before their sub elements. * - RIT_CHILD_FIRST show elements after their sub elements. * - * \note If you want to see only those elements which have sub elements then + * @note If you want to see only those elements which have sub elements then * use a ParentIterator. */ function __construct(RecursiveIterator $iterator, $mode); - /** \return the level of recursion (>=0). + /** @return the level of recursion (>=0). */ function getDepth(); - /** \param $level the level of the sub iterator to return. - * \return the current inner sub iterator or the iterator at the + /** @param $level the level of the sub iterator to return. + * @return the current inner sub iterator or the iterator at the * specified $level. */ function getSubIterator([$level]); @@ -371,67 +371,82 @@ function count(); } -/** \ingroup SPL - * \brief An Array wrapper +/** @ingroup SPL + * @brief Seekable iterator + * + * This interface is used to optimize LimitIterator functionality. but it + * may also be used for other situations where seeking a specific offset is + * required and easily possible. + */ +interface SeekableIterator extends Iterator +{ + /** Seek to a specific position if available or throw an exception. + * @param $position offset to seek to. + */ + function seek($position); +} + +/** @ingroup SPL + * @brief An Array wrapper * * This array wrapper allows to recursively iterate over Arrays and public * Object properties. * - * \see ArrayIterator + * @see ArrayIterator */ class ArrayObject implements IteratorAggregate, ArrayAccess, Countable { /** Construct a new array iterator from anything that has a hash table. * That is any Array or Object. * - * \param $array the array to use. + * @param $array the array to use. */ function __construct($array); - /** \return the iterator which is an ArrayIterator object connected to + /** @return the iterator which is an ArrayIterator object connected to * this object. */ function getIterator(); - /** \param $index offset to inspect - * \return whetehr offset $index esists + /** @param $index offset to inspect + * @return whetehr offset $index esists */ function offsetExists($index); - /** \param $index offset to return value for - * \return value at offset $index + /** @param $index offset to return value for + * @return value at offset $index */ function offsetGet($index); - /** \param $index index to set - * \param $newval new value to store at offset $index + /** @param $index index to set + * @param $newval new value to store at offset $index */ function offsetSet($index, $newval); - /** \param $index offset to unset + /** @param $index offset to unset */ function offsetUnset($index); - /** \param $value is appended as last element - * \warning this method cannot be called when the ArrayObject refers to + /** @param $value is appended as last element + * @warning this method cannot be called when the ArrayObject refers to * an object. */ function append($value); - /** \return a \b copy of the array - * \note when the ArrayObject refers to an object then this method + /** @return a \b copy of the array + * @note when the ArrayObject refers to an object then this method * returns an array of the public properties. */ function getArrayCopy(); - /** \return the number of elements in the array or the number of public + /** @return the number of elements in the array or the number of public * properties in the object. */ function count(); } -/** \ingroup SPL - * \brief An Array iterator +/** @ingroup SPL + * @brief An Array iterator * * This iterator allows to unset and modify values and keys while iterating * over Arrays and Objects. @@ -441,58 +456,58 @@ * refer to it either by using foreach or by calling its getIterator() * method manually. */ -class ArrayIterator implements Iterator, SeekableIterator, ArrayAccess, Countable +class ArrayIterator implements SeekableIterator, ArrayAccess, Countable { /** Construct a new array iterator from anything that has a hash table. * That is any Array or Object. * - * \param $array the array to use. + * @param $array the array to use. */ public function __construct($array); - /** \param $index offset to inspect - * \return whetehr offset $index esists + /** @param $index offset to inspect + * @return whetehr offset $index esists */ function offsetExists($index); - /** \param $index offset to return value for - * \return value at offset $index + /** @param $index offset to return value for + * @return value at offset $index */ function offsetGet($index); - /** \param $index index to set - * \param $newval new value to store at offset $index + /** @param $index index to set + * @param $newval new value to store at offset $index */ function offsetSet($index, $newval); - /** \param $index offset to unset + /** @param $index offset to unset */ function offsetUnset($index); - /** \param $value is appended as last element - * \warning this method cannot be called when the ArrayIterator refers to + /** @param $value is appended as last element + * @warning this method cannot be called when the ArrayIterator refers to * an object. */ function append($value); - /** \return a \b copy of the array - * \note when the ArrayIterator refers to an object then this method + /** @return a \b copy of the array + * @note when the ArrayIterator refers to an object then this method * returns an array of the public properties. */ function getArrayCopy(); - /** \param $position offset to seek to + /** @param $position offset to seek to */ function seek($position); - /** \return the number of elements in the array or the number of public + /** @return the number of elements in the array or the number of public * properties in the object. */ function count(); } -/** \ingroup SPL - * \brief An iterator that filters other iterators +/** @ingroup SPL + * @brief An iterator that filters other iterators * * Iterator that wrapps around another iterator and only returns selected * elements of the inner iterator. The only thing that needs to be done to @@ -504,37 +519,22 @@ { /** Construct an instance form a Iterator. * - * \param $iterator inner iterator + * @param $iterator inner iterator */ function __construct(Iterator $iterator); - /** \return whether the current element of the inner iterator should be + /** @return whether the current element of the inner iterator should be * used as a current element of this iterator or if it should be skipped. */ abstract function accept(); - /** \return the inner Iterator + /** @return the inner Iterator */ function getInnerIterator(); } -/** \ingroup SPL - * \brief Seekable iterator - * - * This interface is used to optimize LimitIterator functionality. but it - * may also be used for other situations where seeking a specific offset is - * required and easily possible. - */ -interface SeekableIterator extends Iterator -{ - /** Seek to a specific position if available or throw an exception. - * \param $position offset to seek to. - */ - function seek($position); -} - -/** \ingroup SPL - * \brief Limiting iterator +/** @ingroup SPL + * @brief Limiting iterator * * A class that starts iteration at a certain offset and only iterates over * a specified amount of elements. @@ -546,18 +546,18 @@ { /** Construct an instance form a Iterator. * - * \param $iterator inner iterator - * \param $offset starting position (zero based) - * \param $count amount of elements returned, if available) + * @param $iterator inner iterator + * @param $offset starting position (zero based) + * @param $count amount of elements returned, if available) */ function __construct(Iterator $iterator, $offset = 0, $count = -1); - /** \return whether the current element of the inner iterator should be + /** @return whether the current element of the inner iterator should be * used as a current element of this iterator or if it should be skipped. */ abstract function accept(); - /** \return the inner Iterator + /** @return the inner Iterator */ function getInnerIterator(); @@ -566,17 +566,17 @@ * method will be used. Otherwise the iterator will be rewound if * necessary and then manually advanced element by element. * - * \param $position index to seek to. + * @param $position index to seek to. */ function seek($position); - /** \return the current position (zero based) + /** @return the current position (zero based) */ function getPosition(); } -/** \ingroup SPL - * \brief Iterator that shows only parents +/** @ingroup SPL + * @brief Iterator that shows only parents * * A recursive iterator that only returns elements that themselves can be * trversed. @@ -585,13 +585,13 @@ { /** Construct an instance form a RecursiveIterator. * - * \param $iterator inner iterator + * @param $iterator inner iterator */ function __construct(RecursiveIterator $iterator); } -/** \ingroup SPL - * \brief Caching iterator +/** @ingroup SPL + * @brief Caching iterator * * This Iterator allways reads one ahead. That allows it to know whether * more elements are available. @@ -600,152 +600,156 @@ { /** Construct an instance form a RecursiveIterator. * - * \param $iterator inner iterator - * \param $getStrVal whether to fetch the value returned by __toString() - * or the (string) conversion. This is optional since - * it is not always used nad takes an additional fcall. + * @param $iterator inner iterator + * @param flags Bitmask: + * - CIT_CALL_TOSTRING whether to call __toString() for + * every element. This is optional since it is not + * always used nad takes an additional fcall. */ - function __construct(Iterator $iterator, $getStrVal = false); + function __construct(Iterator $iterator, $flags = CIT_CALL_TOSTRING); - /** \return whether the inner iterator is valid. That is this iterator + /** @return whether the inner iterator is valid. That is this iterator * is valid and has one more element. */ function valid(); - /** \return The last value from the inner iterators __toString() or + /** @return The last value from the inner iterators __toString() or * (string) conversion. The value is only fetched when the __constructor * was called with $getStrVal = true. */ function __tostring(); - /** \return the inner Iterator + /** @return the inner Iterator */ function getInnerIterator(); } -/** \ingroup SPL - * \brief The recursive version of the CachingIterator. +/** @ingroup SPL + * @brief The recursive version of the CachingIterator. */ class CachingRecursiveIterator extends CachingIterator implements RecursiveIterator { /** Construct an instance form a RecursiveIterator. * - * \param $iterator inner iterator - * \param $getStrVal whether to fetch the value returned by __toString() - * or the (string) conversion. This is optional since - * it is not always used nad takes an additional fcall. + * @param $iterator inner iterator + * @param flags Bitmask: + * - CIT_CALL_TOSTRING whether to call __toString() for + * every element. This is optional since it is not + * always used nad takes an additional fcall. + * - CIT_CATCH_GET_CHILD whether to catch exceptions when + * trying to get childs) */ function __construct(RecursiveIterator $iterator, $getStrVal); } -/** \ingroup SPL - * \brief Directory iterator +/** @ingroup SPL + * @brief Directory iterator */ class DirectoryIterator implements Iterator { /** Construct a directory iterator from a path-string. * - * \param $path directory to iterate. + * @param $path directory to iterate. */ function __construct($path); - /** \return The opened path. + /** @return The opened path. */ function getPath(); - /** \return The current file name. + /** @return The current file name. */ function getFilename(); - /** \return The current entries path and file name. + /** @return The current entries path and file name. */ function getPathname(); - /** \return The current entry's permissions. + /** @return The current entry's permissions. */ function getPerms(); - /** \return The current entry's inode. + /** @return The current entry's inode. */ function getInode(); - /** \return The current entry's size in bytes . + /** @return The current entry's size in bytes . */ function getSize(); - /** \return The current entry's owner name. + /** @return The current entry's owner name. */ function getOwner(); - /** \return The current entry's group name. + /** @return The current entry's group name. */ function getGroup(); - /** \return The current entry's last access time. + /** @return The current entry's last access time. */ function getATime(); - /** \return The current entry's last modification time. + /** @return The current entry's last modification time. */ function getMTime(); - /** \return The current entry's last change time. + /** @return The current entry's last change time. */ function getCTime(); - /** \return The current entry's size in bytes . + /** @return The current entry's size in bytes . */ function getType(); - /** \return Whether the current entry is writeable. + /** @return Whether the current entry is writeable. */ function isWritable(); - /** \return Whether the current entry is readable. + /** @return Whether the current entry is readable. */ function isReadable(); - /** \return Whether the current entry is executable. + /** @return Whether the current entry is executable. */ function isExecutable(); - /** \return Whether the current entry is . + /** @return Whether the current entry is . */ function isFile(); - /** \return Whether the current entry is a directory. + /** @return Whether the current entry is a directory. */ function isDir(); - /** \return Whether the current entry is either '.' or '..'. + /** @return Whether the current entry is either '.' or '..'. */ function isDot(); - /** \return whether the current entry is a link. + /** @return whether the current entry is a link. */ function isLink(); - /** \return getFilename() + /** @return getFilename() */ function __toString(); } -/** \ingroup SPL - * \brief recursive directory iterator +/** @ingroup SPL + * @brief recursive directory iterator */ class RecursiveDirectoryIterator extends DirectoryIterator implements RecursiveIterator { - /** \return whether the current is a directory (not '.' or '..'). + /** @return whether the current is a directory (not '.' or '..'). */ function hasChildren(); - /** \return a RecursiveDirectoryIterator for the current entry. + /** @return a RecursiveDirectoryIterator for the current entry. */ function getChildren(); } -/** \ingroup SPL - * \brief recursive SimpleXML_Element iterator +/** @ingroup SPL + * @brief recursive SimpleXML_Element iterator * * The SimpleXMLIterator implements the RecursiveIterator interface. This * allows iteration over all elements using foreach or an appropriate while @@ -756,11 +760,11 @@ */ class SimpleXMLIterator extends SimpleXMLElement implements RecursiveIterator { - /** \return whether the current node has sub nodes. + /** @return whether the current node has sub nodes. */ function hasChildren(); - /** \return a SimpleXMLIterator for the current node. + /** @return a SimpleXMLIterator for the current node. */ function getChildren(); }
-- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php