1 /*

     2 YUI 3.10.3 (build 2fb5187)

     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.10.3', {"requires": ["yui-base"]});