Hash |
Hash can be thought of as an associative array, binding unique keys to values (which are not necessarily unique), though it can not guarantee consistent order its elements when iterating. Because of the nature of JavaScript programming language, every object is in fact a hash; but Hash adds a number of methods that let you enumerate keys and values, iterate over key/value pairs, merge two hashes together, encode the hash into a query string representation, etc.
On this page
There are two ways to construct a Hash instance: the first is regular JavaScript object instantiation with the new keyword, and the second is using the $H function. Passing a plain JavaScript object to any of them would clone it, keeping your original object intact, but passing a Hash instance to $H will return the same instance unchanged.
You can call both constructor methods without arguments, too; they will assume an empty hash.
var h = $H({ name: 'Prototype', version: 1.5 }); // equivalent: var h = new Hash({ ... });
h.keys().sort().join(', ') // -> 'name, version'
h.merge({ version: '1.5 final', author: 'Sam Stephenson' }); h.each(function(pair) { alert(pair.key + ' = "' + pair.value + '"'); }); // Alerts, in non-guaranteed order, 'name = "Prototype"', 'version = "1.5 final"' and 'author = "Sam Stephenson"'.
$H({ action: 'ship', order_id: 123, fees: ['fee1', 'fee2'] }).toQueryString() // -> action=ship&order_id=123&fees=fee1&fees=fee2
Hash can not hold any key because of having Enumerable mixed in, as well as its own methods. After adding a key that has the same name as any of those methods, this method will no longer be callable. You can get away with doing that to methods you will not need, but imagine the following:
var h = new Hash({ ... }); h['each'] = 'my own stuff'; h.map(); // -> errors out because 'each' is not a function
The most important method in Enumerable is ‘each’, and—since almost every other method uses it—overwriting it renders our hash instance practically useless. You won’t get away with using ‘_each’, too, since it also is an internal Enumerable method.
each
each(iterator) -> Hash
Iterates over the name/value pairs in the hash.
inspect
inspect() -> String
Returns the debug-oriented string representation of the hash.
keys
keys() -> [String...]
Provides an Array of keys (that is, property names) for the hash.
merge
merge(hash) -> alteredHash
Injects all the pairs in the given hash into the current one, which is then returned.
remove
remove(key) -> value remove(key1, key2...) -> Array
Removes keys from a hash and returns their values.
toQueryString
toQueryString() -> String
Turns a hash into its URL-encoded query string representation.
values
values() -> Array
Collect the values of a hash and returns them in an array.
|
Prototype API 1.5.0 - prototypejs.org