The `goog.array` Namespace

`.ArrayLike`

@typedef: {Array|NodeList|Arguments|{length: number}}

`.binaryInsert(array, value, opt_compareFn)`

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

array {Array.<T>}: The array to modify.
value {T}: The object to insert.
opt_compareFn {?function(T,T):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. @template T

`.binaryRemove(array, value, opt_compareFn)`

Removes a value from a sorted array.

array {Array}: The array to modify.
value {*}: The object to remove.
opt_compareFn {Function=}: 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.

`.binarySearch(arr, target, opt_compareFn)`

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)

arr {goog.array.ArrayLike}: The array to be searched.
target {*}: The sought value.
opt_compareFn {Function=}: 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 {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.

`.binarySelect(arr, evaluator, opt_obj)`

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)

arr {goog.array.ArrayLike}: The array to be searched.
evaluator {Function}: 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 {Object=}: 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.

`.bucket(array, sorter)`

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

array {Array.<T>}: The array.
sorter {function(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.
returns {!Object}: 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. @template T

`.clear(arr)`

Clears the array.

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

`.clone`

Does a shallow copy of an array.

arr {goog.array.ArrayLike}: Array or array-like object to clone.
returns {!Array}: Clone of the input array.

`.compare3(arr1, arr2, opt_compareFn)`

3-way array compare function.

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

`.concat(var_args)`

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.

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.

`.contains(arr, obj)`

Whether the array contains the given object.

arr {goog.array.ArrayLike}: The array to test for the presence of the element.
obj {*}: The object for which to test.
returns {boolean}: true if obj is present.

`.defaultCompare(a, b)`

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

a {*}: The first object to be compared.
b {*}: 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.

`.defaultCompareEquality(a, b)`

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

a {*}: The first object to compare.
b {*}: The second object to compare.
returns {boolean}: True if the two arguments are equal, false otherwise.

`.equals(arr1, arr2, opt_equalsFn)`

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.

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 {@link goog.array.defaultCompareEquality} which compares the elements using the built-in '===' operator.
returns {boolean}: Whether the two arrays are equal.

`.every`

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 {@link http://tinyurl.com/developer-mozilla-org-array-every}

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 {boolean}: false if any element fails the test. @template T,S

`.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]

arr1 {Array}: The array to modify.
var_args {...*}: The elements or arrays of elements to add to arr1.

`.filter`

Calls a function for each element in an array, and if the function returns true adds the element to a new array. See {@link http://tinyurl.com/developer-mozilla-org-array-filter}

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 {!Array}: a new array in which only elements that passed the test are present. @template T,S

`.find(arr, f, opt_obj)`

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

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 {T}: The first array element that passes the test, or null if no element is found. @template T,S

`.findIndex(arr, f, opt_obj)`

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

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 {number}: The index of the first array element that passes the test, or -1 if no element is found. @template T,S

`.findIndexRight(arr, f, opt_obj)`

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

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 {number}: The index of the last array element that passes the test, or -1 if no element is found. @template T,S

`.findRight(arr, f, opt_obj)`

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

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 {T}: The last array element that passes the test, or null if no element is found. @template T,S

`.flatten(var_args)`

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

var_args {...*}: The values to flatten.
returns {!Array}: An array containing the flattened values.

`.forEach`

Calls a function for each element in an array. See {@link http://tinyurl.com/developer-mozilla-org-array-foreach}

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. The function is called only for indexes of the array which have assigned values; it is not called for indexes which have been deleted or which have never been assigned values.
opt_obj {S=}: The object to be used as the value of 'this' within f. @template T,S

`.forEachRight(arr, f, opt_obj)`

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

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. @template T,S

`.indexOf`

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 {@link http://tinyurl.com/developer-mozilla-org-array-indexof}

arr {goog.array.ArrayLike}: The array to be searched.
obj {*}: 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.

`.insert(arr, obj)`

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

arr {Array.<T>}: Array into which to insert the item.
obj {T}: Value to add. @template T

`.insertArrayAt(arr, elementsToAdd, opt_i)`

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

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.

`.insertAt(arr, obj, opt_i)`

Inserts an object at the given index of the array.

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.

`.insertBefore(arr, obj, opt_obj2)`

Inserts an object into an array before a specified object.

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. @template T

`.isEmpty(arr)`

Whether the array is empty.

arr {goog.array.ArrayLike}: The array to test.
returns {boolean}: true if empty.

`.isSorted(arr, opt_compareFn, opt_strict)`

Tells if the array is sorted.

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 {boolean}: Whether the array is sorted. @template T

`.lastIndexOf`

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 {@link http://tinyurl.com/developer-mozilla-org-array-lastindexof}

arr {goog.array.ArrayLike}: The array to be searched.
obj {*}: 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 {number}: The index of the last matching array element.

`.map`

Calls a function for each element in an array and inserts the result into a new array. See {@link http://tinyurl.com/developer-mozilla-org-array-map}

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) and should return something. The result will be inserted into a new array.
opt_obj {S=}: The object to be used as the value of 'this' within f.
returns {!Array}: a new array with the results from f. @template T,S

`.peek(array)`

Returns the last element in an array without removing it.

array {goog.array.ArrayLike}: The array.
returns {*}: Last item in array.

`.reduce(arr, f, val, opt_obj)`

Passes every element of an array into a function and accumulates the result. See {@link 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

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 {R}: Result of evaluating f repeatedly across the values of the array. @template T,S,R

`.reduceRight(arr, f, val, opt_obj)`

Passes every element of an array into a function and accumulates the result, starting from the last element and working towards the first. See {@link 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'

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 {R}: Object returned as a result of evaluating f repeatedly across the values of the array. @template T,S,R

`.remove(arr, obj)`

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

arr {goog.array.ArrayLike}: Array from which to remove value.
obj {*}: Object to remove.
returns {boolean}: True if an element was removed.

`.removeAt(arr, i)`

Removes from an array the element at index i

arr {goog.array.ArrayLike}: Array or array like object from which to remove value.
i {number}: The index to remove.
returns {boolean}: True if an element was removed.

`.removeDuplicates(arr, opt_rv)`

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 {@link goog.getUid}. Runtime: N, Worstcase space: 2N (no dupes)

arr {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.

`.removeIf(arr, f, opt_obj)`

Removes the first value that satisfies the given condition.

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 {boolean}: True if an element was removed. @template T,S

`.repeat(value, n)`

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

value {*}: The value to repeat.
n {number}: The repeat count.
returns {!Array}: An array with the repeated value.

`.rotate(array, n)`

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

array {!Array.<T>}: The array to rotate.
n {number}: The amount to rotate.
returns {!Array.<T>}: The array. @template T

`.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)

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.

`.slice(arr, start, opt_end)`

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.

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 {!Array.<T>}: A new array containing the specified segment of the original array. @template T

`.some`

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 {@link http://tinyurl.com/developer-mozilla-org-array-some}

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 {boolean}: true if any element passes the test. @template T,S

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

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. @template T

`.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}.

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.

`.splice(arr, index, howMany, var_args)`

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.

arr {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 {...*}: Optional, additional elements to insert into the array.
returns {!Array}: the removed elements.

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

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. @template T

`.toArray(object)`

Converts an object to an array.

object {goog.array.ArrayLike}: The object to convert to an array.
returns {!Array}: 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.

`.toObject(arr, keyFunc, opt_obj)`

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

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 {!Object.<T>}: The new object. @template T,S

`.zip(var_args)`

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 {@link http://docs.python.org/library/functions.html#zip}

var_args {...!goog.array.ArrayLike}: Arrays to be combined.
returns {!Array.<!Array>}: A new array of arrays created from provided arrays.

The goog.array Namespace

.ArrayLike

.binaryInsert(array, value, opt_compareFn)

.binaryRemove(array, value, opt_compareFn)

.binarySearch(arr, target, opt_compareFn)

.binarySelect(arr, evaluator, opt_obj)

.bucket(array, sorter)

.clear(arr)

.clone

.compare(arr1, arr2, opt_equalsFn) [deprecated]

.compare3(arr1, arr2, opt_compareFn)

.concat(var_args)

.contains(arr, obj)

.defaultCompare(a, b)

.defaultCompareEquality(a, b)

.equals(arr1, arr2, opt_equalsFn)

.every

.extend(arr1, var_args)

.filter

.find(arr, f, opt_obj)

.findIndex(arr, f, opt_obj)

.findIndexRight(arr, f, opt_obj)

.findRight(arr, f, opt_obj)

.flatten(var_args)

.forEach

.forEachRight(arr, f, opt_obj)

.indexOf

.insert(arr, obj)

.insertArrayAt(arr, elementsToAdd, opt_i)

.insertAt(arr, obj, opt_i)

.insertBefore(arr, obj, opt_obj2)

.isEmpty(arr)

.isSorted(arr, opt_compareFn, opt_strict)

.lastIndexOf

.map

.peek(array)

.reduce(arr, f, val, opt_obj)

.reduceRight(arr, f, val, opt_obj)

.remove(arr, obj)

.removeAt(arr, i)

.removeDuplicates(arr, opt_rv)

.removeIf(arr, f, opt_obj)

.repeat(value, n)

.rotate(array, n)

.shuffle(arr, opt_randFn)

.slice(arr, start, opt_end)

.some

.sort(arr, opt_compareFn)

.sortObjectsByKey(arr, key, opt_compareFn)

.splice(arr, index, howMany, var_args)

.stableSort(arr, opt_compareFn)

.toArray(object)

.toObject(arr, keyFunc, opt_obj)

.zip(var_args)