The goog.iter Namespace
.Iterable
- @typedef
- {goog.iter.Iterator|{length:number}|{__iterator__}}
Class/interface for iterators. An iterator needs to implement a {@code next}
method and it needs to throw a {@code goog.iter.StopIteration} when the
iteration passes beyond the end. Iterators have no {@code hasNext} method.
It is recommended to always use the helper functions to iterate over the
iterator or in case you are only targeting JavaScript 1.7 for in loops.
… more
.StopIteration {Error}
Singleton Error object that is used to terminate iterations.
.chain(var_args)
Takes zero or more iterators and returns one iterator that will iterate over
them in the order chained.
var_args {...goog.iter.Iterator}
- Any number of iterator objects.
- returns {!
goog.iter.Iterator}
- Returns a new iterator that will iterate over
all the given iterators' contents.
.cycle(iterable)
Create an iterator to cycle over the iterable's elements indefinitely.
For example, ([1, 2, 3]) would return : 1, 2, 3, 1, 2, 3, ...
iterable {!goog.iter.Iterable}
- The iterable object.
- returns {!
goog.iter.Iterator}
- An iterator that iterates indefinitely over
the values in {@code iterable}.
- @see: http://docs.python.org/library/itertools.html#itertools.cycle.
-
.dropWhile(iterable, f, opt_obj)
Builds a new iterator that iterates over the original, but skips elements as
long as a supplied function returns true.
iterable {goog.iter.Iterable}
- The iterator object.
f {Function}
- 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 {Object=}
- The object to be used as the value of 'this' within
{@code f}.
- returns {!
goog.iter.Iterator}
- A new iterator that drops elements from the
original iterator as long as {@code f} is true.
.equals(iterable1, iterable2)
Iterates over 2 iterators and returns true if they contain the same sequence
of elements and have the same length.
iterable1 {goog.iter.Iterable}
- The first iterable object.
iterable2 {goog.iter.Iterable}
- The second iterable object.
- returns {
boolean}
- true if the iterators contain the same sequence of
elements and have the same length.
.every(iterable, f, opt_obj)
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.
iterable {goog.iter.Iterable}
- The iterator object.
f {Function}
- 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 {Object=}
- The object to be used as the value of 'this' within
{@code f}.
- returns {
boolean}
- true if every value passes the test.
.filter(iterable, f, opt_obj)
Calls a function for every element in the iterator, and if the function
returns true adds the element to a new iterator.
iterable {goog.iter.Iterable}
- The iterator to iterate over.
f {Function}
- 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 {Object=}
- The object to be used as the value of 'this' within
{@code f}.
- returns {!
goog.iter.Iterator}
- A new iterator in which only elements that
passed the test are present.
.forEach(iterable, f, opt_obj)
Calls a function for each element in the iterator with the element of the
iterator passed as argument.
iterable {goog.iter.Iterable}
- The iterator to iterate
over. If the iterable is an object {@code toIterator} will be called on
it.
f {Function}
- 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
{@see goog.array#forEach} as well as others.
opt_obj {Object=}
- The object to be used as the value of 'this' within
{@code f}.
.join(iterable, deliminator)
Joins the values in a iterator with a delimiter.
iterable {goog.iter.Iterable}
- The iterator to get the values from.
deliminator {string}
- The text to put between the values.
- returns {
string}
- The joined value string.
.map(iterable, f, opt_obj)
For every element in the iterator call a function and return a new iterator
with that value.
iterable {goog.iter.Iterable}
- The iterator to iterate over.
f {Function}
- 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 {Object=}
- The object to be used as the value of 'this' within
{@code f}.
- returns {!
goog.iter.Iterator}
- A new iterator that returns the results of
applying the function to each element in the original iterator.
.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.
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.
.product(var_args)
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]).
var_args {...!goog.array.ArrayLike.<*>}
- Zero or more sets, as arrays.
- returns {!
goog.iter.Iterator}
- An iterator that gives each n-tuple (as an
array).
- @see
- http://docs.python.org/library/itertools.html#itertools.product
.range(startOrStop, opt_stop, opt_step)
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)
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 {!
goog.iter.Iterator}
- A new iterator that returns the values in the
range.
.reduce(iterable, f, val, opt_obj)
Passes every element of an iterator into a function and accumulates the
result.
iterable {goog.iter.Iterable}
- The iterator to iterate over.
f {Function}
- 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 {*}
- The initial value to pass into the function on the first call.
opt_obj {Object=}
- The object to be used as the value of 'this'
within f.
- returns {*}
- Result of evaluating f repeatedly across the values of
the iterator.
.some(iterable, f, opt_obj)
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.
iterable {goog.iter.Iterable}
- The iterator object.
f {Function}
- 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 {Object=}
- The object to be used as the value of 'this' within
{@code f}.
- returns {
boolean}
- true if any value passes the test.
.takeWhile(iterable, f, opt_obj)
Builds a new iterator that iterates over the original, but only as long as a
supplied function returns true.
iterable {goog.iter.Iterable}
- The iterator object.
f {Function}
- 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 {Object=}
- This is used as the 'this' object in f when called.
- returns {!
goog.iter.Iterator}
- A new iterator that keeps elements in the
original iterator as long as the function is true.
.toArray(iterable)
Converts the iterator to an array
iterable {goog.iter.Iterable}
- The iterator to convert to an array.
- returns {!
Array}
- An array of the elements the iterator iterates over.
.toIterator(iterable)
Returns an iterator that knows how to iterate over the values in the object.
iterable {goog.iter.Iterable}
- If the object is an iterator it
will be returned as is. If the object has a {@code __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 {!
goog.iter.Iterator}
- An iterator that knows how to iterate over the
values in {@code iterable}.