Dict.jsm

The Dict.jsm JavaScript code module offers routines for managing dictionaries of key/value pairs. To use it, you first need to import the code module into your JavaScript scope:

Components.utils.import("resource://gre/modules/Dict.jsm");

Creating a dictionary

You can create a new, empty dictionary by simply calling the Dict() constructor:

var newDict = new Dict();

If you wish, you may also pass in an object literal of key/value pairs with which to initialize the dictionary:

var someObj = {};
var newDict = new Dict({key1: "foo", key2: someObj});

Note that values may be any JavaScript object type.

In Firefox 19 and above, you may also pass a JSON String to initialize the dictionary:

var someJSON = '{key1: "foo", key2: {}}';
var newDict = new Dict(someJSON);

Method overview

Properties

Constructor

Dict()

Creates and returns a new dictionary object.

Dict Dict();

Dict Dict(
  Object initalKeysAndValues
); 

Parameters

initialKeysAndValues Optional

A object containing key/value pairs with which to initialize the dictionary.

Return value

A newly created dictionary object implementing the methods described in this article.

Methods

copy()

Returns a shallow copy of the dictionary; that is, a copy of the dictionary including the items immediately included within the dictionary; however, any objects referenced by those top-level objects are not copied.

Dict copy();

Parameters

None.

Return value

A new dictionary object containing the same top-level items as the original dictionary on which the copy() method was called.

del()

Deletes a key/value pair from the dictionary, given a key.

boolean del(
  String aKey
); 

Parameters

aKey

The key for the item to delete from the dictionary.

Return value

true if an entry was found and removed; false if no match was found.

get()

Returns the value corresponding to the specified key.

Object get(
  String aKey,
  [optional] Object aDefault
);

Parameters

aKey

The key whose value should be returned.

aDefault Optional

The value to return if the specified key isn't found. If you don't specify a default value, undefined is returned for keys that aren't found.

Return value

The value of the specified key, or undefined if no matching key was found.

has()

Determines whether or not the specified key exists in the dictionary.

boolean has(
  String aKey
);

Parameters

aKey

The key for which to determine existence in the dictionary.

Return value

true if the specified key is in the dictionary, otherwise false.

listitems()

Returns an array of the key/value pairs in the dictionary.

Array listitems();

Parameters

None.

Return value

An array of the key/value pairs in the dictionary.

listkeys()

Returns an array of the keys in the dictionary.

Array listkeys();

Parameters

None.

Return value

An array of the keys in the dictionary.

listvalues()

Returns an array of the values in the dictionary.

Array listvalues();

Parameters

None.

Return value

An array of the values in the dictionary.

set()

Sets the value for a given key, adding a new key to the dictionary if necessary.

void set(
  String aKey,
  Object aValue
);

Parameters

aKey

The key whose value is to be set.

aValue

The value to assign to the given key.

toJSON()

Returns a JSON String representation of the dictionary.

String toJSON();

Parameters

None.

Return value

A JSON String representation of the dictionary's key/value pairs. This will be "{}" for an empty dictionary.

toString()

Returns a string representation of the dictionary.

String toString();

Parameters

None.

Return value

A string representation of the dictionary's key/value pairs. This will be "{}" for an empty dictionary.

Examples

Creating and populating a dictionary

This example creates a new dictionary and adds some key/value pairs to it.

var myDict = new Dict();
myDict.set("name", "John Smith");
myDict.set("email", "[email protected]");
myDict.set("phone", "650-555-1234"); 

Working with existing keys

You can then check to see if a given key exists:

if (myDict.has("email")) {
  /* an "email" key exists on the object */
}