Dict.jsm

  • Revision slug: JavaScript_code_modules/Dict.jsm
  • Revision title: Dict.jsm
  • Revision id: 88991
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment fix some incorrect stuff; 165 words added, 228 words removed

Revision Content

{{ gecko_minversion_header("5.0") }}

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

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 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 its key-value pair.

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_inline() }}
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_inline() }}
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.

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 */
} 

Revision Source

<p>{{ gecko_minversion_header("5.0") }}</p>
<p>The <code>Dict.jsm</code> 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:</p>
<pre>Components.utils.import("resource://gre/modules/Dict.jsm");
</pre>
<h2>Creating a dictionary</h2>
<p>You can create a new, empty dictionary by simply calling the <code>Dict()</code> constructor:</p>
<pre>var newDict = new Dict();
</pre>
<p>If you wish, you may also pass in an array of key/value pairs with which to initialize the dictionary:</p>
<pre>var someObj = {};
var newDict = new Dict({key1: "foo", key2: someObj});
</pre>
<p>Note that values may be any JavaScript object type.</p>
<div class="note"><strong>Note:</strong> 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.</div>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>Dict <a href="/en/JavaScript_code_modules/Dict.jsm#copy()" title="en/JavaScript code modules/Dict.jsm#copy()">copy</a>();<br> </code></td> </tr> <tr> <td><code>boolean <a href="/en/JavaScript_code_modules/Dict.jsm#del()" title="en/JavaScript code modules/Dict.jsm#del()">del</a>(<a href="/en/JavaScript/Reference/Global_Objects/String" title="en/JavaScript/Reference/Global Objects/String">String</a> aKey);</code></td> </tr> <tr> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Object" title="en/JavaScript/Reference/Global Objects/Object">Object</a> <a href="/en/JavaScript_code_modules/Dict.jsm#get()" title="en/JavaScript code modules/Dict.jsm#get()">get</a>(</code><code><a href="/en/JavaScript/Reference/Global_Objects/String" title="en/JavaScript/Reference/Global Objects/String">String</a></code><code> </code><code>aKey</code><code>, [optional] </code><code><a href="/en/JavaScript/Reference/Global_Objects/Object" title="en/JavaScript/Reference/Global Objects/Object">Object</a></code><code> aDefault);<br> </code></td> </tr> <tr> <td><code>boolean <a href="/en/JavaScript_code_modules/Dict.jsm#has()" title="en/JavaScript code modules/Dict.jsm#has()">has</a>(</code><code><a href="/en/JavaScript/Reference/Global_Objects/String" title="en/JavaScript/Reference/Global Objects/String">String</a></code><code> </code><code>aKey</code><code>);</code></td> </tr> <tr> <td><code>Array <a href="/en/JavaScript_code_modules/Dict.jsm#listitems()" title="en/JavaScript code modules/Dict.jsm#listitems()">listitems</a>();<br> </code></td> </tr> <tr> <td><code>Array <a href="/en/JavaScript_code_modules/Dict.jsm#listkeys()" title="en/JavaScript code modules/Dict.jsm#listkeys()">listkeys</a>();<br> </code></td> </tr> <tr> <td><code>Array <a href="/en/JavaScript_code_modules/Dict.jsm#listvalues()" title="en/JavaScript code modules/Dict.jsm#listvalues()">listvalues</a>();<br> </code></td> </tr> <tr> <td><code>void <a href="/en/JavaScript_code_modules/Dict.jsm#set()" title="en/JavaScript code modules/Dict.jsm#set()">set</a>(String </code><code>aKey</code><code>, </code><code><a href="/en/JavaScript/Reference/Global_Objects/Object" title="en/JavaScript/Reference/Global Objects/Object">Object</a></code><code> aValue);<br> </code></td> </tr> <tr> <td><code><a href="/en/JavaScript/Reference/Global_Objects/String" title="en/JavaScript/Reference/Global Objects/String">String</a></code><code> <a href="/en/JavaScript_code_modules/Dict.jsm#toString()" title="en/JavaScript code modules/Dict.jsm#toString()">toString</a>();<br> </code></td> </tr> </tbody>
</table>
<h2>Properties</h2>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>count</code></td> <td><a href="/en/JavaScript/Reference/Global_Objects/Number" title="en/JavaScript/Reference/Global Objects/Number"><code>Number</code></a></td> <td>The number of items in the dictionary.</td> </tr> <tr> <td>items</td> <td>Iterator</td> <td> <p>Returns an iterator over all of the items in the dictionary; each item is returned as its key-value pair.</p> <div class="note"><strong>Note:</strong> 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.</div> </td> </tr> <tr> <td>keys</td> <td>Iterator</td> <td> <p>Returns an iterator over all the keys in the dictionary.</p> <div class="note"><strong>Note:</strong> 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.</div> </td> </tr> <tr> <td>values</td> <td>Iterator</td> <td> <p>Returns an iterator over all the values in the dictionary.</p> <div class="note"><strong>Note:</strong> 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.</div> </td> </tr> </tbody>
</table>
<h2>Constructor</h2>
<h2>Dict()</h2>
<p>Creates and returns a new dictionary object.</p>
<pre>Dict Dict();

Dict Dict(
  Object initalKeysAndValues
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>initialKeysAndValues</code> {{ optional_inline() }}</dt> <dd>A object containing key/value pairs with which to initialize the dictionary.</dd>
</dl>
<h6>Return value</h6>
<p>A newly created dictionary object implementing the methods described in this article.</p>
<h2 name="Methods">Methods</h2>
<h2>copy()</h2>
<p>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.</p>
<pre>Dict copy();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>A new dictionary object containing the same top-level items as the original dictionary on which the <code>copy()</code> method was called.</p>
<h2>del()</h2>
<p>Deletes a key/value pair from the dictionary, given a key.</p>
<pre>boolean del(
  String aKey
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aKey</code></dt> <dd>The key for the item to delete from the dictionary.</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if an entry was found and removed; <code>false</code> if no match was found.</p>
<h2>get()</h2>
<p>Returns the value corresponding to the specified key.</p>
<pre><code>Object get(<br>  String </code><code>aKey</code><code>,<br>  [optional] Object aDefault<br>);</code>
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aKey</code></dt> <dd>The key whose value should be returned.</dd> <dt><code>aDefault</code> {{ optional_inline() }}</dt> <dd>The value to return if the specified key isn't found. If you don't specify a default value, <code>undefined</code> is returned for keys that aren't found.</dd>
</dl>
<h6>Return value</h6>
<p>The value of the specified key, or <code>undefined</code> if no matching key was found.</p>
<h2>has()</h2>
<p>Determines whether or not the specified key exists in the dictionary.</p>
<pre><code>boolean has(<br>  String </code><code>aKey<br></code><code>);</code>
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aKey</code></dt> <dd>The key for which to determine existence in the dictionary.</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the specified key is in the dictionary, otherwise <code>false</code>.</p>
<h2>listitems()</h2>
<p>Returns an array of the key/value pairs in the dictionary.</p>
<div class="note"><strong>Note:</strong> The order in which items are returned is arbitrary.</div>
<pre>Array listitems();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>An array of the key/value pairs in the dictionary.</p>
<h2>listkeys()</h2>
<p>Returns an array of the keys in the dictionary.</p>
<div class="note"><strong>Note:</strong> The order in which items are returned is arbitrary.</div>
<pre>Array listkeys();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>An array of the keys in the dictionary.</p>
<h2>listvalues()</h2>
<p>Returns an array of the values in the dictionary.</p>
<div class="note"><strong>Note:</strong> The order in which items are returned is arbitrary.</div>
<pre>Array listvalues();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>An array of the values in the dictionary.</p>
<h2>set()</h2>
<p>Sets the value for a given key, adding a new key to the dictionary if necessary.</p>
<pre><code>void set(<br>  String </code><code>aKey</code><code>,<br>  Object aValue<br>);</code>
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aKey</code></dt> <dd>The key whose value is to be set.</dd> <dt><code>aValue</code></dt> <dd>The value to assign to the given key.</dd>
</dl>
<h2>toString()</h2>
<p>Returns a string representation of the dictionary.</p>
<pre>String toString();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p>A string representation of the dictionary's key/value pairs. This will be "{}" for an empty dictionary.</p>
<h2>Examples</h2>
<h3>Creating and populating a dictionary</h3>
<p>This example creates a new dictionary and adds some key/value pairs to it.</p>
<pre class="brush: js">var myDict = new Dict();
myDict.set("name", "John Smith");
myDict.set("email", "jsmith@example.com");
myDict.set("phone", "650-555-1234"); 
</pre>
<h3>Working with existing keys</h3>
<p>You can then check to see if a given key exists:</p>
<pre class="brush: js">if (myDict.has("email")) {
  /* an "email" key exists on the object */
} 
</pre>
Revert to this revision