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