michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: "use strict";
michael@0: 
michael@0: module.metadata = {
michael@0:   "stability": "experimental"
michael@0: };
michael@0: 
michael@0: exports.Collection = Collection;
michael@0: 
michael@0: /**
michael@0:  * Adds a collection property to the given object.  Setting the property to a
michael@0:  * scalar value empties the collection and adds the value.  Setting it to an
michael@0:  * array empties the collection and adds all the items in the array.
michael@0:  *
michael@0:  * @param obj
michael@0:  *        The property will be defined on this object.
michael@0:  * @param propName
michael@0:  *        The name of the property.
michael@0:  * @param array
michael@0:  *        If given, this will be used as the collection's backing array.
michael@0:  */
michael@0: exports.addCollectionProperty = function addCollProperty(obj, propName, array) {
michael@0:   array = array || [];
michael@0:   let publicIface = new Collection(array);
michael@0: 
michael@0:   Object.defineProperty(obj, propName, {
michael@0:     configurable: true,
michael@0:     enumerable: true,
michael@0: 
michael@0:     set: function set(itemOrItems) {
michael@0:       array.splice(0, array.length);
michael@0:       publicIface.add(itemOrItems);
michael@0:     },
michael@0: 
michael@0:     get: function get() {
michael@0:       return publicIface;
michael@0:     }
michael@0:   });
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * A collection is ordered, like an array, but its items are unique, like a set.
michael@0:  *
michael@0:  * @param array
michael@0:  *        The collection is backed by an array.  If this is given, it will be
michael@0:  *        used as the backing array.  This way the caller can fully control the
michael@0:  *        collection.  Otherwise a new empty array will be used, and no one but
michael@0:  *        the collection will have access to it.
michael@0:  */
michael@0: function Collection(array) {
michael@0:   array = array || [];
michael@0: 
michael@0:   /**
michael@0:    * Provides iteration over the collection.  Items are yielded in the order
michael@0:    * they were added.
michael@0:    */
michael@0:   this.__iterator__ = function Collection___iterator__() {
michael@0:     let items = array.slice();
michael@0:     for (let i = 0; i < items.length; i++)
michael@0:       yield items[i];
michael@0:   };
michael@0: 
michael@0:   /**
michael@0:    * The number of items in the collection.
michael@0:    */
michael@0:   this.__defineGetter__("length", function Collection_get_length() {
michael@0:     return array.length;
michael@0:   });
michael@0: 
michael@0:   /**
michael@0:    * Adds a single item or an array of items to the collection.  Any items
michael@0:    * already contained in the collection are ignored.
michael@0:    *
michael@0:    * @param  itemOrItems
michael@0:    *         An item or array of items.
michael@0:    * @return The collection.
michael@0:    */
michael@0:   this.add = function Collection_add(itemOrItems) {
michael@0:     let items = toArray(itemOrItems);
michael@0:     for (let i = 0; i < items.length; i++) {
michael@0:       let item = items[i];
michael@0:       if (array.indexOf(item) < 0)
michael@0:         array.push(item);
michael@0:     }
michael@0:     return this;
michael@0:   };
michael@0: 
michael@0:   /**
michael@0:    * Removes a single item or an array of items from the collection.  Any items
michael@0:    * not contained in the collection are ignored.
michael@0:    *
michael@0:    * @param  itemOrItems
michael@0:    *         An item or array of items.
michael@0:    * @return The collection.
michael@0:    */
michael@0:   this.remove = function Collection_remove(itemOrItems) {
michael@0:     let items = toArray(itemOrItems);
michael@0:     for (let i = 0; i < items.length; i++) {
michael@0:       let idx = array.indexOf(items[i]);
michael@0:       if (idx >= 0)
michael@0:         array.splice(idx, 1);
michael@0:     }
michael@0:     return this;
michael@0:   };
michael@0: };
michael@0: 
michael@0: function toArray(itemOrItems) {
michael@0:   let isArr = itemOrItems &&
michael@0:               itemOrItems.constructor &&
michael@0:               itemOrItems.constructor.name === "Array";
michael@0:   return isArr ? itemOrItems : [itemOrItems];
michael@0: }