+ * Represents a collection of a set of key and value pairs. Each key in the HashMap + * must be unique, the same key cannot exist twice. Access to items is provided via + * the key only. Sample usage: + *
+var map = new Ext.util.HashMap();
+map.add('key1', 1);
+map.add('key2', 2);
+map.add('key3', 3);
+
+map.each(function(key, value, length){
+ console.log(key, value, length);
+});
+ * The HashMap is an unordered class, + * there is no guarantee when iterating over the items that they will be in any particular + * order. If this is required, then use a {@link Ext.util.MixedCollection}. + *
+ * @constructor + * @param {Object} config The configuration options + */ +Ext.define('Ext.util.HashMap', { + + /** + * @cfg {Function} keyFn A function that is used to retrieve a default key for a passed object. + * A default is provided that returns the id property on the object. This function is only used + * if the add method is called with a single argument. + */ + + mixins: { + observable: 'Ext.util.Observable' + }, + + constructor: function(config) { + var me = this; + + me.addEvents( + /** + * @event add + * Fires when a new item is added to the hash + * @param {Ext.util.HashMap} this. + * @param {String} key The key of the added item. + * @param {Object} value The value of the added item. + */ + 'add', + /** + * @event clear + * Fires when the hash is cleared. + * @param {Ext.util.HashMap} this. + */ + 'clear', + /** + * @event remove + * Fires when an item is removed from the hash. + * @param {Ext.util.HashMap} this. + * @param {String} key The key of the removed item. + * @param {Object} value The value of the removed item. + */ + 'remove', + /** + * @event replace + * Fires when an item is replaced in the hash. + * @param {Ext.util.HashMap} this. + * @param {String} key The key of the replaced item. + * @param {Object} value The new value for the item. + * @param {Object} old The old value for the item. + */ + 'replace' + ); + + me.mixins.observable.constructor.call(me, config); + me.clear(true); + }, + + /** + * Gets the number of items in the hash. + * @return {Number} The number of items in the hash. + */ + getCount: function() { + return this.length; + }, + + /** + * Implementation for being able to extract the key from an object if only + * a single argument is passed. + * @private + * @param {String} key The key + * @param {Object} value The value + * @return {Array} [key, value] + */ + getData: function(key, value) { + // if we have no value, it means we need to get the key from the object + if (value === undefined) { + value = key; + key = this.getKey(value); + } + + return [key, value]; + }, + + /** + * Extracts the key from an object. This is a default implementation, it may be overridden + * @private + * @param {Object} o The object to get the key from + * @return {String} The key to use. + */ + getKey: function(o) { + return o.id; + }, + + /** + * Adds an item to the collection. Fires the {@link #add} event when complete. + * @param {String} keyThe key to associate with the item, or the new item.
+ *If a {@link #getKey} implementation was specified for this HashMap, + * or if the key of the stored items is in a property called id, + * the HashMap will be able to derive the key for the new item. + * In this case just pass the new item in this parameter.
+ * @param {Object} o The item to add. + * @return {Object} The item added. + */ + add: function(key, value) { + var me = this, + data; + + if (arguments.length === 1) { + value = key; + key = me.getKey(value); + } + + if (me.containsKey(key)) { + me.replace(key, value); + } + + data = me.getData(key, value); + key = data[0]; + value = data[1]; + me.map[key] = value; + ++me.length; + me.fireEvent('add', me, key, value); + return value; + }, + + /** + * Replaces an item in the hash. If the key doesn't exist, the + * {@link #add} method will be used. + * @param {String} key The key of the item. + * @param {Object} value The new value for the item. + * @return {Object} The new value of the item. + */ + replace: function(key, value) { + var me = this, + map = me.map, + old; + + if (!me.containsKey(key)) { + me.add(key, value); + } + old = map[key]; + map[key] = value; + me.fireEvent('replace', me, key, value, old); + return value; + }, + + /** + * Remove an item from the hash. + * @param {Object} o The value of the item to remove. + * @return {Boolean} True if the item was successfully removed. + */ + remove: function(o) { + var key = this.findKey(o); + if (key !== undefined) { + return this.removeAtKey(key); + } + return false; + }, + + /** + * Remove an item from the hash. + * @param {String} key The key to remove. + * @return {Boolean} True if the item was successfully removed. + */ + removeAtKey: function(key) { + var me = this, + value; + + if (me.containsKey(key)) { + value = me.map[key]; + delete me.map[key]; + --me.length; + me.fireEvent('remove', me, key, value); + return true; + } + return false; + }, + + /** + * Retrieves an item with a particular key. + * @param {String} key The key to lookup. + * @return {Object} The value at that key. If it doesn't exist, undefined is returned. + */ + get: function(key) { + return this.map[key]; + }, + + /** + * Removes all items from the hash. + * @return {Ext.util.HashMap} this + */ + clear: function(/* private */ initial) { + var me = this; + me.map = {}; + me.length = 0; + if (initial !== true) { + me.fireEvent('clear', me); + } + return me; + }, + + /** + * Checks whether a key exists in the hash. + * @param {String} key The key to check for. + * @return {Boolean} True if they key exists in the hash. + */ + containsKey: function(key) { + return this.map[key] !== undefined; + }, + + /** + * Checks whether a value exists in the hash. + * @param {Object} value The value to check for. + * @return {Boolean} True if the value exists in the dictionary. + */ + contains: function(value) { + return this.containsKey(this.findKey(value)); + }, + + /** + * Return all of the keys in the hash. + * @return {Array} An array of keys. + */ + getKeys: function() { + return this.getArray(true); + }, + + /** + * Return all of the values in the hash. + * @return {Array} An array of values. + */ + getValues: function() { + return this.getArray(false); + }, + + /** + * Gets either the keys/values in an array from the hash. + * @private + * @param {Boolean} isKey True to extract the keys, otherwise, the value + * @return {Array} An array of either keys/values from the hash. + */ + getArray: function(isKey) { + var arr = [], + key, + map = this.map; + for (key in map) { + if (map.hasOwnProperty(key)) { + arr.push(isKey ? key: map[key]); + } + } + return arr; + }, + + /** + * Executes the specified function once for each item in the hash. + * Returning false from the function will cease iteration. + * + * The paramaters passed to the function are: + *The key of the item
The value of the item
The total number of items in the hash