Adds common array-extras methods to a class that also mixes ArrayList

arraylist-extras.js

/*global YUI*/
/**
 * Adds common array-extras methods to a class that also mixes ArrayList
 *
 * Example usage:
 *
 *     var MyClass = Y.Base.create("myclass", Y.Base, [Y.ArrayList, Y.ArrayListExtras]),
 *       mc = new MyClass();
 *
 *     mc.add("hi");
 *     mc.add("by");
 *     mc.map(function (item) { return item.toUpperCase() }); // ["HI", "BYE"]
 *     
 * @module arraylist-extras
 * @requires array-extras
 */
YUI.add("arraylist-extras", function (Y) {
  "use strict";
  var YArray = Y.Array,
    ArrayListExtras = function () {};

  /**
   * Adds common array methods to a class that also mixes ArrayList
   * 
   * @class ArrayListExtras
   * @constructor
   */
  ArrayListExtras.prototype = {
    /**
     * Executes the supplied function on each item in the arraylist, searching for the
     * first item that matches the supplied function.
     * 
     * @method find
     * @param {Function} f the function to execute on each item. Iteration is stopped
     *   as soon as this function returns `true`.
     * @param {Object} [o] Optional context object.
     * @return {Object} the first item that the supplied function returns `true` for,
     *   or `null` if it never returns `true`.
     */
    find: function (f, o) {
      return YArray.find(this._items, f, o || this);
    },
    /**
     * Executes the supplied function on each item in the arraylist and returns a new array
     * containing all the values returned by the supplied function.
     * 
     * @method map
     * @param {Function} f the function to execute on each item.
     * @param {object} [o] Optional context object.
     * @return {Array} A new array containing the return value of the supplied function
     *   for each item in the original array.
     */
    map: function (f, o) {
      return YArray.map(this._items, f, o || this);
    },
    /**
     * Executes the supplied function on each item in the arraylist, "folding" the arraylist
     * into a single value.
     * 
     * @method reduce
     * @param {Any} init Initial value to start with.
     * @param {Function} f Function to execute on each item. This function should
     *   update and return the value of the computation. It will receive the following
     *   arguments:
     *     @param {Any} f.previousValue Value returned from the previous iteration,
     *       or the initial value if this is the first iteration.
     *     @param {Any} f.currentValue Value of the current item being iterated.
     *     @param {Number} f.index Index of the current item.
     *     @param {Array} f.array Array being iterated.
     * @param {Object} [o] Optional context object.
     * @return {Any} Final result from iteratively applying the given function to each
     *   element in the array.
     */
    reduce: function (i, f, o) {
      return YArray.reduce(this._items, i, f, o || this);
    }
  };

}, "3.4.1", {
  requires: ["array-extras"]
});