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.