Home

# Library goog.array

Function Summary
| `binaryInsert(?Array array, <Any Type> value, ?Function= opt_compareFn) ⇒ boolean` Inserts a value into a sorted array. The array is not modified if the value is already present.
| `binaryRemove(?Array array, <Any Type> value, ?Function= opt_compareFn) ⇒ boolean` Removes a value from a sorted array.

`binarySearch(?goog.array.ArrayLike arr, <Any Type> target, ?Function= 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)

`binarySearch_(?goog.array.ArrayLike arr, ?Function compareFn, boolean isEvaluator, <Any Type> opt_target, ?Object= 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)

`binarySelect(?goog.array.ArrayLike arr, ?Function evaluator, ?Object= 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)

| `bucket(?Array array, ?Function sorter) ⇒ !Object` Splits an array into disjoint buckets according to a splitting function.
| `clear(?goog.array.ArrayLike arr)` Clears the array.
| `clone(?goog.array.ArrayLike arr) ⇒ !Array` Does a shallow copy of an array.
| `compare(?goog.array.ArrayLike arr1, ?goog.array.ArrayLike arr2, ?Function= opt_equalsFn) ⇒ boolean`
| `compare3(!goog.array.ArrayLike arr1, !goog.array.ArrayLike arr2, function (*, *): number= opt_compareFn) ⇒ number` 3-way array compare function.

`concat(<Any Type> 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.

| `contains(?goog.array.ArrayLike arr, <Any Type> obj) ⇒ boolean` Whether the array contains the given object.
| `defaultCompare(<Any Type> a, <Any Type> b) ⇒ number` Compares its two arguments for order, using the built in < and > operators.
| `defaultCompareEquality(<Any Type> a, <Any Type> b) ⇒ boolean` Compares its two arguments for equality, using the built in === operator.
| `equals(?goog.array.ArrayLike arr1, ?goog.array.ArrayLike arr2, ?Function= 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.
| `extend(?Array arr1, <Any Type> 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]
| `find(?goog.array.ArrayLike arr, ?Function f, ?Object= opt_obj) ⇒ <Any Type>` Search an array for the first element that satisfies a given condition and return that element.
| `findIndex(?goog.array.ArrayLike arr, ?Function f, ?Object= opt_obj) ⇒ number` Search an array for the first element that satisfies a given condition and return its index.
| `findIndexRight(?goog.array.ArrayLike arr, ?Function f, ?Object= opt_obj) ⇒ number` Search an array (in reverse order) for the last element that satisfies a given condition and return its index.
| `findRight(?goog.array.ArrayLike arr, ?Function f, ?Object= opt_obj) ⇒ <Any Type>` Search an array (in reverse order) for the last element that satisfies a given condition and return that element.
| `flatten(<Any Type> var_args) ⇒ !Array` Returns an array consisting of every argument with all arrays expanded in-place recursively.
| `forEachRight(?goog.array.ArrayLike arr, ?Function f, ?Object= opt_obj)` Calls a function for each element in an array, starting from the last element rather than the first.
| `insert(?Array arr, <Any Type> obj)` Pushes an item into an array, if it's not already in the array.
| `insertArrayAt(?goog.array.ArrayLike arr, ?goog.array.ArrayLike elementsToAdd, number= opt_i)` Inserts at the given index of the array, all elements of another array.
| `insertAt(?goog.array.ArrayLike arr, <Any Type> obj, number= opt_i)` Inserts an object at the given index of the array.
| `insertBefore(?Array arr, <Any Type> obj, <Any Type> opt_obj2)` Inserts an object into an array before a specified object.
| `isEmpty(?goog.array.ArrayLike arr) ⇒ boolean` Whether the array is empty.
| `isSorted(!Array arr, ?Function= opt_compareFn, boolean= opt_strict) ⇒ boolean` Tells if the array is sorted.
| `peek(?goog.array.ArrayLike array) ⇒ <Any Type>` Returns the last element in an array without removing it.
| `reduce(?goog.array.ArrayLike arr, ?Function f, <Any Type> val, ?Object= opt_obj) ⇒ <Any Type>` 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

`reduceRight(?goog.array.ArrayLike arr, ?Function f, <Any Type> val, ?Object= opt_obj) ⇒ <Any Type>`

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'

| `remove(?goog.array.ArrayLike arr, <Any Type> obj) ⇒ boolean` Removes the first occurrence of a particular value from an array.
| `removeAt(?goog.array.ArrayLike arr, number i) ⇒ boolean` Removes from an array the element at index i

`removeDuplicates(?goog.array.ArrayLike arr, ?Array= 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)

| `removeIf(?goog.array.ArrayLike arr, ?Function f, ?Object= opt_obj) ⇒ boolean` Removes the first value that satisfies the given condition.
| `repeat(<Any Type> value, number n) ⇒ !Array` Returns an array consisting of the given value repeated N times.
| `rotate(!Array array, number n) ⇒ !Array` 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].
| `shuffle(!Array arr, ?Function= 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)
| `slice(?goog.array.ArrayLike arr, number start, number= opt_end) ⇒ !Array` 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.

`sort(?Array arr, ?Function= 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`

| `sortObjectsByKey(?Array.<(Object|null)> arr, string key, ?Function= 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}.
| `splice(?goog.array.ArrayLike arr, (number|undefined) index, number howMany, <Any Type> var_args) ⇒ !Array` 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.

`stableSort(?Array arr, function (*, *): number= 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.

| `toArray(?goog.array.ArrayLike object) ⇒ !Array` Converts an object to an array.

`zip((goog.array.ArrayLike|undefined) 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 {@link http://docs.python.org/library/functions.html#zip}