lib/yuilib/3.13.0/array-extras/array-extras-debug.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('array-extras', function (Y, NAME) {
   9
  10 /**
  11 Adds additional utility methods to the `Y.Array` class.
  12
  13 @module collection
  14 @submodule array-extras
  15 **/
  16
  17 var A          = Y.Array,
  18     L          = Y.Lang,
  19     ArrayProto = Array.prototype;
  20
  21 /**
  22 Returns the index of the last item in the array that contains the specified
  23 value, or `-1` if the value isn't found.
  24
  25 @method lastIndexOf
  26 @param {Array} a Array to search in.
  27 @param {Any} val Value to search for.
  28 @param {Number} [fromIndex] Index at which to start searching backwards.
  29   Defaults to the array's length - 1. If negative, it will be taken as an offset
  30   from the end of the array. If the calculated index is less than 0, the array
  31   will not be searched and `-1` will be returned.
  32 @return {Number} Index of the item that contains the value, or `-1` if not
  33   found.
  34 @static
  35 @for Array
  36 **/
  37 A.lastIndexOf = L._isNative(ArrayProto.lastIndexOf) ?
  38     function(a, val, fromIndex) {
  39         // An undefined fromIndex is still considered a value by some (all?)
  40         // native implementations, so we can't pass it unless it's actually
  41         // specified.
  42         return fromIndex || fromIndex === 0 ? a.lastIndexOf(val, fromIndex) :
  43                 a.lastIndexOf(val);
  44     } :
  45     function(a, val, fromIndex) {
  46         var len = a.length,
  47             i   = len - 1;
  48
  49         if (fromIndex || fromIndex === 0) {
  50             i = Math.min(fromIndex < 0 ? len + fromIndex : fromIndex, len);
  51         }
  52
  53         if (i > -1 && len > 0) {
  54             for (; i > -1; --i) {
  55                 if (i in a && a[i] === val) {
  56                     return i;
  57                 }
  58             }
  59         }
  60
  61         return -1;
  62     };
  63
  64 /**
  65 Returns a copy of the input array with duplicate items removed.
  66
  67 Note: If the input array only contains strings, the `Y.Array.dedupe()` method is
  68 a much faster alternative.
  69
  70 @method unique
  71 @param {Array} array Array to dedupe.
  72 @param {Function} [testFn] Custom function to use to test the equality of two
  73     values. A truthy return value indicates that the values are equal. A falsy
  74     return value indicates that the values are not equal.
  75
  76     @param {Any} testFn.a First value to compare.
  77     @param {Any} testFn.b Second value to compare.
  78     @param {Number} testFn.index Index of the current item in the original
  79         array.
  80     @param {Array} testFn.array The original array.
  81     @return {Boolean} _true_ if the items are equal, _false_ otherwise.
  82
  83 @return {Array} Copy of the input array with duplicate items removed.
  84 @static
  85 **/
  86 A.unique = function (array, testFn) {
  87     var i       = 0,
  88         len     = array.length,
  89         results = [],
  90         j, result, resultLen, value;
  91
  92     // Note the label here. It's used to jump out of the inner loop when a value
  93     // is not unique.
  94     outerLoop: for (; i < len; i++) {
  95         value = array[i];
  96
  97         // For each value in the input array, iterate through the result array
  98         // and check for uniqueness against each result value.
  99         for (j = 0, resultLen = results.length; j < resultLen; j++) {
 100             result = results[j];
 101
 102             // If the test function returns true or there's no test function and
 103             // the value equals the current result item, stop iterating over the
 104             // results and continue to the next value in the input array.
 105             if (testFn) {
 106                 if (testFn.call(array, value, result, i, array)) {
 107                     continue outerLoop;
 108                 }
 109             } else if (value === result) {
 110                 continue outerLoop;
 111             }
 112         }
 113
 114         // If we get this far, that means the current value is not already in
 115         // the result array, so add it.
 116         results.push(value);
 117     }
 118
 119     return results;
 120 };
 121
 122 /**
 123 Executes the supplied function on each item in the array. Returns a new array
 124 containing the items for which the supplied function returned a truthy value.
 125
 126 @method filter
 127 @param {Array} a Array to filter.
 128 @param {Function} f Function to execute on each item.
 129 @param {Object} [o] Optional context object.
 130 @return {Array} Array of items for which the supplied function returned a
 131   truthy value (empty if it never returned a truthy value).
 132 @static
 133 */
 134 A.filter = L._isNative(ArrayProto.filter) ?
 135     function(a, f, o) {
 136         return ArrayProto.filter.call(a, f, o);
 137     } :
 138     function(a, f, o) {
 139         var i       = 0,
 140             len     = a.length,
 141             results = [],
 142             item;
 143
 144         for (; i < len; ++i) {
 145             if (i in a) {
 146                 item = a[i];
 147
 148                 if (f.call(o, item, i, a)) {
 149                     results.push(item);
 150                 }
 151             }
 152         }
 153
 154         return results;
 155     };
 156
 157 /**
 158 The inverse of `Array.filter()`. Executes the supplied function on each item.
 159 Returns a new array containing the items for which the supplied function
 160 returned `false`.
 161
 162 @method reject
 163 @param {Array} a the array to iterate.
 164 @param {Function} f the function to execute on each item.
 165 @param {object} [o] Optional context object.
 166 @return {Array} The items for which the supplied function returned `false`.
 167 @static
 168 */
 169 A.reject = function(a, f, o) {
 170     return A.filter(a, function(item, i, a) {
 171         return !f.call(o, item, i, a);
 172     });
 173 };
 174
 175 /**
 176 Executes the supplied function on each item in the array. Iteration stops if the
 177 supplied function does not return a truthy value.
 178
 179 @method every
 180 @param {Array} a the array to iterate.
 181 @param {Function} f the function to execute on each item.
 182 @param {Object} [o] Optional context object.
 183 @return {Boolean} `true` if every item in the array returns `true` from the
 184   supplied function, `false` otherwise.
 185 @static
 186 */
 187 A.every = L._isNative(ArrayProto.every) ?
 188     function(a, f, o) {
 189         return ArrayProto.every.call(a, f, o);
 190     } :
 191     function(a, f, o) {
 192         for (var i = 0, l = a.length; i < l; ++i) {
 193             if (i in a && !f.call(o, a[i], i, a)) {
 194                 return false;
 195             }
 196         }
 197
 198         return true;
 199     };
 200
 201 /**
 202 Executes the supplied function on each item in the array and returns a new array
 203 containing all the values returned by the supplied function.
 204
 205 @example
 206
 207     // Convert an array of numbers into an array of strings.
 208     Y.Array.map([1, 2, 3, 4], function (item) {
 209       return '' + item;
 210     });
 211     // => ['1', '2', '3', '4']
 212
 213 @method map
 214 @param {Array} a the array to iterate.
 215 @param {Function} f the function to execute on each item.
 216 @param {object} [o] Optional context object.
 217 @return {Array} A new array containing the return value of the supplied function
 218   for each item in the original array.
 219 @static
 220 */
 221 A.map = L._isNative(ArrayProto.map) ?
 222     function(a, f, o) {
 223         return ArrayProto.map.call(a, f, o);
 224     } :
 225     function(a, f, o) {
 226         var i       = 0,
 227             len     = a.length,
 228             results = ArrayProto.concat.call(a);
 229
 230         for (; i < len; ++i) {
 231             if (i in a) {
 232                 results[i] = f.call(o, a[i], i, a);
 233             }
 234         }
 235
 236         return results;
 237     };
 238
 239
 240 /**
 241 Executes the supplied function on each item in the array, "folding" the array
 242 into a single value.
 243
 244 @method reduce
 245 @param {Array} a Array to iterate.
 246 @param {Any} init Initial value to start with.
 247 @param {Function} f Function to execute on each item. This function should
 248   update and return the value of the computation. It will receive the following
 249   arguments:
 250     @param {Any} f.previousValue Value returned from the previous iteration,
 251       or the initial value if this is the first iteration.
 252     @param {Any} f.currentValue Value of the current item being iterated.
 253     @param {Number} f.index Index of the current item.
 254     @param {Array} f.array Array being iterated.
 255 @param {Object} [o] Optional context object.
 256 @return {Any} Final result from iteratively applying the given function to each
 257   element in the array.
 258 @static
 259 */
 260 A.reduce = L._isNative(ArrayProto.reduce) ?
 261     function(a, init, f, o) {
 262         // ES5 Array.reduce doesn't support a thisObject, so we need to
 263         // implement it manually.
 264         return ArrayProto.reduce.call(a, function(init, item, i, a) {
 265             return f.call(o, init, item, i, a);
 266         }, init);
 267     } :
 268     function(a, init, f, o) {
 269         var i      = 0,
 270             len    = a.length,
 271             result = init;
 272
 273         for (; i < len; ++i) {
 274             if (i in a) {
 275                 result = f.call(o, result, a[i], i, a);
 276             }
 277         }
 278
 279         return result;
 280     };
 281
 282 /**
 283 Executes the supplied function on each item in the array, searching for the
 284 first item that matches the supplied function.
 285
 286 @method find
 287 @param {Array} a the array to search.
 288 @param {Function} f the function to execute on each item. Iteration is stopped
 289   as soon as this function returns `true`.
 290 @param {Object} [o] Optional context object.
 291 @return {Object} the first item that the supplied function returns `true` for,
 292   or `null` if it never returns `true`.
 293 @static
 294 */
 295 A.find = function(a, f, o) {
 296     for (var i = 0, l = a.length; i < l; i++) {
 297         if (i in a && f.call(o, a[i], i, a)) {
 298             return a[i];
 299         }
 300     }
 301     return null;
 302 };
 303
 304 /**
 305 Iterates over an array, returning a new array of all the elements that match the
 306 supplied regular expression.
 307
 308 @method grep
 309 @param {Array} a Array to iterate over.
 310 @param {RegExp} pattern Regular expression to test against each item.
 311 @return {Array} All the items in the array that produce a match against the
 312   supplied regular expression. If no items match, an empty array is returned.
 313 @static
 314 */
 315 A.grep = function(a, pattern) {
 316     return A.filter(a, function(item, index) {
 317         return pattern.test(item);
 318     });
 319 };
 320
 321 /**
 322 Partitions an array into two new arrays, one with the items for which the
 323 supplied function returns `true`, and one with the items for which the function
 324 returns `false`.
 325
 326 @method partition
 327 @param {Array} a Array to iterate over.
 328 @param {Function} f Function to execute for each item in the array. It will
 329   receive the following arguments:
 330     @param {Any} f.item Current item.
 331     @param {Number} f.index Index of the current item.
 332     @param {Array} f.array The array being iterated.
 333 @param {Object} [o] Optional execution context.
 334 @return {Object} An object with two properties: `matches` and `rejects`. Each is
 335   an array containing the items that were selected or rejected by the test
 336   function (or an empty array if none).
 337 @static
 338 */
 339 A.partition = function(a, f, o) {
 340     var results = {
 341         matches: [],
 342         rejects: []
 343     };
 344
 345     A.each(a, function(item, index) {
 346         var set = f.call(o, item, index, a) ? results.matches : results.rejects;
 347         set.push(item);
 348     });
 349
 350     return results;
 351 };
 352
 353 /**
 354 Creates an array of arrays by pairing the corresponding elements of two arrays
 355 together into a new array.
 356
 357 @method zip
 358 @param {Array} a Array to iterate over.
 359 @param {Array} a2 Another array whose values will be paired with values of the
 360   first array.
 361 @return {Array} An array of arrays formed by pairing each element of the first
 362   array with an item in the second array having the corresponding index.
 363 @static
 364 */
 365 A.zip = function(a, a2) {
 366     var results = [];
 367     A.each(a, function(item, index) {
 368         results.push([item, a2[index]]);
 369     });
 370     return results;
 371 };
 372
 373 /**
 374 Flattens an array of nested arrays at any abitrary depth into a single, flat
 375 array.
 376
 377 @method flatten
 378 @param {Array} a Array with nested arrays to flatten.
 379 @return {Array} An array whose nested arrays have been flattened.
 380 @static
 381 @since 3.7.0
 382 **/
 383 A.flatten = function(a) {
 384     var result = [],
 385         i, len, val;
 386
 387     // Always return an array.
 388     if (!a) {
 389         return result;
 390     }
 391
 392     for (i = 0, len = a.length; i < len; ++i) {
 393         val = a[i];
 394
 395         if (L.isArray(val)) {
 396             // Recusively flattens any nested arrays.
 397             result.push.apply(result, A.flatten(val));
 398         } else {
 399             result.push(val);
 400         }
 401     }
 402
 403     return result;
 404 };
 405
 406
 407 }, '3.13.0', {"requires": ["yui-base"]});