Source for file List.class.php

Documentation is available at List.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package List
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * List Class
  22.  *
  23.  * @category Gumbo
  24.  * @package List
  25.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  26.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  27.  * @author Michael Luster <mluster79@yahoo.com>
  28.  * @link http://sourceforge.net/projects/phpgumbo
  29.  * @desc List Class
  30.  * @version 0.0.1
  31.  */
  32.  
  33. gumbo_load ("Interface_List");
  34.  
  35. class Gumbo_List implements Gumbo_Interface_List, IteratorAggregate {
  36.     
  37.     /** @var array $_list */
  38.     private $_list = array ();
  39.     
  40.     
  41.     
  42.     /**
  43.      * Constructor
  44.      * @param array $list 
  45.      */
  46.     public function __construct ($list=null) {
  47.         if (!is_null ($list) && is_array ($list)) {
  48.             $this->_list = $list;
  49.         }
  50.     }
  51.     
  52.     
  53.     
  54.     /** OVERLOADED METHODS **/
  55.     /**
  56.      * Returns Data (wrapper to get())
  57.      * @param int|string$key for integers, use $list->{$num}
  58.      * @return mixed 
  59.      */
  60.     public function __get ($key) {
  61.         return $this->get ($key);
  62.     }
  63.     
  64.     /**
  65.      * Sets Data (wrapper to add())
  66.      * @param int|string$key 
  67.      * @param mixed $data 
  68.      */
  69.     public function __set ($key, $data) {
  70.         $this->add ($data, $key);
  71.     }
  72.     
  73.     /**
  74.      * Returns if key is set (wrapper to exists())
  75.      * @param int|string$key 
  76.      * @return bool 
  77.      */
  78.     public function __isset ($key) {
  79.         return $this->exists ($key);
  80.     }
  81.     
  82.     /**
  83.      * Removes Data (wrapper to remove())
  84.      * @param int|string$key 
  85.      */
  86.     public function __unset ($key) {
  87.         $this->remove ($key);
  88.     }
  89.     
  90.     
  91.     
  92.     /** ACTION METHODS **/
  93.     /**
  94.      * Adds a new Item to the List
  95.      * @param mixed $data 
  96.      * @param int|string$key 
  97.      * @throws Gumbo_Exception
  98.      */
  99.     public function add ($data, $key=null) {
  100.         try {
  101.             // verify precondition
  102.             if (!is_null ($key) && !is_int ($key) && !is_string ($key)) {
  103.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str|null' => {$key}:" . gettype ($key));
  104.             }
  105.             
  106.             if (is_null ($key)) {
  107.                 $this->_list [] = $data;
  108.             } else {
  109.                 $this->_list [$key] = $data;
  110.             }
  111.         } catch (Gumbo_Exception $e) {
  112.             $e->setFunction (__METHOD__);
  113.             gumbo_trigger ($e);
  114.         }
  115.     }
  116.     
  117.     /**
  118.      * Removes an Item from the List
  119.      * @precondition exists($key)
  120.      * @param int|string$key 
  121.      * @throws Gumbo_Exception
  122.      */
  123.     public function remove ($key) {
  124.         try {
  125.             // verify precondition
  126.             if (!is_int ($key) && !is_string ($key)) {
  127.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str' => {$key}:" . gettype ($key));
  128.             }
  129.             if (!$this->exists ($key)) {
  130.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str' => {$key}:" . gettype ($key));
  131.             }
  132.             
  133.             unset ($this->_list [$key]);
  134.         } catch (Gumbo_Exception $e) {
  135.             $e->setFunction (__METHOD__);
  136.             gumbo_trigger ($e);
  137.         }
  138.     }
  139.     
  140.     /**
  141.      * Removes a value from the List
  142.      * @param mixed $data 
  143.      * @throws Gumbo_Exception
  144.      */
  145.     public function removeValue ($data) {
  146.         try {
  147.             $found = false;
  148.             foreach ($this->getAll () as $key=>$val) {
  149.                 if ($val === $data) {
  150.                     $found = true;
  151.                     unset ($this->_list [$key]);
  152.                 }
  153.             }
  154.             if (!$found) {
  155.                 throw new Gumbo_Exception ("Underfined Data: {$data}");
  156.             }
  157.         } catch (Gumbo_Exception $e) {
  158.             $e->setFunction (__METHOD__);
  159.             gumbo_trigger ($e);
  160.         }
  161.         
  162.     }
  163.     
  164.     /**
  165.      * Resets the List
  166.      * @postcondition !size()
  167.      */
  168.     public function reset () {
  169.         $this->_list = array ();
  170.     }
  171.     
  172.     
  173.     
  174.     /** ACCESSOR METHODS **/
  175.     /**
  176.      * Returns a single Value
  177.      * @precondition exists($key)
  178.      * @param int|string$key 
  179.      * @return mixed 
  180.      * @throws Gumbo_Exception
  181.      */
  182.     public function get ($key) {
  183.         try {
  184.             // verify precondition
  185.             if (!$this->exists ($key)) {
  186.                 throw new Gumbo_Exception ("Key Undefined: {$key}");
  187.             }
  188.             
  189.             return $this->_list [$key];
  190.         } catch (Gumbo_Exception $e) {
  191.             $e->setFunction (__METHOD__);
  192.             gumbo_trigger ($e);
  193.         }
  194.         return null;
  195.     }
  196.     
  197.     /**
  198.      * Returns the entire List
  199.      * @return array 
  200.      */
  201.     public function getAll () {
  202.         return $this->_list;
  203.     }
  204.     
  205.     /**
  206.      * Returns the size of the list
  207.      * @return int 
  208.      */
  209.     public function size () {
  210.         return count ($this->_list);
  211.     }
  212.     
  213.     /**
  214.      * Returns if the Key exists, or if the List contains data
  215.      * @param int|string$key 
  216.      * @return bool 
  217.      */
  218.     public function exists ($key=null) {
  219.         try {
  220.             if (!is_null ($key) && !is_int ($key) && !is_string ($key)) {
  221.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str' => {$key}:" . gettype ($key));
  222.             }
  223.             if ($this->size () > 0) {
  224.                 if (!is_null ($key)) {
  225.                     return isset ($this->_list [$key]);
  226.                 }
  227.                 return true;
  228.             }
  229.         } catch (Gumbo_Exception $e) {
  230.             $e->setFunction (__METHOD__);
  231.             gumbo_trigger ($e);
  232.         }
  233.         return false;
  234.     }
  235.     
  236.     
  237.     
  238.     /**
  239.      * Returns an Iterator
  240.      * @return Iterator 
  241.      * @uses Gumbo_Iterator
  242.      */
  243.     public function getIterator () {
  244.         gumbo_load ("Iterator");
  245.         return new Gumbo_Iterator ($this->getAll ());
  246.     }
  247.     
  248. }
  249.  
  250. ?>