From 85254498dc064948055fd0ef02d712dca73dd0ff Mon Sep 17 00:00:00 2001
From: Etienne Kneuss <colder@php.net>
Date: Mon, 21 Jan 2008 21:54:00 +0000
Subject: [PATCH] Add doxygen docs for SplDoublyLinkedList, SplStack, SplQueue

---
 NEWS                                     |   2 +
 ext/spl/internal/spldoublylinkedlist.inc | 100 +++++++++++++++++++++++
 ext/spl/internal/splqueue.inc            |  50 ++++++++++++
 ext/spl/internal/splstack.inc            |  35 ++++++++
 ext/spl/spl.php                          |  16 +++-
 5 files changed, 199 insertions(+), 4 deletions(-)
 create mode 100644 ext/spl/internal/spldoublylinkedlist.inc
 create mode 100644 ext/spl/internal/splqueue.inc
 create mode 100644 ext/spl/internal/splstack.inc

diff --git a/NEWS b/NEWS
index f437e25c227..809f41a95b4 100644
--- a/NEWS
+++ b/NEWS
@@ -59,5 +59,7 @@ PHP                                                                        NEWS
 - Added shm_has_var() function. (Mike)
 - Added str_getcsv() function. (Sara)
 - Added ext/hash support to ext/session's ID generator. (Sara)
+- Added SplDoublyLinkedList, SplStack, SplQueue classes. (Etienne)
 
 - Fixed bug #40325 (Vary: header missing in gzip output handlers). (Mike)
+
diff --git a/ext/spl/internal/spldoublylinkedlist.inc b/ext/spl/internal/spldoublylinkedlist.inc
new file mode 100644
index 00000000000..dffcefd2557
--- /dev/null
+++ b/ext/spl/internal/spldoublylinkedlist.inc
@@ -0,0 +1,100 @@
+<?php
+
+/** @file spldoublylinkedlist.inc
+ * @ingroup SPL
+ * @brief class SplDoublyLinkedList
+ * @author  Etienne Kneuss
+ * @date    2008
+ *
+ * SPL - Standard PHP Library
+ */
+
+/** @ingroup SPL
+ * @brief Doubly Linked List
+ * @since PHP 5.3
+ *
+ * The SplDoublyLinkedList class provides the main functionnalities of a
+ * doubly linked list (DLL).
+ */
+class SplDoublyLinkedList implements Traversable, ArrayAccess, Countable
+{
+
+	/** Iterator mode
+	 * @see setIteratorMode
+	 */
+	const IT_MODE_LIFO     = 0x00000001;
+
+	/** Iterator mode
+	 * @see setIteratorMode
+	 */
+	const IT_MODE_FIFO     = 0x00000000;
+
+
+	/** Iterator mode
+	 * @see setIteratorMode
+	 */
+	const IT_MODE_KEEP     = 0x00000000;
+
+	/** Iterator mode
+	 * @see setIteratorMode
+	 */
+	const IT_MODE_DELETE   = 0x00000002;
+
+	/** @return the element popped from the end of the DLL.
+	 */
+	function pop() {/**/}
+
+	/** @return the element shifted from the beginning of the DLL.
+	 */
+	function shift() {/**/}
+
+	/** Pushes an element to the end of the DLL.
+	 * @param $data variable to add to the DLL.
+	 */
+	function push($data) {/**/}
+
+	/** Adds an element to the beginning of the DLL.
+	 * @param $data variable to add to the DLL.
+	 */
+	function unshift($data) {/**/}
+
+	/** @return the element at the beginning of the DLL.
+	 */
+	function top() {/**/}
+
+	/** @return the element at the end of the DLL.
+	 */
+	function bottom() {/**/}
+
+	/** @return number elements in the DLL.
+	 */
+	function count() {/**/}
+
+	/** @return whether the DLL is empty.
+	 */
+	function isEmpty() {/**/}
+
+	/** Changes the iteration mode. There are two orthogonal sets of modes that 
+	 * can be set:
+	 * - The direction of the iteration (either one or the other)
+	 *  - SplDoublyLnkedList::IT_MODE_LIFO (Stack style)
+	 *  - SplDoublyLnkedList::IT_MODE_FIFO (Queue style)
+	 *
+	 * - The behavior of the iterator (either one or the other)
+	 *  - SplDoublyLnkedList::IT_MODE_DELETE (Elements are deleted by the iterator)
+	 *  - SplDoublyLnkedList::IT_MODE_KEEP   (Elements are traversed by the iterator)
+	 *
+	 * The default mode is 0 : SplDoublyLnkedList::IT_MODE_FIFO | SplDoublyLnkedList::IT_MODE_KEEP
+	 *
+	 * @param $mode new mode of iteration
+	 */
+	function setIteratorMode($mode) {/**/}
+
+	/** @return the current iteration mode
+	 * @see setIteratorMode
+	 */
+	function getIteratorMode() {/**/}
+
+}
+
+?>
diff --git a/ext/spl/internal/splqueue.inc b/ext/spl/internal/splqueue.inc
new file mode 100644
index 00000000000..aaa62db843f
--- /dev/null
+++ b/ext/spl/internal/splqueue.inc
@@ -0,0 +1,50 @@
+<?php
+
+/** @file splqueue.inc
+ * @ingroup SPL
+ * @brief class SplQueue
+ * @author  Etienne Kneuss
+ * @date    2008
+ *
+ * SPL - Standard PHP Library
+ */
+
+/** @ingroup SPL
+ * @brief Implementation of a Queue through a DoublyLinkedList. As SplQueue 
+ * extends SplDoublyLinkedList, unshift() and pop() are still available even
+ * though they don't make much sense for a queue. For convenience, two aliases
+ * are available:
+ * - enqueue() is an alias of push()
+ * - dequeue() is an alias of shift()
+ *
+ * @since PHP 5.3
+ *
+ * The SplQueue class provides the main functionnalities of a
+ * queue implemented by a doubly linked list.
+ */
+class SplQueue extends SplDoublyLinkedList
+{
+	/** Changes the iteration mode. For queues, the direction mode
+	 * is frozen. Attempting to modify it will result in an RuntimeException.
+	 *
+	 * @throws RuntimeException
+	 * @param $mode new mode of iteration
+	 * @see SplDoublyLinkedList::setIteratorMode
+	 */
+	function setIteratorMode($mode) {/**/}
+
+	/** @return the first element of the queue.
+	 * @note dequeue is an alias of push()
+	 * @see splDoublyLinkedList::push()
+	 */
+	function dequeue() {/**/}
+
+	/** Pushes an element at the end of the queue.
+	 * @param $data variable to add to the queue.
+	 * @note enqueue is an alias of shift()
+	 * @see splDoublyLinkedList::shift()
+	 */
+	function enqueue($data) {/**/}
+}
+
+?>
diff --git a/ext/spl/internal/splstack.inc b/ext/spl/internal/splstack.inc
new file mode 100644
index 00000000000..a83d2c4b8e9
--- /dev/null
+++ b/ext/spl/internal/splstack.inc
@@ -0,0 +1,35 @@
+<?php
+
+/** @file splstack.inc
+ * @ingroup SPL
+ * @brief class SplStack
+ * @author  Etienne Kneuss
+ * @date    2008
+ *
+ * SPL - Standard PHP Library
+ */
+
+
+/** @ingroup SPL
+ * @brief Implementation of a stack through a DoublyLinkedList. As SplStack 
+ * extends SplDoublyLinkedList, shift() and unshift() are still available even
+ * though they don't make much sense for a stack.
+ *
+ * @since PHP 5.3
+ *
+ * The SplStack class provides the main functionnalities of a
+ * stack implemented by a doubly linked list.
+ */
+class SplStack extends SplDoublyLinkedList
+{
+	/** Changes the iteration mode. For stacks, the direction mode
+	 * is frozen. Attempting to modify it will result in an RuntimeException.
+	 *
+	 * @throws RuntimeException
+	 * @param $mode new mode of iteration
+	 * @see SplDoublyLinkedList::setIteratorMode
+	 */
+	function setIteratorMode($mode) {/**/}
+}
+
+?>
diff --git a/ext/spl/spl.php b/ext/spl/spl.php
index bb6af7e050f..ee898693d22 100755
--- a/ext/spl/spl.php
+++ b/ext/spl/spl.php
@@ -105,13 +105,21 @@
  * - interface SplSubject
  * - class SplObjectStorage
  *
- * 8) @ref Examples
+ * 8) Datastructures
+ *
+ * SPL proposes a set of datastructures implemented internally.
+ *
+ * - class SplDoublyLinkedList
+ * - class SplStack                 extends SplDoublyLinkedList
+ * - class SplQueue                 extends SplDoublyLinkedList
+ *
+ * 9) @ref Examples
  *
  * The classes and interfaces in this group are contained as PHP code in the 
  * examples subdirectory of ext/SPL. Sooner or later they will be moved to
  * c-code.
  * 
- * 9) Some articles about SPL:
+ * 10) Some articles about SPL:
  * - <a href="http://www.phpro.org/tutorials/Introduction-to-SPL.html">Introduction to Standard PHP Library (SPL)</a>
  * - <a href="http://www.sitepoint.com/article/php5-standard-library/1">Introducing PHP 5's Standard Library</a>
  * - <a href="http://www.ramikayyali.com/archives/2005/02/25/iterators">Iterators in PHP5</a>
@@ -120,13 +128,13 @@
  * - <a href="http://www.devshed.com/c/a/PHP/The-Standard-PHP-Library-Part-2/">The Standard PHP Library, Part 2</a>
  * - <a href="http://www.professionelle-softwareentwicklung-mit-php5.de/erste_auflage/oop.iterators.spl.html">Die Standard PHP Library (SPL) [german]</a>
  *
- * 10) Talks on SPL:
+ * 11) Talks on SPL:
  * - 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>
  * - 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>
  * - 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>
  * - 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>
  *
- * 11) Debug sessions:
+ * 12) Debug sessions:
  * - 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>
  * - 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>
  * - 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>