1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-Array'>/**
2 </span> * @author Jacky Nguyen <jacky@sencha.com>
3 * @docauthor Jacky Nguyen <jacky@sencha.com>
6 * A set of useful static methods to deal with arrays; provide missing methods for older browsers.
13 var arrayPrototype = Array.prototype,
14 slice = arrayPrototype.slice,
15 supportsForEach = 'forEach' in arrayPrototype,
16 supportsMap = 'map' in arrayPrototype,
17 supportsIndexOf = 'indexOf' in arrayPrototype,
18 supportsEvery = 'every' in arrayPrototype,
19 supportsSome = 'some' in arrayPrototype,
20 supportsFilter = 'filter' in arrayPrototype,
21 supportsSort = function() {
22 var a = [1,2,3,4,5].sort(function(){ return 0; });
23 return a[0] === 1 && a[1] === 2 && a[2] === 3 && a[3] === 4 && a[4] === 5;
25 supportsSliceOnNodeList = true,
28 // IE 6 - 8 will throw an error when using Array.prototype.slice on NodeList
29 if (typeof document !== 'undefined') {
30 slice.call(document.getElementsByTagName('body'));
33 supportsSliceOnNodeList = false;
36 ExtArray = Ext.Array = {
38 * Iterates an array or an iterable value and invoke the given callback function for each item.
40 var countries = ['Vietnam', 'Singapore', 'United States', 'Russia'];
42 Ext.Array.each(countries, function(name, index, countriesItSelf) {
46 var sum = function() {
49 Ext.Array.each(arguments, function(value) {
56 sum(1, 2, 3); // returns 6
58 * The iteration can be stopped by returning false in the function callback.
60 Ext.Array.each(countries, function(name, index, countriesItSelf) {
61 if (name === 'Singapore') {
62 return false; // break here
66 * @param {Array/NodeList/Mixed} iterable The value to be iterated. If this
67 * argument is not iterable, the callback function is called once.
68 * @param {Function} fn The callback function. If it returns false, the iteration stops and this method returns
69 * the current `index`. Arguments passed to this callback function are:
71 - `item`: {Mixed} The item at the current `index` in the passed `array`
72 - `index`: {Number} The current `index` within the `array`
73 - `allItems`: {Array/NodeList/Mixed} The `array` passed as the first argument to `Ext.Array.each`
75 * @param {Object} scope (Optional) The scope (`this` reference) in which the specified function is executed.
76 * @param {Boolean} reverse (Optional) Reverse the iteration order (loop from the end to the beginning)
78 * @return {Boolean} See description for the `fn` parameter.
81 each: function(array, fn, scope, reverse) {
82 array = ExtArray.from(array);
87 if (reverse !== true) {
88 for (i = 0; i < ln; i++) {
89 if (fn.call(scope || array[i], array[i], i, array) === false) {
95 for (i = ln - 1; i > -1; i--) {
96 if (fn.call(scope || array[i], array[i], i, array) === false) {
105 <span id='Ext-Array-method-forEach'> /**
106 </span> * Iterates an array and invoke the given callback function for each item. Note that this will simply
107 * delegate to the native Array.prototype.forEach method if supported.
108 * It doesn't support stopping the iteration by returning false in the callback function like
109 * {@link Ext.Array#each}. However, performance could be much better in modern browsers comparing with
110 * {@link Ext.Array#each}
112 * @param {Array} array The array to iterate
113 * @param {Function} fn The function callback, to be invoked these arguments:
115 - `item`: {Mixed} The item at the current `index` in the passed `array`
116 - `index`: {Number} The current `index` within the `array`
117 - `allItems`: {Array} The `array` itself which was passed as the first argument
119 * @param {Object} scope (Optional) The execution scope (`this`) in which the specified function is executed.
122 forEach: function(array, fn, scope) {
123 if (supportsForEach) {
124 return array.forEach(fn, scope);
130 for (; i < ln; i++) {
131 fn.call(scope, array[i], i, array);
135 <span id='Ext-Array-method-indexOf'> /**
136 </span> * Get the index of the provided `item` in the given `array`, a supplement for the
137 * missing arrayPrototype.indexOf in Internet Explorer.
139 * @param {Array} array The array to check
140 * @param {Mixed} item The item to look for
141 * @param {Number} from (Optional) The index at which to begin the search
142 * @return {Number} The index of item in the array (or -1 if it is not found)
145 indexOf: function(array, item, from) {
146 if (supportsIndexOf) {
147 return array.indexOf(item, from);
150 var i, length = array.length;
152 for (i = (from < 0) ? Math.max(0, length + from) : from || 0; i < length; i++) {
153 if (array[i] === item) {
161 <span id='Ext-Array-method-contains'> /**
162 </span> * Checks whether or not the given `array` contains the specified `item`
164 * @param {Array} array The array to check
165 * @param {Mixed} item The item to look for
166 * @return {Boolean} True if the array contains the item, false otherwise
169 contains: function(array, item) {
170 if (supportsIndexOf) {
171 return array.indexOf(item) !== -1;
176 for (i = 0, ln = array.length; i < ln; i++) {
177 if (array[i] === item) {
185 <span id='Ext-Array-method-toArray'> /**
186 </span> * Converts any iterable (numeric indices and a length property) into a true array.
189 var args = Ext.Array.toArray(arguments),
190 fromSecondToLastArgs = Ext.Array.toArray(arguments, 1);
192 alert(args.join(' '));
193 alert(fromSecondToLastArgs.join(' '));
196 test('just', 'testing', 'here'); // alerts 'just testing here';
197 // alerts 'testing here';
199 Ext.Array.toArray(document.getElementsByTagName('div')); // will convert the NodeList into an array
200 Ext.Array.toArray('splitted'); // returns ['s', 'p', 'l', 'i', 't', 't', 'e', 'd']
201 Ext.Array.toArray('splitted', 0, 3); // returns ['s', 'p', 'l', 'i']
203 * @param {Mixed} iterable the iterable object to be turned into a true Array.
204 * @param {Number} start (Optional) a zero-based index that specifies the start of extraction. Defaults to 0
205 * @param {Number} end (Optional) a zero-based index that specifies the end of extraction. Defaults to the last
206 * index of the iterable value
207 * @return {Array} array
210 toArray: function(iterable, start, end){
211 if (!iterable || !iterable.length) {
215 if (typeof iterable === 'string') {
216 iterable = iterable.split('');
219 if (supportsSliceOnNodeList) {
220 return slice.call(iterable, start || 0, end || iterable.length);
227 end = end ? ((end < 0) ? iterable.length + end : end) : iterable.length;
229 for (i = start; i < end; i++) {
230 array.push(iterable[i]);
236 <span id='Ext-Array-method-pluck'> /**
237 </span> * Plucks the value of a property from each item in the Array. Example:
239 Ext.Array.pluck(Ext.query("p"), "className"); // [el1.className, el2.className, ..., elN.className]
241 * @param {Array|NodeList} array The Array of items to pluck the value from.
242 * @param {String} propertyName The property name to pluck from each element.
243 * @return {Array} The value from each item in the Array.
245 pluck: function(array, propertyName) {
249 for (i = 0, ln = array.length; i < ln; i++) {
252 ret.push(item[propertyName]);
258 <span id='Ext-Array-method-map'> /**
259 </span> * Creates a new array with the results of calling a provided function on every element in this array.
260 * @param {Array} array
261 * @param {Function} fn Callback function for each item
262 * @param {Object} scope Callback function scope
263 * @return {Array} results
265 map: function(array, fn, scope) {
267 return array.map(fn, scope);
274 for (; i < len; i++) {
275 results[i] = fn.call(scope, array[i], i, array);
281 <span id='Ext-Array-method-every'> /**
282 </span> * Executes the specified function for each array element until the function returns a falsy value.
283 * If such an item is found, the function will return false immediately.
284 * Otherwise, it will return true.
286 * @param {Array} array
287 * @param {Function} fn Callback function for each item
288 * @param {Object} scope Callback function scope
289 * @return {Boolean} True if no false value is returned by the callback function.
291 every: function(array, fn, scope) {
294 Ext.Error.raise('Ext.Array.every must have a callback function passed as second argument.');
298 return array.every(fn, scope);
304 for (; i < ln; ++i) {
305 if (!fn.call(scope, array[i], i, array)) {
313 <span id='Ext-Array-method-some'> /**
314 </span> * Executes the specified function for each array element until the function returns a truthy value.
315 * If such an item is found, the function will return true immediately. Otherwise, it will return false.
317 * @param {Array} array
318 * @param {Function} fn Callback function for each item
319 * @param {Object} scope Callback function scope
320 * @return {Boolean} True if the callback function returns a truthy value.
322 some: function(array, fn, scope) {
325 Ext.Error.raise('Ext.Array.some must have a callback function passed as second argument.');
329 return array.some(fn, scope);
335 for (; i < ln; ++i) {
336 if (fn.call(scope, array[i], i, array)) {
344 <span id='Ext-Array-method-clean'> /**
345 </span> * Filter through an array and remove empty item as defined in {@link Ext#isEmpty Ext.isEmpty}
347 * @see Ext.Array.filter
348 * @param {Array} array
349 * @return {Array} results
351 clean: function(array) {
357 for (; i < ln; i++) {
360 if (!Ext.isEmpty(item)) {
368 <span id='Ext-Array-method-unique'> /**
369 </span> * Returns a new array with unique items
371 * @param {Array} array
372 * @return {Array} results
374 unique: function(array) {
380 for (; i < ln; i++) {
383 if (ExtArray.indexOf(clone, item) === -1) {
391 <span id='Ext-Array-method-filter'> /**
392 </span> * Creates a new array with all of the elements of this array for which
393 * the provided filtering function returns true.
394 * @param {Array} array
395 * @param {Function} fn Callback function for each item
396 * @param {Object} scope Callback function scope
397 * @return {Array} results
399 filter: function(array, fn, scope) {
400 if (supportsFilter) {
401 return array.filter(fn, scope);
408 for (; i < ln; i++) {
409 if (fn.call(scope, array[i], i, array)) {
410 results.push(array[i]);
417 <span id='Ext-Array-method-from'> /**
418 </span> * Converts a value to an array if it's not already an array; returns:
420 * - An empty array if given value is `undefined` or `null`
421 * - Itself if given value is already an array
422 * - An array copy if given value is {@link Ext#isIterable iterable} (arguments, NodeList and alike)
423 * - An array with one item which is the given value, otherwise
425 * @param {Array/Mixed} value The value to convert to an array if it's not already is an array
426 * @param {Boolean} (Optional) newReference True to clone the given array and return a new reference if necessary,
428 * @return {Array} array
431 from: function(value, newReference) {
432 if (value === undefined || value === null) {
436 if (Ext.isArray(value)) {
437 return (newReference) ? slice.call(value) : value;
440 if (value && value.length !== undefined && typeof value !== 'string') {
441 return Ext.toArray(value);
447 <span id='Ext-Array-method-remove'> /**
448 </span> * Removes the specified item from the array if it exists
450 * @param {Array} array The array
451 * @param {Mixed} item The item to remove
452 * @return {Array} The passed array itself
454 remove: function(array, item) {
455 var index = ExtArray.indexOf(array, item);
458 array.splice(index, 1);
464 <span id='Ext-Array-method-include'> /**
465 </span> * Push an item into the array only if the array doesn't contain it yet
467 * @param {Array} array The array
468 * @param {Mixed} item The item to include
469 * @return {Array} The passed array itself
471 include: function(array, item) {
472 if (!ExtArray.contains(array, item)) {
477 <span id='Ext-Array-method-clone'> /**
478 </span> * Clone a flat array without referencing the previous one. Note that this is different
479 * from Ext.clone since it doesn't handle recursive cloning. It's simply a convenient, easy-to-remember method
480 * for Array.prototype.slice.call(array)
482 * @param {Array} array The array
483 * @return {Array} The clone array
485 clone: function(array) {
486 return slice.call(array);
489 <span id='Ext-Array-method-merge'> /**
490 </span> * Merge multiple arrays into one with unique items. Alias to {@link Ext.Array#union}.
492 * @param {Array} array,...
493 * @return {Array} merged
496 var args = slice.call(arguments),
500 for (i = 0, ln = args.length; i < ln; i++) {
501 array = array.concat(args[i]);
504 return ExtArray.unique(array);
507 <span id='Ext-Array-method-intersect'> /**
508 </span> * Merge multiple arrays into one with unique items that exist in all of the arrays.
510 * @param {Array} array,...
511 * @return {Array} intersect
513 intersect: function() {
515 arrays = slice.call(arguments),
516 i, j, k, minArray, array, x, y, ln, arraysLn, arrayLn;
518 if (!arrays.length) {
522 // Find the smallest array
523 for (i = x = 0,ln = arrays.length; i < ln,array = arrays[i]; i++) {
524 if (!minArray || array.length < minArray.length) {
530 minArray = Ext.Array.unique(minArray);
533 // Use the smallest unique'd array as the anchor loop. If the other array(s) do contain
534 // an item in the small array, we're likely to find it before reaching the end
535 // of the inner loop and can terminate the search early.
536 for (i = 0,ln = minArray.length; i < ln,x = minArray[i]; i++) {
539 for (j = 0,arraysLn = arrays.length; j < arraysLn,array = arrays[j]; j++) {
540 for (k = 0,arrayLn = array.length; k < arrayLn,y = array[k]; k++) {
548 if (count === arraysLn) {
556 <span id='Ext-Array-method-difference'> /**
557 </span> * Perform a set difference A-B by subtracting all items in array B from array A.
559 * @param {Array} array A
560 * @param {Array} array B
561 * @return {Array} difference
563 difference: function(arrayA, arrayB) {
564 var clone = slice.call(arrayA),
568 for (i = 0,lnB = arrayB.length; i < lnB; i++) {
569 for (j = 0; j < ln; j++) {
570 if (clone[j] === arrayB[i]) {
581 <span id='Ext-Array-method-sort'> /**
582 </span> * Sorts the elements of an Array.
583 * By default, this method sorts the elements alphabetically and ascending.
585 * @param {Array} array The array to sort.
586 * @param {Function} sortFn (optional) The comparison function.
587 * @return {Array} The sorted array.
589 sort: function(array, sortFn) {
592 return array.sort(sortFn);
598 var length = array.length,
603 for (; i < length; i++) {
605 for (j = i + 1; j < length; j++) {
607 comparison = sortFn(array[j], array[min]);
608 if (comparison < 0) {
611 } else if (array[j] < array[min]) {
617 array[i] = array[min];
625 <span id='Ext-Array-method-flatten'> /**
626 </span> * Recursively flattens into 1-d Array. Injects Arrays inline.
627 * @param {Array} array The array to flatten
628 * @return {Array} The new, flattened array.
630 flatten: function(array) {
633 function rFlatten(a) {
636 for (i = 0, ln = a.length; i < ln; i++) {
639 if (Ext.isArray(v)) {
649 return rFlatten(array);
652 <span id='Ext-Array-method-min'> /**
653 </span> * Returns the minimum value in the Array.
654 * @param {Array|NodeList} array The Array from which to select the minimum value.
655 * @param {Function} comparisonFn (optional) a function to perform the comparision which determines minimization.
656 * If omitted the "<" operator will be used. Note: gt = 1; eq = 0; lt = -1
657 * @return {Mixed} minValue The minimum value
659 min: function(array, comparisonFn) {
663 for (i = 0, ln = array.length; i < ln; i++) {
667 if (comparisonFn(min, item) === 1) {
681 <span id='Ext-Array-method-max'> /**
682 </span> * Returns the maximum value in the Array
683 * @param {Array|NodeList} array The Array from which to select the maximum value.
684 * @param {Function} comparisonFn (optional) a function to perform the comparision which determines maximization.
685 * If omitted the ">" operator will be used. Note: gt = 1; eq = 0; lt = -1
686 * @return {Mixed} maxValue The maximum value
688 max: function(array, comparisonFn) {
692 for (i = 0, ln = array.length; i < ln; i++) {
696 if (comparisonFn(max, item) === -1) {
710 <span id='Ext-Array-method-mean'> /**
711 </span> * Calculates the mean of all items in the array
712 * @param {Array} array The Array to calculate the mean value of.
713 * @return {Number} The mean.
715 mean: function(array) {
716 return array.length > 0 ? ExtArray.sum(array) / array.length : undefined;
719 <span id='Ext-Array-method-sum'> /**
720 </span> * Calculates the sum of all items in the given array
721 * @param {Array} array The Array to calculate the sum value of.
722 * @return {Number} The sum.
724 sum: function(array) {
728 for (i = 0,ln = array.length; i < ln; i++) {
739 <span id='Ext-method-each'> /**
740 </span> * Convenient alias to {@link Ext.Array#each}
744 Ext.each = Ext.Array.each;
746 <span id='Ext-Array-method-union'> /**
747 </span> * Alias to {@link Ext.Array#merge}.
751 Ext.Array.union = Ext.Array.merge;
753 <span id='Ext-method-min'> /**
754 </span> * Old alias to {@link Ext.Array#min}
755 * @deprecated 4.0.0 Use {@link Ext.Array#min} instead
759 Ext.min = Ext.Array.min;
761 <span id='Ext-method-max'> /**
762 </span> * Old alias to {@link Ext.Array#max}
763 * @deprecated 4.0.0 Use {@link Ext.Array#max} instead
767 Ext.max = Ext.Array.max;
769 <span id='Ext-method-sum'> /**
770 </span> * Old alias to {@link Ext.Array#sum}
771 * @deprecated 4.0.0 Use {@link Ext.Array#sum} instead
775 Ext.sum = Ext.Array.sum;
777 <span id='Ext-method-mean'> /**
778 </span> * Old alias to {@link Ext.Array#mean}
779 * @deprecated 4.0.0 Use {@link Ext.Array#mean} instead
783 Ext.mean = Ext.Array.mean;
785 <span id='Ext-method-flatten'> /**
786 </span> * Old alias to {@link Ext.Array#flatten}
787 * @deprecated 4.0.0 Use {@link Ext.Array#flatten} instead
791 Ext.flatten = Ext.Array.flatten;
793 <span id='Ext-method-clean'> /**
794 </span> * Old alias to {@link Ext.Array#clean Ext.Array.clean}
795 * @deprecated 4.0.0 Use {@link Ext.Array.clean} instead
799 Ext.clean = Ext.Array.clean;
801 <span id='Ext-method-unique'> /**
802 </span> * Old alias to {@link Ext.Array#unique Ext.Array.unique}
803 * @deprecated 4.0.0 Use {@link Ext.Array.unique} instead
807 Ext.unique = Ext.Array.unique;
809 <span id='Ext-method-pluck'> /**
810 </span> * Old alias to {@link Ext.Array#pluck Ext.Array.pluck}
811 * @deprecated 4.0.0 Use {@link Ext.Array#pluck Ext.Array.pluck} instead
815 Ext.pluck = Ext.Array.pluck;
817 <span id='Ext-method-toArray'> /**
818 </span> * Convenient alias to {@link Ext.Array#toArray Ext.Array.toArray}
819 * @param {Iterable} the iterable object to be turned into a true Array.
822 * @return {Array} array
824 Ext.toArray = function() {
825 return ExtArray.toArray.apply(ExtArray, arguments);
828 </pre></pre></body></html>