Prototype JavaScript framework - Hash

toObject

2007-11-17T15:26:00Z

toObject() -> Object

Returns a cloned, vanilla object.

Examples


var h = new Hash({ a: 'apple', b: 'banana', c: 'coconut' });
var obj = h.toObject();

Object.inspect(h);
// -> #<Hash:{'a': 'kiwi', 'b': 'banana', 'c': 'coconut'}>

Object.inspect(obj);
// -> [object Object]

obj.a = 'orange';
h.get('a');
// -> 'apple'

clone

2007-11-17T15:22:00Z

clone() -> newHash

Returns a clone of hash.

Examples


var h = new Hash({ a: 'apple'});
var clone = h.clone();

h.unset('a');
h.inspect();
// -> #<Hash:{}>

clone.inspect();
// -> #<Hash:{'a': 'apple'}>

update

2007-11-17T14:48:00Z

update(object) -> Hash

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

Duplicate keys will cause an overwrite of hash’s keys. This is useful for selectively overwriting values on specific keys (e.g. exerting some level of control over a series of options).

The argument can be a Hash or just a vanilla Object.

Examples


var h = $H({ name: 'Prototype', version: 1.5 });

h.update({ version: 1.6, author: 'Sam' }).inspect();
// -> #<Hash:{'name': 'Prototype', 'version': 1.6, 'author': 'Sam'}>

h.inspect();
// -> #<Hash:{'name': 'Prototype', 'version': 1.6, 'author': 'Sam'}>

get

2007-11-17T14:19:00Z

get(key) -> value

Returns the value of the hash’s key property.

Examples


var h = new Hash({ a: 'apple', b: 'banana', c: 'coconut' });

h.get('a');
// -> 'apple'

h.get('d');
// -> undefined

unset

2007-11-17T14:13:00Z

unset(key) -> value

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

Examples


var h = new Hash({ a: 'apple', b: 'banana', c: 'coconut' });

h.unset('a');
// -> 'apple'
h.inspect();
// -> #<Hash:{'b': 'banana', 'c': 'coconut'}>

h.unset('d');
// -> undefined
h.inspect();
// -> #<Hash:{'b': 'banana', 'c': 'coconut'}>

set

2007-11-17T14:01:00Z

set(key, value) -> value

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

Examples


var h = new Hash({ a: 'apple', b: 'banana', c: 'coconut' });

h.set('d', 'orange');
// -> 'orange'
h.inspect();
// -> #<Hash:{'a': 'apple', 'b': 'banana', 'c': 'coconut', 'd': 'orange'}>

h.set('a', 'kiwi');
// -> 'kiwi'
h.inspect();
// -> #<Hash:{'a': 'kiwi', 'b': 'banana', 'c': 'coconut', 'd': 'orange'}>

toJSON

2007-03-10T00:54:00Z

toJSON() -> String

Returns a JSON string.

Example


$H({name: 'Violet', occupation: 'character', age: 25 }).toJSON();
//-> '{"name": "Violet", "occupation": "character", "age": 25}'

remove

2007-01-17T10:12:00Z

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

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

This method is not available since Prototype 1.6.0. Use Hash#unset() for removing a value from a Hash instance. For removing multiple values, use a loop:

['foo', 'bar'].each(function(key) {
  hash.unset(key);
});

Examples


var h = new Hash({ a:'apple', b:'banana', c:'coconut' })

h.remove('a', 'c')
// -> ['apple', 'coconut']
h.values()
// -> ['banana']

each

2007-01-06T15:53:00Z

each(iterator) -> Hash

Iterates over the name/value pairs in the hash.

This is actually the each method from the mixed-in Enumerable module. It is documented here to illustrate the structure of the passed first argument, and the order of iteration.

Pairs are passed as the first argument of the iterator, in the form of objects with two properties:

key, which is the key name as a String
value, which is the corresponding value (and can, possibly, be undefined)

The order of iteration is browser-dependent, as it relies on the native for ... in loop. Although most modern browsers exhibit ordered behavior, this may not always be the case, so don't count on it in your scripts.

It is possible to have function values in a hash, though the iteration skips over Hash and Enumerable methods (naturally). More precisely, it skips the properties found on the object's prototype.

Example

var h = $H({ version: 1.5, author: 'Sam Stephenson' });

h.each(function(pair) {
  alert(pair.key + ' = "' + pair.value + '"');
});

// Alerts, in non-guaranteed order: 'version = "1.5"' and 'author = "Sam Stephenson"'

inspect

2007-01-06T15:38:00Z

inspect() -> String

Returns the debug-oriented string representation of the hash.

For more information on inspect methods, see Object.inspect.

Examples

$H({ name: 'Prototype', version: 1.5 }).inspect()
// -> "<#Hash:{name: 'Prototype', version: 1.5}>"

Hashes and ordering

Don’t compare Hash instances by their string representation returned by this method. Although rarely the case, a consistent order of key-value pairs is not guaranteed in JavaScript.

toQueryString

2007-01-02T18:15:00Z

toQueryString() -> String

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

This is a form of serialization, and is mostly useful to provide complex parameter sets for stuff such as objects in the Ajax namespace (e.g. Ajax.Request).

Undefined-value pairs will be serialized as if empty-valued. Array-valued pairs will get serialized with one name/value pair per array element. All values get URI-encoded using JavaScript's native encodeURIComponent function.

The order of pairs in the serialized form is not guaranteed (and mostly irrelevant anyway), except for array-based parts, which are serialized in array order.

Examples

$H({ action: 'ship', order_id: 123, fees: ['f1', 'f2'], 'label': 'a demo' }).toQueryString()
// -> 'action=ship&order_id=123&fees=f1&fees=f2&label=a%20demo'

// an empty hash is an empty query string:
$H().toQueryString()
// -> ''

Using Hash.toQueryString(obj) as a class method has been deprecated. Use it as an instance method only, or use Object.toQueryString instead.

merge

2006-12-07T20:30:00Z

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).

Duplicate keys will cause an overwrite. This is useful for selectively overwriting values on specific keys (e.g. exerting some level of control over a series of options).

The argument can be a Hash or just a vanilla Object.

Examples

As of 1.6.0 Hash#merge returns a new hash:


var h = $H({ name: 'Prototype', version: 1.5 });

h.merge({ version: 1.6, author: 'Sam' }).inspect();
// -> #<Hash:{'name': 'Prototype', 'version': 1.6, 'author': 'Sam'}>

h.inspect();
// -> #<Hash:{'name': 'Prototype', 'version': 1.5}>

Prior to 1.6.0 Hash#merge was destructive:


var h = $H({ name: 'Prototype', version: 1.5 });

h.merge({ version: 1.6, author: 'Sam' }).inspect();
// -> #<Hash:{'name': 'Prototype', 'version': 1.6, 'author': 'Sam'}>

h.inspect();
// -> #<Hash:{'name': 'Prototype', 'version': 1.6, 'author': 'Sam'}>

values

2006-12-07T20:24:00Z

values() -> Array

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

The order of values is browser implementation-dependent (based on the for…in loop on keys), so—although most of the time you will see it as consistent—it’s better not to rely on a specific order. Also remember that the hash may contain values such as null or even undefined.

Examples


$H({ name: 'Prototype', version: 1.5 }).values().sort()
// -> [1.5, 'Prototype']

$H().values()
// -> []

keys

2006-12-07T20:20:00Z

keys() -> [String...]

Provides an Array of keys (that is, property names) for the hash.

Note: the order of key names is browser-dependent (based on the for…in loop). Also, this currently skips any property whose value is a function (such as hash methods).

Examples


$H({ name: 'Prototype', version: 1.5 }).keys().sort()
// -> ['name', 'version']

$H().keys()
// -> []

Hash

2006-12-05T21:47:00Z

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.

Prototype JavaScript framework - Hash

toObject

Examples

clone

Examples

update

Examples

See also

get

Examples

unset

Examples

set

Examples

toJSON

Example

remove

Examples

each

Example

inspect

Examples

Hashes and ordering

toQueryString

Examples

merge

Examples

See also

values

Examples

keys

Examples

Hash

Creating a hash

Backwards compatibility changes in Prototype 1.6

Notes for earlier versions of Prototype (< 1.6)