IndexedMap Class
An ordered, indexed hash map data structure. Like Y.Map and Array got together
and had a beautiful baby.
Provides constant time key-based lookups as well as numerical index-based lookups, splicing, and other array-like functionality. Keys may be any value, including objects.
The Y.IndexedMap class extends Y.Map. See that module's documentation for
more details on Map fundamentals.
Constructor
IndexedMap
-
[entries] -
[options]
Parameters:
-
[entries]Array[] | Map optionalArray or Map of entries to add to this map. If an array, then each entry should itself be an array in which the first item is the key and the second item is the value for that entry.
-
[options]Object optionalOptions.
-
[autoStamp=false]Boolean optionalIf
true, objects used as keys will be automatically stamped with a unique id as the value of the property defined by theobjectIdNameoption ("_yuid" by default) if that property isn't already set. This will result in much faster lookups for object keys. -
[objectIdName="_yuid"]String optionalName of a property whose string value should be used as the unique key when present on an object that's given as a key. This will significantly speed up lookups of object-based keys that define this property.
-
Item Index
Methods
Methods
_defaultSortFn
-
a -
b
Default sort comparator used when sort() is called without a callback.
Returns:
Result of the comparison.
_indexMapKey
-
index -
key
Indexes the given key to enable faster lookups.
Parameters:
-
indexNumberNumerical index of the key in the internal
_mapKeysarray. -
keyMixedKey to index.
_indexOfKey
-
key
Returns the numerical index of the entry with the given key, or -1 if
not found.
This is a very efficient operation with string keys, but may be slower with non-string keys.
Parameters:
-
keyMixedKey to look up.
Returns:
Index of the entry with the given key, or -1 if not
found.
_isSafeKey
-
key
Returns true if the given string key is safe to use in environments that
don't support Object.create().
Parameters:
-
keyStringKey to check.
Returns:
true if the key is safe.
_reindexMap
()
protected
Reindexes all the keys in this map.
_removeMapEntry
-
index
Removes the entry at the given index from internal arrays.
This method does not update the size property.
Parameters:
-
indexNumberIndex of the entry to remove.
_sameValueZero
-
a -
b
Returns true if the two given values are the same value, false
otherwise.
This is an implementation of the ES6 SameValueZero comparison
algorithm. It's more correct than === in that it considers NaN to be the
same as NaN.
Note that 0 and -0 are considered the same by this algorithm.
Parameters:
-
aMixedFirst value to compare.
-
bMixedSecond value to compare.
Returns:
true if a and b are the same value, false
otherwise.
_updateMapSize
()
protected
Updates the value of the size property in old browsers. In ES5 browsers
this is a noop, since the size property is a getter.
clear
()
chainable
Deletes all entries from this map.
concat
-
[maps*]
Returns a new map comprised of this map's entries combined with those of the maps or arrays passed as arguments. Does not alter this map or those given as arguments in any way.
Entries in later (rightmost) arguments will take precedence over entries in earlier (leftmost) arguments if their keys are the same.
This method also accepts arrays of entries in lieu of actual Y.Map instances.
The returned map will be created using the same options and constructor as this map.
Parameters:
Returns:
New map containing the concatenated values of this map and all arguments.
delete
()
Alias for remove().
each
-
callback -
[thisObj]
Executes the given callback function on each entry in this map.
To halt iteration early, return false from the callback.
entries
()
Array
Returns an array of all the entries in this map. Each entry is an array with two items, the first being a key and the second a value associated with that key.
Returns:
Array of entries.
entryAt
-
index
Returns the entry at the given index, or undefined if not found.
An entry is an array with two items, the first being a key and the second a value associated with that key.
Parameters:
-
indexNumberIndex to look up.
Returns:
Entry at the given index, or undefined if not
found.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['b', 'battlestar galactica']
]);
map.entryAt(1); // => ['b', 'battlestar galactica']
map.entryAt(5); // => undefinedforEach
()
Alias for each().
get
-
key -
[defaultValue]
Returns the value associated with the given key, or default if the key isn't found.
Parameters:
-
keyMixedKey to look up.
-
[defaultValue]Mixed optionalDefault value to return if key isn't found.
Returns:
Value associated with the given key, or default if the key isn't found.
has
-
key
Returns true if key exists in this map, false otherwise.
Parameters:
-
keyMixedKey to look up.
Returns:
true if key exists in this map, false otherwise.
indexOfKey
-
key
Returns the numerical index of the entry with the given key, or -1 if
not found.
This is a very efficient operation with string keys, but may be slower with non-string keys.
Parameters:
-
keyMixedKey to look up.
Returns:
Index of the entry with the given key, or -1 if not
found.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['b', 'battlestar galactica']
]);
map.indexOfKey('b'); // => 1
map.indexOfKey('z'); // => -1keyAt
-
index
Returns the key at the given index, or undefined if not found.
Parameters:
-
indexNumberIndex to look up.
Returns:
Key at the given index, or undefined if not found.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['b', 'battlestar galactica']
]);
map.keyAt(0); // => 'a'
map.keyAt(5); // => undefinedmerge
-
maps
Merges the entries from one or more other maps or entry arrays into this map. Entries in later (rightmost) arguments will take precedence over entries in earlier (leftmost) arguments if their keys are the same.
This method also accepts arrays of entries in lieu of actual Y.Map instances, so the following operations have the same result:
// This...
map.merge(new Y.Map([['a', 'apple'], ['b', 'bear']]));
// ...has the same result as this...
map.merge([['a', 'apple'], ['b', 'bear']]);pop
()
Array
Removes the last entry from this map and returns it.
Returns:
Entry that was removed, or undefined if this map is empty.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['b', 'battlestar galactica']
]);
map.pop(); // => ['b', 'battlestar galactica']
map.pop(); // => ['a', 'airwolf']
map.pop(); // => undefinedpush
-
entry
Appends the given entry or entries to the end of this map and returns the map's new size.
Any entries that already exist in this map with the same keys as the new entries will be removed to make way for the new entries, regardless of their position. If this map has been sorted, you may need to re-sort it after appending new entries.
Parameters:
-
entryArray multipleOne or more entries to append to this map.
Returns:
New size of this map.
Example:
var map = new Y.IndexedMap();
map.push(
['a', 'airwolf'],
['b', 'battlestar galactica']
); // => 2
map.get('a'); // => 'airwolf'remove
-
key
Deletes the entry with the given key.
Parameters:
-
keyMixedKey to delete.
Returns:
true if the key existed and was deleted, false
otherwise.
set
-
key -
value
Sets the value of the entry with the given key. If the key already exists, its value will be overwritten; otherwise it will be created.
The key may be any JavaScript value (including both primitives and objects), but string keys will allow fast lookups, whereas non-string keys may result in slower lookups.
Parameters:
-
keyMixedKey to set.
-
valueMixedValue to set.
shift
()
Array
Removes the first entry from this map and returns it. This will cause the indices of subsequent entries in the map to be adjusted.
Returns:
Entry that was removed, or undefined if this map is empty.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['b', 'battlestar galactica']
]);
map.shift(); // => ['a', 'airwolf']
map.shift(); // => ['b', 'battlestar galactica']
map.shift(); // => undefinedslice
-
[begin] -
[end]
Returns a new IndexedMap containing a shallow copy of a portion of this map.
The returned map will be created using the same options and constructor as this map.
This method does not remove any entries or modify this map in any way.
Parameters:
-
[begin]Number optionalZero-based index at which to begin extracting entries. If begin is negative, it will be treated as relative to the end of the map. If begin is omitted, it defaults to
0. -
[end]Number optionalZero-based index at which to end extraction.
slice()extracts entries up to but not including end. If end is negative, it will be treated as relative to the end of the map. If _end is omitted, all elements between begin and the end of the map will be extracted.
Returns:
New IndexedMap containing a shallow copy of the specified portion of this map.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['m', 'manimal'],
['s', 'space: 1999']
]);
map.slice(1, 2);
// => new IndexedMap containing ['m', 'manimal']
map.slice(1);
// => new IndexedMap containing ['m', 'manimal'] and ['s', 'space: 1999']
map.slice(-1);
// => new IndexedMap containing ['s', 'space: 1999']
map.slice(0, -1);
// => new IndexedMap containing ['a', 'airwolf'] and ['m', 'manimal']
map.slice();
// => new IndexedMap containing all three entries (effectively a copy)sort
-
[callback]
Sorts the entries in this map.
If a callback is not given, entries will be sorted by converting their values to strings and comparing the values in lexicographic order (a simple ASCII sort).
If a callback is given, entries will be sorted according to the return value of the callback. The two entries (a and b) passed to the callback are sorted based on the value the callback returns.
The callback should return -1 (or any negative number) to sort a before
b, 0 if a and b are equal, 1 (or any positive number) to sort b
before a.
Parameters:
-
[callback]Function optionalSort comparator callback. Receives two entriess as arguments, and should return an integer indicating whether the first is less than (
-1), equal to (0), or greater than (1) the second.
Example:
var map = new Y.IndexedMap([
[0, 'manimal'],
[1, 'space: 1999'],
[2, 'airwolf']
]);
// ASCII sort by string values (the default).
map.sort();
map.entries();
// => [
// [2, 'airwolf'],
// [0, 'manimal'],
// [1, 'space: 1999']
// ]
// Numerical sort by key (a custom sort).
map.sort(function (a, b) {
return a[0] - b[0];
});
map.entries();
// => [
// [0, 'manimal'],
// [1, 'space: 1999']
// [2, 'airwolf'],
// ]
// Reverse ASCII sort by value (a custom sort).
map.sort(function (a, b) {
var aValue = a[1].toString(),
bValue = b[1].toString();
if (bValue === aValue) {
return 0;
}
return bValue < aValue ? -1 : 1;
});
map.entries();
// => [
// [1, 'space: 1999']
// [0, 'manimal'],
// [2, 'airwolf'],
// ]splice
-
start -
[count] -
[entry*]
Changes the contents of this map, adding new entries while removing old entries.
If one or more new entries are specified, they will be added to this map starting at start.
Any entries that already exist in this map with the same keys as the new entries will be removed to make way for the new entries, regardless of their position. If this map has been sorted, you may need to re-sort it after splicing in new entries.
Parameters:
-
startNumberIndex at which to start changing this map. A negative value will result in a position relative to the end of the map.
-
[count]Number optionalNumber of entries to remove, starting at start. If count is
0, no entries will be removed. If nocountparameter is given, all entries after start will be removed. -
[entry*]Array optionalZero or more new entries to add to this map. Each entry must be an array in which the first element is the key and the second element is the value to add.
Returns:
An array of entries that were removed, if any.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['m', 'manimal'],
['s', 'space: 1999']
]);
// Insert 'battlestar galactica' between 'airwolf' and 'manimal'.
map.splice(1, 0, ['b', 'battlestar galactica']); // => []
// Remove 'manimal'.
map.splice(2, 1); // => [['m', 'manimal']]
// Insert 'mission: impossible' and 'star trek' after
// battlestar galactica. Since 'star trek' reuses the 's' key, the
// 'space: 1999' entry will be removed.
map.splice(2, 0, ['m', 'mission: impossible'], ['s', 'star trek']);
// => [['s', 'space: 1999']]
// Remove everything after 'airwolf', because who needs those shows
// when you've got a show about a badass helicopter?
map.splice(1);
// => [['b', 'battlestar galactica'], ['m', 'mission: impossible'],
// ['s', 'star trek']]toJSON
()
Array
Returns a JSON-serializable representation of this map.
This is effectively an alias for entries(), but could be overridden to
return a customized representation.
Returns:
JSON-serializable array of entries in this map.
unshift
-
entry
Prepends the given entry or entries to the beginning of this map and returns the map's new size.
Any entries that already exist in this map with the same keys as the new entries will be removed to make way for the new entries, regardless of their position. If this map has been sorted, you may need to re-sort it after prepending new entries.
Parameters:
-
entryArray multipleOne or more entries to append to this map.
Returns:
New size of this map.
Example:
var map = new Y.IndexedMap([
['m', 'manimal'],
['s', 'space: 1999']
]);
map.unshift(
['a', 'airwolf'],
['b', 'battlestar galactica']
); // => 2
map.entries();
// => [
// ['a', 'airwolf'],
// ['b', 'battlestar galactica'],
// ['m', 'manimal'],
// ['s', 'space: 1999']
// ]valueAt
-
index
Returns the value at the given index, or undefined if not found.
Parameters:
-
indexNumberIndex to look up.
Returns:
Value at the given index, or undefined if not found.
Example:
var map = new Y.IndexedMap([
['a', 'airwolf'],
['b', 'battlestar galactica']
]);
map.valueAt(0); // => 'airwolf'
map.valueAt(5); // => undefinedProperties
_isIndexStale
Boolean
protected
Whether or not the internal key index is in need of reindexing.
Rather than reindexing immediately whenever it becomes necessary, we use this flag to allow on-demand indexing the first time an up-to-date index is actually needed.
This makes multiple remove() operations significantly faster, at the
expense of a single reindex operation the next time a key is looked up.
_mapKeyIndices
Object
protected
Internal index mapping string keys to their indices in the _mapKeys array.
_mapObjectIndices
Object
protected
Internal index mapping object key ids to their indices in the _mapKeys
array. This is separate from _mapKeyIndices in order to prevent collisions
between object key ids and string keys.