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