Revision 509085 of util/collection

<div class="note">
 <p>Unstable</p>
</div>
<p><span class="seoSummary">A simple list-like class and utilities for using it.</span></p>
<h2 id="Usage">Usage</h2>
<p>A collection is ordered, like an array, but its items are unique, like a set.</p>
<h2 id="Globals">Globals</h2>
<h3 id="Constructors">Constructors</h3>
<h4 class="addon-sdk-api-name" id="Collection(array)"><code>Collection(array)</code></h4>
<p>Creates a new collection. The collection is backed by an array.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>array : array</strong><br />
 If <em>array</em> 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.</p>
<h3 id="Functions">Functions</h3>
<h4 class="addon-sdk-api-name" id="addCollectionProperty(object.2C_propName.2C_backingArray)"><code>addCollectionProperty(object, propName, backingArray)</code></h4>
<p>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.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>object : object</strong><br />
 The property will be defined on this object.</p>
<p><strong>propName : string</strong><br />
 The name of the property.</p>
<p><strong>backingArray : array</strong><br />
 If given, this will be used as the collection's backing array.</p>
<h2 id="Collection">Collection</h2>
<p>A collection object provides for...in-loop iteration. Items are yielded in the order they were added. For example, the following code...</p>
<pre class="brush: js">
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);</pre>
<p>... would print this to the console:</p>
<pre>
  1
  2
  3
</pre>
<p>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.</p>
<h3 id="Methods">Methods</h3>
<h4 class="addon-sdk-api-name" id="add(itemOrItems)"><code>add(itemOrItems)</code></h4>
<p>Adds a single item or an array of items to the collection. Any items already contained in the collection are ignored.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>itemOrItems : object</strong><br />
 An item or array of items.</p>
<h5 id="Returns">Returns</h5>
<p><strong>Collection</strong> : The Collection.</p>
<h4 class="addon-sdk-api-name" id="remove(itemOrItems)"><code>remove(itemOrItems)</code></h4>
<p>Removes a single item or an array of items from the collection. Any items not contained in the collection are ignored.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>itemOrItems : object</strong><br />
 An item or array of items.</p>
<h5 id="Returns">Returns</h5>
<p><strong>Collection</strong> : The Collection.</p>
<h3 id="Properties">Properties</h3>
<h4 class="addon-sdk-api-name" id="length"><code>length</code></h4>
<p>The number of items in the collection array.</p>