9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove@submodule yui-base
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveProvides utility methods for working with arrays. Additional array helpers can
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovebe found in the `collection` and `array-extras` modules.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove`Y.Array(thing)` returns a native array created from _thing_. Depending on
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove_thing_'s type, one of the following will happen:
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove * Arrays are returned unmodified unless a non-zero _startIndex_ is
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove * Array-like collections (see `Array.test()`) are converted to arrays.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove * For everything else, a new array is created with _thing_ as the sole
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveNote: elements that are also collections, such as `<form>` and `<select>`
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Groveelements, are not automatically converted to arrays. To force a conversion,
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovepass `true` as the value of the _force_ parameter.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Any} thing The thing to arrayify.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Number} [startIndex=0] If non-zero and _thing_ is an array or array-like
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove collection, a subset of items starting at the specified index will be
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Boolean} [force=false] If `true`, _thing_ will be treated as an
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove array-like collection no matter what.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@return {Array} A native array created from _thing_, according to the rules
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove described above.
10f15e6d01fb5a16131e11a283f2792ac030a83cRyan Grove // IE throws when trying to slice HTMLElement collections.
10f15e6d01fb5a16131e11a283f2792ac030a83cRyan Grove } catch (ex) {
10f15e6d01fb5a16131e11a283f2792ac030a83cRyan Grove for (len = thing.length; startIndex < len; ++startIndex) {
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveDedupes an array of strings, returning an array that's guaranteed to contain
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Groveonly one copy of a given string.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveThis method differs from `Array.unique()` in that it's optimized for use only
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovewith strings, whereas `unique` may be used with other types (but is slower).
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveUsing `dedupe()` with non-string values may result in unexpected behavior.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@method dedupe
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {String[]} array Array of strings to dedupe.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@return {Array} Deduped copy of _array_.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveExecutes the supplied function on each item in the array. This method wraps
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovethe native ES5 `Array.forEach()` method if available.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Array} array Array to iterate.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Function} fn Function to execute on each item in the array. The function
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove will receive the following arguments:
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove @param {Any} fn.item Current array item.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove @param {Number} fn.index Current array index.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove @param {Array} fn.array Array being iterated.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Object} [thisObj] `this` object to use when calling _fn_.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@return {YUI} The YUI instance.
3e4a3c30997cfa913fabd7b346e3a71388441bedRyan GroveYArray.each = YArray.forEach = Lang._isNative(Native.forEach) ? function (array, fn, thisObj) {
0a1f30d712713e39834369dc0781ada8459ea5d2Ryan Grove Native.forEach.call(array || [], fn, thisObj || Y);
0a1f30d712713e39834369dc0781ada8459ea5d2Ryan Grove for (var i = 0, len = (array && array.length) || 0; i < len; ++i) {
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveAlias for `each()`.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@method forEach
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveReturns an object using the first array as keys and the second as values. If
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovethe second array is not provided, or if it doesn't contain the same number of
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovevalues as the first array, then `true` will be used in place of the missing
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove Y.Array.hash(['a', 'b', 'c'], ['foo', 'bar']);
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove // => {a: 'foo', b: 'bar', c: true}
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {String[]} keys Array of strings to use as keys.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Array} [values] Array to use as values.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@return {Object} Hash using the first array as keys and the second as values.
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove hash[keys[i]] = vlen > i && i in values ? values[i] : true;
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveReturns the index of the first item in the array that's equal (using a strict
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Groveequality check) to the specified _value_, or `-1` if the value isn't found.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveThis method wraps the native ES5 `Array.indexOf()` method if available.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@method indexOf
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Array} array Array to search.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Any} value Value to search for.
d5f407f728b461f7362049b93dd6754a1ad8a24fRyan Grove@param {Number} [from=0] The index at which to begin the search.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@return {Number} Index of the item strictly equal to _value_, or `-1` if not
97ab26e5f393dc5993135ae207ccc137ce3c7008Ryuichi OkumuraYArray.indexOf = Lang._isNative(Native.indexOf) ? function (array, value, from) {
97ab26e5f393dc5993135ae207ccc137ce3c7008Ryuichi Okumura return Native.indexOf.call(array, value, from);
d5f407f728b461f7362049b93dd6754a1ad8a24fRyan Grove from = (from > 0 || -1) * Math.floor(Math.abs(from));
97ab26e5f393dc5993135ae207ccc137ce3c7008Ryuichi Okumura if (from in array && array[from] === value) {
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveNumeric sort convenience function.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveThe native `Array.prototype.sort()` function converts values to strings and
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovesorts them in lexicographic order, which is unsuitable for sorting numeric
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovevalues. Provide `Array.numericSort` as a custom sort function when you want
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Groveto sort values in numeric order.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove [42, 23, 8, 16, 4, 15].sort(Y.Array.numericSort);
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove // => [4, 8, 15, 16, 23, 42]
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@method numericSort
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Number} a First value to compare.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Number} b Second value to compare.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@return {Number} Difference between _a_ and _b_.
0a1f30d712713e39834369dc0781ada8459ea5d2Ryan Grove return a - b;
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan GroveExecutes the supplied function on each item in the array. Returning a truthy
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grovevalue from the function will stop the processing of remaining items.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Array} array Array to iterate over.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Function} fn Function to execute on each item. The function will receive
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove the following arguments:
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove @param {Any} fn.value Current array item.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove @param {Number} fn.index Current array index.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove @param {Array} fn.array Array being iterated over.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@param {Object} [thisObj] `this` object to use when calling _fn_.
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove@return {Boolean} `true` if the function returns a truthy value on any of the
cc993d3cace28dec43cfc6f55b41961e90e76ba9Ryan Grove items in the array; `false` otherwise.
3e4a3c30997cfa913fabd7b346e3a71388441bedRyan GroveYArray.some = Lang._isNative(Native.some) ? function (array, fn, thisObj) {
0a1f30d712713e39834369dc0781ada8459ea5d2Ryan Grove for (var i = 0, len = array.length; i < len; ++i) {
701eda2eb4521a1f3fb46f0d6aa587433a9ccbb7Ryan Grove if (i in array && fn.call(thisObj, array[i], i, array)) {
0a1f30d712713e39834369dc0781ada8459ea5d2Ryan Grove return true;
0a1f30d712713e39834369dc0781ada8459ea5d2Ryan Grove return false;
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan GroveEvaluates _obj_ to determine if it's an array, an array-like collection, or
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grovesomething else. This is useful when working with the function `arguments`
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grovecollection and `HTMLElement` collections.
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan GroveNote: This implementation doesn't consider elements that are also
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grovecollections, such as `<form>` and `<select>`, to be array-like.
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove@param {Object} obj Object to test.
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove@return {Number} A number indicating the results of the test:
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove * 0: Neither an array nor an array-like collection.
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove * 1: Real array.
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove * 2: Array-like collection.
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove // indexed, but no tagName (element) or alert (window),
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove // or functions without apply/call (Safari
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove // HTMLElementCollection bug).
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove if ('length' in obj && !obj.tagName && !obj.alert && !obj.apply) {
9f141fd009d9c3960fc5e59c9f80d42643b8549eRyan Grove } catch (ex) {}