• clone
• each
• get
• inspect
• keys
• merge
• remove
• set
• toJSON
• toObject
• toQueryString
• unset
• update
• values

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.

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 or a Hash to any of them would clone it, keeping your original object intact.

You can call both constructor methods without arguments, too; they will assume an empty hash.

Backwards compatibility changes in Prototype 1.6

Backwards compatibility change - Although it serves the same purpose as before, the new version of Hash is not compatible with the Hash class in previous versions of Prototype.

Hash properties are now hidden away in a private store to prevent the risk of collision with Hash’s instance and mixed-in methods. This means that properties of the hash can no longer be set, accessed or deleted directly; you must use the Hash#get(key), Hash#set(key, value) and Hash#unset(key) instance methods instead. To illustrate:

var myhash = new Hash();

// old API  -->  new API
myhash.name = "Bob";  -->  myhash.set('name', 'Bob');
myhash.name;          -->  myhash.get('name');
delete myhash.name;   -->  myhash.unset('name');

You should also be aware of other changes to the Hash API:

• The $H(object) shortcut is now completely equivalent to new Hash(object). Both always return a new object, regardless of whether the argument was an Object or another Hash.
• Hash#merge returns a new Hash instead of modifying the Hash it’s called on.
• Hash#update is a destructive version of Hash#merge that modifies the Hash it’s called on.
• Hash#clone returns a new, cloned instance of Hash.
• Hash#toObject that returns a copy of the Hash’s inner Object.
• Hash.toQueryString is now an alias of Object.toQueryString. (Hash.toQueryString is deprecated and will be removed in a future version of Prototype.)
• Hash#remove has been removed in favor of Hash#unset.
• Hash.toJSON has been removed in favor of Object.toJSON or the Hash#toJSON instance method.

Notes for earlier versions of Prototype (< 1.6)

Passing a hash to $H did not clone it.

Hash could not hold any key because of having Enumerable mixed in, as well as its own methods. After adding a key that had the same name as any of those methods, this method would no longer be callable. You could get away with doing that to methods you didn’t need, but there were still issues:

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 couldn’t get away with using ‘_each’, too, since it also is an internal Enumerable method.

Methods

clone() -> newHash

each(iterator) -> Hash

get(key) -> value

inspect() -> String

keys() -> [String...]

merge(object) -> newHash

remove(key) -> value
remove(key1, key2...) -> Array

set(key, value) -> value

toJSON() -> String

toObject() -> Object

toQueryString() -> String

unset(key) -> value

update(object) -> Hash

values() -> Array