yui-array.js revision 0263b559dcd210a19a22676b25ecbcac81d1692c
c4e6d94ea429e473a6732b6eb5e0fc980e822881Adam Moore(function() {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @module yui
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Adds the following array utilities to the YUI instance
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @class YUI~array
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Y.Array(o) returns an array:
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * - Arrays are return unmodified unless the start position is specified.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * - "Array-like" collections (@see Array.test) are converted to arrays
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * - For everything else, a new array is created with the input as the sole item
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * - The start position is used if the input is or is like an array to return
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * a subset of the collection.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @TODO this will not automatically convert elements that are also collections
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * such as forms and selects. Passing true as the third param will
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * force a conversion.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Array
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param o the item to arrayify
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param i {int} if an array or array-like, this is the start index
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param al {boolean} if true, it forces the array-like fork. This
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * can be used to avoid multiple array.test calls.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @return {Array} the resulting array
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore // switch (t) {
b45133051f787045386e6848ced7996daffd97e5Adam Moore // // return (startIdx) ? o.slice(startIdx) : o;
b45133051f787045386e6848ced7996daffd97e5Adam Moore // return Native.slice.call(o, startIdx || 0);
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore // return [o];
b45133051f787045386e6848ced7996daffd97e5Adam Moore // IE errors when trying to slice element collections
b45133051f787045386e6848ced7996daffd97e5Adam Moore } catch(e) {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Evaluates the input to determine if it is an array, array-like, or
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * something else. This is used to handle the arguments collection
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * available within functions, and HTMLElement collections
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Array.test
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @todo current implementation (intenionally) will not implicitly
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * handle html elements that are array-like (forms, selects, etc).
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @return {int} a number indicating the results:
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * 0: Not an array or an array-like collection
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * 1: A real array.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * 2: array-like collection.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore // indexed, but no tagName (element) or alert (window)
21a04e4a1f3596ab3a9e17fffa80b45eace6b29aAdam Moore if ("length" in o && !("tagName" in o) && !("alert" in o) &&
21a04e4a1f3596ab3a9e17fffa80b45eace6b29aAdam Moore } catch(e) {}
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Executes the supplied function on each item in the array.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Array.each
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param a {Array} the array to iterate
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param f {Function} the function to execute on each item
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param o Optional context object
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @return {YUI} the YUI instance
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore function (a, f, o) {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore function (a, f, o) {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore f.call(o || Y, a[i], i, a);
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Returns an object using the first array as keys, and
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * the second as values. If the second array is not
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * provided the value is set to true for each.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Array.hash
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param k {Array} keyset
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param v {Array} optional valueset
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @return {object} the hash
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Returns the index of the first item in the array
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * that contains the specified value, -1 if the
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * value isn't found.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Array.indexOf
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param a {Array} the array to search
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param val the value to search for
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @return {int} the index of the item that contains the value or -1
a3e6db667fcd33ac653355e76d3660ecf232193bJeff Craig function(a, val) {
a3e6db667fcd33ac653355e76d3660ecf232193bJeff Craig function(a, val) {
a3e6db667fcd33ac653355e76d3660ecf232193bJeff Craig if (a[i] === val) {
eb86457f85638a9eb7c4d5f84eb367d24061abfbAdam Moore * Numeric sort convenience function.
eb86457f85638a9eb7c4d5f84eb367d24061abfbAdam Moore * Y.ArrayAssert.itemsAreEqual([1, 2, 3], [3, 1, 2].sort(Y.Array.numericSort));
eb86457f85638a9eb7c4d5f84eb367d24061abfbAdam Moore * @method numericSort
eb86457f85638a9eb7c4d5f84eb367d24061abfbAdam Moore return (a - b);
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * Executes the supplied function on each item in the array.
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * Returning true from the processing function will stop the
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * processing of the remaining
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * @method Array.some
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * @param a {Array} the array to iterate
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * @param f {Function} the function to execute on each item
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * @param o Optional context object
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * @return {boolean} true if the function returns true on
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore * any of the items in the array
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore function (a, f, o) {
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore function (a, f, o) {
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore var l = a.length, i;
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore if (f.call(o, a[i], i, a)) {
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore return true;
3c245663d1bfadc0536b538247884c0667cc9313Adam Moore return false;