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