2
Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3
Code licensed under the BSD License:
4
http://developer.yahoo.com/yui/license.html
8
YUI.add('array-extras', function(Y) {
11
* Collection utilities beyond what is provided in the YUI core
13
* @submodule array-extras
16
var L = Y.Lang, Native = Array.prototype, A = Y.Array;
19
* Adds the following array utilities to the YUI instance
20
* (Y.Array). This is in addition to the methods provided
22
* @class YUI~array~extras
26
* Returns the index of the last item in the array
27
* that contains the specified value, -1 if the
29
* @method Array.lastIndexOf
31
* @param a {Array} the array to search
32
* @param val the value to search for
33
* @return {int} the index of hte item that contains the value or -1
35
A.lastIndexOf = (Native.lastIndexOf) ?
37
return a.lastIndexOf(val);
40
for (var i=a.length-1; i>=0; i=i-1) {
49
* Returns a copy of the array with the duplicate entries removed
50
* @method Array.unique
52
* @param a {Array} the array to find the subset of uniques for
53
* @param sort {bool} flag to denote if the array is sorted or not. Defaults to false, the more general operation
54
* @return {Array} a copy of the array with duplicate entries removed
56
A.unique = function(a, sort) {
57
var b = a.slice(), i = 0, n = -1, item = null;
59
while (i < b.length) {
61
while ((n = A.lastIndexOf(b, item)) !== i) {
67
// Note: the sort option doesn't really belong here... I think it was added
68
// because there was a way to fast path the two operations together. That
69
// implementation was not working, so I replaced it with the following.
70
// Leaving it in so that the API doesn't get broken.
72
if (L.isNumber(b[0])) {
73
b.sort(A.numericSort);
83
* Executes the supplied function on each item in the array.
84
* Returns a new array containing the items that the supplied
85
* function returned true for.
86
* @method Array.filter
87
* @param a {Array} the array to iterate
88
* @param f {Function} the function to execute on each item
89
* @param o Optional context object
91
* @return {Array} The items on which the supplied function
92
* returned true. If no items matched an empty array is
95
A.filter = (Native.filter) ?
97
return Native.filter.call(a, f, o);
101
A.each(a, function(item, i, a) {
102
if (f.call(o, item, i, a)) {
111
* The inverse of filter. Executes the supplied function on each item.
112
* Returns a new array containing the items that the supplied
113
* function returned *false* for.
114
* @method Array.reject
115
* @param a {Array} the array to iterate
116
* @param f {Function} the function to execute on each item
117
* @param o Optional context object
119
* @return {Array} The items on which the supplied function
122
A.reject = function(a, f, o) {
123
return A.filter(a, function(item, i, a) {
124
return !f.call(o, item, i, a);
129
* Executes the supplied function on each item in the array.
130
* Iteration stops if the supplied function does not return
132
* @method Array.every
133
* @param a {Array} the array to iterate
134
* @param f {Function} the function to execute on each item
135
* @param o Optional context object
137
* @return {boolean} true if every item in the array returns true
138
* from the supplied function.
140
A.every = (Native.every) ?
142
return Native.every.call(a,f,o);
145
for (var i = 0, l = a.length; i < l; i=i+1) {
146
if (!f.call(o, a[i], i, a)) {
155
* Executes the supplied function on each item in the array.
157
* @param a {Array} the array to iterate
158
* @param f {Function} the function to execute on each item
159
* @param o Optional context object
161
* @return {Array} A new array containing the return value
162
* of the supplied function for each item in the original
165
A.map = (Native.map) ?
167
return Native.map.call(a, f, o);
171
A.each(a, function(item, i, a) {
172
results.push(f.call(o, item, i, a));
179
* Executes the supplied function on each item in the array.
180
* Reduce "folds" the array into a single value. The callback
181
* function receives four arguments:
182
* the value from the previous callback call (or the initial value),
183
* the value of the current element, the current index, and
184
* the array over which iteration is occurring.
185
* @method Array.reduce
186
* @param a {Array} the array to iterate
187
* @param init The initial value to start from
188
* @param f {Function} the function to execute on each item. It
189
* is responsible for returning the updated value of the
191
* @param o Optional context object
193
* @return A value that results from iteratively applying the
194
* supplied function to each element in the array.
196
A.reduce = (Native.reduce) ?
197
function(a, init, f, o) {
198
//Firefox's Array.reduce does not allow inclusion of a
199
// thisObject, so we need to implement it manually
200
return Native.reduce.call(a, function(init, item, i, a) {
201
return f.call(o, init, item, i, a);
204
function(a, init, f, o) {
206
A.each(a, function (item, i, a) {
207
r = f.call(o, r, item, i, a);
214
* Executes the supplied function on each item in the array,
215
* searching for the first item that matches the supplied
218
* @param a {Array} the array to search
219
* @param f {Function} the function to execute on each item.
220
* Iteration is stopped as soon as this function returns true
222
* @param o Optional context object
224
* @return {object} the first item that the supplied function
225
* returns true for, or null if it never returns true
227
A.find = function(a, f, o) {
228
for(var i=0, l = a.length; i < l; i++) {
229
if (f.call(o, a[i], i, a)) {
237
* Iterates over an array, returning a new array of all the elements
238
* that match the supplied regular expression
240
* @param a {Array} a collection to iterate over
241
* @param pattern {RegExp} The regular expression to test against
244
* @return {Array} All the items in the collection that
245
* produce a match against the supplied regular expression.
246
* If no items match, an empty array is returned.
248
A.grep = function (a, pattern) {
249
return A.filter(a, function (item, index) {
250
return pattern.test(item);
256
* Partitions an array into two new arrays, one with the items
257
* that match the supplied function, and one with the items that
259
* @method Array.partition
260
* @param a {Array} a collection to iterate over
261
* @paran f {Function} a function that will receive each item
262
* in the collection and its index.
263
* @param o Optional execution context of f.
265
* @return An object with two members, 'matches' and 'rejects',
266
* that are arrays containing the items that were selected or
267
* rejected by the test function (or an empty array).
269
A.partition = function (a, f, o) {
275
A.each(a, function (item, index) {
276
var set = f.call(o, item, index, a) ? results.matches : results.rejects;
284
* Creates an array of arrays by pairing the corresponding
285
* elements of two arrays together into a new array.
287
* @param a {Array} a collection to iterate over
288
* @param a2 {Array} another collection whose members will be
289
* paired with members of the first parameter
291
* @return An array of arrays formed by pairing each element
292
* of the first collection with an item in the second collection
293
* having the corresponding index.
295
A.zip = function (a, a2) {
297
A.each(a, function (item, index) {
298
results.push([item, a2[index]]);
added
removed
src-js/lazrjs/yui/collection/array-extras.js
