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