Hash Atom feed

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
1.6

clone() -> newHash

Returns a clone of hash.

each

each(iterator) -> Hash

Iterates over the name/value pairs in the hash.

get
1.6

get(key) -> value

Returns the value of the hash’s key property.

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
1.6 modified

merge(object) -> newHash

Merges object to hash and returns the result of that merge. Prior to v1.6.0: This was destructive (object's values were added to hash). Since v1.6.0: This is no longer destructive (hash is cloned before the operation).

remove
deprecated

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

Removes keys from a hash and returns their values. Not available since v1.6.0.

set
1.6

set(key, value) -> value

Sets the hash’s key property to value and returns value.

toJSON
1.5.1

toJSON() -> String

Returns a JSON string.

toObject
1.6

toObject() -> Object

Returns a cloned, vanilla object.

toQueryString
1.6 modified

toQueryString() -> String

Turns a hash into its URL-encoded query string representation.

unset
1.6

unset(key) -> value

Deletes the hash’s key property and returns its value.

update
1.6

update(object) -> Hash

Updates hash with the key/value pairs of object. The original hash will be modified.

values

values() -> Array

Collect the values of a hash and returns them in an array.