Source for file Hashtable.php

Documentation is available at Hashtable.php

  1. 1: <?php
  2. 2:  
  3. 3: /**
  4. 4:  * Nette Framework
  5. 5:  *
  6. 6:  * @copyright  Copyright (c) 2004, 2010 David Grudl
  7. 7:  * @license    http://nettephp.com/license  Nette license
  8. 8:  * @link       http://nettephp.com
  9. 9:  * @category   Nette
  10. 10:  * @package    Nette\Collections
  11. 11:  */
  12. 12:  
  13. 13:  
  14. 14:  
  15. 15: /**
  16. 16:  * The exception that is thrown when the key specified for accessing
  17. 17:  * an element in a collection does not match any key.
  18. 18:  * @package    Nette\Collections
  19. 19:  */
  20. 20: class KeyNotFoundException extends RuntimeException
  21. 21: {
  22. 22: }
  23. 23:  
  24. 24:  
  25. 25:  
  26. 26: /**
  27. 27:  * Provides the base class for a generic collection of keys and values.
  28. 28:  *
  29. 29:  * @copyright  Copyright (c) 2004, 2010 David Grudl
  30. 30:  * @package    Nette\Collections
  31. 31:  */
  32. 32: class Hashtable extends Collection implements IMap
  33. 33: {
  34. 34:     /** @var bool */
  35. 35:     private $throwKeyNotFound FALSE;
  36. 36:  
  37. 37:  
  38. 38:  
  39. 39:     /**
  40. 40:      * Inserts the specified element to the map.
  41. 41:      * @param  mixed 
  42. 42:      * @param  mixed 
  43. 43:      * @return bool 
  44. 44:      * @throws InvalidArgumentException, \InvalidStateException
  45. 45:      */
  46. 46:     public function add($key$item)
  47. 47:     {
  48. 48:         // note: $item is nullable to be compatible with that of ICollection::add()
  49. 49:         if (!is_scalar($key)) {
  50. 50:             throw new InvalidArgumentException("Key must be either a string or an integer, " gettype($key." given.");
  51. 51:         }
  52. 52:  
  53. 53:         if (parent::offsetExists($key)) {
  54. 54:             throw new InvalidStateException('An element with the same key already exists.');
  55. 55:         }
  56. 56:  
  57. 57:         $this->beforeAdd($item);
  58. 58:         parent::offsetSet($key$item);
  59. 59:         return TRUE;
  60. 60:     }
  61. 61:  
  62. 62:  
  63. 63:  
  64. 64:     /**
  65. 65:      * Append is not supported.
  66. 66:      */
  67. 67:     public function append($item)
  68. 68:     {
  69. 69:         throw new NotSupportedException;
  70. 70:     }
  71. 71:  
  72. 72:  
  73. 73:  
  74. 74:     /**
  75. 75:      * Returns a array of the keys contained in this map.
  76. 76:      * return array
  77. 77:      */
  78. 78:     public function getKeys()
  79. 79:     {
  80. 80:         return array_keys($this->getArrayCopy());
  81. 81:     }
  82. 82:  
  83. 83:  
  84. 84:  
  85. 85:     /**
  86. 86:      * Returns the key of the first occurrence of the specified element,.
  87. 87:      * or FALSE if this map does not contain this element.
  88. 88:      * @param  mixed 
  89. 89:      * @return mixed 
  90. 90:      */
  91. 91:     public function search($item)
  92. 92:     {
  93. 93:         return array_search($item$this->getArrayCopy()TRUE);
  94. 94:     }
  95. 95:  
  96. 96:  
  97. 97:  
  98. 98:     /**
  99. 99:      * Import from array or any traversable object.
  100. 100:      * @param  array|\Traversable
  101. 101:      * @return void 
  102. 102:      * @throws InvalidArgumentException
  103. 103:      */
  104. 104:     public function import($arr)
  105. 105:     {
  106. 106:         $this->updating();
  107. 107:  
  108. 108:         if (!(is_array($arr|| $arr instanceof Traversable)) {
  109. 109:             throw new InvalidArgumentException("Argument must be traversable.");
  110. 110:         }
  111. 111:  
  112. 112:         if ($this->getItemType(=== NULL// optimalization
  113. 113:             $this->setArray((array) $arr);
  114. 114:  
  115. 115:         else {
  116. 116:             $this->clear();
  117. 117:             foreach ($arr as $key => $item{
  118. 118:                 $this->offsetSet($key$item);
  119. 119:             }
  120. 120:         }
  121. 121:     }
  122. 122:  
  123. 123:  
  124. 124:  
  125. 125:     /**
  126. 126:      * Returns variable or $default if there is no element.
  127. 127:      * @param  string key
  128. 128:      * @param  mixed  default value
  129. 129:      * @return mixed 
  130. 130:      * @throws InvalidArgumentException
  131. 131:      */
  132. 132:     public function get($key$default NULL)
  133. 133:     {
  134. 134:         if (!is_scalar($key)) {
  135. 135:             throw new InvalidArgumentException("Key must be either a string or an integer, " gettype($key." given.");
  136. 136:         }
  137. 137:  
  138. 138:         if (parent::offsetExists($key)) {
  139. 139:             return parent::offsetGet($key);
  140. 140:  
  141. 141:         else {
  142. 142:             return $default;
  143. 143:         }
  144. 144:     }
  145. 145:  
  146. 146:  
  147. 147:  
  148. 148:     /**
  149. 149:      * Do throw KeyNotFoundException?
  150. 150:      * @return void 
  151. 151:      */
  152. 152:     public function throwKeyNotFound($val TRUE)
  153. 153:     {
  154. 154:         $this->throwKeyNotFound = (bool) $val;
  155. 155:     }
  156. 156:  
  157. 157:  
  158. 158:  
  159. 159:     /********************* interface \ArrayAccess ****************d*g**/
  160. 160:  
  161. 161:  
  162. 162:  
  163. 163:     /**
  164. 164:      * Inserts (replaces) item (\ArrayAccess implementation).
  165. 165:      * @param  string key
  166. 166:      * @param  object 
  167. 167:      * @return void 
  168. 168:      * @throws NotSupportedException, \InvalidArgumentException
  169. 169:      */
  170. 170:     public function offsetSet($key$item)
  171. 171:     {
  172. 172:         if (!is_scalar($key)) // prevents NULL
  173. 173:             throw new InvalidArgumentException("Key must be either a string or an integer, " gettype($key." given.");
  174. 174:         }
  175. 175:  
  176. 176:         $this->beforeAdd($item);
  177. 177:         parent::offsetSet($key$item);
  178. 178:     }
  179. 179:  
  180. 180:  
  181. 181:  
  182. 182:     /**
  183. 183:      * Returns item (\ArrayAccess implementation).
  184. 184:      * @param  string key
  185. 185:      * @return mixed 
  186. 186:      * @throws KeyNotFoundException, \InvalidArgumentException
  187. 187:      */
  188. 188:     public function offsetGet($key)
  189. 189:     {
  190. 190:         if (!is_scalar($key)) {
  191. 191:             throw new InvalidArgumentException("Key must be either a string or an integer, " gettype($key." given.");
  192. 192:         }
  193. 193:  
  194. 194:         if (parent::offsetExists($key)) {
  195. 195:             return parent::offsetGet($key);
  196. 196:  
  197. 197:         elseif ($this->throwKeyNotFound{
  198. 198:             throw new KeyNotFoundException;
  199. 199:  
  200. 200:         else {
  201. 201:             return NULL;
  202. 202:         }
  203. 203:     }
  204. 204:  
  205. 205:  
  206. 206:  
  207. 207:     /**
  208. 208:      * Exists item? (\ArrayAccess implementation).
  209. 209:      * @param  string key
  210. 210:      * @return bool 
  211. 211:      * @throws InvalidArgumentException
  212. 212:      */
  213. 213:     public function offsetExists($key)
  214. 214:     {
  215. 215:         if (!is_scalar($key)) {
  216. 216:             throw new InvalidArgumentException("Key must be either a string or an integer, " gettype($key." given.");
  217. 217:         }
  218. 218:  
  219. 219:         return parent::offsetExists($key);
  220. 220:     }
  221. 221:  
  222. 222:  
  223. 223:  
  224. 224:     /**
  225. 225:      * Removes the element at the specified position in this list.
  226. 226:      * @param  string key
  227. 227:      * @return void 
  228. 228:      * @throws NotSupportedException, \InvalidArgumentException
  229. 229:      */
  230. 230:     public function offsetUnset($key)
  231. 231:     {
  232. 232:         $this->updating();
  233. 233:  
  234. 234:         if (!is_scalar($key)) {
  235. 235:             throw new InvalidArgumentException("Key must be either a string or an integer, " gettype($key." given.");
  236. 236:         }
  237. 237:  
  238. 238:         if (parent::offsetExists($key)) {
  239. 239:             parent::offsetUnset($key);
  240. 240:         }
  241. 241:     }
  242. 242: