Dict.jsm

Introduced in Firefox 5, this is now obsolete and has been removed in Firefox 40: use ES2015 Map.

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.

Note: You can actually specify non-strings as keys; these are converted to strings before being used, so they're documented here as if they were a string parameter.

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);
Note: Any String you pass will be assumed to be JSON.

Method overview

Dict copy();
boolean del(String aKey);
Object get(String aKey, [optional] Object aDefault);
boolean has(String aKey);
Array listitems();
Array listkeys();
Array listvalues();
void set(String aKey, Object aValue);
String toJSON();
String toString();

Properties

Attribute Type Description
count Number The number of items in the dictionary.
items Iterator

Returns an iterator over all of the items in the dictionary; each item is returned as a pair (a two-element array) with the first element being the key and the second being the value.

Note: The order in which items are returned is arbitrary, and may change without notice. In addition, if the dictionary changes during iteration, no guarantees are made as to what will happen.
keys Iterator

Returns an iterator over all the keys in the dictionary.

Note: The order in which items are returned is arbitrary, and may change without notice. In addition, if the dictionary changes during iteration, no guarantees are made as to what will happen.
values Iterator

Returns an iterator over all the values in the dictionary.

Note: The order in which items are returned is arbitrary, and may change without notice. In addition, if the dictionary changes during iteration, no guarantees are made as to what will happen.

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.

Note: The order in which items are returned is arbitrary.
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.

Note: The order in which items are returned is arbitrary.
Array listkeys();
Parameters

None.

Return value

An array of the keys in the dictionary.

listvalues()

Returns an array of the values in the dictionary.

Note: The order in which items are returned is arbitrary.
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", "jsmith@example.com");
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 */
}

Document Tags and Contributors

Tags: 
 Contributors to this page: kdex, teoli, gfritzsche, hobophobe, Sid0, Sheppy
 Last updated by: kdex,