[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["yui-base"]});