array-extras.js revision 701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * Collection utilities beyond what is provided in the YUI core
3196419a9bc437f0c1d6429213ecaa16b4c7569cAdam Moore * @module collection
266bfbd67fc220029bdadabd3c49e733f9f39360Luke Smith * @submodule array-extras
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/**
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * Returns the index of the last item in the array that contains the specified
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * value, or -1 if the value isn't found.
b4f1241a5618c650677ee9396e8229fef5e8977fLuke Smith * @method Array.lastIndexOf
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @static
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * @param {Array} a Array to search in.
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * @param {any} val Value to search for.
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * @param {Number} fromIndex (optional) Index at which to start searching
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * backwards. Defaults to the array's length - 1. If negative, it will be
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * taken as an offset from the end of the array. If the calculated index is
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * less than 0, the array will not be searched and -1 will be returned.
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * @return {Number} Index of the item that contains the value, or -1 if not
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove * found.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore */
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan GroveA.lastIndexOf = Native.lastIndexOf ?
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove function(a, val, fromIndex) {
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove // An undefined fromIndex is still considered a value by some (all?)
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove // native implementations, so we can't pass it unless it's actually
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove // specified.
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove return fromIndex || fromIndex === 0 ? a.lastIndexOf(val, fromIndex) :
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove a.lastIndexOf(val);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore } :
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove function(a, val, fromIndex) {
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove var len = a.length,
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove i = len - 1;
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove if (fromIndex || fromIndex === 0) {
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove i = Math.min(fromIndex < 0 ? len + fromIndex : fromIndex, len);
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove }
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove if (i > -1 && len > 0) {
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove for (; i > -1; --i) {
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove if (a[i] === val) {
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove return i;
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore }
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove
b1715f7fb8a67be6502d58d4dc5a00918f01fa16Ryan Grove return -1;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove * Returns a copy of the specified array with duplicate items removed.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @method Array.unique
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove * @param {Array} a Array to dedupe.
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove * @return {Array} Copy of the array with duplicate items removed.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore * @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore */
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.unique = function(a, sort) {
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove // Note: the sort param is deprecated and intentionally undocumented since
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove // YUI 3.3.0. It never did what the API docs said it did (see the older
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove // comment below as well).
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove var i = 0,
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove len = a.length,
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove results = [],
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove item, j;
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove for (; i < len; ++i) {
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove item = a[i];
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove // This loop iterates over the results array in reverse order and stops
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove // if it finds an item that matches the current input array item (a
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove // dupe). If it makes it all the way through without finding a dupe, the
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove // current item is pushed onto the results array.
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove for (j = results.length; j > -1; --j) {
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove if (item === results[j]) {
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove break;
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove }
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove }
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove if (j === -1) {
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove results.push(item);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore }
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) {
a05b931c6d7db4a5df53cfd1d2d505cb07859e66Ryan Grove Y.log('The sort parameter is deprecated and will be removed in a future version of YUI.', 'warn', 'deprecated');
a05b931c6d7db4a5df53cfd1d2d505cb07859e66Ryan Grove
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove if (L.isNumber(results[0])) {
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove results.sort(A.numericSort);
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore } else {
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove results.sort();
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore }
0dd2ce2702cb49626c42d19bff27c7b58738dc05Adam Moore
07ed44f0197e6e672f8d8af4b787d895ca237180Ryan Grove return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
d4e1418016231206366a3c7d9945be93696db05fRyan Grove* Executes the supplied function on each item in the array. Returns a new array
d4e1418016231206366a3c7d9945be93696db05fRyan Grove* containing the items for which the supplied function returned a truthy value.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.filter
d4e1418016231206366a3c7d9945be93696db05fRyan Grove* @param {Array} a Array to filter.
d4e1418016231206366a3c7d9945be93696db05fRyan Grove* @param {Function} f Function to execute on each item.
d4e1418016231206366a3c7d9945be93696db05fRyan Grove* @param {Object} o Optional context object.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
d4e1418016231206366a3c7d9945be93696db05fRyan Grove* @return {Array} Array of items for which the supplied function returned a
d4e1418016231206366a3c7d9945be93696db05fRyan Grove* truthy value (empty if it never returned a truthy value).
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
d4e1418016231206366a3c7d9945be93696db05fRyan GroveA.filter = Native.filter ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore function(a, f, o) {
d4e1418016231206366a3c7d9945be93696db05fRyan Grove return a.filter(f, o);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore function(a, f, o) {
d4e1418016231206366a3c7d9945be93696db05fRyan Grove var i = 0,
d4e1418016231206366a3c7d9945be93696db05fRyan Grove len = a.length,
d4e1418016231206366a3c7d9945be93696db05fRyan Grove results = [],
d4e1418016231206366a3c7d9945be93696db05fRyan Grove item;
d4e1418016231206366a3c7d9945be93696db05fRyan Grove
d4e1418016231206366a3c7d9945be93696db05fRyan Grove for (; i < len; ++i) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove if (i in a) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove item = a[i];
d4e1418016231206366a3c7d9945be93696db05fRyan Grove
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove if (f.call(o, item, i, a)) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove results.push(item);
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore }
d4e1418016231206366a3c7d9945be93696db05fRyan Grove }
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam 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
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a the array to iterate.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Function} f the function to execute on each item.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {object} 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.
d32cc429960e4473bb98b1533dd05a9893f7a6c8Adam Moore* Iteration stops if the supplied function does not return
d32cc429960e4473bb98b1533dd05a9893f7a6c8Adam Moore* a truthy value.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.every
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a the array to iterate.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Function} f the function to execute on each item.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {object} 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*/
4c6883fc6c94ac75099a9876dcc79becac62beafRyan GroveA.every = Native.every ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore function(a, f, o) {
4c6883fc6c94ac75099a9876dcc79becac62beafRyan Grove return a.every(f, o);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore function(a, f, o) {
4c6883fc6c94ac75099a9876dcc79becac62beafRyan Grove for (var i = 0, l = a.length; i < l; ++i) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove if (i in a && !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
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a the array to iterate.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Function} f the function to execute on each item.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {object} 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*/
847451b874697fc7df2c96af3935bcdc4c32f105Ryan GroveA.map = Native.map ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore function(a, f, o) {
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove return a.map(f, o);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore } :
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore function(a, f, o) {
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove var i = 0,
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove len = a.length,
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove results = a.concat();
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove for (; i < len; ++i) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove if (i in a) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove results[i] = f.call(o, a[i], i, a);
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove }
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove }
847451b874697fc7df2c96af3935bcdc4c32f105Ryan Grove
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore };
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore/**
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Executes the supplied function on each item in the array.
b416c92a5cae43a05878fd286aecf0523cfbca40Adam Moore* Reduce "folds" the array into a single value. The callback
f6baa527839e75655081768c365a749c59edc80dAdam Moore* function receives four arguments:
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* the value from the previous callback call (or the initial value),
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* the value of the current element, the current index, and
b416c92a5cae43a05878fd286aecf0523cfbca40Adam Moore* the array over which iteration is occurring.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @method Array.reduce
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a the array to iterate.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {any} init The initial value to start from.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Function} f the function to execute on each item. It
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* is responsible for returning the updated value of the
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* computation.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {object} o Optional context object.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @return {any} A value that results from iteratively applying the
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* supplied function to each element in the array.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan GroveA.reduce = Native.reduce ?
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore function(a, init, f, o) {
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove // ES5 Array.reduce doesn't support a thisObject, so we need to
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove // implement it manually
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove return a.reduce(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) {
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove var i = 0,
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove len = a.length,
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove result = init;
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove for (; i < len; ++i) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove if (i in a) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove result = f.call(o, result, a[i], i, a);
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove }
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove }
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove
259d423ddcd9feed2ca363af9e28bf8df4b0d832Ryan Grove return result;
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
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a the array to search.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Function} f the function to execute on each item.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* Iteration is stopped as soon as this function returns true
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* on an item.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {object} o Optional context object.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @return {object} the first item that the supplied function
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* returns true for, or null if it never returns true.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam MooreA.find = function(a, f, o) {
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore for (var i = 0, l = a.length; i < l; i++) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove if (i in a && 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
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a a collection to iterate over.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {RegExp} pattern The regular expression to test against
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* each item.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @return {Array} All the items in the collection that
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* produce a match against the supplied regular expression.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* If no items match, an empty array is returned.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam MooreA.grep = function(a, pattern) {
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam 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
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a a collection to iterate over.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Function} f a function that will receive each item
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* in the collection and its index.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {object} o Optional execution context of f.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @return {object} An object with two members, 'matches' and 'rejects',
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* that are arrays containing the items that were selected or
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* rejected by the test function (or an empty array).
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam MooreA.partition = function(a, f, o) {
77233109ecd5f5823f64aed88ebfbae24c2d402fAdam Moore var results = {
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore matches: [],
77233109ecd5f5823f64aed88ebfbae24c2d402fAdam Moore rejects: []
77233109ecd5f5823f64aed88ebfbae24c2d402fAdam Moore };
77233109ecd5f5823f64aed88ebfbae24c2d402fAdam Moore
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam 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 });
77233109ecd5f5823f64aed88ebfbae24c2d402fAdam 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
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a a collection to iterate over.
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @param {Array} a2 another collection whose members will be
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* paired with members of the first parameter.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* @static
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* @return {array} An array of arrays formed by pairing each element
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore* of the first collection with an item in the second collection
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore* having the corresponding index.
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore*/
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam MooreA.zip = function(a, a2) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore var results = [];
a0e486c33f9e4fae413b80adc659a906586f1ed3Adam Moore A.each(a, function(item, index) {
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore results.push([item, a2[index]]);
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore });
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore return results;
bb9912c86249bf7dec59ddc9d28434cabba9309aAdam Moore};