1: <?php
  2: /**
  3:  * PHP version 5
  4:  * @package    generalDriver
  5:  * @author     Christian Schiffler <c.schiffler@cyberspectrum.de>
  6:  * @author     Stefan Heimes <stefan_heimes@hotmail.com>
  7:  * @author     Tristan Lins <tristan.lins@bit3.de>
  8:  * @copyright  The MetaModels team.
  9:  * @license    LGPL.
 10:  * @filesource
 11:  */
 12: 
 13: namespace DcGeneral\Data;
 14: 
 15: use DcGeneral\Exception\DcGeneralRuntimeException;
 16: 
 17: /**
 18:  * Interface InterfaceGeneralCollection
 19:  *
 20:  * This represents an iterable collection of Model elements.
 21:  */
 22: interface CollectionInterface extends \IteratorAggregate
 23: {
 24:     /**
 25:      * Get length of this collection.
 26:      *
 27:      * @return int
 28:      */
 29:     public function length();
 30: 
 31:     /**
 32:      * Get the model at a specific index.
 33:      *
 34:      * @param int $intIndex The index of the model to retrieve.
 35:      *
 36:      * @return ModelInterface
 37:      */
 38:     public function get($intIndex);
 39: 
 40:     /**
 41:      * Alias for push - Append a model to the end of this collection.
 42:      *
 43:      * @param ModelInterface $objModel The model to append to the collection.
 44:      *
 45:      * @return void
 46:      *
 47:      * @throws DcGeneralRuntimeException When no model has been passed.
 48:      *
 49:      * @deprecated Use push.
 50:      */
 51:     public function add(ModelInterface $objModel);
 52: 
 53:     /**
 54:      * Append a model to the end of this collection.
 55:      *
 56:      * @param ModelInterface $objModel The model to append to the collection.
 57:      *
 58:      * @return void
 59:      *
 60:      * @throws DcGeneralRuntimeException When no model has been passed.
 61:      */
 62:     public function push(ModelInterface $objModel);
 63: 
 64:     /**
 65:      * Remove the model at the end of the collection and return it.
 66:      *
 67:      * If the collection is empty, null will be returned.
 68:      *
 69:      * @return ModelInterface
 70:      */
 71:     public function pop();
 72: 
 73:     /**
 74:      * Insert a model at the beginning of the collection.
 75:      *
 76:      * @param ModelInterface $objModel The model to insert into the collection.
 77:      *
 78:      * @return void
 79:      */
 80:     public function unshift(ModelInterface $objModel);
 81: 
 82:     /**
 83:      * Remove the model from the beginning of the collection and return it.
 84:      *
 85:      * If the collection is empty, null will be returned.
 86:      *
 87:      * @return ModelInterface
 88:      */
 89:     public function shift();
 90: 
 91:     /**
 92:      * Insert a record at the specific position.
 93:      *
 94:      * Move all records at position >= $index one index up.
 95:      * If $index is out of bounds, just add at the end (does not fill with empty records!).
 96:      *
 97:      * @param int            $intIndex The index where the model shall be placed.
 98:      *
 99:      * @param ModelInterface $objModel The model to insert.
100:      *
101:      * @return void
102:      */
103:     public function insert($intIndex, ModelInterface $objModel);
104: 
105:     /**
106:      * Remove the given index or model from the collection and renew the index.
107:      *
108:      * ATTENTION: Don't use key to unset in foreach because of the new index.
109:      *
110:      * @param mixed $mixedValue The index (integer) or InterfaceGeneralModel instance to remove.
111:      *
112:      * @return void
113:      */
114:     public function remove($mixedValue);
115: 
116:     /**
117:      * Make a reverse sorted collection of this collection.
118:      *
119:      * @return ModelInterface
120:      */
121:     public function reverse();
122: 
123:     /**
124:      * Sort the records with the given callback and return the new sorted collection.
125:      *
126:      * @param callback $callback The callback function to use.
127:      *
128:      * @return ModelInterface
129:      */
130:     public function sort($callback);
131: }
132: