collection/js/array-extras.js

	array-extras.js revision 4002f3e3d5b27aeaeda15e32b8e8b237fe61fd48
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * Collection utilities beyond what is provided in the YUI core
3196419a9bc437f0c1d6429213ecaa16b4c7569cAdam Moore * @module collection
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore */
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moorevar L = Y.Lang, Native = Array.prototype, A = Y.Array;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
525f1907a1db0a892ea2a2e2abe27082f7484204Adam Moore/**
525f1907a1db0a892ea2a2e2abe27082f7484204Adam Moore * Adds the following array utilities to the YUI instance
525f1907a1db0a892ea2a2e2abe27082f7484204Adam Moore * (Y.Array).  This is in addition to the methods provided
525f1907a1db0a892ea2a2e2abe27082f7484204Adam Moore * in the core.
525f1907a1db0a892ea2a2e2abe27082f7484204Adam Moore * @class YUI~array~extras
525f1907a1db0a892ea2a2e2abe27082f7484204Adam Moore */
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * Returns the index of the last item in the array
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * that contains the specified value, -1 if the
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * value isn't found.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * method Array.lastIndexOf
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @param a {Array} the array to search
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @param val the value to search for
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @return {int} the index of hte item that contains the value or -1
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore */
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.lastIndexOf = (Native.lastIndexOf) ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a ,val) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return a.lastIndexOf(val);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, val) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        for (var i=a.length-1; i>=0; i=i-1) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            if (a[i] === val) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore                break;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return i;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * Returns a copy of the array with the duplicate entries removed
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @method Array.unique
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @param a {Array} the array to find the subset of uniques for
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @param sort {bool} flag to denote if the array is sorted or not. Defaults to false, the more general operation
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @return {Array} a copy of the array with duplicate entries removed
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore */
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.unique = function(a, sort) {
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    var b = a.slice(), i = 0, n = -1, item = null;
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    while (i < b.length) {
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore        item = b[i];
4002f3e3d5b27aeaeda15e32b8e8b237fe61fd48Adam Moore        while ((n = A.lastIndexOf(b, item)) !== i) {
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore            b.splice(n, 1);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        }
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore        i += 1;
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    }
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    // Note: the sort option doesn't really belong here... I think it was added
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    // because there was a way to fast path the two operations together.  That
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    // implementation was not working, so I replaced it with the following.
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    // Leaving it in so that the API doesn't get broken.
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    if (sort) {
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore        if (L.isNumber(b[0])) {
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore            b.sort(A.numericSort);
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore        } else {
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore            b.sort();
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    }
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore    return b;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Executes the supplied function on each item in the array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Returns a new array containing the items that the supplied
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* function returned true for.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.filter
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} the array to iterate
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param f {Function} the function to execute on each item
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param o Optional context object
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return {Array} The items on which the supplied function
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* returned true. If no items matched an empty array is
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* returned.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.filter = (Native.filter) ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return Native.filter.call(a, f, o);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        var results = [];
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        A.each(a, function(item, i, a) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            if (f.call(o, item, i, a)) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore                results.push(item);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* The inverse of filter. Executes the supplied function on each item.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Returns a new array containing the items that the supplied
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* function returned *false* for.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.reject
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} the array to iterate
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param f {Function} the function to execute on each item
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param o Optional context object
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return {Array} The items on which the supplied function
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* returned false.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.reject = function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    return A.filter(a, function(item, i, a) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return !f.call(o, item, i, a);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Executes the supplied function on each item in the array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.every
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} the array to iterate
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param f {Function} the function to execute on each item
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param o Optional context object
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return {boolean} true if every item in the array returns true
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* from the supplied function.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.every = (Native.every) ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return Native.every.call(a,f,o);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        var l = a.length;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        for (var i = 0; i < l; i=i+1) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            if (!f.call(o, a[i], i, a)) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore                return false;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return true;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Executes the supplied function on each item in the array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.map
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} the array to iterate
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param f {Function} the function to execute on each item
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param o Optional context object
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return {Array} A new array containing the return value
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* of the supplied function for each item in the original
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.map = (Native.map) ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return Native.map.call(a, f, o);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        var results = [];
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        A.each(a, function(item, i, a) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            results.push(f.call(o, item, i, a));
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Executes the supplied function on each item in the array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Reduce "folds" the array into a single value.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.reduce
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} the array to iterate
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param init The initial value to start from
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param f {Function} the function to execute on each item. It
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* is responsible for returning the updated value of the
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* computation.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param o Optional context object
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return A value that results from iteratively applying the
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* supplied function to each element in the array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.reduce = (Native.reduce) ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, init, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        //Firefox's Array.reduce does not allow inclusion of a
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        //  thisObject, so we need to implement it manually
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return Native.reduce.call(a, function(init, item, i, a) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            return f.call(o, init, item, i, a);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        }, init);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    function(a, init, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        var r = init;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        A.each(a, function (item, i, a) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            r = f.call(o, r, item, i, a);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return r;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Executes the supplied function on each item in the array,
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* searching for the first item that matches the supplied
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* function.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.find
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} the array to search
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param f {Function} the function to execute on each item.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Iteration is stopped as soon as this function returns true
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* on an item.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param o Optional context object
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return {object} the first item that the supplied function
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* returns true for, or null if it never returns true
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.find = function(a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    var l = a.length;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    for(var i=0; i < l; i++) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        if (f.call(o, a[i], i, a)) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore            return a[i];
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    return null;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Iterates over an array, returning a new array of all the elements
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* that match the supplied regular expression
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.grep
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} a collection to iterate over
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param pattern {RegExp} The regular expression to test against
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* each item
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return {Array} All the items in the collection that
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* produce a match against the supplied regular expression.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* If no items match, an empty array is returned.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.grep = function (a, pattern) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    return A.filter(a, function (item, index) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        return pattern.test(item);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Partitions an array into two new arrays, one with the items
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* that match the supplied function, and one with the items that
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* do not.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.partition
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} a collection to iterate over
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @paran f {Function} a function that will receive each item
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* in the collection and its index.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param o Optional execution context of f.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return An object with two members, 'matches' and 'rejects',
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* that are arrays containing the items that were selected or
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* rejected by the test function (or an empty array).
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.partition = function (a, f, o) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    var results = {matches: [], rejects: []};
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    A.each(a, function (item, index) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        var set = f.call(o, item, index, a) ? results.matches : results.rejects;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        set.push(item);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Creates an array of arrays by pairing the corresponding
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* elements of two arrays together into a new array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.zip
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a {Array} a collection to iterate over
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @param a2 {Array} another collection whose members will be
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* paired with members of the first parameter
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return An array of arrays formed by pairing each element
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* of the first collection with an item in the second collection
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* having the corresponding index.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.zip = function (a, a2) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    var results = [];
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    A.each(a, function (item, index) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore        results.push([item, a2[index]]);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore    return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};