util/collection

We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.

Don't use these techniques to develop new add-ons. Use WebExtensions instead.

If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions instead.

Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Unstable

A simple list-like class and utilities for using it.

Usage

A collection is ordered, like an array, but its items are unique, like a set.

Globals

Constructors

Collection([array])

Creates a new collection. The collection is backed by an array.

Parameters

array : array
If array is given, it will be used as the backing array. This way the caller can fully control the collection. Otherwise a new empty array will be used, and no one but the collection will have access to it.

Functions

addCollectionProperty(object, propName, [backingArray])

Adds a collection property to the given object. Setting the property to a scalar value empties the collection and adds the value. Setting it to an array empties the collection and adds all the items in the array.

Parameters

object : object
The property will be defined on this object.

propName : string
The name of the property.

backingArray : array
If given, this will be used as the collection's backing array.

Collection

A collection object provides for...in-loop iteration. Items are yielded in the order they were added. For example, the following code...

var collection = require("sdk/util/collection");
var c = new collection.Collection();
c.add(1);
c.add(2);
c.add(3);
for (item in c)
  console.log(item);

... would print this to the console:

  1
  2
  3

Iteration proceeds over a copy of the collection made before iteration begins, so it is safe to mutate the collection during iteration; doing so does not affect the results of the iteration.

Methods

add(itemOrItems)

Adds a single item or an array of items to the collection. Any items already contained in the collection are ignored.

Parameters

itemOrItems : object
An item or array of items.

Returns

Collection : The Collection.

remove(itemOrItems)

Removes a single item or an array of items from the collection. Any items not contained in the collection are ignored.

Parameters

itemOrItems : object
An item or array of items.

Returns

Collection : The Collection.

Properties

length

The number of items in the collection array.

Document Tags and Contributors

 Contributors to this page: wbamberg, n8chz, jsantell
 Last updated by: wbamberg,