js_cols Class: LinkedHashMap

new LinkedHashMap(opt_maxCount, isLFOcache)

Class for a LinkedHashMap datastructure, which combines O(1) map access for key/value pairs with a linked list for a consistent iteration order. This implementation is based on goog.structs.LinkedMap from the google closure library, but allows any type as keys. It is also possible to obtain an iterator over the values in this implentation, and direct insertion before or after a given key is also supported. Sample usage:

var m = new js_cols.LinkedHashMap();
m.insert('param1', 'A');
m.insert('param2', 'B');
m.insert('param3', 'C');
alert(m.getKeys()); // param1, param2, param3

var c = new js_cols.LinkedHashMap(5, true);
for (var i = 0; i < 10; i++) {
  c.insert('entry' + i, false);
}
alert(c.getKeys()); // entry9, entry8, entry7, entry6, entry5

c.insert('entry5', true);
c.insert('entry1', false);
alert(c.getKeys()); // entry1, entry5, entry9, entry8, entry7

The assymptotic running time for important operations are below:

  Method                 big-O
----------------------------------------------------------------------------
- clear                  O(1)
- clone                  O(n logn)
- contains               O(1)
- containsAll            O(m) m is the cardinality of the supplied collection
- every                  O(n * O(f)) f is the function supplied as argument
- filter                 O(n * O(f)) f is the function supplied as argument
- forEach                O(n * O(f)) f is the function supplied as argument
- get                    O(1)
- getValues              O(n)
- insert                 O(1)
- insertBefore           O(1)
- insertAfter            O(1)
- insertAll              O(m) m is the cardinality of the supplied collection
- map                    O(n * O(f)) f is the function supplied as argument
- peek                   O(1)
- peekLast               O(1)
- peekValue              O(1)
- pop                    O(1)
- remove                 O(1)
- removeAll              O(m logn) m is the cardinality of the supplied collection
- shift                  O(1)
- some                   O(n * O(f)) f is the function supplied as argument
- contains               O(n * O(f)) f is the function supplied as argument

WARNING: keys will be modified, a property named something like "js_cols_uid_2kczq5" will be added. This liberates the user of implementing a getHashCode function, and improves performance as hashing collisions are avoided.

Parameters:

Name	Type	Argument	Description
`opt_maxCount`	number	<optional>	The maximum number of objects to store in the LinkedHashMap. If unspecified or 0, there is no maximum.
`isLFOcache`	boolean	<optional>	When set, the LinkedHashMap stores items in order from most recently used to least recently used, instead of insertion order.

Methods

clear()

Removes all entries in this object.

clone() → {js_cols.LinkedHashMap}

Returns a shallow clone of this LinkedHashMap, containing the same key/value pairs.

Returns:

the new LinkedHashMap.

Type: js_cols.LinkedHashMap

contains(key) → {boolean}

Tests whether a provided key is currently in the LinkedHashMap. This does not affect item ordering in cache-style LinkedHashMaps. This operation is identical to containsKey

Parameters:

Name	Type	Description
`key`	*	The key to check for.

Returns:

Whether the key is in the LinkedHashMap.

Type: boolean

containsAll(col) → {Boolean}

Checks that all values contained in the collection are also contained as keys in the Map

Parameters:

Name	Type	Description
`col`

Returns:

Type: Boolean

containsKey(key) → {boolean}

Tests whether a provided key is currently in the LinkedHashMap. This does not affect item ordering in cache-style LinkedHashMaps.

Parameters:

Name	Type	Description
`key`	*	The key to check for.

Returns:

Whether the key is in the LinkedHashMap.

Type: boolean

containsValue(value) → {boolean}

Tests whether a provided value is currently in the LinkedHashMap. This does not affect item ordering in cache-style LinkedHashMaps.

Parameters:

Name	Type	Description
`value`	*	The value to check for.

Returns:

Whether the value is in the LinkedHashMap.

Type: boolean

every(f, opt_obj) → {boolean}

Calls a function on each item in the LinkedHashMap and returns true only if every function call returns a true-like value.

Parameters:

Name	Type	Argument	Description
`f`	function		The function to call for each item. The function takes three arguments: the value, the key, and the LinkedHashMap, and returns a boolean.
`opt_obj`	Object	<optional>	The object context to use as "this" for the function.

Returns:

Whether f evaluates to true for every item in the LinkedHashMap.

Type: boolean

filter(f, opt_obj) → {js_cols.LinkedHashMap}

Calls a function on each item in the LinkedHashMap, if the function returns true, the key/value pair is inserted into a LinkedHashMap that is returned when all elements in the the map has been visited

Parameters:

Name	Type	Argument	Description
`f`	function		The function to call for each item. The function takes three arguments: the value, the key, and the LinkedHashMap.
`opt_obj`	Object	<optional>	The object context to use as "this" for the function.

Returns:

The key / value pairs that evaluated to true in the function calls for each item in the LinkedHashMap.

Type: js_cols.LinkedHashMap

forEach(f, opt_obj)

Calls a function on each item in the LinkedHashMap.

Parameters:

Name	Type	Argument	Description
`f`	function		The function to call for each item. The function takes three arguments: the value, the key, and the LinkedHashMap.
`opt_obj`	Object	<optional>	The object context to use as "this" for the function.

get(key, opt_val) → {*}

Retrieves the value for a given key. If this is a LRU-caching LinkedHashMap, the entry will become the most recently used.

Parameters:

Name	Type	Argument	Description
`key`	*		The key to retrieve the value for.
`opt_val`	*	<optional>	A default value that will be returned if the key is not found, defaults to undefined.

Returns:

The retrieved value.

Type: *

getCount() → {number}

Returns the current size of the LinkedHashMap (number of key/value pairs)

Returns:

The number of items currently in the LinkedHashMap.

Type: number

getKeys() → {Array}

Inserts all keys of this map into an Array and returns it

Returns:

The list of the keys in the appropriate order for this LinkedHashMap.

Type: Array

getValues() → {Array}

Inserts all Valuesof this map into an Array and returns it

Returns:

The list of the values in the appropriate order for this LinkedHashMap.

Type: Array

insert(key, value)

Sets a value for a given key. If this is a LRUcaching LinkedHashMap, this entry will become the most recently used.

Parameters:

Name	Type	Description
`key`	*	The key to set the value for.
`value`	*	The value associated with the key

insertAfter(exKey, key, value) → {boolean}

Sets a value for a given key, and inserts them after a specified key. If this is a LRUcaching LinkedHashMap, a call to this method will be ignored.

Parameters:

Name	Type	Description
`exKey`	*	a key, after which the new key/value pair should be inserted
`key`	*	The key to set the value for.
`value`	*	The value associated with the key

Returns:

whether the key/value pair was inserted

Type: boolean

insertAll(element)

Inserts a collection of key/value pairs into the LinkedHashMap

Parameters:

Name	Type	Description
`element`	*	the value

insertBefore(exKey, key, value) → {boolean}

Sets a value for a given key, and inserts them before a specified key. If this is a LRUcaching LinkedHashMap, a call to this method will be ignored.

Parameters:

Name	Type	Description
`exKey`	*	a key, before which the new key/value pair should be inserted
`key`	*	The key to set the value for.
`value`	*	The value associated with the key

Returns:

whether the key/value pair was inserted

Type: boolean

intersection(col) → {js_cols.LinkedHashMap}

Finds all key/value pairs that are present in both this map and the given collection. If the collection has no notion of keys (i.e. a Set or an Array), each element of the collection will be treated as key, and it will be inserted to the returned map with its corresponding value from this map.

Parameters:

Name	Type	Description
`col`

Returns:

A new set containing all the key/value pairs (primitives or objects) present in both this set and the given collection.

Type: js_cols.LinkedHashMap

isEmpty() → {Boolean}

Whether the map is empty

Returns:

True if the map is empty, false if it contains any key/value pairs.

Type: Boolean

isSubmapOf(col) → {Boolean}

Detects wheter all key/value pairs present in this map are also present in the given collection. If the collection has no notion of keys (i.e. a Set or an Array), the result will be whether the keys in this map is a subset of the elements in the collection. This operation is O(n O(col.contains)). Example: if col is another LinkedHashMap, running time is O(n), if col is an Array or LinkedList, running time is O(n m), if col is a HashSet, running time is O(n).

Parameters:

Name	Type	Description
`col`

Returns:

wheter this map is a submap of col

Type: Boolean

iterator(key) → {js_cols.LinkedList.LinkedListIterator}

NOTICE: the iterator returned by this method is unable to add, remove or update items Returns an iterator over the values of the list, starting before the first node, if no starting key is specified.

Parameters:

Name	Type	Description
`key`	*	the starting key for the Iterator (if not present in the map, it will start from the beginning of the list)

See:

{js_cols.LinkedList.LinkedListIterator}

Returns:

an iterator over the values in this LinkedHashMap

Type: js_cols.LinkedList.LinkedListIterator

map(f, opt_obj) → {Array}

Calls a function on each item in the LinkedHashMap and returns the results of those calls in an array.

Parameters:

Name	Type	Argument	Description
`f`	function		The function to call for each item. The function takes three arguments: the value, the key, and the LinkedHashMap.
`opt_obj`	Object	<optional>	The object context to use as "this" for the function.

Returns:

The results of the function calls for each item in the LinkedHashMap.

Type: Array

peek() → {*}

Returns the value of the first node without making any modifications.

Returns:

The value of the first node or undefined if the map is empty.

Type: *

peekLast() → {*}

Returns the value of the last node without making any modifications.

Returns:

The value of the last node or undefined if the map is empty.

Type: *

peekValue(key, opt_val) → {*}

Retrieves the value for a given key without updating the entry to be the most recently used.

Parameters:

Name	Type	Argument	Description
`key`	string		The key to retrieve the value for.
`opt_val`	*	<optional>	A default value that will be returned if the key is not found.

Returns:

The retrieved value.

Type: *

pop() → {*}

Removes the last node from the list and returns its value.

Returns:

The value of the popped node, or undefined if the map was empty.

Type: *

remove(key) → {boolean}

Removes a value from the LinkedHashMap based on its key.

Parameters:

Name	Type	Description
`key`	*	The key to remove.

Returns:

True if the entry was removed, false if the key was not found.

Type: boolean

removeAll(col)

Removes a all values contained in the collection from the map The values in the collection are treated as keys in the map, and the values associated with those keys are removed.

Parameters:

Name	Type	Description
`col`

setMaxCount(maxCount)

Sets the maximum number of entries allowed in this object, truncating any excess objects if necessary.

Parameters:

Name	Type	Description
`maxCount`	number	The new maximum number of entries to allow.

shift() → {*}

Removes the first node from the list and returns its value.

Returns:

The value of the popped node, or undefined if the map was empty.

Type: *

some(f, opt_obj) → {boolean}

Calls a function on each item in the LinkedHashMap and returns true if any of those function calls returns a true-like value.

Parameters:

Name	Type	Argument	Description
`f`	function		The function to call for each item. The function takes three arguments: the value, the key, and the LinkedHashMap, and returns a boolean.
`opt_obj`	Object	<optional>	The object context to use as "this" for the function.

Returns:

Whether f evaluates to true for at least one item in the LinkedHashMap.

Type: boolean