docs/source/HashMap.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-util-HashMap'>/**
  19 </span> * @class Ext.util.HashMap
  20  * &lt;p&gt;
  21  * Represents a collection of a set of key and value pairs. Each key in the HashMap
  22  * must be unique, the same key cannot exist twice. Access to items is provided via
  23  * the key only. Sample usage:
  24  * &lt;pre&gt;&lt;code&gt;
  25 var map = new Ext.util.HashMap();
  26 map.add('key1', 1);
  27 map.add('key2', 2);
  28 map.add('key3', 3);
  29
  30 map.each(function(key, value, length){
  31     console.log(key, value, length);
  32 });
  33  * &lt;/code&gt;&lt;/pre&gt;
  34  * &lt;/p&gt;
  35  *
  36  * &lt;p&gt;The HashMap is an unordered class,
  37  * there is no guarantee when iterating over the items that they will be in any particular
  38  * order. If this is required, then use a {@link Ext.util.MixedCollection}.
  39  * &lt;/p&gt;
  40  */
  41 Ext.define('Ext.util.HashMap', {
  42     mixins: {
  43         observable: 'Ext.util.Observable'
  44     },
  45
  46 <span id='Ext-util-HashMap-cfg-keyFn'>    /**
  47 </span>     * @cfg {Function} keyFn A function that is used to retrieve a default key for a passed object.
  48      * A default is provided that returns the &lt;b&gt;id&lt;/b&gt; property on the object. This function is only used
  49      * if the add method is called with a single argument.
  50      */
  51
  52 <span id='Ext-util-HashMap-method-constructor'>    /**
  53 </span>     * Creates new HashMap.
  54      * @param {Object} config (optional) Config object.
  55      */
  56     constructor: function(config) {
  57         config = config || {};
  58
  59         var me = this,
  60             keyFn = config.keyFn;
  61
  62         me.addEvents(
  63 <span id='Ext-util-HashMap-event-add'>            /**
  64 </span>             * @event add
  65              * Fires when a new item is added to the hash
  66              * @param {Ext.util.HashMap} this.
  67              * @param {String} key The key of the added item.
  68              * @param {Object} value The value of the added item.
  69              */
  70             'add',
  71 <span id='Ext-util-HashMap-event-clear'>            /**
  72 </span>             * @event clear
  73              * Fires when the hash is cleared.
  74              * @param {Ext.util.HashMap} this.
  75              */
  76             'clear',
  77 <span id='Ext-util-HashMap-event-remove'>            /**
  78 </span>             * @event remove
  79              * Fires when an item is removed from the hash.
  80              * @param {Ext.util.HashMap} this.
  81              * @param {String} key The key of the removed item.
  82              * @param {Object} value The value of the removed item.
  83              */
  84             'remove',
  85 <span id='Ext-util-HashMap-event-replace'>            /**
  86 </span>             * @event replace
  87              * Fires when an item is replaced in the hash.
  88              * @param {Ext.util.HashMap} this.
  89              * @param {String} key The key of the replaced item.
  90              * @param {Object} value The new value for the item.
  91              * @param {Object} old The old value for the item.
  92              */
  93             'replace'
  94         );
  95
  96         me.mixins.observable.constructor.call(me, config);
  97         me.clear(true);
  98
  99         if (keyFn) {
 100             me.getKey = keyFn;
 101         }
 102     },
 103
 104 <span id='Ext-util-HashMap-method-getCount'>    /**
 105 </span>     * Gets the number of items in the hash.
 106      * @return {Number} The number of items in the hash.
 107      */
 108     getCount: function() {
 109         return this.length;
 110     },
 111
 112 <span id='Ext-util-HashMap-method-getData'>    /**
 113 </span>     * Implementation for being able to extract the key from an object if only
 114      * a single argument is passed.
 115      * @private
 116      * @param {String} key The key
 117      * @param {Object} value The value
 118      * @return {Array} [key, value]
 119      */
 120     getData: function(key, value) {
 121         // if we have no value, it means we need to get the key from the object
 122         if (value === undefined) {
 123             value = key;
 124             key = this.getKey(value);
 125         }
 126
 127         return [key, value];
 128     },
 129
 130 <span id='Ext-util-HashMap-method-getKey'>    /**
 131 </span>     * Extracts the key from an object. This is a default implementation, it may be overridden
 132      * @param {Object} o The object to get the key from
 133      * @return {String} The key to use.
 134      */
 135     getKey: function(o) {
 136         return o.id;
 137     },
 138
 139 <span id='Ext-util-HashMap-method-add'>    /**
 140 </span>     * Adds an item to the collection. Fires the {@link #add} event when complete.
 141      * @param {String} key &lt;p&gt;The key to associate with the item, or the new item.&lt;/p&gt;
 142      * &lt;p&gt;If a {@link #getKey} implementation was specified for this HashMap,
 143      * or if the key of the stored items is in a property called &lt;tt&gt;&lt;b&gt;id&lt;/b&gt;&lt;/tt&gt;,
 144      * the HashMap will be able to &lt;i&gt;derive&lt;/i&gt; the key for the new item.
 145      * In this case just pass the new item in this parameter.&lt;/p&gt;
 146      * @param {Object} o The item to add.
 147      * @return {Object} The item added.
 148      */
 149     add: function(key, value) {
 150         var me = this,
 151             data;
 152
 153         if (arguments.length === 1) {
 154             value = key;
 155             key = me.getKey(value);
 156         }
 157
 158         if (me.containsKey(key)) {
 159             return me.replace(key, value);
 160         }
 161
 162         data = me.getData(key, value);
 163         key = data[0];
 164         value = data[1];
 165         me.map[key] = value;
 166         ++me.length;
 167         me.fireEvent('add', me, key, value);
 168         return value;
 169     },
 170
 171 <span id='Ext-util-HashMap-method-replace'>    /**
 172 </span>     * Replaces an item in the hash. If the key doesn't exist, the
 173      * {@link #add} method will be used.
 174      * @param {String} key The key of the item.
 175      * @param {Object} value The new value for the item.
 176      * @return {Object} The new value of the item.
 177      */
 178     replace: function(key, value) {
 179         var me = this,
 180             map = me.map,
 181             old;
 182
 183         if (!me.containsKey(key)) {
 184             me.add(key, value);
 185         }
 186         old = map[key];
 187         map[key] = value;
 188         me.fireEvent('replace', me, key, value, old);
 189         return value;
 190     },
 191
 192 <span id='Ext-util-HashMap-method-remove'>    /**
 193 </span>     * Remove an item from the hash.
 194      * @param {Object} o The value of the item to remove.
 195      * @return {Boolean} True if the item was successfully removed.
 196      */
 197     remove: function(o) {
 198         var key = this.findKey(o);
 199         if (key !== undefined) {
 200             return this.removeAtKey(key);
 201         }
 202         return false;
 203     },
 204
 205 <span id='Ext-util-HashMap-method-removeAtKey'>    /**
 206 </span>     * Remove an item from the hash.
 207      * @param {String} key The key to remove.
 208      * @return {Boolean} True if the item was successfully removed.
 209      */
 210     removeAtKey: function(key) {
 211         var me = this,
 212             value;
 213
 214         if (me.containsKey(key)) {
 215             value = me.map[key];
 216             delete me.map[key];
 217             --me.length;
 218             me.fireEvent('remove', me, key, value);
 219             return true;
 220         }
 221         return false;
 222     },
 223
 224 <span id='Ext-util-HashMap-method-get'>    /**
 225 </span>     * Retrieves an item with a particular key.
 226      * @param {String} key The key to lookup.
 227      * @return {Object} The value at that key. If it doesn't exist, &lt;tt&gt;undefined&lt;/tt&gt; is returned.
 228      */
 229     get: function(key) {
 230         return this.map[key];
 231     },
 232
 233 <span id='Ext-util-HashMap-method-clear'>    /**
 234 </span>     * Removes all items from the hash.
 235      * @return {Ext.util.HashMap} this
 236      */
 237     clear: function(/* private */ initial) {
 238         var me = this;
 239         me.map = {};
 240         me.length = 0;
 241         if (initial !== true) {
 242             me.fireEvent('clear', me);
 243         }
 244         return me;
 245     },
 246
 247 <span id='Ext-util-HashMap-method-containsKey'>    /**
 248 </span>     * Checks whether a key exists in the hash.
 249      * @param {String} key The key to check for.
 250      * @return {Boolean} True if they key exists in the hash.
 251      */
 252     containsKey: function(key) {
 253         return this.map[key] !== undefined;
 254     },
 255
 256 <span id='Ext-util-HashMap-method-contains'>    /**
 257 </span>     * Checks whether a value exists in the hash.
 258      * @param {Object} value The value to check for.
 259      * @return {Boolean} True if the value exists in the dictionary.
 260      */
 261     contains: function(value) {
 262         return this.containsKey(this.findKey(value));
 263     },
 264
 265 <span id='Ext-util-HashMap-method-getKeys'>    /**
 266 </span>     * Return all of the keys in the hash.
 267      * @return {Array} An array of keys.
 268      */
 269     getKeys: function() {
 270         return this.getArray(true);
 271     },
 272
 273 <span id='Ext-util-HashMap-method-getValues'>    /**
 274 </span>     * Return all of the values in the hash.
 275      * @return {Array} An array of values.
 276      */
 277     getValues: function() {
 278         return this.getArray(false);
 279     },
 280
 281 <span id='Ext-util-HashMap-method-getArray'>    /**
 282 </span>     * Gets either the keys/values in an array from the hash.
 283      * @private
 284      * @param {Boolean} isKey True to extract the keys, otherwise, the value
 285      * @return {Array} An array of either keys/values from the hash.
 286      */
 287     getArray: function(isKey) {
 288         var arr = [],
 289             key,
 290             map = this.map;
 291         for (key in map) {
 292             if (map.hasOwnProperty(key)) {
 293                 arr.push(isKey ? key: map[key]);
 294             }
 295         }
 296         return arr;
 297     },
 298
 299 <span id='Ext-util-HashMap-method-each'>    /**
 300 </span>     * Executes the specified function once for each item in the hash.
 301      * Returning false from the function will cease iteration.
 302      *
 303      * The paramaters passed to the function are:
 304      * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
 305      * &lt;li&gt;&lt;b&gt;key&lt;/b&gt; : String&lt;p class=&quot;sub-desc&quot;&gt;The key of the item&lt;/p&gt;&lt;/li&gt;
 306      * &lt;li&gt;&lt;b&gt;value&lt;/b&gt; : Number&lt;p class=&quot;sub-desc&quot;&gt;The value of the item&lt;/p&gt;&lt;/li&gt;
 307      * &lt;li&gt;&lt;b&gt;length&lt;/b&gt; : Number&lt;p class=&quot;sub-desc&quot;&gt;The total number of items in the hash&lt;/p&gt;&lt;/li&gt;
 308      * &lt;/ul&gt;&lt;/div&gt;
 309      * @param {Function} fn The function to execute.
 310      * @param {Object} scope The scope to execute in. Defaults to &lt;tt&gt;this&lt;/tt&gt;.
 311      * @return {Ext.util.HashMap} this
 312      */
 313     each: function(fn, scope) {
 314         // copy items so they may be removed during iteration.
 315         var items = Ext.apply({}, this.map),
 316             key,
 317             length = this.length;
 318
 319         scope = scope || this;
 320         for (key in items) {
 321             if (items.hasOwnProperty(key)) {
 322                 if (fn.call(scope, key, items[key], length) === false) {
 323                     break;
 324                 }
 325             }
 326         }
 327         return this;
 328     },
 329
 330 <span id='Ext-util-HashMap-method-clone'>    /**
 331 </span>     * Performs a shallow copy on this hash.
 332      * @return {Ext.util.HashMap} The new hash object.
 333      */
 334     clone: function() {
 335         var hash = new this.self(),
 336             map = this.map,
 337             key;
 338
 339         hash.suspendEvents();
 340         for (key in map) {
 341             if (map.hasOwnProperty(key)) {
 342                 hash.add(key, map[key]);
 343             }
 344         }
 345         hash.resumeEvents();
 346         return hash;
 347     },
 348
 349 <span id='Ext-util-HashMap-method-findKey'>    /**
 350 </span>     * @private
 351      * Find the key for a value.
 352      * @param {Object} value The value to find.
 353      * @return {Object} The value of the item. Returns &lt;tt&gt;undefined&lt;/tt&gt; if not found.
 354      */
 355     findKey: function(value) {
 356         var key,
 357             map = this.map;
 358
 359         for (key in map) {
 360             if (map.hasOwnProperty(key) &amp;&amp; map[key] === value) {
 361                 return key;
 362             }
 363         }
 364         return undefined;
 365     }
 366 });
 367 </pre>
 368 </body>
 369 </html>