iterator-tools

iterator-tools.js

Iterator tools inspired from the python standard library.

Functions

accumulate(iterable, func=(a, b) => a + b)

Make an iterator that returns accumulated sums. If the optional func argument is supplied, it should be a function of two arguments and it will be used instead of addition.

accumulate([1, 2, 3, 4, 5])                   // 1 3 6 10 15 
accumulate([1, 2, 3, 4, 5], (a, b) => a * b)  // 1 2 6 24 120 

chain(...iterables)

Make an iterator that returns elements from the first iterable until it is exhausted, then proceeds to the next iterable, until all of the iterables are exhausted.

chain('ABC', 'DEF')  // A B C D E F 

chainFromIterable(iterable)

Alternate constructor for chain(). Gets chained inputs from a single iterable argument that is evaluated lazily.

chainFromIterable(['ABC', 'DEF'])  // A B C D E F 

combinations(iterable, r)

Return r length subsequences of elements from the input iterable.

combinations('ABCD', 2)    // AB AC AD BC BD CD 
combinations(range(4), 3)  // 012 013 023 123 

combinationsWithReplacement(iterable, r)

Return r length subsequences of elements from the input iterable allowing individual elements to be repeated more than once.

combinationsWithReplacement('ABC', 2)  // AA AB AC BB BC CC 

compress(data, selectors)

Make an iterator that filters elements from data returning only those that have a corresponding element in selectors that evaluates to true. Stops when either the data or selectors iterables has been exhausted.

compress('ABCDEF', [1, 0, 1, 0, 1, 1])  // A C E F 

count(start=0, step=1)

Make an iterator that returns evenly spaced values starting with number start.

count(10)        // 10 11 12 13 14 ... 
count(2.5, 0.5)  // 2.5 3.0 3.5 ... 

cycle(iterable)

Make an iterator returning elements from the iterable and saving a copy of each.

cycle('ABCD')  // A B C D A B C D A B C D ... 

dropWhile(iterable, predicate=(i) => i)

Make an iterator that drops elements from the iterable as long as the predicate is true; afterwards, returns every element.

dropWhile([1, 4, 6, 4, 1], (x) => x < 5)  // 6 4 1 

filter(iterable, predicate=(i) => i)

Make an iterator that filters elements from iterable returning only those for which the predicate is true. If predicate isn't defined, return the items that are true.

filterFalse(range(10), (x) => x % 2)  // 1 3 5 7 9 

filterFalse(iterable, predicate=(i) => i)

Make an iterator that filters elements from iterable returning only those for which the predicate is false. If predicate isn't defined, return the items that are false.

filterFalse(range(10), (x) => x % 2)  // 0 2 4 6 8 

groupBy(iterable, key=(i) => i)

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, key defaults to an identity function and returns the element unchanged. Generally, the iterable needs to already be sorted on the same key function.

groupBy('AAAABBBCCDAABBB')  // A, A A A A 
                            // B, B B B 
                            // C, C C 
                            // D, D 
                            // A, A A 
                            // B, B B 

map(...iterable, fn)

Make an iterator that computes the function using arguments obtained from the iterables.

map([1, 2], [3, 4], (a, b) => a + b)  // 4 6 

mapApply(...iterable, fn)

Make an iterator that computes the function using arguments obtained from the iterables. Used instead of map() when argument parameters are already grouped in arrays from a single iterable.

mapApply([[2, 5], [3, 2], [10, 3]], Math.pow)  // 32 9 1000 

permutations(iterable, r=undefined)

Return successive r length permutations of elements in the iterable.

If r is undefined, r defaults to the length of the iterable and all possible full-length permutations are generated.

permutations('ABCD', 2)  // AB AC AD BA BC BD CA CB CD DA DB DC 
permutations(range(3))   // 012 021 102 120 201 210 

product(...iterables, repeat=1)

Cartesian product of input iterables. To compute the product of an iterable with itself, specify the number of repetitions with the optional repeat argument.

product('ABCD', 'xy')  // Ax Ay Bx By Cx Cy Dx Dy 
product(range(2), 3)   // 000 001 010 011 100 101 110 111 

range(stop) or range(start, stop, step=1)

Make an iterator that returns a number starting from start to stop, incremented by step.

range(10)          // 0 1 2 3 4 5 6 7 8 9 
range(1, 11)       // 1 2 3 4 5 6 7 8 9 10 
range(0, 30, 5)    // 0 5 10 15 20 25 
range(0, 10, 3)    // 0 3 6 9 
range(0, -10, -1)  // 0 -1 -2 -3 -4 -5 -6 -7 -8 -9 

repeat(element, times=Infinity)

Make an iterator that returns element over and over again. Runs indefinitely unless the times argument is specified.

repeat(10, 3)  // 10 10 10 

slice(iterable, stop=Infinity) or slice(iterable, start=0, stop=Infinity, step=1)

Make an iterator that returns selected elements from the iterable. If start is non-zero, then elements from the iterable are skipped until start is reached. Afterward, elements are returned consecutively unless step is set higher than one which results in items being skipped.

slice('ABCDEFG', 2)               // A B 
slice('ABCDEFG', 2, 4)            // C D 
slice('ABCDEFG', 2, Infinity)     // C D E F G 
slice('ABCDEFG', 0, Infinity, 2)  // A C E G 

takeWhile(iterable, predicate=(i) => i)

Make an iterator that returns elements from the iterable as long as the predicate is true.

takeWhile([1, 4, 6, 4, 1], (x) => x < 5)  // 1 4 

tee(iterable, n=2)

Return n independent iterators from a single iterable.

const [a, b] = tee([1, 2, 3]);
a.next().value // 1 
a.next().value // 2 
b.next().value // 1 

zip(...iterables)

Make an iterator that aggregates elements from each of the iterables. Returns an iterator of arrays, where the i-th array contains the i-th element from each of the argument iterables. The iterator stops when the shortest input iterable is exhausted. With a single iterable argument, it returns an iterator of arrays of size 1. With no arguments, it returns an empty iterator.

zip('ABCD', 'xy')  // [A, x] [B, y] 

zipLongest(...iterables)

Make an iterator that aggregates elements from each of the iterables. If the iterables are of uneven length, missing values are filled-in with undefined.

zipLongest('ABCD', 'xy')  // [A, x] [B, y] [C, undefined] [D, undefined]