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