iterable-ext

# IterableExt<T>

Extensions to the Iterable<T> interface.

Usage

To get started you will need to install the iterable-ext package using npm or yarn:

yarn add iterable-ext

Then add the following at the top of your source typescript file:

import IterableExt from "iterable-ext";

You can now use the power of IterableExt!

const iterableExt = IterableExt.fromGenerator(function* () {
  for (let i = 0; true; ++i)
    yield i;
});
function isEven(x: number) { return x % 2 === 0; }
function sqr(x: number) { return x * x; }
function add(x: number, y: number) { return x + y; }
function sum(iterableExt: IterableExt<number>) { return iterableExt.fold(0, add); }
console.log(sum(iterableExt.filter(isEven).map(sqr).take(4)));

This example creates a list of all the natural numbers (0, 1, 2, ...), filters out just the even ones (0, 2, 4, ...), squares them (0, 4, 16, ...), takes the first four of them and then adds them together.

Members

Construction

fromGenerator

Signature

static fromGenerator<T>(generator: () => Iterator<T>): IterableExt<T>

static method

Purpose

Create an Iterable<T> from a generator function (typically defined with function*).

Example

const iterableFromGenerator = IterableExt.fromGenerator(function* () {
  yield 5;
  yield 6;
  yield 7;
});
iterableFromGenerator.forEach(console.log);

Complexity

O(1)

fromIterable

Signature

static fromIterable<T>(iterable: Iterable<T>): IterableExt<T>

static method

Purpose

Create an Iterable<T> from an existing Iterable<T>, such as an array.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt.forEach(console.log);

Complexity

O(1)

Iteration

for (... of ...)

Signature

[Symbol.iterator](): Iterator<T>

instance method

Purpose

Allow iteration over an Iterable<T> using the for (const elt of iterableExt) syntax.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
for (const elt of iterableExt)
  console.log(elt);

Complexity

O(1)

Obtaining the iterator is O(1), iterating over it obviously won't be.

Properties

isEmpty

Signature

isEmpty: boolean

read-only instance property

Purpose

Get whether there are zero elements in the collection.

Example

if (IterableExt.fromIterable([3, 5, 7]).isEmpty === false && IterableExt.fromIterable([]).isEmpty === true)
  console.log("All is well");

Complexity

O(1)

count

Signature

count: number

read-only instance property

Purpose

Get the number of elements in the collection.

Example

if (IterableExt.fromIterable([3, 5, 7]).count === 3 && IterableExt.fromIterable([]).count === 0)
  console.log("All is well");

Complexity

O(n)

Scalar methods

get

Signature

get(index: number): T | undefined

instance method

Purpose

Get an element from the collection by index.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
if (iterableExt.get(1) === 5)
  console.log("All is well");

Complexity

O(n)

last

Signature

last(): T | undefined

instance method

Purpose

Get the last element in the collection.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
if (iterableExt.last() === 7)
  console.log("All is well");

Complexity

O(n)

find

Signature

find(predicate: (elt: T) => boolean): T | undefined

instance method

Purpose

Get the first element in the collection for which predicate returns true.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
if (iterableExt.find((x) => x > 3) === 5)
  console.log("All is well");

Complexity

O(n)

findIndex

Signature

findIndex(predicate: (elt: T) => boolean): number | undefined

instance method

Purpose

Get the index of the first element in the collection for which predicate returns true.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
if (iterableExt.findIndex((x) => x > 3) === 1)
  console.log("All is well");

Complexity

O(n)

Modification

insert

Signature

insert(index: number, elt: T): IterableExt<T>

instance method

Purpose

Get a new IterableExt<T> containing all the elements of the current instance with elt inserted before the element at position index.

Example

let iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt = iterableExt.insert(1, 9);
iterableExt.forEach(console.log);

Complexity

O(1)

prepend

Signature

prepend(elt: T): IterableExt<T>

instance method

Purpose

Get a new IterableExt<T> containing all the elements of the current instance with elt inserted before the first element.

Example

let iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt = iterableExt.prepend(9);
iterableExt.forEach(console.log);

Complexity

O(1) Although prepend and insert have the same order of complexity, iterating over a collection created with prepend will be very slightly faster than iterating over the same collection created using insert.

postpend

Signature

postpend(elt: T): IterableExt<T>

instance method

Purpose

Get a new IterableExt<T> containing all the elements of the current instance with elt added after the last element.

Example

let iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt = iterableExt.postpend(9);
iterableExt.forEach(console.log);

Complexity

O(1)

concat

Signature

concat(other: IterableExt<T>): IterableExt<T>

instance method

Purpose

Get a new IterableExt<T> containing all the elements of the current instance with all the elements of other added in order after the last element.

Example

let iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt = iterableExt.concat(iterableExt).concat(iterableExt.concat(iterableExt));
console.log(iterableExt.count);

Complexity

O(1)

skip

Signature

skip(count: number): IterableExt<T>

instance method

Purpose

Get a new IterableExt<T> containing all except the first count elements of the current instance.

Example

let iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt = iterableExt.skip(2);
iterableExt.forEach(console.log);

Complexity

O(1)

take

Signature

take(count: number): IterableExt<T>

instance method

Purpose

Get a new IterableExt<T> with only the first count elements of the current instance.

Example

let iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt = iterableExt.take(2);
iterableExt.forEach(console.log);

Complexity

O(1)

Projection

flatten

Signature

static flatten<T>(outer: IterableExt<IterableExt<T>>): IterableExt<T>

static method

Purpose

Get a new IterableExt<T> containing all the elements of all of the IterableExt<T> collections in outer, specifically all the elements of the first collection in outer added in order followed by all the elements of the second collection in outer added in order, etc.

Example

let iterableIterables = IterableExt.fromIterable([
  IterableExt.fromIterable([3, 5, 7]),
  IterableExt.fromIterable([4, 6, 8]),
  IterableExt.fromIterable([12, 23]),
]);
let iterableExt = IterableExt.flatten(iterableIterables);
console.log(iterableExt.join(", "));

Complexity

O(1)

map

Signature

map<S>(projector: (elt: T) => S): IterableExt<S>

instance method

Purpose

Get a new IterableExt<S> containing the elements generated by applying projector to all the elements of the current instance in order. The type of the elements in the resulting collection can be different to those in the current instance.

Example

function sqr(x: number) { return x * x; }
let iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt = iterableExt.map(sqr);
console.log(iterableExt.join(", "));

Complexity

O(1)

zip

Signature

static zip<T>(collections: IterableExt<T>[]): IterableExt<T[]>

static method

Purpose

Get a new IterableExt<T[]> where each element is an array containing the elements from all the collections in collections that have the same index as the generated element. The length of the array at every index in the new collection is the same as the length of the collections array. The length of the new collection is equal to the length of the shortest collection in collections.

Example

const iterablesArray = [
  IterableExt.fromIterable([3, 5, 7]),
  IterableExt.fromIterable([4, 6, 8]),
  IterableExt.fromIterable([12, 23]),
];
const zippedIterable = IterableExt.zip(iterablesArray);
console.log(zippedIterable.join("; "));

Complexity

O(n) zip is linear in the number of collections to be zipped but independant of the size of those collections. It gets an iterator for each collection when called but only advances those iterators when the resulting Iterable is iterated.

Iteration

fold

Signature

fold<S>(seed: S, folder: (elt1: S, elt2: T) => S): S

instance method

Purpose

Example

function add(x: number, y: number) { return x + y; }
function sum(iterableExt: IterableExt<number>) { return iterableExt.fold(0, add); }
const iterableExt = IterableExt.fromIterable([3, 5, 7]);
console.log(sum(iterableExt));

Complexity

O(n)

scan

Signature

scan<S>(seed: S, folder: (elt1: S, elt2: T) => S): IterableExt<S>

instance method

Purpose

For all the elements in the current instance apply folder to a current state and that element, producing a new state that will be used for the application with the next element. Uses seed as the state for the first application (with the first element in the current instance). Return a new IterableExt<S> containing the states produced by each application, including both seed and the final state after the last application. The length of the resulting collection is one greater than the length of the current instance.

Example

function add(x: number, y: number) { return x + y; }
function sums(iterableExt: IterableExt<number>) { return iterableExt.scan(0, add); }
const iterableExt = IterableExt.fromIterable([3, 5, 7]);
console.log(sums(iterableExt).join(", "));

Complexity

O(n)

forEach

Signature

forEach(f: (elt: T) => void): void

instance method

Purpose

Apply function f to all the elements of the current instance in order.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
iterableExt.forEach(console.log);

Complexity

O(n)

Misc

filter

Signature

filter(predicate: (elt: T) => boolean): IterableExt<T>

instance method

Purpose

Get a new IterableExt<T> containing only the elements of the current instance for which predicate returns true in their original order.

Example

function isEven(x: number) { return x % 2 === 0; }
const iterableExt = IterableExt.fromIterable([3, 5, 6, 7, 8, 9]);
console.log(iterableExt.filter(isEven).join(", "));

Complexity

O(1)

join

Signature

join(separator: string): string

instance method

Purpose

Get a new string consisting of all the elements of the current instance appended to an empty string with separator appended to the string between each element. There will not be a separator at the beginning or the end of the resulting string. Calling join on an empty collection gives an empty string.

Example

const iterableExt = IterableExt.fromIterable([3, 5, 7]);
console.log(iterableExt.join(" - "));

Complexity

O(n)