docs/source/HashMap.html

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