# lib/goog/array/array.js

1 | // Copyright 2006 The Closure Library Authors. All Rights Reserved.
2 | //
3 | // Licensed under the Apache License, Version 2.0 (the "License");
4 | // you may not use this file except in compliance with the License.
5 | // You may obtain a copy of the License at
6 | //
7 | // http://www.apache.org/licenses/LICENSE-2.0
8 | //
9 | // Unless required by applicable law or agreed to in writing, software
10 | // distributed under the License is distributed on an "AS-IS" BASIS,
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | // See the License for the specific language governing permissions and
13 | // limitations under the License.
14 |
15 | /**
16 | * @fileoverview Utilities for manipulating arrays.
17 | *
18 | * @author arv@google.com (Erik Arvidsson)
19 | */
20 |
21 |
22 | goog.provide('goog.array');
23 | goog.provide('goog.array.ArrayLike');
24 |
25 | goog.require('goog.asserts');
26 |
27 |
28 | /**
29 | * @define {boolean} NATIVE_ARRAY_PROTOTYPES indicates whether the code should
30 | * rely on Array.prototype functions, if available.
31 | *
32 | * The Array.prototype functions can be defined by external libraries like
33 | * Prototype and setting this flag to false forces closure to use its own
34 | * goog.array implementation.
35 | *
36 | * If your javascript can be loaded by a third party site and you are wary about
37 | * relying on the prototype functions, specify
38 | * "--define goog.NATIVE_ARRAY_PROTOTYPES=false" to the JSCompiler.
39 | *
40 | * Setting goog.TRUSTED_SITE to false will automatically set
41 | * NATIVE_ARRAY_PROTOTYPES to false.
42 | */
43 | goog.define('goog.NATIVE_ARRAY_PROTOTYPES', goog.TRUSTED_SITE);
44 |
45 |
46 | /**
47 | * @define {boolean} If true, JSCompiler will use the native implementation of
48 | * array functions where appropriate (e.g., {@code Array#filter}) and remove the
49 | * unused pure JS implementation.
50 | */
51 | goog.define('goog.array.ASSUME_NATIVE_FUNCTIONS', false);
52 |
53 |
54 | /**
55 | * @typedef {Array|NodeList|Arguments|{length: number}}
56 | */
57 | goog.array.ArrayLike;
58 |
59 |
60 | /**
61 | * Returns the last element in an array without removing it.
62 | * Same as goog.array.last.
63 | * @param {Array<T>|goog.array.ArrayLike} array The array.
64 | * @return {T} Last item in array.
65 | * @template T
66 | */
67 | goog.array.peek = function(array) {
68 | return array[array.length - 1];
69 | };
70 |
71 |
72 | /**
73 | * Returns the last element in an array without removing it.
74 | * Same as goog.array.peek.
75 | * @param {Array<T>|goog.array.ArrayLike} array The array.
76 | * @return {T} Last item in array.
77 | * @template T
78 | */
79 | goog.array.last = goog.array.peek;
80 |
81 |
82 | /**
83 | * Reference to the original {@code Array.prototype}.
84 | * @private {!Object}
85 | */
86 | goog.array.ARRAY_PROTOTYPE_ = Array.prototype;
87 |
88 |
89 | // NOTE(arv): Since most of the array functions are generic it allows you to
90 | // pass an array-like object. Strings have a length and are considered array-
91 | // like. However, the 'in' operator does not work on strings so we cannot just
92 | // use the array path even if the browser supports indexing into strings. We
93 | // therefore end up splitting the string.
94 |
95 |
96 | /**
97 | * Returns the index of the first element of an array with a specified value, or
98 | * -1 if the element is not present in the array.
99 | *
100 | * See {@link http://tinyurl.com/developer-mozilla-org-array-indexof}
101 | *
102 | * @param {Array<T>|goog.array.ArrayLike} arr The array to be searched.
103 | * @param {T} obj The object for which we are searching.
104 | * @param {number=} opt_fromIndex The index at which to start the search. If
105 | * omitted the search starts at index 0.
106 | * @return {number} The index of the first matching array element.
107 | * @template T
108 | */
109 | goog.array.indexOf = goog.NATIVE_ARRAY_PROTOTYPES &&
110 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
111 | goog.array.ARRAY_PROTOTYPE_.indexOf) ?
112 | function(arr, obj, opt_fromIndex) {
113 | goog.asserts.assert(arr.length != null);
114 |
115 | return goog.array.ARRAY_PROTOTYPE_.indexOf.call(arr, obj, opt_fromIndex);
116 | } :
117 | function(arr, obj, opt_fromIndex) {
118 | var fromIndex = opt_fromIndex == null ?
119 | 0 : (opt_fromIndex < 0 ?
120 | Math.max(0, arr.length + opt_fromIndex) : opt_fromIndex);
121 |
122 | if (goog.isString(arr)) {
123 | // Array.prototype.indexOf uses === so only strings should be found.
124 | if (!goog.isString(obj) || obj.length != 1) {
125 | return -1;
126 | }
127 | return arr.indexOf(obj, fromIndex);
128 | }
129 |
130 | for (var i = fromIndex; i < arr.length; i++) {
131 | if (i in arr && arr[i] === obj)
132 | return i;
133 | }
134 | return -1;
135 | };
136 |
137 |
138 | /**
139 | * Returns the index of the last element of an array with a specified value, or
140 | * -1 if the element is not present in the array.
141 | *
142 | * See {@link http://tinyurl.com/developer-mozilla-org-array-lastindexof}
143 | *
144 | * @param {!Array<T>|!goog.array.ArrayLike} arr The array to be searched.
145 | * @param {T} obj The object for which we are searching.
146 | * @param {?number=} opt_fromIndex The index at which to start the search. If
147 | * omitted the search starts at the end of the array.
148 | * @return {number} The index of the last matching array element.
149 | * @template T
150 | */
151 | goog.array.lastIndexOf = goog.NATIVE_ARRAY_PROTOTYPES &&
152 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
153 | goog.array.ARRAY_PROTOTYPE_.lastIndexOf) ?
154 | function(arr, obj, opt_fromIndex) {
155 | goog.asserts.assert(arr.length != null);
156 |
157 | // Firefox treats undefined and null as 0 in the fromIndex argument which
158 | // leads it to always return -1
159 | var fromIndex = opt_fromIndex == null ? arr.length - 1 : opt_fromIndex;
160 | return goog.array.ARRAY_PROTOTYPE_.lastIndexOf.call(arr, obj, fromIndex);
161 | } :
162 | function(arr, obj, opt_fromIndex) {
163 | var fromIndex = opt_fromIndex == null ? arr.length - 1 : opt_fromIndex;
164 |
165 | if (fromIndex < 0) {
166 | fromIndex = Math.max(0, arr.length + fromIndex);
167 | }
168 |
169 | if (goog.isString(arr)) {
170 | // Array.prototype.lastIndexOf uses === so only strings should be found.
171 | if (!goog.isString(obj) || obj.length != 1) {
172 | return -1;
173 | }
174 | return arr.lastIndexOf(obj, fromIndex);
175 | }
176 |
177 | for (var i = fromIndex; i >= 0; i--) {
178 | if (i in arr && arr[i] === obj)
179 | return i;
180 | }
181 | return -1;
182 | };
183 |
184 |
185 | /**
186 | * Calls a function for each element in an array. Skips holes in the array.
187 | * See {@link http://tinyurl.com/developer-mozilla-org-array-foreach}
188 | *
189 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array like object over
190 | * which to iterate.
191 | * @param {?function(this: S, T, number, ?): ?} f The function to call for every
192 | * element. This function takes 3 arguments (the element, the index and the
193 | * array). The return value is ignored.
194 | * @param {S=} opt_obj The object to be used as the value of 'this' within f.
195 | * @template T,S
196 | */
197 | goog.array.forEach = goog.NATIVE_ARRAY_PROTOTYPES &&
198 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
199 | goog.array.ARRAY_PROTOTYPE_.forEach) ?
200 | function(arr, f, opt_obj) {
201 | goog.asserts.assert(arr.length != null);
202 |
203 | goog.array.ARRAY_PROTOTYPE_.forEach.call(arr, f, opt_obj);
204 | } :
205 | function(arr, f, opt_obj) {
206 | var l = arr.length; // must be fixed during loop... see docs
207 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
208 | for (var i = 0; i < l; i++) {
209 | if (i in arr2) {
210 | f.call(opt_obj, arr2[i], i, arr);
211 | }
212 | }
213 | };
214 |
215 |
216 | /**
217 | * Calls a function for each element in an array, starting from the last
218 | * element rather than the first.
219 | *
220 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
221 | * like object over which to iterate.
222 | * @param {?function(this: S, T, number, ?): ?} f The function to call for every
223 | * element. This function
224 | * takes 3 arguments (the element, the index and the array). The return
225 | * value is ignored.
226 | * @param {S=} opt_obj The object to be used as the value of 'this'
227 | * within f.
228 | * @template T,S
229 | */
230 | goog.array.forEachRight = function(arr, f, opt_obj) {
231 | var l = arr.length; // must be fixed during loop... see docs
232 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
233 | for (var i = l - 1; i >= 0; --i) {
234 | if (i in arr2) {
235 | f.call(opt_obj, arr2[i], i, arr);
236 | }
237 | }
238 | };
239 |
240 |
241 | /**
242 | * Calls a function for each element in an array, and if the function returns
243 | * true adds the element to a new array.
244 | *
245 | * See {@link http://tinyurl.com/developer-mozilla-org-array-filter}
246 | *
247 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
248 | * like object over which to iterate.
249 | * @param {?function(this:S, T, number, ?):boolean} f The function to call for
250 | * every element. This function
251 | * takes 3 arguments (the element, the index and the array) and must
252 | * return a Boolean. If the return value is true the element is added to the
253 | * result array. If it is false the element is not included.
254 | * @param {S=} opt_obj The object to be used as the value of 'this'
255 | * within f.
256 | * @return {!Array<T>} a new array in which only elements that passed the test
257 | * are present.
258 | * @template T,S
259 | */
260 | goog.array.filter = goog.NATIVE_ARRAY_PROTOTYPES &&
261 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
262 | goog.array.ARRAY_PROTOTYPE_.filter) ?
263 | function(arr, f, opt_obj) {
264 | goog.asserts.assert(arr.length != null);
265 |
266 | return goog.array.ARRAY_PROTOTYPE_.filter.call(arr, f, opt_obj);
267 | } :
268 | function(arr, f, opt_obj) {
269 | var l = arr.length; // must be fixed during loop... see docs
270 | var res = [];
271 | var resLength = 0;
272 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
273 | for (var i = 0; i < l; i++) {
274 | if (i in arr2) {
275 | var val = arr2[i]; // in case f mutates arr2
276 | if (f.call(opt_obj, val, i, arr)) {
277 | res[resLength++] = val;
278 | }
279 | }
280 | }
281 | return res;
282 | };
283 |
284 |
285 | /**
286 | * Calls a function for each element in an array and inserts the result into a
287 | * new array.
288 | *
289 | * See {@link http://tinyurl.com/developer-mozilla-org-array-map}
290 | *
291 | * @param {Array<VALUE>|goog.array.ArrayLike} arr Array or array like object
292 | * over which to iterate.
293 | * @param {function(this:THIS, VALUE, number, ?): RESULT} f The function to call
294 | * for every element. This function takes 3 arguments (the element,
295 | * the index and the array) and should return something. The result will be
296 | * inserted into a new array.
297 | * @param {THIS=} opt_obj The object to be used as the value of 'this' within f.
298 | * @return {!Array<RESULT>} a new array with the results from f.
299 | * @template THIS, VALUE, RESULT
300 | */
301 | goog.array.map = goog.NATIVE_ARRAY_PROTOTYPES &&
302 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
303 | goog.array.ARRAY_PROTOTYPE_.map) ?
304 | function(arr, f, opt_obj) {
305 | goog.asserts.assert(arr.length != null);
306 |
307 | return goog.array.ARRAY_PROTOTYPE_.map.call(arr, f, opt_obj);
308 | } :
309 | function(arr, f, opt_obj) {
310 | var l = arr.length; // must be fixed during loop... see docs
311 | var res = new Array(l);
312 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
313 | for (var i = 0; i < l; i++) {
314 | if (i in arr2) {
315 | res[i] = f.call(opt_obj, arr2[i], i, arr);
316 | }
317 | }
318 | return res;
319 | };
320 |
321 |
322 | /**
323 | * Passes every element of an array into a function and accumulates the result.
324 | *
325 | * See {@link http://tinyurl.com/developer-mozilla-org-array-reduce}
326 | *
327 | * For example:
328 | * var a = [1, 2, 3, 4];
329 | * goog.array.reduce(a, function(r, v, i, arr) {return r + v;}, 0);
330 | * returns 10
331 | *
332 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
333 | * like object over which to iterate.
334 | * @param {function(this:S, R, T, number, ?) : R} f The function to call for
335 | * every element. This function
336 | * takes 4 arguments (the function's previous result or the initial value,
337 | * the value of the current array element, the current array index, and the
338 | * array itself)
339 | * function(previousValue, currentValue, index, array).
340 | * @param {?} val The initial value to pass into the function on the first call.
341 | * @param {S=} opt_obj The object to be used as the value of 'this'
342 | * within f.
343 | * @return {R} Result of evaluating f repeatedly across the values of the array.
344 | * @template T,S,R
345 | */
346 | goog.array.reduce = goog.NATIVE_ARRAY_PROTOTYPES &&
347 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
348 | goog.array.ARRAY_PROTOTYPE_.reduce) ?
349 | function(arr, f, val, opt_obj) {
350 | goog.asserts.assert(arr.length != null);
351 | if (opt_obj) {
352 | f = goog.bind(f, opt_obj);
353 | }
354 | return goog.array.ARRAY_PROTOTYPE_.reduce.call(arr, f, val);
355 | } :
356 | function(arr, f, val, opt_obj) {
357 | var rval = val;
358 | goog.array.forEach(arr, function(val, index) {
359 | rval = f.call(opt_obj, rval, val, index, arr);
360 | });
361 | return rval;
362 | };
363 |
364 |
365 | /**
366 | * Passes every element of an array into a function and accumulates the result,
367 | * starting from the last element and working towards the first.
368 | *
369 | * See {@link http://tinyurl.com/developer-mozilla-org-array-reduceright}
370 | *
371 | * For example:
372 | * var a = ['a', 'b', 'c'];
373 | * goog.array.reduceRight(a, function(r, v, i, arr) {return r + v;}, '');
374 | * returns 'cba'
375 | *
376 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
377 | * like object over which to iterate.
378 | * @param {?function(this:S, R, T, number, ?) : R} f The function to call for
379 | * every element. This function
380 | * takes 4 arguments (the function's previous result or the initial value,
381 | * the value of the current array element, the current array index, and the
382 | * array itself)
383 | * function(previousValue, currentValue, index, array).
384 | * @param {?} val The initial value to pass into the function on the first call.
385 | * @param {S=} opt_obj The object to be used as the value of 'this'
386 | * within f.
387 | * @return {R} Object returned as a result of evaluating f repeatedly across the
388 | * values of the array.
389 | * @template T,S,R
390 | */
391 | goog.array.reduceRight = goog.NATIVE_ARRAY_PROTOTYPES &&
392 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
393 | goog.array.ARRAY_PROTOTYPE_.reduceRight) ?
394 | function(arr, f, val, opt_obj) {
395 | goog.asserts.assert(arr.length != null);
396 | if (opt_obj) {
397 | f = goog.bind(f, opt_obj);
398 | }
399 | return goog.array.ARRAY_PROTOTYPE_.reduceRight.call(arr, f, val);
400 | } :
401 | function(arr, f, val, opt_obj) {
402 | var rval = val;
403 | goog.array.forEachRight(arr, function(val, index) {
404 | rval = f.call(opt_obj, rval, val, index, arr);
405 | });
406 | return rval;
407 | };
408 |
409 |
410 | /**
411 | * Calls f for each element of an array. If any call returns true, some()
412 | * returns true (without checking the remaining elements). If all calls
413 | * return false, some() returns false.
414 | *
415 | * See {@link http://tinyurl.com/developer-mozilla-org-array-some}
416 | *
417 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
418 | * like object over which to iterate.
419 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call for
420 | * for every element. This function takes 3 arguments (the element, the
421 | * index and the array) and should return a boolean.
422 | * @param {S=} opt_obj The object to be used as the value of 'this'
423 | * within f.
424 | * @return {boolean} true if any element passes the test.
425 | * @template T,S
426 | */
427 | goog.array.some = goog.NATIVE_ARRAY_PROTOTYPES &&
428 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
429 | goog.array.ARRAY_PROTOTYPE_.some) ?
430 | function(arr, f, opt_obj) {
431 | goog.asserts.assert(arr.length != null);
432 |
433 | return goog.array.ARRAY_PROTOTYPE_.some.call(arr, f, opt_obj);
434 | } :
435 | function(arr, f, opt_obj) {
436 | var l = arr.length; // must be fixed during loop... see docs
437 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
438 | for (var i = 0; i < l; i++) {
439 | if (i in arr2 && f.call(opt_obj, arr2[i], i, arr)) {
440 | return true;
441 | }
442 | }
443 | return false;
444 | };
445 |
446 |
447 | /**
448 | * Call f for each element of an array. If all calls return true, every()
449 | * returns true. If any call returns false, every() returns false and
450 | * does not continue to check the remaining elements.
451 | *
452 | * See {@link http://tinyurl.com/developer-mozilla-org-array-every}
453 | *
454 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
455 | * like object over which to iterate.
456 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call for
457 | * for every element. This function takes 3 arguments (the element, the
458 | * index and the array) and should return a boolean.
459 | * @param {S=} opt_obj The object to be used as the value of 'this'
460 | * within f.
461 | * @return {boolean} false if any element fails the test.
462 | * @template T,S
463 | */
464 | goog.array.every = goog.NATIVE_ARRAY_PROTOTYPES &&
465 | (goog.array.ASSUME_NATIVE_FUNCTIONS ||
466 | goog.array.ARRAY_PROTOTYPE_.every) ?
467 | function(arr, f, opt_obj) {
468 | goog.asserts.assert(arr.length != null);
469 |
470 | return goog.array.ARRAY_PROTOTYPE_.every.call(arr, f, opt_obj);
471 | } :
472 | function(arr, f, opt_obj) {
473 | var l = arr.length; // must be fixed during loop... see docs
474 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
475 | for (var i = 0; i < l; i++) {
476 | if (i in arr2 && !f.call(opt_obj, arr2[i], i, arr)) {
477 | return false;
478 | }
479 | }
480 | return true;
481 | };
482 |
483 |
484 | /**
485 | * Counts the array elements that fulfill the predicate, i.e. for which the
486 | * callback function returns true. Skips holes in the array.
487 | *
488 | * @param {!(Array<T>|goog.array.ArrayLike)} arr Array or array like object
489 | * over which to iterate.
490 | * @param {function(this: S, T, number, ?): boolean} f The function to call for
491 | * every element. Takes 3 arguments (the element, the index and the array).
492 | * @param {S=} opt_obj The object to be used as the value of 'this' within f.
493 | * @return {number} The number of the matching elements.
494 | * @template T,S
495 | */
496 | goog.array.count = function(arr, f, opt_obj) {
497 | var count = 0;
498 | goog.array.forEach(arr, function(element, index, arr) {
499 | if (f.call(opt_obj, element, index, arr)) {
500 | ++count;
501 | }
502 | }, opt_obj);
503 | return count;
504 | };
505 |
506 |
507 | /**
508 | * Search an array for the first element that satisfies a given condition and
509 | * return that element.
510 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
511 | * like object over which to iterate.
512 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call
513 | * for every element. This function takes 3 arguments (the element, the
514 | * index and the array) and should return a boolean.
515 | * @param {S=} opt_obj An optional "this" context for the function.
516 | * @return {T|null} The first array element that passes the test, or null if no
517 | * element is found.
518 | * @template T,S
519 | */
520 | goog.array.find = function(arr, f, opt_obj) {
521 | var i = goog.array.findIndex(arr, f, opt_obj);
522 | return i < 0 ? null : goog.isString(arr) ? arr.charAt(i) : arr[i];
523 | };
524 |
525 |
526 | /**
527 | * Search an array for the first element that satisfies a given condition and
528 | * return its index.
529 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
530 | * like object over which to iterate.
531 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call for
532 | * every element. This function
533 | * takes 3 arguments (the element, the index and the array) and should
534 | * return a boolean.
535 | * @param {S=} opt_obj An optional "this" context for the function.
536 | * @return {number} The index of the first array element that passes the test,
537 | * or -1 if no element is found.
538 | * @template T,S
539 | */
540 | goog.array.findIndex = function(arr, f, opt_obj) {
541 | var l = arr.length; // must be fixed during loop... see docs
542 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
543 | for (var i = 0; i < l; i++) {
544 | if (i in arr2 && f.call(opt_obj, arr2[i], i, arr)) {
545 | return i;
546 | }
547 | }
548 | return -1;
549 | };
550 |
551 |
552 | /**
553 | * Search an array (in reverse order) for the last element that satisfies a
554 | * given condition and return that element.
555 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
556 | * like object over which to iterate.
557 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call
558 | * for every element. This function
559 | * takes 3 arguments (the element, the index and the array) and should
560 | * return a boolean.
561 | * @param {S=} opt_obj An optional "this" context for the function.
562 | * @return {T|null} The last array element that passes the test, or null if no
563 | * element is found.
564 | * @template T,S
565 | */
566 | goog.array.findRight = function(arr, f, opt_obj) {
567 | var i = goog.array.findIndexRight(arr, f, opt_obj);
568 | return i < 0 ? null : goog.isString(arr) ? arr.charAt(i) : arr[i];
569 | };
570 |
571 |
572 | /**
573 | * Search an array (in reverse order) for the last element that satisfies a
574 | * given condition and return its index.
575 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
576 | * like object over which to iterate.
577 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call
578 | * for every element. This function
579 | * takes 3 arguments (the element, the index and the array) and should
580 | * return a boolean.
581 | * @param {S=} opt_obj An optional "this" context for the function.
582 | * @return {number} The index of the last array element that passes the test,
583 | * or -1 if no element is found.
584 | * @template T,S
585 | */
586 | goog.array.findIndexRight = function(arr, f, opt_obj) {
587 | var l = arr.length; // must be fixed during loop... see docs
588 | var arr2 = goog.isString(arr) ? arr.split('') : arr;
589 | for (var i = l - 1; i >= 0; i--) {
590 | if (i in arr2 && f.call(opt_obj, arr2[i], i, arr)) {
591 | return i;
592 | }
593 | }
594 | return -1;
595 | };
596 |
597 |
598 | /**
599 | * Whether the array contains the given object.
600 | * @param {goog.array.ArrayLike} arr The array to test for the presence of the
601 | * element.
602 | * @param {*} obj The object for which to test.
603 | * @return {boolean} true if obj is present.
604 | */
605 | goog.array.contains = function(arr, obj) {
606 | return goog.array.indexOf(arr, obj) >= 0;
607 | };
608 |
609 |
610 | /**
611 | * Whether the array is empty.
612 | * @param {goog.array.ArrayLike} arr The array to test.
613 | * @return {boolean} true if empty.
614 | */
615 | goog.array.isEmpty = function(arr) {
616 | return arr.length == 0;
617 | };
618 |
619 |
620 | /**
621 | * Clears the array.
622 | * @param {goog.array.ArrayLike} arr Array or array like object to clear.
623 | */
624 | goog.array.clear = function(arr) {
625 | // For non real arrays we don't have the magic length so we delete the
626 | // indices.
627 | if (!goog.isArray(arr)) {
628 | for (var i = arr.length - 1; i >= 0; i--) {
629 | delete arr[i];
630 | }
631 | }
632 | arr.length = 0;
633 | };
634 |
635 |
636 | /**
637 | * Pushes an item into an array, if it's not already in the array.
638 | * @param {Array<T>} arr Array into which to insert the item.
639 | * @param {T} obj Value to add.
640 | * @template T
641 | */
642 | goog.array.insert = function(arr, obj) {
643 | if (!goog.array.contains(arr, obj)) {
644 | arr.push(obj);
645 | }
646 | };
647 |
648 |
649 | /**
650 | * Inserts an object at the given index of the array.
651 | * @param {goog.array.ArrayLike} arr The array to modify.
652 | * @param {*} obj The object to insert.
653 | * @param {number=} opt_i The index at which to insert the object. If omitted,
654 | * treated as 0. A negative index is counted from the end of the array.
655 | */
656 | goog.array.insertAt = function(arr, obj, opt_i) {
657 | goog.array.splice(arr, opt_i, 0, obj);
658 | };
659 |
660 |
661 | /**
662 | * Inserts at the given index of the array, all elements of another array.
663 | * @param {goog.array.ArrayLike} arr The array to modify.
664 | * @param {goog.array.ArrayLike} elementsToAdd The array of elements to add.
665 | * @param {number=} opt_i The index at which to insert the object. If omitted,
666 | * treated as 0. A negative index is counted from the end of the array.
667 | */
668 | goog.array.insertArrayAt = function(arr, elementsToAdd, opt_i) {
669 | goog.partial(goog.array.splice, arr, opt_i, 0).apply(null, elementsToAdd);
670 | };
671 |
672 |
673 | /**
674 | * Inserts an object into an array before a specified object.
675 | * @param {Array<T>} arr The array to modify.
676 | * @param {T} obj The object to insert.
677 | * @param {T=} opt_obj2 The object before which obj should be inserted. If obj2
678 | * is omitted or not found, obj is inserted at the end of the array.
679 | * @template T
680 | */
681 | goog.array.insertBefore = function(arr, obj, opt_obj2) {
682 | var i;
683 | if (arguments.length == 2 || (i = goog.array.indexOf(arr, opt_obj2)) < 0) {
684 | arr.push(obj);
685 | } else {
686 | goog.array.insertAt(arr, obj, i);
687 | }
688 | };
689 |
690 |
691 | /**
692 | * Removes the first occurrence of a particular value from an array.
693 | * @param {Array<T>|goog.array.ArrayLike} arr Array from which to remove
694 | * value.
695 | * @param {T} obj Object to remove.
696 | * @return {boolean} True if an element was removed.
697 | * @template T
698 | */
699 | goog.array.remove = function(arr, obj) {
700 | var i = goog.array.indexOf(arr, obj);
701 | var rv;
702 | if ((rv = i >= 0)) {
703 | goog.array.removeAt(arr, i);
704 | }
705 | return rv;
706 | };
707 |
708 |
709 | /**
710 | * Removes from an array the element at index i
711 | * @param {goog.array.ArrayLike} arr Array or array like object from which to
712 | * remove value.
713 | * @param {number} i The index to remove.
714 | * @return {boolean} True if an element was removed.
715 | */
716 | goog.array.removeAt = function(arr, i) {
717 | goog.asserts.assert(arr.length != null);
718 |
719 | // use generic form of splice
720 | // splice returns the removed items and if successful the length of that
721 | // will be 1
722 | return goog.array.ARRAY_PROTOTYPE_.splice.call(arr, i, 1).length == 1;
723 | };
724 |
725 |
726 | /**
727 | * Removes the first value that satisfies the given condition.
728 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
729 | * like object over which to iterate.
730 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call
731 | * for every element. This function
732 | * takes 3 arguments (the element, the index and the array) and should
733 | * return a boolean.
734 | * @param {S=} opt_obj An optional "this" context for the function.
735 | * @return {boolean} True if an element was removed.
736 | * @template T,S
737 | */
738 | goog.array.removeIf = function(arr, f, opt_obj) {
739 | var i = goog.array.findIndex(arr, f, opt_obj);
740 | if (i >= 0) {
741 | goog.array.removeAt(arr, i);
742 | return true;
743 | }
744 | return false;
745 | };
746 |
747 |
748 | /**
749 | * Removes all values that satisfy the given condition.
750 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array
751 | * like object over which to iterate.
752 | * @param {?function(this:S, T, number, ?) : boolean} f The function to call
753 | * for every element. This function
754 | * takes 3 arguments (the element, the index and the array) and should
755 | * return a boolean.
756 | * @param {S=} opt_obj An optional "this" context for the function.
757 | * @return {number} The number of items removed
758 | * @template T,S
759 | */
760 | goog.array.removeAllIf = function(arr, f, opt_obj) {
761 | var removedCount = 0;
762 | goog.array.forEachRight(arr, function(val, index) {
763 | if (f.call(opt_obj, val, index, arr)) {
764 | if (goog.array.removeAt(arr, index)) {
765 | removedCount++;
766 | }
767 | }
768 | });
769 | return removedCount;
770 | };
771 |
772 |
773 | /**
774 | * Returns a new array that is the result of joining the arguments. If arrays
775 | * are passed then their items are added, however, if non-arrays are passed they
776 | * will be added to the return array as is.
777 | *
778 | * Note that ArrayLike objects will be added as is, rather than having their
779 | * items added.
780 | *
781 | * goog.array.concat([1, 2], [3, 4]) -> [1, 2, 3, 4]
782 | * goog.array.concat(0, [1, 2]) -> [0, 1, 2]
783 | * goog.array.concat([1, 2], null) -> [1, 2, null]
784 | *
785 | * There is bug in all current versions of IE (6, 7 and 8) where arrays created
786 | * in an iframe become corrupted soon (not immediately) after the iframe is
787 | * destroyed. This is common if loading data via goog.net.IframeIo, for example.
788 | * This corruption only affects the concat method which will start throwing
789 | * Catastrophic Errors (#-2147418113).
790 | *
791 | * See http://endoflow.com/scratch/corrupted-arrays.html for a test case.
792 | *
793 | * Internally goog.array should use this, so that all methods will continue to
794 | * work on these broken array objects.
795 | *
796 | * @param {...*} var_args Items to concatenate. Arrays will have each item
797 | * added, while primitives and objects will be added as is.
798 | * @return {!Array<?>} The new resultant array.
799 | */
800 | goog.array.concat = function(var_args) {
801 | return goog.array.ARRAY_PROTOTYPE_.concat.apply(
802 | goog.array.ARRAY_PROTOTYPE_, arguments);
803 | };
804 |
805 |
806 | /**
807 | * Returns a new array that contains the contents of all the arrays passed.
808 | * @param {...!Array<T>} var_args
809 | * @return {!Array<T>}
810 | * @template T
811 | */
812 | goog.array.join = function(var_args) {
813 | return goog.array.ARRAY_PROTOTYPE_.concat.apply(
814 | goog.array.ARRAY_PROTOTYPE_, arguments);
815 | };
816 |
817 |
818 | /**
819 | * Converts an object to an array.
820 | * @param {Array<T>|goog.array.ArrayLike} object The object to convert to an
821 | * array.
822 | * @return {!Array<T>} The object converted into an array. If object has a
823 | * length property, every property indexed with a non-negative number
824 | * less than length will be included in the result. If object does not
825 | * have a length property, an empty array will be returned.
826 | * @template T
827 | */
828 | goog.array.toArray = function(object) {
829 | var length = object.length;
830 |
831 | // If length is not a number the following it false. This case is kept for
832 | // backwards compatibility since there are callers that pass objects that are
833 | // not array like.
834 | if (length > 0) {
835 | var rv = new Array(length);
836 | for (var i = 0; i < length; i++) {
837 | rv[i] = object[i];
838 | }
839 | return rv;
840 | }
841 | return [];
842 | };
843 |
844 |
845 | /**
846 | * Does a shallow copy of an array.
847 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array-like object to
848 | * clone.
849 | * @return {!Array<T>} Clone of the input array.
850 | * @template T
851 | */
852 | goog.array.clone = goog.array.toArray;
853 |
854 |
855 | /**
856 | * Extends an array with another array, element, or "array like" object.
857 | * This function operates 'in-place', it does not create a new Array.
858 | *
859 | * Example:
860 | * var a = [];
861 | * goog.array.extend(a, [0, 1]);
862 | * a; // [0, 1]
863 | * goog.array.extend(a, 2);
864 | * a; // [0, 1, 2]
865 | *
866 | * @param {Array<VALUE>} arr1 The array to modify.
867 | * @param {...(Array<VALUE>|VALUE)} var_args The elements or arrays of elements
868 | * to add to arr1.
869 | * @template VALUE
870 | */
871 | goog.array.extend = function(arr1, var_args) {
872 | for (var i = 1; i < arguments.length; i++) {
873 | var arr2 = arguments[i];
874 | if (goog.isArrayLike(arr2)) {
875 | var len1 = arr1.length || 0;
876 | var len2 = arr2.length || 0;
877 | arr1.length = len1 + len2;
878 | for (var j = 0; j < len2; j++) {
879 | arr1[len1 + j] = arr2[j];
880 | }
881 | } else {
882 | arr1.push(arr2);
883 | }
884 | }
885 | };
886 |
887 |
888 | /**
889 | * Adds or removes elements from an array. This is a generic version of Array
890 | * splice. This means that it might work on other objects similar to arrays,
891 | * such as the arguments object.
892 | *
893 | * @param {Array<T>|goog.array.ArrayLike} arr The array to modify.
894 | * @param {number|undefined} index The index at which to start changing the
895 | * array. If not defined, treated as 0.
896 | * @param {number} howMany How many elements to remove (0 means no removal. A
897 | * value below 0 is treated as zero and so is any other non number. Numbers
898 | * are floored).
899 | * @param {...T} var_args Optional, additional elements to insert into the
900 | * array.
901 | * @return {!Array<T>} the removed elements.
902 | * @template T
903 | */
904 | goog.array.splice = function(arr, index, howMany, var_args) {
905 | goog.asserts.assert(arr.length != null);
906 |
907 | return goog.array.ARRAY_PROTOTYPE_.splice.apply(
908 | arr, goog.array.slice(arguments, 1));
909 | };
910 |
911 |
912 | /**
913 | * Returns a new array from a segment of an array. This is a generic version of
914 | * Array slice. This means that it might work on other objects similar to
915 | * arrays, such as the arguments object.
916 | *
917 | * @param {Array<T>|goog.array.ArrayLike} arr The array from
918 | * which to copy a segment.
919 | * @param {number} start The index of the first element to copy.
920 | * @param {number=} opt_end The index after the last element to copy.
921 | * @return {!Array<T>} A new array containing the specified segment of the
922 | * original array.
923 | * @template T
924 | */
925 | goog.array.slice = function(arr, start, opt_end) {
926 | goog.asserts.assert(arr.length != null);
927 |
928 | // passing 1 arg to slice is not the same as passing 2 where the second is
929 | // null or undefined (in that case the second argument is treated as 0).
930 | // we could use slice on the arguments object and then use apply instead of
931 | // testing the length
932 | if (arguments.length <= 2) {
933 | return goog.array.ARRAY_PROTOTYPE_.slice.call(arr, start);
934 | } else {
935 | return goog.array.ARRAY_PROTOTYPE_.slice.call(arr, start, opt_end);
936 | }
937 | };
938 |
939 |
940 | /**
941 | * Removes all duplicates from an array (retaining only the first
942 | * occurrence of each array element). This function modifies the
943 | * array in place and doesn't change the order of the non-duplicate items.
944 | *
945 | * For objects, duplicates are identified as having the same unique ID as
946 | * defined by {@link goog.getUid}.
947 | *
948 | * Alternatively you can specify a custom hash function that returns a unique
949 | * value for each item in the array it should consider unique.
950 | *
951 | * Runtime: N,
952 | * Worstcase space: 2N (no dupes)
953 | *
954 | * @param {Array<T>|goog.array.ArrayLike} arr The array from which to remove
955 | * duplicates.
956 | * @param {Array=} opt_rv An optional array in which to return the results,
957 | * instead of performing the removal inplace. If specified, the original
958 | * array will remain unchanged.
959 | * @param {function(T):string=} opt_hashFn An optional function to use to
960 | * apply to every item in the array. This function should return a unique
961 | * value for each item in the array it should consider unique.
962 | * @template T
963 | */
964 | goog.array.removeDuplicates = function(arr, opt_rv, opt_hashFn) {
965 | var returnArray = opt_rv || arr;
966 | var defaultHashFn = function(item) {
967 | // Prefix each type with a single character representing the type to
968 | // prevent conflicting keys (e.g. true and 'true').
969 | return goog.isObject(item) ? 'o' + goog.getUid(item) :
970 | (typeof item).charAt(0) + item;
971 | };
972 | var hashFn = opt_hashFn || defaultHashFn;
973 |
974 | var seen = {}, cursorInsert = 0, cursorRead = 0;
975 | while (cursorRead < arr.length) {
976 | var current = arr[cursorRead++];
977 | var key = hashFn(current);
978 | if (!Object.prototype.hasOwnProperty.call(seen, key)) {
979 | seen[key] = true;
980 | returnArray[cursorInsert++] = current;
981 | }
982 | }
983 | returnArray.length = cursorInsert;
984 | };
985 |
986 |
987 | /**
988 | * Searches the specified array for the specified target using the binary
989 | * search algorithm. If no opt_compareFn is specified, elements are compared
990 | * using <code>goog.array.defaultCompare</code>, which compares the elements
991 | * using the built in < and > operators. This will produce the expected
992 | * behavior for homogeneous arrays of String(s) and Number(s). The array
993 | * specified <b>must</b> be sorted in ascending order (as defined by the
994 | * comparison function). If the array is not sorted, results are undefined.
995 | * If the array contains multiple instances of the specified target value, any
996 | * of these instances may be found.
997 | *
998 | * Runtime: O(log n)
999 | *
1000 | * @param {Array<VALUE>|goog.array.ArrayLike} arr The array to be searched.
1001 | * @param {TARGET} target The sought value.
1002 | * @param {function(TARGET, VALUE): number=} opt_compareFn Optional comparison
1003 | * function by which the array is ordered. Should take 2 arguments to
1004 | * compare, and return a negative number, zero, or a positive number
1005 | * depending on whether the first argument is less than, equal to, or
1006 | * greater than the second.
1007 | * @return {number} Lowest index of the target value if found, otherwise
1008 | * (-(insertion point) - 1). The insertion point is where the value should
1009 | * be inserted into arr to preserve the sorted property. Return value >= 0
1010 | * iff target is found.
1011 | * @template TARGET, VALUE
1012 | */
1013 | goog.array.binarySearch = function(arr, target, opt_compareFn) {
1014 | return goog.array.binarySearch_(arr,
1015 | opt_compareFn || goog.array.defaultCompare, false /* isEvaluator */,
1016 | target);
1017 | };
1018 |
1019 |
1020 | /**
1021 | * Selects an index in the specified array using the binary search algorithm.
1022 | * The evaluator receives an element and determines whether the desired index
1023 | * is before, at, or after it. The evaluator must be consistent (formally,
1024 | * goog.array.map(goog.array.map(arr, evaluator, opt_obj), goog.math.sign)
1025 | * must be monotonically non-increasing).
1026 | *
1027 | * Runtime: O(log n)
1028 | *
1029 | * @param {Array<VALUE>|goog.array.ArrayLike} arr The array to be searched.
1030 | * @param {function(this:THIS, VALUE, number, ?): number} evaluator
1031 | * Evaluator function that receives 3 arguments (the element, the index and
1032 | * the array). Should return a negative number, zero, or a positive number
1033 | * depending on whether the desired index is before, at, or after the
1034 | * element passed to it.
1035 | * @param {THIS=} opt_obj The object to be used as the value of 'this'
1036 | * within evaluator.
1037 | * @return {number} Index of the leftmost element matched by the evaluator, if
1038 | * such exists; otherwise (-(insertion point) - 1). The insertion point is
1039 | * the index of the first element for which the evaluator returns negative,
1040 | * or arr.length if no such element exists. The return value is non-negative
1041 | * iff a match is found.
1042 | * @template THIS, VALUE
1043 | */
1044 | goog.array.binarySelect = function(arr, evaluator, opt_obj) {
1045 | return goog.array.binarySearch_(arr, evaluator, true /* isEvaluator */,
1046 | undefined /* opt_target */, opt_obj);
1047 | };
1048 |
1049 |
1050 | /**
1051 | * Implementation of a binary search algorithm which knows how to use both
1052 | * comparison functions and evaluators. If an evaluator is provided, will call
1053 | * the evaluator with the given optional data object, conforming to the
1054 | * interface defined in binarySelect. Otherwise, if a comparison function is
1055 | * provided, will call the comparison function against the given data object.
1056 | *
1057 | * This implementation purposefully does not use goog.bind or goog.partial for
1058 | * performance reasons.
1059 | *
1060 | * Runtime: O(log n)
1061 | *
1062 | * @param {Array<?>|goog.array.ArrayLike} arr The array to be searched.
1063 | * @param {function(?, ?, ?): number | function(?, ?): number} compareFn
1064 | * Either an evaluator or a comparison function, as defined by binarySearch
1065 | * and binarySelect above.
1066 | * @param {boolean} isEvaluator Whether the function is an evaluator or a
1067 | * comparison function.
1068 | * @param {?=} opt_target If the function is a comparison function, then
1069 | * this is the target to binary search for.
1070 | * @param {Object=} opt_selfObj If the function is an evaluator, this is an
1071 | * optional this object for the evaluator.
1072 | * @return {number} Lowest index of the target value if found, otherwise
1073 | * (-(insertion point) - 1). The insertion point is where the value should
1074 | * be inserted into arr to preserve the sorted property. Return value >= 0
1075 | * iff target is found.
1076 | * @private
1077 | */
1078 | goog.array.binarySearch_ = function(arr, compareFn, isEvaluator, opt_target,
1079 | opt_selfObj) {
1080 | var left = 0; // inclusive
1081 | var right = arr.length; // exclusive
1082 | var found;
1083 | while (left < right) {
1084 | var middle = (left + right) >> 1;
1085 | var compareResult;
1086 | if (isEvaluator) {
1087 | compareResult = compareFn.call(opt_selfObj, arr[middle], middle, arr);
1088 | } else {
1089 | compareResult = compareFn(opt_target, arr[middle]);
1090 | }
1091 | if (compareResult > 0) {
1092 | left = middle + 1;
1093 | } else {
1094 | right = middle;
1095 | // We are looking for the lowest index so we can't return immediately.
1096 | found = !compareResult;
1097 | }
1098 | }
1099 | // left is the index if found, or the insertion point otherwise.
1100 | // ~left is a shorthand for -left - 1.
1101 | return found ? left : ~left;
1102 | };
1103 |
1104 |
1105 | /**
1106 | * Sorts the specified array into ascending order. If no opt_compareFn is
1107 | * specified, elements are compared using
1108 | * <code>goog.array.defaultCompare</code>, which compares the elements using
1109 | * the built in < and > operators. This will produce the expected behavior
1110 | * for homogeneous arrays of String(s) and Number(s), unlike the native sort,
1111 | * but will give unpredictable results for heterogenous lists of strings and
1112 | * numbers with different numbers of digits.
1113 | *
1114 | * This sort is not guaranteed to be stable.
1115 | *
1116 | * Runtime: Same as <code>Array.prototype.sort</code>
1117 | *
1118 | * @param {Array<T>} arr The array to be sorted.
1119 | * @param {?function(T,T):number=} opt_compareFn Optional comparison
1120 | * function by which the
1121 | * array is to be ordered. Should take 2 arguments to compare, and return a
1122 | * negative number, zero, or a positive number depending on whether the
1123 | * first argument is less than, equal to, or greater than the second.
1124 | * @template T
1125 | */
1126 | goog.array.sort = function(arr, opt_compareFn) {
1127 | // TODO(arv): Update type annotation since null is not accepted.
1128 | arr.sort(opt_compareFn || goog.array.defaultCompare);
1129 | };
1130 |
1131 |
1132 | /**
1133 | * Sorts the specified array into ascending order in a stable way. If no
1134 | * opt_compareFn is specified, elements are compared using
1135 | * <code>goog.array.defaultCompare</code>, which compares the elements using
1136 | * the built in < and > operators. This will produce the expected behavior
1137 | * for homogeneous arrays of String(s) and Number(s).
1138 | *
1139 | * Runtime: Same as <code>Array.prototype.sort</code>, plus an additional
1140 | * O(n) overhead of copying the array twice.
1141 | *
1142 | * @param {Array<T>} arr The array to be sorted.
1143 | * @param {?function(T, T): number=} opt_compareFn Optional comparison function
1144 | * by which the array is to be ordered. Should take 2 arguments to compare,
1145 | * and return a negative number, zero, or a positive number depending on
1146 | * whether the first argument is less than, equal to, or greater than the
1147 | * second.
1148 | * @template T
1149 | */
1150 | goog.array.stableSort = function(arr, opt_compareFn) {
1151 | for (var i = 0; i < arr.length; i++) {
1152 | arr[i] = {index: i, value: arr[i]};
1153 | }
1154 | var valueCompareFn = opt_compareFn || goog.array.defaultCompare;
1155 | function stableCompareFn(obj1, obj2) {
1156 | return valueCompareFn(obj1.value, obj2.value) || obj1.index - obj2.index;
1157 | };
1158 | goog.array.sort(arr, stableCompareFn);
1159 | for (var i = 0; i < arr.length; i++) {
1160 | arr[i] = arr[i].value;
1161 | }
1162 | };
1163 |
1164 |
1165 | /**
1166 | * Sort the specified array into ascending order based on item keys
1167 | * returned by the specified key function.
1168 | * If no opt_compareFn is specified, the keys are compared in ascending order
1169 | * using <code>goog.array.defaultCompare</code>.
1170 | *
1171 | * Runtime: O(S(f(n)), where S is runtime of <code>goog.array.sort</code>
1172 | * and f(n) is runtime of the key function.
1173 | *
1174 | * @param {Array<T>} arr The array to be sorted.
1175 | * @param {function(T): K} keyFn Function taking array element and returning
1176 | * a key used for sorting this element.
1177 | * @param {?function(K, K): number=} opt_compareFn Optional comparison function
1178 | * by which the keys are to be ordered. Should take 2 arguments to compare,
1179 | * and return a negative number, zero, or a positive number depending on
1180 | * whether the first argument is less than, equal to, or greater than the
1181 | * second.
1182 | * @template T,K
1183 | */
1184 | goog.array.sortByKey = function(arr, keyFn, opt_compareFn) {
1185 | var keyCompareFn = opt_compareFn || goog.array.defaultCompare;
1186 | goog.array.sort(arr, function(a, b) {
1187 | return keyCompareFn(keyFn(a), keyFn(b));
1188 | });
1189 | };
1190 |
1191 |
1192 | /**
1193 | * Sorts an array of objects by the specified object key and compare
1194 | * function. If no compare function is provided, the key values are
1195 | * compared in ascending order using <code>goog.array.defaultCompare</code>.
1196 | * This won't work for keys that get renamed by the compiler. So use
1197 | * {'foo': 1, 'bar': 2} rather than {foo: 1, bar: 2}.
1198 | * @param {Array<Object>} arr An array of objects to sort.
1199 | * @param {string} key The object key to sort by.
1200 | * @param {Function=} opt_compareFn The function to use to compare key
1201 | * values.
1202 | */
1203 | goog.array.sortObjectsByKey = function(arr, key, opt_compareFn) {
1204 | goog.array.sortByKey(arr,
1205 | function(obj) { return obj[key]; },
1206 | opt_compareFn);
1207 | };
1208 |
1209 |
1210 | /**
1211 | * Tells if the array is sorted.
1212 | * @param {!Array<T>} arr The array.
1213 | * @param {?function(T,T):number=} opt_compareFn Function to compare the
1214 | * array elements.
1215 | * Should take 2 arguments to compare, and return a negative number, zero,
1216 | * or a positive number depending on whether the first argument is less
1217 | * than, equal to, or greater than the second.
1218 | * @param {boolean=} opt_strict If true no equal elements are allowed.
1219 | * @return {boolean} Whether the array is sorted.
1220 | * @template T
1221 | */
1222 | goog.array.isSorted = function(arr, opt_compareFn, opt_strict) {
1223 | var compare = opt_compareFn || goog.array.defaultCompare;
1224 | for (var i = 1; i < arr.length; i++) {
1225 | var compareResult = compare(arr[i - 1], arr[i]);
1226 | if (compareResult > 0 || compareResult == 0 && opt_strict) {
1227 | return false;
1228 | }
1229 | }
1230 | return true;
1231 | };
1232 |
1233 |
1234 | /**
1235 | * Compares two arrays for equality. Two arrays are considered equal if they
1236 | * have the same length and their corresponding elements are equal according to
1237 | * the comparison function.
1238 | *
1239 | * @param {goog.array.ArrayLike} arr1 The first array to compare.
1240 | * @param {goog.array.ArrayLike} arr2 The second array to compare.
1241 | * @param {Function=} opt_equalsFn Optional comparison function.
1242 | * Should take 2 arguments to compare, and return true if the arguments
1243 | * are equal. Defaults to {@link goog.array.defaultCompareEquality} which
1244 | * compares the elements using the built-in '===' operator.
1245 | * @return {boolean} Whether the two arrays are equal.
1246 | */
1247 | goog.array.equals = function(arr1, arr2, opt_equalsFn) {
1248 | if (!goog.isArrayLike(arr1) || !goog.isArrayLike(arr2) ||
1249 | arr1.length != arr2.length) {
1250 | return false;
1251 | }
1252 | var l = arr1.length;
1253 | var equalsFn = opt_equalsFn || goog.array.defaultCompareEquality;
1254 | for (var i = 0; i < l; i++) {
1255 | if (!equalsFn(arr1[i], arr2[i])) {
1256 | return false;
1257 | }
1258 | }
1259 | return true;
1260 | };
1261 |
1262 |
1263 | /**
1264 | * 3-way array compare function.
1265 | * @param {!Array<VALUE>|!goog.array.ArrayLike} arr1 The first array to
1266 | * compare.
1267 | * @param {!Array<VALUE>|!goog.array.ArrayLike} arr2 The second array to
1268 | * compare.
1269 | * @param {function(VALUE, VALUE): number=} opt_compareFn Optional comparison
1270 | * function by which the array is to be ordered. Should take 2 arguments to
1271 | * compare, and return a negative number, zero, or a positive number
1272 | * depending on whether the first argument is less than, equal to, or
1273 | * greater than the second.
1274 | * @return {number} Negative number, zero, or a positive number depending on
1275 | * whether the first argument is less than, equal to, or greater than the
1276 | * second.
1277 | * @template VALUE
1278 | */
1279 | goog.array.compare3 = function(arr1, arr2, opt_compareFn) {
1280 | var compare = opt_compareFn || goog.array.defaultCompare;
1281 | var l = Math.min(arr1.length, arr2.length);
1282 | for (var i = 0; i < l; i++) {
1283 | var result = compare(arr1[i], arr2[i]);
1284 | if (result != 0) {
1285 | return result;
1286 | }
1287 | }
1288 | return goog.array.defaultCompare(arr1.length, arr2.length);
1289 | };
1290 |
1291 |
1292 | /**
1293 | * Compares its two arguments for order, using the built in < and >
1294 | * operators.
1295 | * @param {VALUE} a The first object to be compared.
1296 | * @param {VALUE} b The second object to be compared.
1297 | * @return {number} A negative number, zero, or a positive number as the first
1298 | * argument is less than, equal to, or greater than the second,
1299 | * respectively.
1300 | * @template VALUE
1301 | */
1302 | goog.array.defaultCompare = function(a, b) {
1303 | return a > b ? 1 : a < b ? -1 : 0;
1304 | };
1305 |
1306 |
1307 | /**
1308 | * Compares its two arguments for inverse order, using the built in < and >
1309 | * operators.
1310 | * @param {VALUE} a The first object to be compared.
1311 | * @param {VALUE} b The second object to be compared.
1312 | * @return {number} A negative number, zero, or a positive number as the first
1313 | * argument is greater than, equal to, or less than the second,
1314 | * respectively.
1315 | * @template VALUE
1316 | */
1317 | goog.array.inverseDefaultCompare = function(a, b) {
1318 | return -goog.array.defaultCompare(a, b);
1319 | };
1320 |
1321 |
1322 | /**
1323 | * Compares its two arguments for equality, using the built in === operator.
1324 | * @param {*} a The first object to compare.
1325 | * @param {*} b The second object to compare.
1326 | * @return {boolean} True if the two arguments are equal, false otherwise.
1327 | */
1328 | goog.array.defaultCompareEquality = function(a, b) {
1329 | return a === b;
1330 | };
1331 |
1332 |
1333 | /**
1334 | * Inserts a value into a sorted array. The array is not modified if the
1335 | * value is already present.
1336 | * @param {Array<VALUE>|goog.array.ArrayLike} array The array to modify.
1337 | * @param {VALUE} value The object to insert.
1338 | * @param {function(VALUE, VALUE): number=} opt_compareFn Optional comparison
1339 | * function by which the array is ordered. Should take 2 arguments to
1340 | * compare, and return a negative number, zero, or a positive number
1341 | * depending on whether the first argument is less than, equal to, or
1342 | * greater than the second.
1343 | * @return {boolean} True if an element was inserted.
1344 | * @template VALUE
1345 | */
1346 | goog.array.binaryInsert = function(array, value, opt_compareFn) {
1347 | var index = goog.array.binarySearch(array, value, opt_compareFn);
1348 | if (index < 0) {
1349 | goog.array.insertAt(array, value, -(index + 1));
1350 | return true;
1351 | }
1352 | return false;
1353 | };
1354 |
1355 |
1356 | /**
1357 | * Removes a value from a sorted array.
1358 | * @param {!Array<VALUE>|!goog.array.ArrayLike} array The array to modify.
1359 | * @param {VALUE} value The object to remove.
1360 | * @param {function(VALUE, VALUE): number=} opt_compareFn Optional comparison
1361 | * function by which the array is ordered. Should take 2 arguments to
1362 | * compare, and return a negative number, zero, or a positive number
1363 | * depending on whether the first argument is less than, equal to, or
1364 | * greater than the second.
1365 | * @return {boolean} True if an element was removed.
1366 | * @template VALUE
1367 | */
1368 | goog.array.binaryRemove = function(array, value, opt_compareFn) {
1369 | var index = goog.array.binarySearch(array, value, opt_compareFn);
1370 | return (index >= 0) ? goog.array.removeAt(array, index) : false;
1371 | };
1372 |
1373 |
1374 | /**
1375 | * Splits an array into disjoint buckets according to a splitting function.
1376 | * @param {Array<T>} array The array.
1377 | * @param {function(this:S, T,number,Array<T>):?} sorter Function to call for
1378 | * every element. This takes 3 arguments (the element, the index and the
1379 | * array) and must return a valid object key (a string, number, etc), or
1380 | * undefined, if that object should not be placed in a bucket.
1381 | * @param {S=} opt_obj The object to be used as the value of 'this' within
1382 | * sorter.
1383 | * @return {!Object} An object, with keys being all of the unique return values
1384 | * of sorter, and values being arrays containing the items for
1385 | * which the splitter returned that key.
1386 | * @template T,S
1387 | */
1388 | goog.array.bucket = function(array, sorter, opt_obj) {
1389 | var buckets = {};
1390 |
1391 | for (var i = 0; i < array.length; i++) {
1392 | var value = array[i];
1393 | var key = sorter.call(opt_obj, value, i, array);
1394 | if (goog.isDef(key)) {
1395 | // Push the value to the right bucket, creating it if necessary.
1396 | var bucket = buckets[key] || (buckets[key] = []);
1397 | bucket.push(value);
1398 | }
1399 | }
1400 |
1401 | return buckets;
1402 | };
1403 |
1404 |
1405 | /**
1406 | * Creates a new object built from the provided array and the key-generation
1407 | * function.
1408 | * @param {Array<T>|goog.array.ArrayLike} arr Array or array like object over
1409 | * which to iterate whose elements will be the values in the new object.
1410 | * @param {?function(this:S, T, number, ?) : string} keyFunc The function to
1411 | * call for every element. This function takes 3 arguments (the element, the
1412 | * index and the array) and should return a string that will be used as the
1413 | * key for the element in the new object. If the function returns the same
1414 | * key for more than one element, the value for that key is
1415 | * implementation-defined.
1416 | * @param {S=} opt_obj The object to be used as the value of 'this'
1417 | * within keyFunc.
1418 | * @return {!Object<T>} The new object.
1419 | * @template T,S
1420 | */
1421 | goog.array.toObject = function(arr, keyFunc, opt_obj) {
1422 | var ret = {};
1423 | goog.array.forEach(arr, function(element, index) {
1424 | ret[keyFunc.call(opt_obj, element, index, arr)] = element;
1425 | });
1426 | return ret;
1427 | };
1428 |
1429 |
1430 | /**
1431 | * Creates a range of numbers in an arithmetic progression.
1432 | *
1433 | * Range takes 1, 2, or 3 arguments:
1434 | * <pre>
1435 | * range(5) is the same as range(0, 5, 1) and produces [0, 1, 2, 3, 4]
1436 | * range(2, 5) is the same as range(2, 5, 1) and produces [2, 3, 4]
1437 | * range(-2, -5, -1) produces [-2, -3, -4]
1438 | * range(-2, -5, 1) produces [], since stepping by 1 wouldn't ever reach -5.
1439 | * </pre>
1440 | *
1441 | * @param {number} startOrEnd The starting value of the range if an end argument
1442 | * is provided. Otherwise, the start value is 0, and this is the end value.
1443 | * @param {number=} opt_end The optional end value of the range.
1444 | * @param {number=} opt_step The step size between range values. Defaults to 1
1445 | * if opt_step is undefined or 0.
1446 | * @return {!Array<number>} An array of numbers for the requested range. May be
1447 | * an empty array if adding the step would not converge toward the end
1448 | * value.
1449 | */
1450 | goog.array.range = function(startOrEnd, opt_end, opt_step) {
1451 | var array = [];
1452 | var start = 0;
1453 | var end = startOrEnd;
1454 | var step = opt_step || 1;
1455 | if (opt_end !== undefined) {
1456 | start = startOrEnd;
1457 | end = opt_end;
1458 | }
1459 |
1460 | if (step * (end - start) < 0) {
1461 | // Sign mismatch: start + step will never reach the end value.
1462 | return [];
1463 | }
1464 |
1465 | if (step > 0) {
1466 | for (var i = start; i < end; i += step) {
1467 | array.push(i);
1468 | }
1469 | } else {
1470 | for (var i = start; i > end; i += step) {
1471 | array.push(i);
1472 | }
1473 | }
1474 | return array;
1475 | };
1476 |
1477 |
1478 | /**
1479 | * Returns an array consisting of the given value repeated N times.
1480 | *
1481 | * @param {VALUE} value The value to repeat.
1482 | * @param {number} n The repeat count.
1483 | * @return {!Array<VALUE>} An array with the repeated value.
1484 | * @template VALUE
1485 | */
1486 | goog.array.repeat = function(value, n) {
1487 | var array = [];
1488 | for (var i = 0; i < n; i++) {
1489 | array[i] = value;
1490 | }
1491 | return array;
1492 | };
1493 |
1494 |
1495 | /**
1496 | * Returns an array consisting of every argument with all arrays
1497 | * expanded in-place recursively.
1498 | *
1499 | * @param {...*} var_args The values to flatten.
1500 | * @return {!Array<?>} An array containing the flattened values.
1501 | */
1502 | goog.array.flatten = function(var_args) {
1503 | var CHUNK_SIZE = 8192;
1504 |
1505 | var result = [];
1506 | for (var i = 0; i < arguments.length; i++) {
1507 | var element = arguments[i];
1508 | if (goog.isArray(element)) {
1509 | for (var c = 0; c < element.length; c += CHUNK_SIZE) {
1510 | var chunk = goog.array.slice(element, c, c + CHUNK_SIZE);
1511 | var recurseResult = goog.array.flatten.apply(null, chunk);
1512 | for (var r = 0; r < recurseResult.length; r++) {
1513 | result.push(recurseResult[r]);
1514 | }
1515 | }
1516 | } else {
1517 | result.push(element);
1518 | }
1519 | }
1520 | return result;
1521 | };
1522 |
1523 |
1524 | /**
1525 | * Rotates an array in-place. After calling this method, the element at
1526 | * index i will be the element previously at index (i - n) %
1527 | * array.length, for all values of i between 0 and array.length - 1,
1528 | * inclusive.
1529 | *
1530 | * For example, suppose list comprises [t, a, n, k, s]. After invoking
1531 | * rotate(array, 1) (or rotate(array, -4)), array will comprise [s, t, a, n, k].
1532 | *
1533 | * @param {!Array<T>} array The array to rotate.
1534 | * @param {number} n The amount to rotate.
1535 | * @return {!Array<T>} The array.
1536 | * @template T
1537 | */
1538 | goog.array.rotate = function(array, n) {
1539 | goog.asserts.assert(array.length != null);
1540 |
1541 | if (array.length) {
1542 | n %= array.length;
1543 | if (n > 0) {
1544 | goog.array.ARRAY_PROTOTYPE_.unshift.apply(array, array.splice(-n, n));
1545 | } else if (n < 0) {
1546 | goog.array.ARRAY_PROTOTYPE_.push.apply(array, array.splice(0, -n));
1547 | }
1548 | }
1549 | return array;
1550 | };
1551 |
1552 |
1553 | /**
1554 | * Moves one item of an array to a new position keeping the order of the rest
1555 | * of the items. Example use case: keeping a list of JavaScript objects
1556 | * synchronized with the corresponding list of DOM elements after one of the
1557 | * elements has been dragged to a new position.
1558 | * @param {!(Array|Arguments|{length:number})} arr The array to modify.
1559 | * @param {number} fromIndex Index of the item to move between 0 and
1560 | * {@code arr.length - 1}.
1561 | * @param {number} toIndex Target index between 0 and {@code arr.length - 1}.
1562 | */
1563 | goog.array.moveItem = function(arr, fromIndex, toIndex) {
1564 | goog.asserts.assert(fromIndex >= 0 && fromIndex < arr.length);
1565 | goog.asserts.assert(toIndex >= 0 && toIndex < arr.length);
1566 | // Remove 1 item at fromIndex.
1567 | var removedItems = goog.array.ARRAY_PROTOTYPE_.splice.call(arr, fromIndex, 1);
1568 | // Insert the removed item at toIndex.
1569 | goog.array.ARRAY_PROTOTYPE_.splice.call(arr, toIndex, 0, removedItems[0]);
1570 | // We don't use goog.array.insertAt and goog.array.removeAt, because they're
1571 | // significantly slower than splice.
1572 | };
1573 |
1574 |
1575 | /**
1576 | * Creates a new array for which the element at position i is an array of the
1577 | * ith element of the provided arrays. The returned array will only be as long
1578 | * as the shortest array provided; additional values are ignored. For example,
1579 | * the result of zipping [1, 2] and [3, 4, 5] is [[1,3], [2, 4]].
1580 | *
1581 | * This is similar to the zip() function in Python. See {@link
1582 | * http://docs.python.org/library/functions.html#zip}
1583 | *
1584 | * @param {...!goog.array.ArrayLike} var_args Arrays to be combined.
1585 | * @return {!Array<!Array<?>>} A new array of arrays created from
1586 | * provided arrays.
1587 | */
1588 | goog.array.zip = function(var_args) {
1589 | if (!arguments.length) {
1590 | return [];
1591 | }
1592 | var result = [];
1593 | var minLen = arguments[0].length;
1594 | for (var i = 1; i < arguments.length; i++) {
1595 | if (arguments[i].length < minLen) {
1596 | minLen = arguments[i].length;
1597 | }
1598 | }
1599 | for (var i = 0; i < minLen; i++) {
1600 | var value = [];
1601 | for (var j = 0; j < arguments.length; j++) {
1602 | value.push(arguments[j][i]);
1603 | }
1604 | result.push(value);
1605 | }
1606 | return result;
1607 | };
1608 |
1609 |
1610 | /**
1611 | * Shuffles the values in the specified array using the Fisher-Yates in-place
1612 | * shuffle (also known as the Knuth Shuffle). By default, calls Math.random()
1613 | * and so resets the state of that random number generator. Similarly, may reset
1614 | * the state of the any other specified random number generator.
1615 | *
1616 | * Runtime: O(n)
1617 | *
1618 | * @param {!Array<?>} arr The array to be shuffled.
1619 | * @param {function():number=} opt_randFn Optional random function to use for
1620 | * shuffling.
1621 | * Takes no arguments, and returns a random number on the interval [0, 1).
1622 | * Defaults to Math.random() using JavaScript's built-in Math library.
1623 | */
1624 | goog.array.shuffle = function(arr, opt_randFn) {
1625 | var randFn = opt_randFn || Math.random;
1626 |
1627 | for (var i = arr.length - 1; i > 0; i--) {
1628 | // Choose a random array index in [0, i] (inclusive with i).
1629 | var j = Math.floor(randFn() * (i + 1));
1630 |
1631 | var tmp = arr[i];
1632 | arr[i] = arr[j];
1633 | arr[j] = tmp;
1634 | }
1635 | };
1636 |
1637 |
1638 | /**
1639 | * Returns a new array of elements from arr, based on the indexes of elements
1640 | * provided by index_arr. For example, the result of index copying
1641 | * ['a', 'b', 'c'] with index_arr [1,0,0,2] is ['b', 'a', 'a', 'c'].
1642 | *
1643 | * @param {!Array<T>} arr The array to get a indexed copy from.
1644 | * @param {!Array<number>} index_arr An array of indexes to get from arr.
1645 | * @return {!Array<T>} A new array of elements from arr in index_arr order.
1646 | * @template T
1647 | */
1648 | goog.array.copyByIndex = function(arr, index_arr) {
1649 | var result = [];
1650 | goog.array.forEach(index_arr, function(index) {
1651 | result.push(arr[index]);
1652 | });
1653 | return result;
1654 | };