# Namespace goog.array

code »
Show:Public Protected Private

## Type Definitions

code »goog.array.ArrayLike : `(Array|NodeList|Arguments|{length: number})`
No description.

## Global Functions

code »`<VALUE>` goog.array.binaryInsert ( array, value, opt_compareFn ) ⇒ `boolean`

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

Parameters

array: `(Array.<VALUE>|goog.array.ArrayLike)`
  The array to modify.
value: `VALUE`
  The object to insert.
opt_compareFn: `function(VALUE, VALUE): 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

True if an element was inserted.

code »`<VALUE>` goog.array.binaryRemove ( array, value, opt_compareFn ) ⇒ `boolean`

Removes a value from a sorted array.

Parameters

array: `(!Array.<VALUE>|!goog.array.ArrayLike)`
  The array to modify.
value: `VALUE`
  The object to remove.
opt_compareFn: `function(VALUE, VALUE): 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

True if an element was removed.

code »`<TARGET, VALUE>` goog.array.binarySearch ( arr, target, opt_compareFn ) ⇒ `number`

Searches the specified array for the specified target using the binary search algorithm. If no opt_compareFn is specified, elements are compared using `goog.array.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, any of these instances may be found. Runtime: O(log n)

Parameters

arr: `(Array.<VALUE>|goog.array.ArrayLike)`
  The array to be searched.
target: `TARGET`
  The sought value.
opt_compareFn: `function(TARGET, VALUE): 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

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.

code »`<THIS, VALUE, TARGET>` goog.array.binarySearch_ ( arr, compareFn, isEvaluator, opt_target, opt_selfObj ) ⇒ `number`

Implementation of a binary search algorithm which knows how to use both comparison functions and evaluators. If an evaluator is provided, will call the evaluator with the given optional data object, conforming to the interface defined in binarySelect. Otherwise, if a comparison function is provided, will call the comparison function against the given data object. This implementation purposefully does not use goog.bind or goog.partial for performance reasons. Runtime: O(log n)

Parameters

arr: `(Array.<VALUE>|goog.array.ArrayLike)`
  The array to be searched.
compareFn: `(function(TARGET, VALUE): number|function(this: THIS, VALUE, number, ?): number)`
  Either an evaluator or a comparison function, as defined by binarySearch and binarySelect above.
isEvaluator: `boolean`
  Whether the function is an evaluator or a comparison function.
opt_target: `TARGET=`
  If the function is a comparison function, then this is the target to binary search for.
opt_selfObj: `THIS=`
  If the function is an evaluator, this is an optional this object for the evaluator.

Returns

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.

code »`<THIS, VALUE>` goog.array.binarySelect ( arr, evaluator, opt_obj ) ⇒ `number`

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, goog.array.map(goog.array.map(arr, evaluator, opt_obj), goog.math.sign) must be monotonically non-increasing). Runtime: O(log n)

Parameters

arr: `(Array.<VALUE>|goog.array.ArrayLike)`
  The array to be searched.
evaluator: `function(this: THIS, VALUE, 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=`
  The object to be used as the value of 'this' within evaluator.

Returns

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.

code »`<T, S>` goog.array.bucket ( array, sorter, opt_obj ) ⇒ `!Object`

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

Parameters

array: `Array.<T>`
  The array.
sorter: `function(this: S, T, number, Array.<T>): ?`
  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=`
  The object to be used as the value of 'this' within sorter.

Returns

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.

code »goog.array.clear ( arr )

Clears the array.

Parameters

arr: `goog.array.ArrayLike`
  Array or array like object to clear.

code »`<T>` goog.array.clone ( arr ) ⇒ `!Array.<T>`

Does a shallow copy of an array.

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array-like object to clone.

Returns

Clone of the input array.

code »`<VALUE>` goog.array.compare3 ( arr1, arr2, opt_compareFn ) ⇒ `number`

3-way array compare function.

Parameters

arr1: `(!Array.<VALUE>|!goog.array.ArrayLike)`
  The first array to compare.
arr2: `(!Array.<VALUE>|!goog.array.ArrayLike)`
  The second array to compare.
opt_compareFn: `function(VALUE, VALUE): 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

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

code »goog.array.concat ( var_args ) ⇒ `!Array`

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. goog.array.concat([1, 2], [3, 4]) -> [1, 2, 3, 4] goog.array.concat(0, [1, 2]) -> [0, 1, 2] goog.array.concat([1, 2], null) -> [1, 2, null] There is bug in all current versions of IE (6, 7 and 8) where arrays created in an iframe become corrupted soon (not immediately) after the iframe is destroyed. This is common if loading data via goog.net.IframeIo, for example. This corruption only affects the concat method which will start throwing Catastrophic Errors (#-2147418113). See http://endoflow.com/scratch/corrupted-arrays.html for a test case. Internally goog.array should use this, so that all methods will continue to work on these broken array objects.

Parameters

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

Returns

The new resultant array.

code »goog.array.contains ( arr, obj ) ⇒ `boolean`

Whether the array contains the given object.

Parameters

arr: `goog.array.ArrayLike`
  The array to test for the presence of the element.
obj: `*`
  The object for which to test.

Returns

true if obj is present.

code »`<T, S>` goog.array.count ( arr, f, opt_obj ) ⇒ `number`

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

Parameters

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

Returns

The number of the matching elements.

code »`<VALUE>` goog.array.defaultCompare ( a, b ) ⇒ `number`

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

Parameters

a: `VALUE`
  The first object to be compared.
b: `VALUE`
  The second object to be compared.

Returns

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

code »goog.array.defaultCompareEquality ( a, b ) ⇒ `boolean`

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

True if the two arguments are equal, false otherwise.

code »goog.array.equals ( arr1, arr2, opt_equalsFn ) ⇒ `boolean`

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: `goog.array.ArrayLike`
  The first array to compare.
arr2: `goog.array.ArrayLike`
  The second array to compare.
opt_equalsFn: `Function=`
  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

Whether the two arrays are equal.

code »`<T, S>` goog.array.every ( arr, f, opt_obj ) ⇒ `boolean`

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: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  The object to be used as the value of 'this' within f.

Returns

false if any element fails the test.

code »`<VALUE>` goog.array.extend ( arr1, var_args )

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 = []; goog.array.extend(a, [0, 1]); a; // [0, 1] goog.array.extend(a, 2); a; // [0, 1, 2]

Parameters

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

code »`<T, S>` goog.array.filter ( arr, f, opt_obj ) ⇒ `!Array.<T>`

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: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  The object to be used as the value of 'this' within f.

Returns

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

code »`<T, S>` goog.array.find ( arr, f, opt_obj ) ⇒ `?T`

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

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  An optional "this" context for the function.

Returns

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

code »`<T, S>` goog.array.findIndex ( arr, f, opt_obj ) ⇒ `number`

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

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  An optional "this" context for the function.

Returns

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

code »`<T, S>` goog.array.findIndexRight ( arr, f, opt_obj ) ⇒ `number`

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

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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: `Object=`
  An optional "this" context for the function.

Returns

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

code »`<T, S>` goog.array.findRight ( arr, f, opt_obj ) ⇒ `?T`

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

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  An optional "this" context for the function.

Returns

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

code »goog.array.flatten ( var_args ) ⇒ `!Array`

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

Parameters

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

Returns

An array containing the flattened values.

code »`<T, S>` goog.array.forEach ( arr, f, opt_obj )

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: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): ?`
  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=`
  The object to be used as the value of 'this' within f.

code »`<T, S>` goog.array.forEachRight ( arr, f, opt_obj )

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

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): ?`
  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=`
  The object to be used as the value of 'this' within f.

code »`<T>` goog.array.indexOf ( arr, obj, opt_fromIndex ) ⇒ `number`

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: `(Array.<T>|goog.array.ArrayLike)`
  The array to be searched.
obj: `T`
  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

The index of the first matching array element.

code »`<T>` goog.array.insert ( arr, obj )

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

Parameters

arr: `Array.<T>`
  Array into which to insert the item.
obj: `T`
  Value to add.

code »goog.array.insertArrayAt ( arr, elementsToAdd, opt_i )

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

Parameters

arr: `goog.array.ArrayLike`
  The array to modify.
elementsToAdd: `goog.array.ArrayLike`
  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.

code »goog.array.insertAt ( arr, obj, opt_i )

Inserts an object at the given index of the array.

Parameters

arr: `goog.array.ArrayLike`
  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.

code »`<T>` goog.array.insertBefore ( arr, obj, opt_obj2 )

Inserts an object into an array before a specified object.

Parameters

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

code »goog.array.isEmpty ( arr ) ⇒ `boolean`

Whether the array is empty.

Parameters

arr: `goog.array.ArrayLike`
  The array to test.

Returns

true if empty.

code »`<T>` goog.array.isSorted ( arr, opt_compareFn, opt_strict ) ⇒ `boolean`

Tells if the array is sorted.

Parameters

arr: `!Array.<T>`
  The array.
opt_compareFn: `?function(T, T): number=`
  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

Whether the array is sorted.

code »`<T>` goog.array.join ( var_args ) ⇒ `!Array.<T>`

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

Parameters

var_args

code »`<T>` goog.array.last ( array ) ⇒ `T`

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

Parameters

array: `(Array.<T>|goog.array.ArrayLike)`
  The array.

Returns

Last item in array.

code »`<T>` goog.array.lastIndexOf ( arr, obj, opt_fromIndex ) ⇒ `number`

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: `(!Array.<T>|!goog.array.ArrayLike)`
  The array to be searched.
obj: `T`
  The object for which we are searching.
opt_fromIndex: `?number=`
  The index at which to start the search. If omitted the search starts at the end of the array.

Returns

The index of the last matching array element.

code »`<THIS, VALUE, RESULT>` goog.array.map ( arr, f, opt_obj ) ⇒ `!Array.<RESULT>`

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: `(Array.<VALUE>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `function(this: THIS, VALUE, number, ?): RESULT`
  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=`
  The object to be used as the value of 'this' within f.

Returns

a new array with the results from f.

code »goog.array.moveItem ( arr, fromIndex, toIndex )

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: `!(Array|Arguments|{length: number})`
  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`.

code »`<T>` goog.array.peek ( array ) ⇒ `T`

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

Parameters

array: `(Array.<T>|goog.array.ArrayLike)`
  The array.

Returns

Last item in array.

code »goog.array.range ( startOrEnd, opt_end, opt_step ) ⇒ `!Array.<number>`

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

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

code »`<T, S, R>` goog.array.reduce ( arr, f, val, opt_obj ) ⇒ `R`

Passes every element of an array into a function and accumulates the result. See `http://tinyurl.com/developer-mozilla-org-array-reduce` For example: var a = [1, 2, 3, 4]; goog.array.reduce(a, function(r, v, i, arr) {return r + v;}, 0); returns 10

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, R, T, number, ?): R`
  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=`
  The object to be used as the value of 'this' within f.

Returns

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

code »`<T, S, R>` goog.array.reduceRight ( arr, f, val, opt_obj ) ⇒ `R`

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']; goog.array.reduceRight(a, function(r, v, i, arr) {return r + v;}, ''); returns 'cba'

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, R, T, number, ?): R`
  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=`
  The object to be used as the value of 'this' within f.

Returns

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

code »`<T>` goog.array.remove ( arr, obj ) ⇒ `boolean`

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

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array from which to remove value.
obj: `T`
  Object to remove.

Returns

True if an element was removed.

code »`<T, S>` goog.array.removeAllIf ( arr, f, opt_obj ) ⇒ `number`

Removes all values that satisfy the given condition.

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  An optional "this" context for the function.

Returns

The number of items removed

code »goog.array.removeAt ( arr, i ) ⇒ `boolean`

Removes from an array the element at index i

Parameters

arr: `goog.array.ArrayLike`
  Array or array like object from which to remove value.
i: `number`
  The index to remove.

Returns

True if an element was removed.

code »`<T>` goog.array.removeDuplicates ( arr, opt_rv, opt_hashFn )

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: `(Array.<T>|goog.array.ArrayLike)`
  The array from which to remove duplicates.
opt_rv: `Array=`
  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): 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.

code »`<T, S>` goog.array.removeIf ( arr, f, opt_obj ) ⇒ `boolean`

Removes the first value that satisfies the given condition.

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  An optional "this" context for the function.

Returns

True if an element was removed.

code »`<VALUE>` goog.array.repeat ( value, n ) ⇒ `!Array.<VALUE>`

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

Parameters

value: `VALUE`
  The value to repeat.
n: `number`
  The repeat count.

Returns

An array with the repeated value.

code »`<T>` goog.array.rotate ( array, n ) ⇒ `!Array.<T>`

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>`
  The array to rotate.
n: `number`
  The amount to rotate.

Returns

The array.

code »goog.array.shuffle ( arr, opt_randFn )

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 the 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.

code »`<T>` goog.array.slice ( arr, start, opt_end ) ⇒ `!Array.<T>`

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: `(Array.<T>|goog.array.ArrayLike)`
  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

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

code »`<T, S>` goog.array.some ( arr, f, opt_obj ) ⇒ `boolean`

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: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate.
f: `?function(this: S, T, number, ?): boolean`
  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=`
  The object to be used as the value of 'this' within f.

Returns

true if any element passes the test.

code »`<T>` goog.array.sort ( arr, opt_compareFn )

Sorts the specified array into ascending order. If no opt_compareFn is specified, elements are compared using `goog.array.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 heterogenous 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>`
  The array to be sorted.
opt_compareFn: `?function(T, T): 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.

code »goog.array.sortObjectsByKey ( arr, key, opt_compareFn )

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 `goog.array.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>`
  An array of objects to sort.
key: `string`
  The object key to sort by.
opt_compareFn: `Function=`
  The function to use to compare key values.

code »`<T>` goog.array.splice ( arr, index, howMany, var_args ) ⇒ `!Array.<T>`

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: `(Array.<T>|goog.array.ArrayLike)`
  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`
  Optional, additional elements to insert into the array.

Returns

the removed elements.

code »`<T>` goog.array.stableSort ( arr, opt_compareFn )

Sorts the specified array into ascending order in a stable way. If no opt_compareFn is specified, elements are compared using `goog.array.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>`
  The array to be sorted.
opt_compareFn: `?function(T, T): 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.

code »`<T>` goog.array.toArray ( object ) ⇒ `!Array.<T>`

Converts an object to an array.

Parameters

object: `(Array.<T>|goog.array.ArrayLike)`
  The object to convert to an array.

Returns

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.

code »`<T, S>` goog.array.toObject ( arr, keyFunc, opt_obj ) ⇒ `!Object.<T>`

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

Parameters

arr: `(Array.<T>|goog.array.ArrayLike)`
  Array or array like object over which to iterate whose elements will be the values in the new object.
keyFunc: `?function(this: S, T, number, ?): string`
  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=`
  The object to be used as the value of 'this' within keyFunc.

Returns

The new object.

code »goog.array.zip ( var_args ) ⇒ `!Array`

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: `...!goog.array.ArrayLike`
  Arrays to be combined.

Returns

A new array of arrays created from provided arrays.

## Global Properties

code »goog.array.ARRAY_PROTOTYPE_ : `Array.prototype`

Reference to the original `Array.prototype`.

## Compiler Constants

code »goog.array.ASSUME_NATIVE_FUNCTIONS : `boolean`