# Namespace goog.iter

code »

## Classes

goog.iter.Iterator Class/interface for iterators.

Show:Public Protected Private

## Type Definitions

code »goog.iter.Iterable : `(goog.iter.Iterator|{length: number}|{__iterator__: ?})`
No description.

## Global Functions

code »goog.iter.chain ( var_args ) ⇒ `!goog.iter.Iterator`

Takes zero or more iterators and returns one iterator that will iterate over them in the order chained.

Parameters
var_args: `...goog.iter.Iterator` Any number of iterator objects.
Returns
Returns a new iterator that will iterate over all the given iterators' contents.

code »goog.iter.cycle ( iterable ) ⇒ `!goog.iter.Iterator`

Create an iterator to cycle over the iterable's elements indefinitely. For example, ([1, 2, 3]) would return : 1, 2, 3, 1, 2, 3, ...

Parameters
iterable: `!goog.iter.Iterable` The iterable object.
Returns
An iterator that iterates indefinitely over the values in `iterable`.

code »`<T>` goog.iter.dropWhile ( iterable, f, opt_obj ) ⇒ `!goog.iter.Iterator`

Builds a new iterator that iterates over the original, but skips elements as long as a supplied function returns true.

Parameters
iterable: `goog.iter.Iterable` The iterator object. f: `function(this: T, ?, undefined, ?): boolean` The function to call for every value. This function takes 3 arguments (the value, undefined, and the iterator) and should return a boolean. opt_obj: `T=` The object to be used as the value of 'this' within `f`.
Returns
A new iterator that drops elements from the original iterator as long as `f` is true.

code »goog.iter.equals ( iterable1, iterable2 ) ⇒ `boolean`

Iterates over 2 iterators and returns true if they contain the same sequence of elements and have the same length.

Parameters
iterable1: `goog.iter.Iterable` The first iterable object. iterable2: `goog.iter.Iterable` The second iterable object.
Returns
true if the iterators contain the same sequence of elements and have the same length.

code »`<T>` goog.iter.every ( iterable, f, opt_obj ) ⇒ `boolean`

Goes through the values in the iterator. Calls f for each these and if any of them returns false this returns false (without checking the rest). If all return true this will return true.

Parameters
iterable: `goog.iter.Iterable` The iterator object. f: `function(this: T, ?, undefined, ?): boolean` The function to call for every value. This function takes 3 arguments (the value, undefined, and the iterator) and should return a boolean. opt_obj: `T=` The object to be used as the value of 'this' within `f`.
Returns
true if every value passes the test.

code »`<T>` goog.iter.filter ( iterable, f, opt_obj ) ⇒ `!goog.iter.Iterator`

Calls a function for every element in the iterator, and if the function returns true adds the element to a new iterator.

Parameters
iterable: `goog.iter.Iterable` The iterator to iterate over. f: `function(this: T, ?, undefined, ?): boolean` The function to call for every element. This function takes 3 arguments (the element, undefined, and the iterator) and should return a boolean. If the return value is true the element will be included in the returned iteror. If it is false the element is not included. opt_obj: `T=` The object to be used as the value of 'this' within `f`.
Returns
A new iterator in which only elements that passed the test are present.

code »`<T>` goog.iter.forEach ( iterable, f, opt_obj )

Calls a function for each element in the iterator with the element of the iterator passed as argument.

Parameters
iterable: `goog.iter.Iterable` The iterator to iterate over. If the iterable is an object `toIterator` will be called on it. f: `function(this: T, ?, ?, ?): ?` The function to call for every element. This function takes 3 arguments (the element, undefined, and the iterator) and the return value is irrelevant. The reason for passing undefined as the second argument is so that the same function can be used in goog.array#forEach as well as others. opt_obj: `T=` The object to be used as the value of 'this' within `f`.

code »goog.iter.join ( iterable, deliminator ) ⇒ `string`

Joins the values in a iterator with a delimiter.

Parameters
iterable: `goog.iter.Iterable` The iterator to get the values from. deliminator: `string` The text to put between the values.
Returns
The joined value string.

code »`<T>` goog.iter.map ( iterable, f, opt_obj ) ⇒ `!goog.iter.Iterator`

For every element in the iterator call a function and return a new iterator with that value.

Parameters
iterable: `goog.iter.Iterable` The iterator to iterate over. f: `function(this: T, ?, undefined, ?): ?` The function to call for every element. This function takes 3 arguments (the element, undefined, and the iterator) and should return a new value. opt_obj: `T=` The object to be used as the value of 'this' within `f`.
Returns
A new iterator that returns the results of applying the function to each element in the original iterator.

code »goog.iter.nextOrValue ( iterable, defaultValue ) ⇒ `*`

Advances the iterator to the next position, returning the given default value instead of throwing an exception if the iterator has no more entries.

Parameters
iterable: `goog.iter.Iterable` The iterable object. defaultValue: `*` The value to return if the iterator is empty.
Returns
The next item in the iteration, or defaultValue if the iterator was empty.

code »goog.iter.product ( var_args ) ⇒ `!goog.iter.Iterator`

Cartesian product of zero or more sets. Gives an iterator that gives every combination of one element chosen from each set. For example, ([1, 2], [3, 4]) gives ([1, 3], [1, 4], [2, 3], [2, 4]).

Parameters
var_args: `...!goog.array.ArrayLike` Zero or more sets, as arrays.
Returns
An iterator that gives each n-tuple (as an array).

code »goog.iter.range ( startOrStop, opt_stop, opt_step ) ⇒ `!goog.iter.Iterator`

Creates a new iterator that returns the values in a range. This function can take 1, 2 or 3 arguments:

     range(5) same as range(0, 5, 1)
     range(2, 5) same as range(2, 5, 1)

Parameters
startOrStop: `number` The stop value if only one argument is provided. The start value if 2 or more arguments are provided. If only one argument is used the start value is 0. opt_stop: `number=` The stop value. If left out then the first argument is used as the stop value. opt_step: `number=` The number to increment with between each call to next. This can be negative.
Returns
A new iterator that returns the values in the range.

code »`<T, V>` goog.iter.reduce ( iterable, f, val, opt_obj ) ⇒ `V`

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

Parameters
iterable: `goog.iter.Iterable` The iterator to iterate over. f: `function(this: T, V, ?): V` The function to call for every element. This function takes 2 arguments (the function's previous result or the initial value, and the value of the current element). function(previousValue, currentElement) : newValue. val: `V` The initial value to pass into the function on the first call. opt_obj: `T=` The object to be used as the value of 'this' within f.
Returns
Result of evaluating f repeatedly across the values of the iterator.

code »`<T>` goog.iter.some ( iterable, f, opt_obj ) ⇒ `boolean`

Goes through the values in the iterator. Calls f for each these and if any of them returns true, this returns true (without checking the rest). If all return false this will return false.

Parameters
iterable: `goog.iter.Iterable` The iterator object. f: `function(this: T, ?, undefined, ?): boolean` The function to call for every value. This function takes 3 arguments (the value, undefined, and the iterator) and should return a boolean. opt_obj: `T=` The object to be used as the value of 'this' within `f`.
Returns
true if any value passes the test.

code »`<T>` goog.iter.takeWhile ( iterable, f, opt_obj ) ⇒ `!goog.iter.Iterator`

Builds a new iterator that iterates over the original, but only as long as a supplied function returns true.

Parameters
iterable: `goog.iter.Iterable` The iterator object. f: `function(this: T, ?, undefined, ?): boolean` The function to call for every value. This function takes 3 arguments (the value, undefined, and the iterator) and should return a boolean. opt_obj: `T=` This is used as the 'this' object in f when called.
Returns
A new iterator that keeps elements in the original iterator as long as the function is true.

code »goog.iter.toArray ( iterable ) ⇒ `!Array`

Converts the iterator to an array

Parameters
iterable: `goog.iter.Iterable` The iterator to convert to an array.
Returns
An array of the elements the iterator iterates over.

code »goog.iter.toIterator ( iterable ) ⇒ `!goog.iter.Iterator`

Returns an iterator that knows how to iterate over the values in the object.

Parameters
iterable: `goog.iter.Iterable` If the object is an iterator it will be returned as is. If the object has a `__iterator__` method that will be called to get the value iterator. If the object is an array-like object we create an iterator for that.
Returns
An iterator that knows how to iterate over the values in `iterable`.

## Global Properties

code »goog.iter.StopIteration : `Error`

Singleton Error object that is used to terminate iterations.