Iteration for JavaScript

The best overview right now is in my Iteration for JavaScript [3] blog entry. This information will migrate here eventually.

Errors

StopIteration:

The singleton MochiKit.Base.NamedError that signifies the end of an iterator

Availability:

Available in MochiKit 1.3.1+

Functions

applymap(fun, seq[, self]):

applymap(fun, seq) --> fun.apply(self, seq0), fun.apply(self, seq1), ...

(In Python this is called starmap)

Availability:

Available in MochiKit 1.3.1+

chain(p, q[, ...]):

chain(p, q, ...) --> p0, p1, ... plast, q0, q1, ...

Availability:

Available in MochiKit 1.3.1+

count(n=0, step=1):

count(n=0) --> n, n + 1, n + 2, ...

Availability:

Available in MochiKit 1.3.1+

cycle(p):

cycle(p) --> p0, p1, ... plast, p0, p1, ...

Availability:

Available in MochiKit 1.3.1+

dropwhile(pred, seq):

dropwhile(pred, seq) --> seq[n], seq[n + 1], starting when pred(seq[n]) fails

Availability:

Available in MochiKit 1.3.1+

every(iterable, func):

Return true if func(item) is true for every item in iterable.

Availability:

Available in MochiKit 1.3.1+

exhaust(iterable):

Exhausts an iterable without saving the results anywhere, like list(iterable) when you don't care what the output is.

Availability:

Available in MochiKit 1.3.1+

forEach(iterable, func[, self]):

Call func for each item in iterable, and don't save the results.

Availability:

Available in MochiKit 1.3.1+

groupby(iterable[, keyfunc]):

Make an iterator that returns consecutive keys and groups from the iterable. The key is a function computing a key value for each element. If not specified or is None, key defaults to an identity function and returns the element unchanged. Generally, the iterable needs to already be sorted on the same key function.

The returned group is itself an iterator that shares the underlying iterable with groupby(). Because the source is shared, when the groupby object is advanced, the previous group is no longer visible. So, if that data is needed later, it should be stored as an array:

var groups = [];
var uniquekeys = [];
forEach(groupby(data, keyfunc), function (key_group) {
    groups.push(list(key_group[1]));
    uniquekeys.push(key_group[0]);
});

As a convenience, groupby_as_array() is provided to suit the above use case.

Availability:

Available in MochiKit 1.3.1+

groupby_as_array(iterable[, keyfunc]):

Perform the same task as groupby(), except return an array of arrays instead of an iterator of iterators.

Availability:

Available in MochiKit 1.3.1+

iextend(lst, iterable):

Just like list(iterable), except it pushes results on lst rather than creating a new one.

Availability:

Available in MochiKit 1.3.1+

ifilter(pred, seq):

ifilter(pred, seq) --> elements of seq where pred(elem) is true

Availability:

Available in MochiKit 1.3.1+

ifilterfalse(pred, seq):

ifilterfalse(pred, seq) --> elements of seq where pred(elem) is false

Availability:

Available in MochiKit 1.3.1+

imap(fun, p, q[, ...]):

imap(fun, p, q, ...) --> fun(p0, q0, ...), fun(p1, q1, ...), ...

Availability:

Available in MochiKit 1.3.1+

isIterable(obj):

Returns true if the given object is Iterable-like (have a .next() or .iter() method) [todo: move this to Base? .. and this should return true for Array and Arguments, NodeList etc]

Availability:

Available in MochiKit 1.5+

islice(seq, [start,] stop[, step]):

islice(seq, [start,] stop[, step]) --> elements from seq[start:stop:step] (in Python slice syntax)

Availability:

Available in MochiKit 1.3.1+

iter(iterable[, sentinel]):

Convert the given argument to an iterator (object implementing .next()).

1. If iterable is an iterator (implements .next()), then it will be returned as-is.
2. If iterable is an iterator factory (implements .iter()), then the result of iterable.iter() will be returned.
3. If iterable is a JavaScript 1.7 iterator factory (implements .__iterator__()), then the result of iterable.__iterator__() will be returned (MochiKit 1.4+).
4. Otherwise, the iterator factory MochiKit.Base.AdapterRegistry is used to find a match.
5. If no factory is found, it will throw TypeError

Built-in iterator factories are present for Array-like objects, and objects that implement the iterateNext protocol (e.g. the result of Mozilla's document.evaluate).

When used directly, using an iterator should look like this:

var it = iter(iterable);
try {
    while (true) {
        var o = it.next()
        // use o
    }
} catch (e) {
    if (e != StopIteration) {
        throw e;
    }
    // pass
}

This is ugly, so you should use the higher order functions to work with iterators whenever possible.

Availability:

Available in MochiKit 1.3.1+

izip(p, q[, ...]):

izip(p, q, ...) --> [p0, q0, ...], [p1, q1, ...], ...

Availability:

Available in MochiKit 1.3.1+

list(iterable):

Convert iterable to a new Array

Availability:

Available in MochiKit 1.3.1+

next(iterator[, default]):

Return iterator.next()

If default is given, it is returned if the iterator is exhausted, otherwise StopIteration is raised.

Availability:

Available in MochiKit 1.3.1+

range([start,] stop[, step]):

Return an iterator containing an arithmetic progression of integers.

range(i, j) returns iter([i, i + 1, i + 2, ..., j - 1])

start (!) defaults to 0. When step is given, it specifies the increment (or decrement). The end point is omitted!

For example, range(4) returns iter([0, 1, 2, 3]). This iterates over exactly the valid indexes for an array of 4 elements.

Availability:

Available in MochiKit 1.3.1+

reduce(fn, iterable[, initial]):

Apply fn(a, b) cumulatively to the items of an iterable from left to right, so as to reduce the iterable to a single value.

For example:

reduce(function (a, b) { return a + b; }, [1, 2, 3, 4, 5])

calculates:

((((1 + 2) + 3) + 4) + 5).

If initial is given, it is placed before the items of the sequence in the calculation, and serves as a default when the sequence is empty.

Note that the above example could be written more clearly as:

reduce(operator.add, [1, 2, 3, 4, 5])

Or even simpler:

sum([1, 2, 3, 4, 5])

Availability:

Available in MochiKit 1.3.1+

registerIteratorFactory(name, check, iterfactory[, override]):

Register an iterator factory for use with the iter function.

check is a function(a) that returns true if a can be converted into an iterator with iterfactory.

iterfactory is a function(a) that returns an object with a .next() method that returns the next value in the sequence.

iterfactory is guaranteed to only be called if check(a) returns a true value.

If override is true, then it will be made the highest precedence iterator factory. Otherwise, the lowest.

Availability:

Available in MochiKit 1.3.1+

repeat(elem[, n]):

repeat(elem, [,n]) --> elem, elem, elem, ... endlessly or up to n times

Availability:

Available in MochiKit 1.3.1+

reversed(iterable):

Return a reversed array from iterable.

Availability:

Available in MochiKit 1.3.1+

some(iterable, func):

Return true if func(item) is true for at least one item in iterable.

Availability:

Available in MochiKit 1.3.1+

sorted(iterable[, cmp]):

Return a sorted array from iterable.

Availability:

Available in MochiKit 1.3.1+

sum(iterable, start=0):

Returns the sum of a sequence of numbers plus the value of parameter start (with a default of 0). When the sequence is empty, returns start.

Equivalent to:

reduce(operator.add, iterable, start);

Availability:

Available in MochiKit 1.3.1+

takewhile(pred, seq):

takewhile(pred, seq) --> seq[0], seq[1], ... until pred(seq[n]) fails

Availability:

Available in MochiKit 1.3.1+

tee(iterable, n=2):

tee(it, n=2) --> [it1, it2, it3, ... itn] splits one iterator into n

Availability:

Available in MochiKit 1.3.1+