RefKeyDictionary interface

A JavaScript object implementing the RefKeyDictionary interface represents a dictionary with Ref keys and any JavaScript object as a value.

A JavaScript Object can be used as a lookup dictionary with the [] operator, as long as the keys are strings or numbers. This is very useful, but the limitation on the keys can be annoying when you’re writing a plugin and want to look up things based on a Ref.

RefKeyDictionary objects are provided as a work around for this limitation. They don’t have quite the same interface as a JavaScript Object (so that the fundamental rules of the language still apply). As a bonus, they can be constructed with an optional value constructor function which is called to create the value for unknown keys.

You might find that RefKeyDictionaryHierarchical is more useful when dealing with hierarchical object structures, for example, types and subtypes.

Construction

Use O.refdict(). Pass in an optional value constructor function and size hint.

Interface

In the interface below, key is a Ref object or a String which can be converted to a Ref. Any other value will cause an exception to be thrown.

property length

The number of key value pairs in this dictionary.

function get(key)

Gets the value for a given key.

If set() has not been used to set a value for this key, and a value constructor function was passed in to O.refdict(), that function will be called with the key (converted to a Ref if it’s a String) as the only argument. The returned value from this function will be set for this key as if set() had been called, then returned.

Returns the value for this key, or undefined if no value has been set.

function set(key, value)

Set the value for a given key. value must not be null or undefined.

Returns value.

function remove(key)

Removes the value for the given key.

Returns the value, if one had been set, or undefined.

(This function cannot be called delete() because it would be a syntax error.)

function each(iterator)

The iterator function is called once for each key value pair, with arguments (key, value).

Return true from the iterator function to stop the iteration immediately.