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: "use strict";
michael@0: 
michael@0: module.metadata = {
michael@0:   "stability": "experimental"
michael@0: };
michael@0: 
michael@0: const { Trait } = require('../deprecated/traits');
michael@0: const { iteratorSymbol } = require('../util/iteration');
michael@0: 
michael@0: /**
michael@0:  * @see https://jetpack.mozillalabs.com/sdk/latest/docs/#module/api-utils/list
michael@0:  */
michael@0: const Iterable = Trait.compose({
michael@0:   /**
michael@0:    * Hash map of key-values to iterate over.
michael@0:    * Note: That this property can be a getter if you need dynamic behavior.
michael@0:    * @type {Object}
michael@0:    */
michael@0:   _keyValueMap: Trait.required,
michael@0:   /**
michael@0:    * Custom iterator providing `Iterable`s enumeration behavior.
michael@0:    * @param {Boolean} onKeys
michael@0:    */
michael@0:   __iterator__: function __iterator__(onKeys, onKeyValue) {
michael@0:     let map = this._keyValueMap;
michael@0:     for (let key in map)
michael@0:       yield onKeyValue ? [key, map[key]] : onKeys ? key : map[key];
michael@0:   }
michael@0: });
michael@0: exports.Iterable = Iterable;
michael@0: 
michael@0: /**
michael@0:  * An ordered collection (also known as a sequence) disallowing duplicate
michael@0:  * elements. List is composed out of `Iterable` there for it provides custom
michael@0:  * enumeration behavior that is similar to array (enumerates only on the
michael@0:  * elements of the list). List is a base trait and is meant to be a part of
michael@0:  * composition, since all of it's API is private except length property.
michael@0:  */
michael@0: const listOptions = {
michael@0:   _keyValueMap: null,
michael@0:   /**
michael@0:    * List constructor can take any number of element to populate itself.
michael@0:    * @params {Object|String|Number} element
michael@0:    * @example
michael@0:    *    List(1,2,3).length == 3 // true
michael@0:    */
michael@0:   constructor: function List() {
michael@0:     this._keyValueMap = [];
michael@0:     for (let i = 0, ii = arguments.length; i < ii; i++)
michael@0:       this._add(arguments[i]);
michael@0:   },
michael@0:   /**
michael@0:    * Number of elements in this list.
michael@0:    * @type {Number}
michael@0:    */
michael@0:   get length() this._keyValueMap.length,
michael@0:    /**
michael@0:     * Returns a string representing this list.
michael@0:     * @returns {String}
michael@0:     */
michael@0:   toString: function toString() 'List(' + this._keyValueMap + ')',
michael@0:   /**
michael@0:    * Returns `true` if this list contains the specified `element`.
michael@0:    * @param {Object|Number|String} element
michael@0:    * @returns {Boolean}
michael@0:    */
michael@0:   _has: function _has(element) 0 <= this._keyValueMap.indexOf(element),
michael@0:   /**
michael@0:    * Appends the specified `element` to the end of this list, if it doesn't
michael@0:    * contains it. Ignores the call if `element` is already contained.
michael@0:    * @param {Object|Number|String} element
michael@0:    */
michael@0:   _add: function _add(element) {
michael@0:     let list = this._keyValueMap,
michael@0:         index = list.indexOf(element);
michael@0:     if (0 > index)
michael@0:       list.push(this._public[list.length] = element);
michael@0:   },
michael@0:   /**
michael@0:    * Removes specified `element` from this list, if it contains it.
michael@0:    * Ignores the call if `element` is not contained.
michael@0:    * @param {Object|Number|String} element
michael@0:    */
michael@0:   _remove: function _remove(element) {
michael@0:     let list = this._keyValueMap,
michael@0:         index = list.indexOf(element);
michael@0:     if (0 <= index) {
michael@0:       delete this._public[list.length - 1];
michael@0:       list.splice(index, 1);
michael@0:       for (let length = list.length; index < length; index++)
michael@0:         this._public[index] = list[index];
michael@0:     }
michael@0:   },
michael@0:   /**
michael@0:    * Removes all of the elements from this list.
michael@0:    */
michael@0:   _clear: function _clear() {
michael@0:     for (let i = 0, ii = this._keyValueMap.length; i < ii; i ++)
michael@0:       delete this._public[i];
michael@0:     this._keyValueMap.splice(0);
michael@0:   },
michael@0:   /**
michael@0:    * Custom iterator providing `List`s enumeration behavior.
michael@0:    * We cant reuse `_iterator` that is defined by `Iterable` since it provides
michael@0:    * iteration in an arbitrary order.
michael@0:    * @see https://developer.mozilla.org/en/JavaScript/Reference/Statements/for...in
michael@0:    * @param {Boolean} onKeys
michael@0:    */
michael@0:   __iterator__: function __iterator__(onKeys, onKeyValue) {
michael@0:     let array = this._keyValueMap.slice(0),
michael@0:         i = -1;
michael@0:     for (let element of array)
michael@0:       yield onKeyValue ? [++i, element] : onKeys ? ++i : element;
michael@0:   },
michael@0: };
michael@0: listOptions[iteratorSymbol] = function* iterator() {
michael@0:   let array = this._keyValueMap.slice(0);
michael@0: 
michael@0:   for (let element of array)
michael@0:     yield element;
michael@0: }
michael@0: const List = Trait.resolve({ toString: null }).compose(listOptions);
michael@0: exports.List = List;