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