yui-array.js revision ace5e2555c33a0ceddef42649f6f38fa006707cc
/**
* YUI core
* @module yui
*/
/**
* Array utilities
* @TODO investigate using Array subclasses for some of this
* @class Array
* @static
*/
YUI.add("array", function(Y) {
var L = Y.Lang, Native = Array.prototype;
/**
* Returns an array:
* - Arrays are return unmodified unless the start position is specified.
* - "Array-like" collections (@see Array.test) are converted to arrays
* - For everything else, a new array is created with the input as the sole item
* - The start position is used if the input is or is like an array to return
* a subset of the collection.
*
* @todo this will not automatically convert elements that are also collections
* such as forms and selects. Passing true as the third param will
* force a conversion.
*
* @param o the item to arrayify
* @param i {int} if an array or array-like, this is the start index
* @param al {boolean} if true, it forces the array-like fork. This
* can be used to avoid multiple array.test calls.
*/
Y.Array = function(o, i, al) {
var t = (al) ? 2 : Y.Array.test(o);
switch (t) {
case 1:
return (i) ? o.slice(o, i) : o;
case 2:
return Native.slice.call(o, i || 0);
default:
return [o];
}
};
var A = Y.Array;
// YUI array utilities. The current plan is to make a few useful
// ones 'core', and to have the rest of the array extras an optional
// module
/**
* Evaluates the input to determine if it is an array, array-like, or
* something else. This is used to handle the arguments collection
* available within functions, and HTMLElement collections
*
* @todo current implementation (intenionally) will not implicitly
* handle html elements that are array-like (forms, selects, etc).
*
* @return {int} a number indicating the results:
* 0: Not an array or an array-like collection
* 1: A real array.
* 2: array-like collection.
*/
A.test = function(o) {
var r = 0;
if (L.isObject(o, true)) {
if (L.isArray(o)) {
r = 1;
} else {
try {
// indexed, but no tagName (element) or alert (window)
if ("length" in o && !("tagName" in o) && !("alert" in o)) {
r = 2;
}
} catch(ex) {}
}
}
return r;
};
/**
* Executes the supplied function on each item in the array.
* @method each
*/
A.each = (Native.forEach) ?
function (a, f, o) {
Native.forEach.call(a, f, o || Y);
return Y;
} :
function (a, f, o) {
var l = a.length, i;
for (i = 0; i < l; i=i+1) {
f.call(o || Y, a[i], i, a);
}
return Y;
};
/**
* Returns an object using the first array as keys, and
* the second as values. If the second array is not
* provided the value is set to true for each.
* @method hash
* @param k {Array} keyset
* @param v {Array} optional valueset
* @return the hash
*/
A.hash = function(k, v) {
var o = {}, l = k.length, vl = v && v.length, i;
for (i=0; i<l; i=i+1) {
o[k[i]] = (vl && vl > i) ? v[i] : true;
}
return o;
};
/**
* Returns the index of the first item in the array
* that contains the specified value, -1 if the
* value isn't found.
* @TODO use native method if avail
* @method indexOf
* @param a {Array} the array to search
* @param val the value to search for
* @return the index of the item that contains the value or -1
*/
A.indexOf = function(a, val) {
for (var i=0; i<a.length; i=i+1) {
if (a[i] === val) {
return i;
}
}
return -1;
};
}, "@VERSION@");