goog.array

Module ID	`goog.array`

Utilities for manipulating arrays.

VIEW SOURCE

Exported Functions

Inserts a value into a sorted array. The array is not modified if the value is already present.

Parameters

`array`	`(IArrayLike<(VALUE\|null)>\|null)`
	The array to modify.
`value`	`(VALUE\|null)`
	The object to insert.
`opt_compareFn`	`function((VALUE\|null), (VALUE\|null)): number=`
	Optional comparison function by which the array is ordered. Should take 2 arguments to compare, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

Returns

boolean

True if an element was inserted.

VIEW SOURCE

Removes a value from a sorted array.

Parameters

`array`	`IArrayLike<(VALUE\|null)>`
	The array to modify.
`value`	`(VALUE\|null)`
	The object to remove.
`opt_compareFn`	`function((VALUE\|null), (VALUE\|null)): number=`
	Optional comparison function by which the array is ordered. Should take 2 arguments to compare, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

Returns

boolean

True if an element was removed.

VIEW SOURCE

Searches the specified array for the specified target using the binary search algorithm. If no opt_compareFn is specified, elements are compared using defaultCompare, which compares the elements using the built in < and > operators. This will produce the expected behavior for homogeneous arrays of String(s) and Number(s). The array specified must be sorted in ascending order (as defined by the comparison function). If the array is not sorted, results are undefined. If the array contains multiple instances of the specified target value, the left-most instance will be found.

Runtime: O(log n)

Parameters

`arr`	`(IArrayLike<(VALUE\|null)>\|null)`
	The array to be searched.
`target`	`(TARGET\|null)`
	The sought value.
`opt_compareFn`	`function((TARGET\|null), (VALUE\|null)): number=`
	Optional comparison function by which the array is ordered. Should take 2 arguments to compare, the target value and an element from your array, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

Returns

number

Lowest index of the target value if found, otherwise (-(insertion point) - 1). The insertion point is where the value should be inserted into arr to preserve the sorted property. Return value >= 0 iff target is found.

VIEW SOURCE

Selects an index in the specified array using the binary search algorithm. The evaluator receives an element and determines whether the desired index is before, at, or after it. The evaluator must be consistent (formally, map(map(arr, evaluator, opt_obj), goog.math.sign) must be monotonically non-increasing).

Runtime: O(log n)

Parameters

`arr`	`(IArrayLike<(VALUE\|null)>\|null)`
	The array to be searched.
`evaluator`	`function((VALUE\|null), number, ?): number`
	Evaluator function that receives 3 arguments (the element, the index and the array). Should return a negative number, zero, or a positive number depending on whether the desired index is before, at, or after the element passed to it.
`opt_obj`	`(THIS\|null)=`
	The object to be used as the value of 'this' within evaluator.

Returns

number

Index of the leftmost element matched by the evaluator, if such exists; otherwise (-(insertion point) - 1). The insertion point is the index of the first element for which the evaluator returns negative, or arr.length if no such element exists. The return value is non-negative iff a match is found.

VIEW SOURCE

Splits an array into disjoint buckets according to a splitting function.

Parameters

`array`	`(IArrayLike<(T\|null)>\|null)`
	The array.
`sorter`	`function((T\|null), number, IArrayLike<(T\|null)>): ?`
	Function to call for every element. This takes 3 arguments (the element, the index and the array) and must return a valid object key (a string, number, etc), or undefined, if that object should not be placed in a bucket.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within sorter.

Returns

Object<?, Array<(T|null)>>

An object, with keys being all of the unique return values of sorter, and values being arrays containing the items for which the splitter returned that key.

VIEW SOURCE

Splits an array into disjoint buckets according to a splitting function.

Parameters

`array`	`IArrayLike<(V\|null)>`
	The array.
`sorter`	`function((V\|null), number, IArrayLike<(V\|null)>): (K\|null\|undefined)`
	Function to call for every element. This takes 3 arguments (the element, the index, and the array) and must return a value to use as a key, or undefined, if that object should not be placed in a bucket.

Returns

Map<(K|null), Array<(V|null)>>

A map, with keys being all of the unique return values of sorter, and values being arrays containing the items for which the splitter returned that key.

VIEW SOURCE

Clears the array.

Parameters

`arr`	`(IArrayLike<?>\|null)`
	Array or array like object to clear.

VIEW SOURCE

Does a shallow copy of an array.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array-like object to clone.

Returns

Array<(T|null)>

Clone of the input array.

VIEW SOURCE

3-way array compare function.

Parameters

`arr1`	`IArrayLike<(VALUE\|null)>`
	The first array to compare.
`arr2`	`IArrayLike<(VALUE\|null)>`
	The second array to compare.
`opt_compareFn`	`function((VALUE\|null), (VALUE\|null)): number=`
	Optional comparison function by which the array is to be ordered. Should take 2 arguments to compare, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

Returns

number

Negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

VIEW SOURCE

Returns a new array that is the result of joining the arguments. If arrays are passed then their items are added, however, if non-arrays are passed they will be added to the return array as is.

Note that ArrayLike objects will be added as is, rather than having their items added.

concat([1, 2], [3, 4]) -> [1, 2, 3, 4] concat(0, [1, 2]) -> [0, 1, 2] concat([1, 2], null) -> [1, 2, null]

Parameters

`var_args`	`...*`
	Items to concatenate. Arrays will have each item added, while primitives and objects will be added as is.

Returns

Array<?>

The new resultant array.

VIEW SOURCE

Maps each element of the input array into zero or more elements of the output array.

Parameters

`arr`	`(IArrayLike<(VALUE\|null)>\|string)`
	Array or array like object over which to iterate.
`f`	`function((VALUE\|null), number, ?): Array<(RESULT\|null)>`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return an array. The result will be used to extend a new array.
`opt_obj`	`(THIS\|null)=`
	The object to be used as the value of 'this' within f.

Returns

Array<(RESULT|null)>

a new array with the concatenation of all arrays returned from f.

VIEW SOURCE

Whether the array contains the given object.

Parameters

`arr`	`(IArrayLike<?>\|string\|null)`
	The array to test for the presence of the element.
`obj`	`*`
	The object for which to test.

Returns

boolean

true if obj is present.

VIEW SOURCE

Returns a new array of elements from arr, based on the indexes of elements provided by index_arr. For example, the result of index copying ['a', 'b', 'c'] with index_arr [1,0,0,2] is ['b', 'a', 'a', 'c'].

Parameters

`arr`	`IArrayLike<(T\|null)>`
	The array to get a indexed copy from.
`index_arr`	`IArrayLike<number>`
	An array of indexes to get from arr.

Returns

Array<(T|null)>

A new array of elements from arr in index_arr order.

VIEW SOURCE

Counts the array elements that fulfill the predicate, i.e. for which the callback function returns true. Skips holes in the array.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string)`
	Array or array like object over which to iterate.
`f`	`function((T\|null), number, ?): boolean`
	The function to call for every element. Takes 3 arguments (the element, the index and the array).
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

Returns

number

The number of the matching elements.

VIEW SOURCE

Compares its two arguments for order, using the built in < and > operators.

Parameters

`a`	`(VALUE\|null)`
	The first object to be compared.
`b`	`(VALUE\|null)`
	The second object to be compared.

Returns

number

A negative number, zero, or a positive number as the first argument is less than, equal to, or greater than the second, respectively.

VIEW SOURCE

Compares its two arguments for equality, using the built in === operator.

Parameters

`a`	`*`
	The first object to compare.
`b`	`*`
	The second object to compare.

Returns

boolean

True if the two arguments are equal, false otherwise.

VIEW SOURCE

Compares two arrays for equality. Two arrays are considered equal if they have the same length and their corresponding elements are equal according to the comparison function.

Parameters

`arr1`	`(IArrayLike<(A\|null)>\|null)`
	The first array to compare.
`arr2`	`(IArrayLike<(B\|null)>\|null)`
	The second array to compare.
`opt_equalsFn`	`(function((A\|null), (B\|null)): boolean\|null)=`
	Optional comparison function. Should take 2 arguments to compare, and return true if the arguments are equal. Defaults to `goog.array.defaultCompareEquality` which compares the elements using the built-in '===' operator.

Returns

boolean

Whether the two arrays are equal.

VIEW SOURCE

Call f for each element of an array. If all calls return true, every() returns true. If any call returns false, every() returns false and does not continue to check the remaining elements.

See http://tinyurl.com/developer-mozilla-org-array-every

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

Returns

boolean

false if any element fails the test.

VIEW SOURCE

Extends an array with another array, element, or "array like" object. This function operates 'in-place', it does not create a new Array.

Example: var a = []; extend(a, [0, 1]); a; // [0, 1] extend(a, 2); a; // [0, 1, 2]

Parameters

`arr1`	`(Array<(VALUE\|null)>\|null)`
	The array to modify.
`var_args`	`...(IArrayLike<(VALUE\|null)>\|VALUE\|null)`
	The elements or arrays of elements to add to arr1.

VIEW SOURCE

Calls a function for each element in an array, and if the function returns true adds the element to a new array.

See http://tinyurl.com/developer-mozilla-org-array-filter

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and must return a Boolean. If the return value is true the element is added to the result array. If it is false the element is not included.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

Returns

Array<(T|null)>

a new array in which only elements that passed the test are present.

VIEW SOURCE

Search an array for the first element that satisfies a given condition and return that element.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	An optional "this" context for the function.

Returns

The first array element that passes the test, or null if no element is found.

VIEW SOURCE

Search an array for the first element that satisfies a given condition and return its index.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	An optional "this" context for the function.

Returns

number

The index of the first array element that passes the test, or -1 if no element is found.

VIEW SOURCE

Search an array (in reverse order) for the last element that satisfies a given condition and return its index.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	An optional "this" context for the function.

Returns

number

The index of the last array element that passes the test, or -1 if no element is found.

VIEW SOURCE

Search an array (in reverse order) for the last element that satisfies a given condition and return that element.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	An optional "this" context for the function.

Returns

The last array element that passes the test, or null if no element is found.

VIEW SOURCE

Returns an array consisting of every argument with all arrays expanded in-place recursively.

Parameters

`var_args`	`...*`
	The values to flatten.

Returns

Array<?>

An array containing the flattened values.

VIEW SOURCE

Calls a function for each element in an array. Skips holes in the array. See http://tinyurl.com/developer-mozilla-org-array-foreach

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): ?\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array). The return value is ignored.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

VIEW SOURCE

Calls a function for each element in an array, starting from the last element rather than the first.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): ?\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array). The return value is ignored.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

VIEW SOURCE

Returns the index of the first element of an array with a specified value, or -1 if the element is not present in the array.

See http://tinyurl.com/developer-mozilla-org-array-indexof

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	The array to be searched.
`obj`	`(T\|null)`
	The object for which we are searching.
`opt_fromIndex`	`number=`
	The index at which to start the search. If omitted the search starts at index 0.

Returns

number

The index of the first matching array element.

VIEW SOURCE

Pushes an item into an array, if it's not already in the array.

Parameters

`arr`	`(Array<(T\|null)>\|null)`
	Array into which to insert the item.
`obj`	`(T\|null)`
	Value to add.

VIEW SOURCE

Inserts at the given index of the array, all elements of another array.

Parameters

`arr`	`(IArrayLike<?>\|null)`
	The array to modify.
`elementsToAdd`	`(IArrayLike<?>\|null)`
	The array of elements to add.
`opt_i`	`number=`
	The index at which to insert the object. If omitted, treated as 0. A negative index is counted from the end of the array.

VIEW SOURCE

Inserts an object at the given index of the array.

Parameters

`arr`	`(IArrayLike<?>\|null)`
	The array to modify.
`obj`	`*`
	The object to insert.
`opt_i`	`number=`
	The index at which to insert the object. If omitted, treated as 0. A negative index is counted from the end of the array.

VIEW SOURCE

Inserts an object into an array before a specified object.

Parameters

`arr`	`(Array<(T\|null)>\|null)`
	The array to modify.
`obj`	`(T\|null)`
	The object to insert.
`opt_obj2`	`(T\|null)=`
	The object before which obj should be inserted. If obj2 is omitted or not found, obj is inserted at the end of the array.

VIEW SOURCE

Compares its two arguments for inverse order, using the built in < and > operators.

Parameters

`a`	`(VALUE\|null)`
	The first object to be compared.
`b`	`(VALUE\|null)`
	The second object to be compared.

Returns

number

A negative number, zero, or a positive number as the first argument is greater than, equal to, or less than the second, respectively.

VIEW SOURCE

Whether the array is empty.

Parameters

`arr`	`(IArrayLike<?>\|string\|null)`
	The array to test.

Returns

boolean

true if empty.

VIEW SOURCE

Tells if the array is sorted.

Parameters

`arr`	`IArrayLike<(T\|null)>`
	The array.
`opt_compareFn`	`(function((T\|null), (T\|null)): number\|null)=`
	Function to compare the array elements. Should take 2 arguments to compare, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.
`opt_strict`	`boolean=`
	If true no equal elements are allowed.

Returns

boolean

Whether the array is sorted.

VIEW SOURCE

Returns a new array that contains the contents of all the arrays passed.

Parameters

`var_args`	`...Array<(T\|null)>`

Returns

Array<(T|null)>

VIEW SOURCE

Returns the last element in an array without removing it. Same as goog.array.peek.

Parameters

`array`	`(IArrayLike<(T\|null)>\|string\|null)`
	The array.

Returns

T

Last item in array.

VIEW SOURCE

Returns the index of the last element of an array with a specified value, or -1 if the element is not present in the array.

See http://tinyurl.com/developer-mozilla-org-array-lastindexof

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string)`
	The array to be searched.
`obj`	`(T\|null)`
	The object for which we are searching.
`opt_fromIndex`	`(number\|null)=`
	The index at which to start the search. If omitted the search starts at the end of the array.

Returns

number

The index of the last matching array element.

VIEW SOURCE

Calls a function for each element in an array and inserts the result into a new array.

See http://tinyurl.com/developer-mozilla-org-array-map

Parameters

`arr`	`(IArrayLike<(VALUE\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`function((VALUE\|null), number, ?): (RESULT\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return something. The result will be inserted into a new array.
`opt_obj`	`(THIS\|null)=`
	The object to be used as the value of 'this' within f.

Returns

Array<(RESULT|null)>

a new array with the results from f.

VIEW SOURCE

Moves one item of an array to a new position keeping the order of the rest of the items. Example use case: keeping a list of JavaScript objects synchronized with the corresponding list of DOM elements after one of the elements has been dragged to a new position.

Parameters

`arr`	`IArrayLike<?>`
	The array to modify.
`fromIndex`	`number`
	Index of the item to move between 0 and `arr.length - 1`.
`toIndex`	`number`
	Target index between 0 and `arr.length - 1`.

VIEW SOURCE

Returns the last element in an array without removing it. Same as goog.array.last.

Parameters

`array`	`(IArrayLike<(T\|null)>\|string\|null)`
	The array.

Returns

T

Last item in array.

VIEW SOURCE

Creates a range of numbers in an arithmetic progression.

Range takes 1, 2, or 3 arguments:

 range(5) is the same as range(0, 5, 1) and produces [0, 1, 2, 3, 4]
 range(2, 5) is the same as range(2, 5, 1) and produces [2, 3, 4]
 range(-2, -5, -1) produces [-2, -3, -4]
 range(-2, -5, 1) produces [], since stepping by 1 wouldn't ever reach -5.

Parameters

`startOrEnd`	`number`
	The starting value of the range if an end argument is provided. Otherwise, the start value is 0, and this is the end value.
`opt_end`	`number=`
	The optional end value of the range.
`opt_step`	`number=`
	The step size between range values. Defaults to 1 if opt_step is undefined or 0.

Returns

Array<number>

An array of numbers for the requested range. May be an empty array if adding the step would not converge toward the end value.

VIEW SOURCE

Passes every element of an array into a function and accumulates the result.

See http://tinyurl.com/developer-mozilla-org-array-reduce Note that this implementation differs from the native Array.prototype.reduce in that the initial value is assumed to be defined (the MDN docs linked above recommend not omitting this parameter, although it is technically optional).

For example: var a = [1, 2, 3, 4]; reduce(a, function(r, v, i, arr) {return r + v;}, 0); returns 10

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`function((R\|null), (T\|null), number, ?): (R\|null)`
	The function to call for every element. This function takes 4 arguments (the function's previous result or the initial value, the value of the current array element, the current array index, and the array itself) function(previousValue, currentValue, index, array).
`val`	`?`
	The initial value to pass into the function on the first call.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

Returns

R

Result of evaluating f repeatedly across the values of the array.

VIEW SOURCE

Passes every element of an array into a function and accumulates the result, starting from the last element and working towards the first.

See http://tinyurl.com/developer-mozilla-org-array-reduceright

For example: var a = ['a', 'b', 'c']; reduceRight(a, function(r, v, i, arr) {return r + v;}, ''); returns 'cba'

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((R\|null), (T\|null), number, ?): (R\|null)\|null)`
	The function to call for every element. This function takes 4 arguments (the function's previous result or the initial value, the value of the current array element, the current array index, and the array itself) function(previousValue, currentValue, index, array).
`val`	`?`
	The initial value to pass into the function on the first call.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

Returns

R

Object returned as a result of evaluating f repeatedly across the values of the array.

VIEW SOURCE

Removes the first occurrence of a particular value from an array.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|null)`
	Array from which to remove value.
`obj`	`(T\|null)`
	Object to remove.

Returns

boolean

True if an element was removed.

VIEW SOURCE

Removes all values that satisfy the given condition.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	An optional "this" context for the function.

Returns

number

The number of items removed

VIEW SOURCE

Removes from an array the element at index i

Parameters

`arr`	`(IArrayLike<?>\|null)`
	Array or array like object from which to remove value.
`i`	`number`
	The index to remove.

Returns

boolean

True if an element was removed.

VIEW SOURCE

Removes all duplicates from an array (retaining only the first occurrence of each array element). This function modifies the array in place and doesn't change the order of the non-duplicate items.

For objects, duplicates are identified as having the same unique ID as defined by goog.getUid.

Alternatively you can specify a custom hash function that returns a unique value for each item in the array it should consider unique.

Runtime: N, Worstcase space: 2N (no dupes)

Parameters

`arr`	`(IArrayLike<(T\|null)>\|null)`
	The array from which to remove duplicates.
`opt_rv`	`(Array\|null)=`
	An optional array in which to return the results, instead of performing the removal inplace. If specified, the original array will remain unchanged.
`opt_hashFn`	`function((T\|null)): string=`
	An optional function to use to apply to every item in the array. This function should return a unique value for each item in the array it should consider unique.

VIEW SOURCE

Removes the first value that satisfies the given condition.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	An optional "this" context for the function.

Returns

boolean

True if an element was removed.

VIEW SOURCE

Removes the last occurrence of a particular value from an array.

Parameters

`arr`	`IArrayLike<(T\|null)>`
	Array from which to remove value.
`obj`	`(T\|null)`
	Object to remove.

Returns

boolean

True if an element was removed.

VIEW SOURCE

Returns an array consisting of the given value repeated N times.

Parameters

`value`	`(VALUE\|null)`
	The value to repeat.
`n`	`number`
	The repeat count.

Returns

Array<(VALUE|null)>

An array with the repeated value.

VIEW SOURCE

Rotates an array in-place. After calling this method, the element at index i will be the element previously at index (i - n) % array.length, for all values of i between 0 and array.length - 1, inclusive.

For example, suppose list comprises [t, a, n, k, s]. After invoking rotate(array, 1) (or rotate(array, -4)), array will comprise [s, t, a, n, k].

Parameters

`array`	`Array<(T\|null)>`
	The array to rotate.
`n`	`number`
	The amount to rotate.

Returns

Array<(T|null)>

The array.

VIEW SOURCE

Shuffles the values in the specified array using the Fisher-Yates in-place shuffle (also known as the Knuth Shuffle). By default, calls Math.random() and so resets the state of that random number generator. Similarly, may reset the state of any other specified random number generator.

Runtime: O(n)

Parameters

`arr`	`Array<?>`
	The array to be shuffled.
`opt_randFn`	`function(): number=`
	Optional random function to use for shuffling. Takes no arguments, and returns a random number on the interval [0, 1). Defaults to Math.random() using JavaScript's built-in Math library.

VIEW SOURCE

Returns a new array from a segment of an array. This is a generic version of Array slice. This means that it might work on other objects similar to arrays, such as the arguments object.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	The array from which to copy a segment.
`start`	`number`
	The index of the first element to copy.
`opt_end`	`number=`
	The index after the last element to copy.

Returns

Array<(T|null)>

A new array containing the specified segment of the original array.

VIEW SOURCE

Calls f for each element of an array. If any call returns true, some() returns true (without checking the remaining elements). If all calls return false, some() returns false.

See http://tinyurl.com/developer-mozilla-org-array-some

Parameters

`arr`	`(IArrayLike<(T\|null)>\|string\|null)`
	Array or array like object over which to iterate.
`f`	`(function((T\|null), number, ?): boolean\|null)`
	The function to call for for every element. This function takes 3 arguments (the element, the index and the array) and should return a boolean.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within f.

Returns

boolean

true if any element passes the test.

VIEW SOURCE

Sorts the specified array into ascending order. If no opt_compareFn is specified, elements are compared using defaultCompare, which compares the elements using the built in < and > operators. This will produce the expected behavior for homogeneous arrays of String(s) and Number(s), unlike the native sort, but will give unpredictable results for heterogeneous lists of strings and numbers with different numbers of digits.

This sort is not guaranteed to be stable.

Runtime: Same as Array.prototype.sort

Parameters

`arr`	`(Array<(T\|null)>\|null)`
	The array to be sorted.
`opt_compareFn`	`(function((T\|null), (T\|null)): number\|null)=`
	Optional comparison function by which the array is to be ordered. Should take 2 arguments to compare, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

VIEW SOURCE

Sort the specified array into ascending order based on item keys returned by the specified key function. If no opt_compareFn is specified, the keys are compared in ascending order using defaultCompare.

Runtime: O(S(f(n)), where S is runtime of sort and f(n) is runtime of the key function.

Parameters

`arr`	`(Array<(T\|null)>\|null)`
	The array to be sorted.
`keyFn`	`function((T\|null)): (K\|null)`
	Function taking array element and returning a key used for sorting this element.
`opt_compareFn`	`(function((K\|null), (K\|null)): number\|null)=`
	Optional comparison function by which the keys are to be ordered. Should take 2 arguments to compare, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

VIEW SOURCE

Sorts an array of objects by the specified object key and compare function. If no compare function is provided, the key values are compared in ascending order using defaultCompare. This won't work for keys that get renamed by the compiler. So use {'foo': 1, 'bar': 2} rather than {foo: 1, bar: 2}.

Parameters

`arr`	`(Array<(Object\|null)>\|null)`
	An array of objects to sort.
`key`	`string`
	The object key to sort by.
`opt_compareFn`	`(Function\|null)=`
	The function to use to compare key values.

VIEW SOURCE

Adds or removes elements from an array. This is a generic version of Array splice. This means that it might work on other objects similar to arrays, such as the arguments object.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|null)`
	The array to modify.
`index`	`(number\|undefined)`
	The index at which to start changing the array. If not defined, treated as 0.
`howMany`	`number`
	How many elements to remove (0 means no removal. A value below 0 is treated as zero and so is any other non number. Numbers are floored).
`var_args`	`...(T\|null)`
	Optional, additional elements to insert into the array.

Returns

Array<(T|null)>

the removed elements.

VIEW SOURCE

Sorts the specified array into ascending order in a stable way. If no opt_compareFn is specified, elements are compared using defaultCompare, which compares the elements using the built in < and > operators. This will produce the expected behavior for homogeneous arrays of String(s) and Number(s).

Runtime: Same as Array.prototype.sort, plus an additional O(n) overhead of copying the array twice.

Parameters

`arr`	`(Array<(T\|null)>\|null)`
	The array to be sorted.
`opt_compareFn`	`(function((T\|null), (T\|null)): number\|null)=`
	Optional comparison function by which the array is to be ordered. Should take 2 arguments to compare, and return a negative number, zero, or a positive number depending on whether the first argument is less than, equal to, or greater than the second.

VIEW SOURCE

Converts an object to an array.

Parameters

`object`	`(IArrayLike<(T\|null)>\|string\|null)`
	The object to convert to an array.

Returns

Array<(T|null)>

The object converted into an array. If object has a length property, every property indexed with a non-negative number less than length will be included in the result. If object does not have a length property, an empty array will be returned.

VIEW SOURCE

Creates a new ES6 Map built from the provided array and the key-generation function.

Parameters

`arr`	`IArrayLike<(V\|null)>`
	Array or array like object over which to iterate whose elements will be the values in the new object.
`keyFunc`	`(function((V\|null), number, ?): (K\|null)\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index, and the array) and should return a value that will be used as the key for the element in the new object. If the function returns the same key for more than one element, the value for that key is implementation-defined.

Returns

Map<(K|null), (V|null)>

The new map.

VIEW SOURCE

Creates a new object built from the provided array and the key-generation function.

Parameters

`arr`	`(IArrayLike<(T\|null)>\|null)`
	Array or array like object over which to iterate whose elements will be the values in the new object.
`keyFunc`	`(function((T\|null), number, ?): string\|null)`
	The function to call for every element. This function takes 3 arguments (the element, the index and the array) and should return a string that will be used as the key for the element in the new object. If the function returns the same key for more than one element, the value for that key is implementation-defined.
`opt_obj`	`(S\|null)=`
	The object to be used as the value of 'this' within keyFunc.

Returns

Object<?, (T|null)>

The new object.

VIEW SOURCE

Creates a new array for which the element at position i is an array of the ith element of the provided arrays. The returned array will only be as long as the shortest array provided; additional values are ignored. For example, the result of zipping [1, 2] and [3, 4, 5] is [[1,3], [2, 4]].

This is similar to the zip() function in Python. See http://docs.python.org/library/functions.html#zip

Parameters

`var_args`	`...IArrayLike<?>`
	Arrays to be combined.

Returns

Array<Array<?>>

A new array of arrays created from provided arrays.

VIEW SOURCE

Compiler Constants

If true, JSCompiler will use the native implementation of array functions where appropriate (e.g., Array#filter) and remove the unused pure JS implementation.

VIEW SOURCE

goog.array

Exported Functions

binaryInsert<VALUE>( array, value, opt_compareFn ) → boolean

binaryRemove<VALUE>( array, value, opt_compareFn ) → boolean

binarySearch<TARGET, VALUE>( arr, target, opt_compareFn ) → number

binarySelect<THIS, VALUE>( arr, evaluator, opt_obj ) → number

bucket<T, S>( array, sorter, opt_obj ) → Object<?, Array<(T|null)>>

bucketToMap<K, V>( array, sorter ) → Map<(K|null), Array<(V|null)>>

clear( arr ) → void

clone<T>( arr ) → Array<(T|null)>

compare3<VALUE>( arr1, arr2, opt_compareFn ) → number

concat( ...var_args ) → Array<?>

concatMap<THIS, VALUE, RESULT>( arr, f, opt_obj ) → Array<(RESULT|null)>

contains( arr, obj ) → boolean

copyByIndex<T>( arr, index_arr ) → Array<(T|null)>

count<T, S>( arr, f, opt_obj ) → number

defaultCompare<VALUE>( a, b ) → number

defaultCompareEquality( a, b ) → boolean

equals<A, B>( arr1, arr2, opt_equalsFn ) → boolean

every<T, S>( arr, f, opt_obj ) → boolean

extend<VALUE>( arr1, ...var_args ) → void

filter<T, S>( arr, f, opt_obj ) → Array<(T|null)>

find<T, S>( arr, f, opt_obj ) → ?

findIndex<T, S>( arr, f, opt_obj ) → number

findIndexRight<T, S>( arr, f, opt_obj ) → number

findRight<T, S>( arr, f, opt_obj ) → ?

flatten( ...var_args ) → Array<?>

forEach<T, S>( arr, f, opt_obj ) → void

forEachRight<T, S>( arr, f, opt_obj ) → void

indexOf<T>( arr, obj, opt_fromIndex ) → number

insert<T>( arr, obj ) → void

insertArrayAt( arr, elementsToAdd, opt_i ) → void

insertAt( arr, obj, opt_i ) → void

insertBefore<T>( arr, obj, opt_obj2 ) → void

inverseDefaultCompare<VALUE>( a, b ) → number

isEmpty( arr ) → boolean

isSorted<T>( arr, opt_compareFn, opt_strict ) → boolean

join<T>( ...var_args ) → Array<(T|null)>

last<T>( array ) → T

lastIndexOf<T>( arr, obj, opt_fromIndex ) → number

map<THIS, VALUE, RESULT>( arr, f, opt_obj ) → Array<(RESULT|null)>

moveItem( arr, fromIndex, toIndex ) → void

peek<T>( array ) → T

range( startOrEnd, opt_end, opt_step ) → Array<number>

reduce<T, S, R>( arr, f, val, opt_obj ) → R

reduceRight<T, S, R>( arr, f, val, opt_obj ) → R

remove<T>( arr, obj ) → boolean

removeAllIf<T, S>( arr, f, opt_obj ) → number

removeAt( arr, i ) → boolean

removeDuplicates<T>( arr, opt_rv, opt_hashFn ) → void

removeIf<T, S>( arr, f, opt_obj ) → boolean

removeLast<T>( arr, obj ) → boolean

repeat<VALUE>( value, n ) → Array<(VALUE|null)>

rotate<T>( array, n ) → Array<(T|null)>

shuffle( arr, opt_randFn ) → void

slice<T>( arr, start, opt_end ) → Array<(T|null)>

some<T, S>( arr, f, opt_obj ) → boolean

sort<T>( arr, opt_compareFn ) → void

sortByKey<T, K>( arr, keyFn, opt_compareFn ) → void

sortObjectsByKey( arr, key, opt_compareFn ) → void

splice<T>( arr, index, howMany, ...var_args ) → Array<(T|null)>

stableSort<T>( arr, opt_compareFn ) → void

toArray<T>( object ) → Array<(T|null)>

toMap<K, V>( arr, keyFunc ) → Map<(K|null), (V|null)>

toObject<T, S>( arr, keyFunc, opt_obj ) → Object<?, (T|null)>

zip( ...var_args ) → Array<Array<?>>

Compiler Constants

goog.array.ASSUME_NATIVE_FUNCTIONS → boolean

binaryInsert`<VALUE>`( `array`, `value`, `opt_compareFn` ) `→` `boolean`

binaryRemove`<VALUE>`( `array`, `value`, `opt_compareFn` ) `→` `boolean`

binarySearch`<TARGET, VALUE>`( `arr`, `target`, `opt_compareFn` ) `→` `number`

binarySelect`<THIS, VALUE>`( `arr`, `evaluator`, `opt_obj` ) `→` `number`

bucket`<T, S>`( `array`, `sorter`, `opt_obj` ) `→` `Object<?, Array<(T|null)>>`

bucketToMap`<K, V>`( `array`, `sorter` ) `→` `Map<(K|null), Array<(V|null)>>`

clear( `arr` ) `→` `void`

clone`<T>`( `arr` ) `→` `Array<(T|null)>`

compare3`<VALUE>`( `arr1`, `arr2`, `opt_compareFn` ) `→` `number`

concat( `...var_args` ) `→` `Array<?>`

concatMap`<THIS, VALUE, RESULT>`( `arr`, `f`, `opt_obj` ) `→` `Array<(RESULT|null)>`

contains( `arr`, `obj` ) `→` `boolean`

copyByIndex`<T>`( `arr`, `index_arr` ) `→` `Array<(T|null)>`

count`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `number`

defaultCompare`<VALUE>`( `a`, `b` ) `→` `number`

defaultCompareEquality( `a`, `b` ) `→` `boolean`

equals`<A, B>`( `arr1`, `arr2`, `opt_equalsFn` ) `→` `boolean`

every`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `boolean`

extend`<VALUE>`( `arr1`, `...var_args` ) `→` `void`

filter`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `Array<(T|null)>`

find`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `?`

findIndex`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `number`

findIndexRight`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `number`

findRight`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `?`

flatten( `...var_args` ) `→` `Array<?>`

forEach`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `void`

forEachRight`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `void`

indexOf`<T>`( `arr`, `obj`, `opt_fromIndex` ) `→` `number`

insert`<T>`( `arr`, `obj` ) `→` `void`

insertArrayAt( `arr`, `elementsToAdd`, `opt_i` ) `→` `void`

insertAt( `arr`, `obj`, `opt_i` ) `→` `void`

insertBefore`<T>`( `arr`, `obj`, `opt_obj2` ) `→` `void`

inverseDefaultCompare`<VALUE>`( `a`, `b` ) `→` `number`

isEmpty( `arr` ) `→` `boolean`

isSorted`<T>`( `arr`, `opt_compareFn`, `opt_strict` ) `→` `boolean`

join`<T>`( `...var_args` ) `→` `Array<(T|null)>`

last`<T>`( `array` ) `→` `T`

lastIndexOf`<T>`( `arr`, `obj`, `opt_fromIndex` ) `→` `number`

map`<THIS, VALUE, RESULT>`( `arr`, `f`, `opt_obj` ) `→` `Array<(RESULT|null)>`

moveItem( `arr`, `fromIndex`, `toIndex` ) `→` `void`

peek`<T>`( `array` ) `→` `T`

range( `startOrEnd`, `opt_end`, `opt_step` ) `→` `Array<number>`

reduce`<T, S, R>`( `arr`, `f`, `val`, `opt_obj` ) `→` `R`

reduceRight`<T, S, R>`( `arr`, `f`, `val`, `opt_obj` ) `→` `R`

remove`<T>`( `arr`, `obj` ) `→` `boolean`

removeAllIf`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `number`

removeAt( `arr`, `i` ) `→` `boolean`

removeDuplicates`<T>`( `arr`, `opt_rv`, `opt_hashFn` ) `→` `void`

removeIf`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `boolean`

removeLast`<T>`( `arr`, `obj` ) `→` `boolean`

repeat`<VALUE>`( `value`, `n` ) `→` `Array<(VALUE|null)>`

rotate`<T>`( `array`, `n` ) `→` `Array<(T|null)>`

shuffle( `arr`, `opt_randFn` ) `→` `void`

slice`<T>`( `arr`, `start`, `opt_end` ) `→` `Array<(T|null)>`

some`<T, S>`( `arr`, `f`, `opt_obj` ) `→` `boolean`

sort`<T>`( `arr`, `opt_compareFn` ) `→` `void`

sortByKey`<T, K>`( `arr`, `keyFn`, `opt_compareFn` ) `→` `void`

sortObjectsByKey( `arr`, `key`, `opt_compareFn` ) `→` `void`

splice`<T>`( `arr`, `index`, `howMany`, `...var_args` ) `→` `Array<(T|null)>`

stableSort`<T>`( `arr`, `opt_compareFn` ) `→` `void`

toArray`<T>`( `object` ) `→` `Array<(T|null)>`

toMap`<K, V>`( `arr`, `keyFunc` ) `→` `Map<(K|null), (V|null)>`

toObject`<T, S>`( `arr`, `keyFunc`, `opt_obj` ) `→` `Object<?, (T|null)>`

zip( `...var_args` ) `→` `Array<Array<?>>`

goog.array.ASSUME_NATIVE_FUNCTIONS `→` `boolean`