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

· | Creating a hash

· | A combined example

· | Notes!

· | Moduleindex

Creating a hash

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.

A combined example

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

Notes

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.

Moduleindex

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