@phosphor/algorithm

@phosphor/algorithm

Version 1.2.0
Published 5 years ago
188 kB
No dependencies
BSD-3-Clause license

Install

npm i @phosphor/algorithm

yarn add @phosphor/algorithm

pnpm add @phosphor/algorithm

Overview

PhosphorJS - Algorithms and Iterators

Index

Interfaces

IIterable
- iter()
IIterator
- clone()
- next()
IRetroable
- retro()

Type Aliases

IterableOrArrayLike
RetroableOrArrayLike

Functions

function chain

chain: <T>(...objects: IterableOrArrayLike<T>[]) => IIterator<T>;

Chain together several iterables.
Parameter objects
The iterable or array-like objects of interest.
Returns
An iterator which yields the values of the iterables in the order in which they are supplied.
#### Example
import { chain, toArray } from '@phosphor/algorithm'; let data1 = [1, 2, 3]; let data2 = [4, 5, 6]; let stream = chain(data1, data2); toArray(stream); // [1, 2, 3, 4, 5, 6]

function each

each: <T>(
    object: IterableOrArrayLike<T>,
    fn: (value: T, index: number) => boolean | void
) => void;

Invoke a function for each value in an iterable.
Parameter object
The iterable or array-like object of interest.
Parameter fn
The callback function to invoke for each value.
#### Notes Iteration can be terminated early by returning false from the callback function.
#### Complexity Linear.
#### Example
import { each } from '@phosphor/algorithm'; let data = [5, 7, 0, -2, 9]; each(data, value => { console.log(value); });

function empty

empty: <T>() => IIterator<T>;

Create an empty iterator.

Returns

A new iterator which yields nothing.

#### Example

import { empty, toArray } from '@phosphor/algorithm';

let stream = empty<number>();

toArray(stream);  // []

function enumerate

enumerate: <T>(
    object: IterableOrArrayLike<T>,
    start?: number
) => IIterator<[number, T]>;

Enumerate an iterable object.
Parameter object
The iterable or array-like object of interest.
Parameter start
The starting enum value. The default is 0.
Returns
An iterator which yields the enumerated values.
#### Example
import { enumerate, toArray } from '@phosphor/algorithm'; let data = ['foo', 'bar', 'baz']; let stream = enumerate(data, 1); toArray(stream); // [[1, 'foo'], [2, 'bar'], [3, 'baz']]

function every

every: <T>(
    object: IterableOrArrayLike<T>,
    fn: (value: T, index: number) => boolean
) => boolean;

Test whether all values in an iterable satisfy a predicate.
Parameter object
The iterable or array-like object of interest.
Parameter fn
The predicate function to invoke for each value.
Returns
true if all values pass the test, false otherwise.
#### Notes Iteration terminates on the first false predicate result.
#### Complexity Linear.
#### Example
import { every } from '@phosphor/algorithm'; let data = [5, 7, 1]; every(data, value => value % 2 === 0); // false every(data, value => value % 2 === 1); // true

function filter

filter: <T>(
    object: IterableOrArrayLike<T>,
    fn: (value: T, index: number) => boolean
) => IIterator<T>;

Filter an iterable for values which pass a test.
Parameter object
The iterable or array-like object of interest.
Parameter fn
The predicate function to invoke for each value.
Returns
An iterator which yields the values which pass the test.
#### Example
import { filter, toArray } from '@phosphor/algorithm'; let data = [1, 2, 3, 4, 5, 6]; let stream = filter(data, value => value % 2 === 0); toArray(stream); // [2, 4, 6]

function find

find: <T>(
    object: IterableOrArrayLike<T>,
    fn: (value: T, index: number) => boolean
) => T | undefined;

Find the first value in an iterable which matches a predicate.

Parameter object

The iterable or array-like object to search.

Parameter fn

The predicate function to apply to the values.

Returns

The first matching value, or undefined if no matching value is found.

#### Complexity Linear.

#### Example

import { find } from '@phosphor/algorithm';

interface IAnimal { species: string, name: string };

function isCat(value: IAnimal): boolean {
  return value.species === 'cat';
}

let data: IAnimal[] = [
  { species: 'dog', name: 'spot' },
  { species: 'cat', name: 'fluffy' },
  { species: 'alligator', name: 'pocho' }
];

find(data, isCat).name;  // 'fluffy'

function findIndex

findIndex: <T>(
    object: IterableOrArrayLike<T>,
    fn: (value: T, index: number) => boolean
) => number;

Find the index of the first value which matches a predicate.

Parameter object

The iterable or array-like object to search.

Parameter fn

The predicate function to apply to the values.

Returns

The index of the first matching value, or -1 if no matching value is found.

#### Complexity Linear.

#### Example

import { findIndex } from '@phosphor/algorithm';

interface IAnimal { species: string, name: string };

function isCat(value: IAnimal): boolean {
  return value.species === 'cat';
}

let data: IAnimal[] = [
  { species: 'dog', name: 'spot' },
  { species: 'cat', name: 'fluffy' },
  { species: 'alligator', name: 'pocho' }
];

findIndex(data, isCat);  // 1

function iter

iter: <T>(object: IterableOrArrayLike<T>) => IIterator<T>;

Create an iterator for an iterable object.
Parameter object
The iterable or array-like object of interest.
Returns
A new iterator for the given object.
#### Notes This function allows iteration algorithms to operate on user-defined iterable types and builtin array-like objects in a uniform fashion.

function iterFn

iterFn: <T>(fn: () => T | undefined) => IIterator<T>;

Create an iterator for an iterator-like function.
Parameter fn
A function which behaves like an iterator next method.
Returns
A new iterator for the given function.
#### Notes The returned iterator **cannot** be cloned.
#### Example
import { each, iterFn } from '@phosphor/algorithm'; let it = iterFn((() => { let i = 0; return () => i > 3 ? undefined : i++; })()); each(it, v => { console.log(v); }); // 0, 1, 2, 3

function iterItems

iterItems: <T>(object: { readonly [key: string]: T }) => IIterator<[string, T]>;

Create an iterator for the items in an object.

Parameter object

The object of interest.

Returns

A new iterator for the items in the given object.

#### Complexity Linear.

#### Example

import { each, items } from '@phosphor/algorithm';

let data = { one: 1, two: 2, three: 3 };

each(items(data), value => { console.log(value); }); // ['one', 1], ['two', 2], ['three', 3]

function iterKeys

iterKeys: <T>(object: { readonly [key: string]: T }) => IIterator<string>;

Create an iterator for the keys in an object.

Parameter object

The object of interest.

Returns

A new iterator for the keys in the given object.

#### Complexity Linear.

#### Example

import { each, keys } from '@phosphor/algorithm';

let data = { one: 1, two: 2, three: 3 };

each(keys(data), key => { console.log(key); }); // 'one', 'two', 'three'

function iterValues

iterValues: <T>(object: { readonly [key: string]: T }) => IIterator<T>;

Create an iterator for the values in an object.

Parameter object

The object of interest.

Returns

A new iterator for the values in the given object.

#### Complexity Linear.

#### Example

import { each, values } from '@phosphor/algorithm';

let data = { one: 1, two: 2, three: 3 };

each(values(data), value => { console.log(value); }); // 1, 2, 3

function map

map: <T, U>(
    object: IterableOrArrayLike<T>,
    fn: (value: T, index: number) => U
) => IIterator<U>;

Transform the values of an iterable with a mapping function.
Parameter object
The iterable or array-like object of interest.
Parameter fn
The mapping function to invoke for each value.
Returns
An iterator which yields the transformed values.
#### Example
import { map, toArray } from '@phosphor/algorithm'; let data = [1, 2, 3]; let stream = map(data, value => value * 2); toArray(stream); // [2, 4, 6]

function max

max: <T>(
    object: IterableOrArrayLike<T>,
    fn: (first: T, second: T) => number
) => T | undefined;

Find the maximum value in an iterable.
Parameter object
The iterable or array-like object to search.
Parameter fn
The 3-way comparison function to apply to the values. It should return < 0 if the first value is less than the second. 0 if the values are equivalent, or > 0 if the first value is greater than the second.
Returns
The maximum value in the iterable. If multiple values are equivalent to the maximum, the left-most value is returned. If the iterable is empty, this returns undefined.
#### Complexity Linear.
#### Example
import { max } from '@phosphor/algorithm'; function numberCmp(a: number, b: number): number { return a - b; } max([7, 4, 0, 3, 9, 4], numberCmp); // 9

function min

min: <T>(
    object: IterableOrArrayLike<T>,
    fn: (first: T, second: T) => number
) => T | undefined;

Find the minimum value in an iterable.
Parameter object
The iterable or array-like object to search.
Parameter fn
The 3-way comparison function to apply to the values. It should return < 0 if the first value is less than the second. 0 if the values are equivalent, or > 0 if the first value is greater than the second.
Returns
The minimum value in the iterable. If multiple values are equivalent to the minimum, the left-most value is returned. If the iterable is empty, this returns undefined.
#### Complexity Linear.
#### Example
import { min } from '@phosphor/algorithm'; function numberCmp(a: number, b: number): number { return a - b; } min([7, 4, 0, 3, 9, 4], numberCmp); // 0

function minmax

minmax: <T>(
    object: IterableOrArrayLike<T>,
    fn: (first: T, second: T) => number
) => [T, T] | undefined;

Find the minimum and maximum values in an iterable.
Parameter object
The iterable or array-like object to search.
Parameter fn
The 3-way comparison function to apply to the values. It should return < 0 if the first value is less than the second. 0 if the values are equivalent, or > 0 if the first value is greater than the second.
Returns
A 2-tuple of the [min, max] values in the iterable. If multiple values are equivalent, the left-most values are returned. If the iterable is empty, this returns undefined.
#### Complexity Linear.
#### Example
import { minmax } from '@phosphor/algorithm'; function numberCmp(a: number, b: number): number { return a - b; } minmax([7, 4, 0, 3, 9, 4], numberCmp); // [0, 9]

function once

once: <T>(value: T) => IIterator<T>;

Create an iterator which yields a value a single time.
Parameter value
The value to wrap in an iterator.
Returns
A new iterator which yields the value a single time.
#### Example
import { once, toArray } from '@phosphor/algorithm'; let stream = once(7); toArray(stream); // [7]

function range

range: (start: number, stop?: number, step?: number) => IIterator<number>;

Create an iterator of evenly spaced values.
Parameter start
The starting value for the range, inclusive.
Parameter stop
The stopping value for the range, exclusive.
Parameter step
The distance between each value.
Returns
An iterator which produces evenly spaced values.
#### Notes In the single argument form of range(stop), start defaults to 0 and step defaults to 1.
In the two argument form of range(start, stop), step defaults to 1.

function reduce

reduce: {
    <T>(
        object: IterableOrArrayLike<T>,
        fn: (accumulator: T, value: T, index: number) => T
    ): T;
    <T, U>(
        object: IterableOrArrayLike<T>,
        fn: (accumulator: U, value: T, index: number) => U,
        initial: U
    ): U;
};

Summarize all values in an iterable using a reducer function.
Parameter object
The iterable or array-like object of interest.
Parameter fn
The reducer function to invoke for each value.
Parameter initial
The initial value to start accumulation.
Returns
The final accumulated value.
#### Notes The reduce function follows the conventions of Array#reduce.
If the iterator is empty, an initial value is required. That value will be used as the return value. If no initial value is provided, an error will be thrown.
If the iterator contains a single item and no initial value is provided, the single item is used as the return value.
Otherwise, the reducer is invoked for each element in the iterable. If an initial value is not provided, the first element will be used as the initial accumulated value.
#### Complexity Linear.
#### Example
import { reduce } from '@phosphor/algorithm'; let data = [1, 2, 3, 4, 5]; let sum = reduce(data, (a, value) => a + value); // 15

function repeat

repeat: <T>(value: T, count: number) => IIterator<T>;

Create an iterator which repeats a value a number of times.
Parameter value
The value to repeat.
Parameter count
The number of times to repeat the value.
Returns
A new iterator which repeats the specified value.
#### Example
import { repeat, toArray } from '@phosphor/algorithm'; let stream = repeat(7, 3); toArray(stream); // [7, 7, 7]

function retro

retro: <T>(object: RetroableOrArrayLike<T>) => IIterator<T>;

Create an iterator for a retroable object.
Parameter object
The retroable or array-like object of interest.
Returns
An iterator which traverses the object's values in reverse.
#### Example
import { retro, toArray } from '@phosphor/algorithm'; let data = [1, 2, 3, 4, 5, 6]; let stream = retro(data); toArray(stream); // [6, 5, 4, 3, 2, 1]

function some

some: <T>(
    object: IterableOrArrayLike<T>,
    fn: (value: T, index: number) => boolean
) => boolean;

Test whether any value in an iterable satisfies a predicate.
Parameter object
The iterable or array-like object of interest.
Parameter fn
The predicate function to invoke for each value.
Returns
true if any value passes the test, false otherwise.
#### Notes Iteration terminates on the first true predicate result.
#### Complexity Linear.
#### Example
import { some } from '@phosphor/algorithm'; let data = [5, 7, 1]; some(data, value => value === 7); // true some(data, value => value === 3); // false

function stride

stride: <T>(object: IterableOrArrayLike<T>, step: number) => IIterator<T>;

Iterate over an iterable using a stepped increment.
Parameter object
The iterable or array-like object of interest.
Parameter step
The distance to step on each iteration. A value of less than 1 will behave the same as a value of 1.
Returns
An iterator which traverses the iterable step-wise.
#### Example
import { stride, toArray } from '@phosphor/algorithm'; let data = [1, 2, 3, 4, 5, 6]; let stream = stride(data, 2); toArray(stream); // [1, 3, 5];

function take

take: <T>(object: IterableOrArrayLike<T>, count: number) => IIterator<T>;

Take a fixed number of items from an iterable.
Parameter object
The iterable or array-like object of interest.
Parameter count
The number of items to take from the iterable.
Returns
An iterator which yields the specified number of items from the source iterable.
#### Notes The returned iterator will exhaust early if the source iterable contains an insufficient number of items.

function toArray

toArray: <T>(object: IterableOrArrayLike<T>) => T[];

Create an array from an iterable of values.

Parameter object

The iterable or array-like object of interest.

Returns

A new array of values from the given object.

#### Example

import { iter, toArray } from '@phosphor/algorithm';

let data = [1, 2, 3, 4, 5, 6];

let stream = iter(data);

toArray(stream);  // [1, 2, 3, 4, 5, 6];

function toObject

toObject: <T>(object: IterableOrArrayLike<[string, T]>) => { [key: string]: T };

Create an object from an iterable of key/value pairs.
Parameter object
The iterable or array-like object of interest.
Returns
A new object mapping keys to values.
#### Example
import { toObject } from '@phosphor/algorithm'; let data = [['one', 1], ['two', 2], ['three', 3]]; toObject(data); // { one: 1, two: 2, three: 3 }

function topologicSort

topologicSort: <T>(edges: IterableOrArrayLike<[T, T]>) => T[];

Topologically sort an iterable of edges.
Parameter edges
The iterable or array-like object of edges to sort. An edge is represented as a 2-tuple of [fromNode, toNode].
Returns
The topologically sorted array of nodes.
#### Notes If a cycle is present in the graph, the cycle will be ignored and the return value will be only approximately sorted.
#### Example ```typescript import { topologicSort } from '@phosphor/algorithm';
let data = [ ['d', 'e'], ['c', 'd'], ['a', 'b'], ['b', 'c'] ];
topologicSort(data); // ['a', 'b', 'c', 'd', 'e']

function zip

zip: <T>(...objects: IterableOrArrayLike<T>[]) => IIterator<T[]>;

Iterate several iterables in lockstep.
Parameter objects
The iterable or array-like objects of interest.
Returns
An iterator which yields successive tuples of values where each value is taken in turn from the provided iterables. It will be as long as the shortest provided iterable.
#### Example
import { zip, toArray } from '@phosphor/algorithm'; let data1 = [1, 2, 3]; let data2 = [4, 5, 6]; let stream = zip(data1, data2); toArray(stream); // [[1, 4], [2, 5], [3, 6]]

Classes

class ArrayIterator

class ArrayIterator<T> implements IIterator<T> {}

An iterator for an array-like object.
#### Notes This iterator can be used for any builtin JS array-like object.

constructor

constructor(source: ArrayLike<T>);

Construct a new array iterator.
Parameter source
The array-like object of interest.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class ChainIterator

class ChainIterator<T> implements IIterator<T> {}

An iterator which chains together several iterators.

constructor

constructor(source: IIterator<IIterator<T>>);

Construct a new chain iterator.
Parameter source
The iterator of iterators of interest.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class EmptyIterator

class EmptyIterator<T> implements IIterator<T> {}

An iterator which is always empty.

constructor

constructor();

Construct a new empty iterator.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class EnumerateIterator

class EnumerateIterator<T> implements IIterator<[number, T]> {}

An iterator which enumerates the source values.

constructor

constructor(source: IIterator<T>, start: number);

Construct a new enumerate iterator.
Parameter source
The iterator of values of interest.
Parameter start
The starting enum value.

method clone

clone: () => IIterator<[number, T]>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<[number, T]>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => [number, T] | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class FilterIterator

class FilterIterator<T> implements IIterator<T> {}

An iterator which yields values which pass a test.

constructor

constructor(source: IIterator<T>, fn: (value: T, index: number) => boolean);

Construct a new filter iterator.
Parameter source
The iterator of values of interest.
Parameter fn
The predicate function to invoke for each value.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class FnIterator

class FnIterator<T> implements IIterator<T> {}

An iterator for an iterator-like function.

constructor

constructor(fn: () => T | undefined);

Construct a new function iterator.
Parameter fn
The iterator-like function of interest.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class ItemIterator

class ItemIterator<T> implements IIterator<[string, T]> {}

An iterator for the items in an object.
#### Notes This iterator can be used for any JS object.

constructor

constructor(source: { readonly [key: string]: T }, keys?: string[]);

Construct a new item iterator.
Parameter source
The object of interest.
Parameter keys
The keys to iterate, if known.

method clone

clone: () => IIterator<[string, T]>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<[string, T]>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => [string, T] | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class KeyIterator

class KeyIterator implements IIterator<string> {}

An iterator for the keys in an object.
#### Notes This iterator can be used for any JS object.

constructor

constructor(source: { readonly [key: string]: any }, keys?: string[]);

Construct a new key iterator.
Parameter source
The object of interest.
Parameter keys
The keys to iterate, if known.

method clone

clone: () => IIterator<string>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<string>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => string | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class MapIterator

class MapIterator<T, U> implements IIterator<U> {}

An iterator which transforms values using a mapping function.

constructor

constructor(source: IIterator<T>, fn: (value: T, index: number) => U);

Construct a new map iterator.
Parameter source
The iterator of values of interest.
Parameter fn
The mapping function to invoke for each value.

method clone

clone: () => IIterator<U>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<U>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => U | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class RangeIterator

class RangeIterator implements IIterator<number> {}

An iterator which produces a range of evenly spaced values.

constructor

constructor(start: number, stop: number, step: number);

Construct a new range iterator.
Parameter start
The starting value for the range, inclusive.
Parameter stop
The stopping value for the range, exclusive.
Parameter step
The distance between each value.

method clone

clone: () => IIterator<number>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<number>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => number | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class RepeatIterator

class RepeatIterator<T> implements IIterator<T> {}

An iterator which repeats a value a specified number of times.

constructor

constructor(value: {}, count: number);

Construct a new repeat iterator.
Parameter value
The value to repeat.
Parameter count
The number of times to repeat the value.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class RetroArrayIterator

class RetroArrayIterator<T> implements IIterator<T> {}

An iterator which traverses an array-like object in reverse.
#### Notes This iterator can be used for any builtin JS array-like object.

constructor

constructor(source: ArrayLike<T>);

Construct a new retro iterator.
Parameter source
The array-like object of interest.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class StrideIterator

class StrideIterator<T> implements IIterator<T> {}

An iterator which traverses a source iterator step-wise.

constructor

constructor(source: IIterator<T>, step: number);

Construct a new stride iterator.
Parameter source
The iterator of values of interest.
Parameter step
The distance to step on each iteration. A value of less than 1 will behave the same as a value of 1.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class TakeIterator

class TakeIterator<T> implements IIterator<T> {}

An iterator which takes a fixed number of items from a source.

constructor

constructor(source: IIterator<T>, count: number);

Construct a new take iterator.
Parameter source
The iterator of interest.
Parameter count
The number of items to take from the source.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class ValueIterator

class ValueIterator<T> implements IIterator<T> {}

An iterator for the values in an object.
#### Notes This iterator can be used for any JS object.

constructor

constructor(source: { readonly [key: string]: T }, keys?: string[]);

Construct a new value iterator.
Parameter source
The object of interest.
Parameter keys
The keys to iterate, if known.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

class ZipIterator

class ZipIterator<T> implements IIterator<T[]> {}

An iterator which iterates several sources in lockstep.

constructor

constructor(source: IIterator<T>[]);

Construct a new zip iterator.
Parameter source
The iterators of interest.

method clone

clone: () => IIterator<T[]>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.

method iter

iter: () => IIterator<T[]>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.

method next

next: () => T[] | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.

Interfaces

interface IIterable

interface IIterable<T> {}

An object which can produce an iterator over its values.

method iter

iter: () => IIterator<T>;

Get an iterator over the object's values.
Returns
An iterator which yields the object's values.
#### Notes Depending on the iterable, the returned iterator may or may not be a new object. A collection or other container-like object should typically return a new iterator, while an iterator itself should normally return this.

interface IIterator

interface IIterator<T> extends IIterable<T> {}

An object which traverses a collection of values.
#### Notes An IIterator is itself an IIterable. Most implementations of IIterator should simply return this from the iter() method.

method clone

clone: () => IIterator<T>;

Create an independent clone of the iterator.
Returns
A new independent clone of the iterator.
#### Notes The cloned iterator can be consumed independently of the current iterator. In essence, it is a copy of the iterator value stream which starts at the current location.
This can be useful for lookahead and stream duplication.

method next

next: () => T | undefined;

Get the next value from the iterator.
Returns
The next value from the iterator, or undefined.
#### Notes The undefined value is used to signal the end of iteration and should therefore not be used as a value in a collection.
The use of the undefined sentinel is an explicit design choice which favors performance over purity. The ES6 iterator design of returning a { value, done } pair is suboptimal, as it requires an object allocation on each iteration; and an isDone() method would increase implementation and runtime complexity.

interface IRetroable

interface IRetroable<T> {}

An object which can produce a reverse iterator over its values.

method retro

retro: () => IIterator<T>;

Get a reverse iterator over the object's values.
Returns
An iterator which yields the object's values in reverse.

Type Aliases

type IterableOrArrayLike

type IterableOrArrayLike<T> = IIterable<T> | ArrayLike<T>;

A type alias for an iterable or builtin array-like object.

type RetroableOrArrayLike

type RetroableOrArrayLike<T> = IRetroable<T> | ArrayLike<T>;

A type alias for a retroable or builtin array-like object.

Namespaces

namespace ArrayExt

namespace ArrayExt {}

The namespace for array-specific algorithms.

function fill

fill: <T>(
    array: MutableArrayLike<T>,
    value: T,
    start?: number,
    stop?: number
) => void;

Fill an array with a static value.
Parameter array
The mutable array-like object to fill.
Parameter value
The static value to use to fill the array.
Parameter start
The index of the first element in the range to be filled, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be filled, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
#### Notes If stop < start the fill will wrap at the end of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop which is non-integral.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = ['one', 'two', 'three', 'four']; ArrayExt.fill(data, 'r'); // ['r', 'r', 'r', 'r'] ArrayExt.fill(data, 'g', 1); // ['r', 'g', 'g', 'g'] ArrayExt.fill(data, 'b', 2, 3); // ['r', 'g', 'b', 'b'] ArrayExt.fill(data, 'z', 3, 1); // ['z', 'z', 'b', 'z']

function findFirstIndex

findFirstIndex: <T>(
    array: ArrayLike<T>,
    fn: (value: T, index: number) => boolean,
    start?: number,
    stop?: number
) => number;

Find the index of the first value which matches a predicate.
Parameter array
The array-like object to search.
Parameter fn
The predicate function to apply to the values.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The index of the first matching value, or -1 if no matching value is found.
#### Notes If stop < start the search will wrap at the end of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop which is non-integral.
Modifying the length of the array while searching.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function isEven(value: number): boolean { return value % 2 === 0; } let data = [1, 2, 3, 4, 3, 2, 1]; ArrayExt.findFirstIndex(data, isEven); // 1 ArrayExt.findFirstIndex(data, isEven, 4); // 5 ArrayExt.findFirstIndex(data, isEven, 6); // -1 ArrayExt.findFirstIndex(data, isEven, 6, 5); // 1

function findFirstValue

findFirstValue: <T>(
    array: ArrayLike<T>,
    fn: (value: T, index: number) => boolean,
    start?: number,
    stop?: number
) => T | undefined;

Find the first value which matches a predicate.
Parameter array
The array-like object to search.
Parameter fn
The predicate function to apply to the values.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The first matching value, or undefined if no matching value is found.
#### Notes If stop < start the search will wrap at the end of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop which is non-integral.
Modifying the length of the array while searching.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function isEven(value: number): boolean { return value % 2 === 0; } let data = [1, 2, 3, 4, 3, 2, 1]; ArrayExt.findFirstValue(data, isEven); // 2 ArrayExt.findFirstValue(data, isEven, 2); // 4 ArrayExt.findFirstValue(data, isEven, 6); // undefined ArrayExt.findFirstValue(data, isEven, 6, 5); // 2

function findLastIndex

findLastIndex: <T>(
    array: ArrayLike<T>,
    fn: (value: T, index: number) => boolean,
    start?: number,
    stop?: number
) => number;

Find the index of the last value which matches a predicate.
Parameter object
The array-like object to search.
Parameter fn
The predicate function to apply to the values.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Returns
The index of the last matching value, or -1 if no matching value is found.
#### Notes If start < stop the search will wrap at the front of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop which is non-integral.
Modifying the length of the array while searching.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function isEven(value: number): boolean { return value % 2 === 0; } let data = [1, 2, 3, 4, 3, 2, 1]; ArrayExt.findLastIndex(data, isEven); // 5 ArrayExt.findLastIndex(data, isEven, 4); // 3 ArrayExt.findLastIndex(data, isEven, 0); // -1 ArrayExt.findLastIndex(data, isEven, 0, 1); // 5

function findLastValue

findLastValue: <T>(
    array: ArrayLike<T>,
    fn: (value: T, index: number) => boolean,
    start?: number,
    stop?: number
) => T | undefined;

Find the last value which matches a predicate.
Parameter object
The array-like object to search.
Parameter fn
The predicate function to apply to the values.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Returns
The last matching value, or undefined if no matching value is found.
#### Notes If start < stop the search will wrap at the front of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop which is non-integral.
Modifying the length of the array while searching.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function isEven(value: number): boolean { return value % 2 === 0; } let data = [1, 2, 3, 4, 3, 2, 1]; ArrayExt.findLastValue(data, isEven); // 2 ArrayExt.findLastValue(data, isEven, 4); // 4 ArrayExt.findLastValue(data, isEven, 0); // undefined ArrayExt.findLastValue(data, isEven, 0, 1); // 2

function firstIndexOf

firstIndexOf: <T>(
    array: ArrayLike<T>,
    value: T,
    start?: number,
    stop?: number
) => number;

Find the index of the first occurrence of a value in an array.
Parameter array
The array-like object to search.
Parameter value
The value to locate in the array. Values are compared using strict === equality.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The index of the first occurrence of the value, or -1 if the value is not found.
#### Notes If stop < start the search will wrap at the end of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop which is non-integral.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = ['one', 'two', 'three', 'four', 'one']; ArrayExt.firstIndexOf(data, 'red'); // -1 ArrayExt.firstIndexOf(data, 'one'); // 0 ArrayExt.firstIndexOf(data, 'one', 1); // 4 ArrayExt.firstIndexOf(data, 'two', 2); // -1 ArrayExt.firstIndexOf(data, 'two', 2, 1); // 1

function insert

insert: <T>(array: Array<T>, index: number, value: T) => void;

Insert a value into an array at a specific index.
Parameter array
The array of interest.
Parameter index
The index at which to insert the value. Negative values are taken as an offset from the end of the array.
Parameter value
The value to set at the specified index.
#### Complexity Linear.
#### Undefined Behavior An index which is non-integral.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = [0, 1, 2]; ArrayExt.insert(data, 0, -1); // [-1, 0, 1, 2] ArrayExt.insert(data, 2, 12); // [-1, 0, 12, 1, 2] ArrayExt.insert(data, -1, 7); // [-1, 0, 12, 1, 7, 2] ArrayExt.insert(data, 6, 19); // [-1, 0, 12, 1, 7, 2, 19]

function lastIndexOf

lastIndexOf: <T>(
    array: ArrayLike<T>,
    value: T,
    start?: number,
    stop?: number
) => number;

Find the index of the last occurrence of a value in an array.
Parameter array
The array-like object to search.
Parameter value
The value to locate in the array. Values are compared using strict === equality.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Returns
The index of the last occurrence of the value, or -1 if the value is not found.
#### Notes If start < stop the search will wrap at the front of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop which is non-integral.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = ['one', 'two', 'three', 'four', 'one']; ArrayExt.lastIndexOf(data, 'red'); // -1 ArrayExt.lastIndexOf(data, 'one'); // 4 ArrayExt.lastIndexOf(data, 'one', 1); // 0 ArrayExt.lastIndexOf(data, 'two', 0); // -1 ArrayExt.lastIndexOf(data, 'two', 0, 1); // 1

function lowerBound

lowerBound: <T, U>(
    array: ArrayLike<T>,
    value: U,
    fn: (element: T, value: U) => number,
    start?: number,
    stop?: number
) => number;

Find the index of the first element which compares >= to a value.
Parameter array
The sorted array-like object to search.
Parameter value
The value to locate in the array.
Parameter fn
The 3-way comparison function to apply to the values. It should return < 0 if an element is less than a value, 0 if an element is equal to a value, or > 0 if an element is greater than a value.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The index of the first element which compares >= to the value, or length if there is no such element. If the computed index for stop is less than start, then the computed index for start is returned.
#### Notes The array must already be sorted in ascending order according to the comparison function.
#### Complexity Logarithmic.
#### Undefined Behavior Searching a range which is not sorted in ascending order.
A start or stop which is non-integral.
Modifying the length of the array while searching.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function numberCmp(a: number, b: number): number { return a - b; } let data = [0, 3, 4, 7, 7, 9]; ArrayExt.lowerBound(data, 0, numberCmp); // 0 ArrayExt.lowerBound(data, 6, numberCmp); // 3 ArrayExt.lowerBound(data, 7, numberCmp); // 3 ArrayExt.lowerBound(data, -1, numberCmp); // 0 ArrayExt.lowerBound(data, 10, numberCmp); // 6

function move

move: <T>(
    array: MutableArrayLike<T>,
    fromIndex: number,
    toIndex: number
) => void;

Move an element in an array from one index to another.
Parameter array
The mutable array-like object of interest.
Parameter fromIndex
The index of the element to move. Negative values are taken as an offset from the end of the array.
Parameter toIndex
The target index of the element. Negative values are taken as an offset from the end of the array.
#### Complexity Linear.
#### Undefined Behavior A fromIndex or toIndex which is non-integral.
#### Example
import { ArrayExt } from from '@phosphor/algorithm'; let data = [0, 1, 2, 3, 4]; ArrayExt.move(data, 1, 2); // [0, 2, 1, 3, 4] ArrayExt.move(data, 4, 2); // [0, 2, 4, 1, 3]

function removeAllOf

removeAllOf: <T>(
    array: Array<T>,
    value: T,
    start?: number,
    stop?: number
) => number;

Remove all occurrences of a value from an array.
Parameter array
The array of interest.
Parameter value
The value to remove from the array. Values are compared using strict === equality.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The number of elements removed from the array.
#### Notes If stop < start the search will conceptually wrap at the end of the array, however the array will be traversed front-to-back.
#### Complexity Linear.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = [14, 12, 23, 39, 14, 12, 19, 14]; ArrayExt.removeAllOf(data, 12); // 2 ArrayExt.removeAllOf(data, 17); // 0 ArrayExt.removeAllOf(data, 14, 1, 4); // 1

function removeAllWhere

removeAllWhere: <T>(
    array: Array<T>,
    fn: (value: T, index: number) => boolean,
    start?: number,
    stop?: number
) => number;

Remove all occurrences of values which match a predicate.
Parameter array
The array of interest.
Parameter fn
The predicate function to apply to the values.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The number of elements removed from the array.
#### Notes If stop < start the search will conceptually wrap at the end of the array, however the array will be traversed front-to-back.
#### Complexity Linear.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function isEven(value: number): boolean { return value % 2 === 0; } function isNegative(value: number): boolean { return value < 0; } let data = [0, 12, -13, -9, 23, 39, 14, -15, 12, 75]; ArrayExt.removeAllWhere(data, isEven); // 4 ArrayExt.removeAllWhere(data, isNegative, 0, 3); // 2

function removeAt

removeAt: <T>(array: Array<T>, index: number) => T | undefined;

Remove and return a value at a specific index in an array.
Parameter array
The array of interest.
Parameter index
The index of the value to remove. Negative values are taken as an offset from the end of the array.
Returns
The value at the specified index, or undefined if the index is out of range.
#### Complexity Linear.
#### Undefined Behavior An index which is non-integral.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = [0, 12, 23, 39, 14, 12, 75]; ArrayExt.removeAt(data, 2); // 23 ArrayExt.removeAt(data, -2); // 12 ArrayExt.removeAt(data, 10); // undefined;

function removeFirstOf

removeFirstOf: <T>(
    array: Array<T>,
    value: T,
    start?: number,
    stop?: number
) => number;

Remove the first occurrence of a value from an array.
Parameter array
The array of interest.
Parameter value
The value to remove from the array. Values are compared using strict === equality.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The index of the removed value, or -1 if the value is not contained in the array.
#### Notes If stop < start the search will wrap at the end of the array.
#### Complexity Linear.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = [0, 12, 23, 39, 14, 12, 75]; ArrayExt.removeFirstOf(data, 12); // 1 ArrayExt.removeFirstOf(data, 17); // -1 ArrayExt.removeFirstOf(data, 39, 3); // -1 ArrayExt.removeFirstOf(data, 39, 3, 2); // 2

function removeFirstWhere

removeFirstWhere: <T>(
    array: Array<T>,
    fn: (value: T, index: number) => boolean,
    start?: number,
    stop?: number
) => { index: number; value: T | undefined };

Remove the first occurrence of a value which matches a predicate.
Parameter array
The array of interest.
Parameter fn
The predicate function to apply to the values.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The removed { index, value }, which will be -1 and undefined if the value is not contained in the array.
#### Notes If stop < start the search will wrap at the end of the array.
#### Complexity Linear.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function isEven(value: number): boolean { return value % 2 === 0; } let data = [0, 12, 23, 39, 14, 12, 75]; ArrayExt.removeFirstWhere(data, isEven); // { index: 0, value: 0 } ArrayExt.removeFirstWhere(data, isEven, 2); // { index: 3, value: 14 } ArrayExt.removeFirstWhere(data, isEven, 4); // { index: -1, value: undefined }

function removeLastOf

removeLastOf: <T>(
    array: Array<T>,
    value: T,
    start?: number,
    stop?: number
) => number;

Remove the last occurrence of a value from an array.
Parameter array
The array of interest.
Parameter value
The value to remove from the array. Values are compared using strict === equality.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Returns
The index of the removed value, or -1 if the value is not contained in the array.
#### Notes If start < stop the search will wrap at the end of the array.
#### Complexity Linear.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = [0, 12, 23, 39, 14, 12, 75]; ArrayExt.removeLastOf(data, 12); // 5 ArrayExt.removeLastOf(data, 17); // -1 ArrayExt.removeLastOf(data, 39, 2); // -1 ArrayExt.removeLastOf(data, 39, 2, 3); // 3

function removeLastWhere

removeLastWhere: <T>(
    array: Array<T>,
    fn: (value: T, index: number) => boolean,
    start?: number,
    stop?: number
) => { index: number; value: T | undefined };

Remove the last occurrence of a value which matches a predicate.
Parameter array
The array of interest.
Parameter fn
The predicate function to apply to the values.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Returns
The removed { index, value }, which will be -1 and undefined if the value is not contained in the array.
#### Notes If start < stop the search will wrap at the end of the array.
#### Complexity Linear.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function isEven(value: number): boolean { return value % 2 === 0; } let data = [0, 12, 23, 39, 14, 12, 75]; ArrayExt.removeLastWhere(data, isEven); // { index: 5, value: 12 } ArrayExt.removeLastWhere(data, isEven, 2); // { index: 1, value: 12 } ArrayExt.removeLastWhere(data, isEven, 2, 1); // { index: -1, value: undefined }

function reverse

reverse: <T>(array: MutableArrayLike<T>, start?: number, stop?: number) => void;

Reverse an array in-place.
Parameter array
The mutable array-like object of interest.
Parameter start
The index of the first element in the range to be reversed, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be reversed, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
#### Complexity Linear.
#### Undefined Behavior A start or stop index which is non-integral.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = [0, 1, 2, 3, 4]; ArrayExt.reverse(data, 1, 3); // [0, 3, 2, 1, 4] ArrayExt.reverse(data, 3); // [0, 3, 2, 4, 1] ArrayExt.reverse(data); // [1, 4, 2, 3, 0]

function rotate

rotate: <T>(
    array: MutableArrayLike<T>,
    delta: number,
    start?: number,
    stop?: number
) => void;

Rotate the elements of an array in-place.
Parameter array
The mutable array-like object of interest.
Parameter delta
The amount of rotation to apply to the elements. A positive value will rotate the elements to the left. A negative value will rotate the elements to the right.
Parameter start
The index of the first element in the range to be rotated, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be rotated, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
#### Complexity Linear.
#### Undefined Behavior A delta, start, or stop which is non-integral.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let data = [0, 1, 2, 3, 4]; ArrayExt.rotate(data, 2); // [2, 3, 4, 0, 1] ArrayExt.rotate(data, -2); // [0, 1, 2, 3, 4] ArrayExt.rotate(data, 10); // [0, 1, 2, 3, 4] ArrayExt.rotate(data, 9); // [4, 0, 1, 2, 3] ArrayExt.rotate(data, 2, 1, 3); // [4, 2, 0, 1, 3]

function shallowEqual

shallowEqual: <T>(
    a: ArrayLike<T>,
    b: ArrayLike<T>,
    fn?: (a: T, b: T) => boolean
) => boolean;

Test whether two arrays are shallowly equal.
Parameter a
The first array-like object to compare.
Parameter b
The second array-like object to compare.
Parameter fn
The comparison function to apply to the elements. It should return true if the elements are "equal". The default compares elements using strict === equality.
Returns
Whether the two arrays are shallowly equal.
#### Complexity Linear.
#### Undefined Behavior Modifying the length of the arrays while comparing.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; let d1 = [0, 3, 4, 7, 7, 9]; let d2 = [0, 3, 4, 7, 7, 9]; let d3 = [42]; ArrayExt.shallowEqual(d1, d2); // true ArrayExt.shallowEqual(d2, d3); // false

function slice

slice: <T>(array: ArrayLike<T>, options?: slice.IOptions) => T[];

Create a slice of an array subject to an optional step.

Parameter array

The array-like object of interest.

Parameter options

The options for configuring the slice.

Returns

A new array with the specified values.

Throws

An exception if the slice step is 0.

#### Complexity Linear.

#### Undefined Behavior A start, stop, or step which is non-integral.

#### Example

import { ArrayExt } from '@phosphor/algorithm';

let data = [0, 3, 4, 7, 7, 9];
ArrayExt.slice(data);                         // [0, 3, 4, 7, 7, 9]
ArrayExt.slice(data, { start: 2 });           // [4, 7, 7, 9]
ArrayExt.slice(data, { start: 0, stop: 4 });  // [0, 3, 4, 7]
ArrayExt.slice(data, { step: 2 });            // [0, 4, 7]
ArrayExt.slice(data, { step: -1 });           // [9, 7, 7, 4, 3, 0]

function upperBound

upperBound: <T, U>(
    array: ArrayLike<T>,
    value: U,
    fn: (element: T, value: U) => number,
    start?: number,
    stop?: number
) => number;

Find the index of the first element which compares > than a value.
Parameter array
The sorted array-like object to search.
Parameter value
The value to locate in the array.
Parameter fn
The 3-way comparison function to apply to the values. It should return < 0 if an element is less than a value, 0 if an element is equal to a value, or > 0 if an element is greater than a value.
Parameter start
The index of the first element in the range to be searched, inclusive. The default value is 0. Negative values are taken as an offset from the end of the array.
Parameter stop
The index of the last element in the range to be searched, inclusive. The default value is -1. Negative values are taken as an offset from the end of the array.
Returns
The index of the first element which compares > than the value, or length if there is no such element. If the computed index for stop is less than start, then the computed index for start is returned.
#### Notes The array must already be sorted in ascending order according to the comparison function.
#### Complexity Logarithmic.
#### Undefined Behavior Searching a range which is not sorted in ascending order.
A start or stop which is non-integral.
Modifying the length of the array while searching.
#### Example
import { ArrayExt } from '@phosphor/algorithm'; function numberCmp(a: number, b: number): number { return a - b; } let data = [0, 3, 4, 7, 7, 9]; ArrayExt.upperBound(data, 0, numberCmp); // 1 ArrayExt.upperBound(data, 6, numberCmp); // 3 ArrayExt.upperBound(data, 7, numberCmp); // 5 ArrayExt.upperBound(data, -1, numberCmp); // 0 ArrayExt.upperBound(data, 10, numberCmp); // 6

type MutableArrayLike

type MutableArrayLike<T> = {
    readonly length: number;
    [index: number]: T;
};

An array-like object which supports item assignment.

namespace ArrayExt.slice

namespace ArrayExt.slice {}

The namespace for the slice function statics.

interface IOptions

interface IOptions {}

The options for the slice function.

property start

start?: number;

The starting index of the slice, inclusive.
Negative values are taken as an offset from the end of the array.
The default is 0 if step > 0 else n - 1.

property step

step?: number;

The step value for the slice.
This must not be 0.
The default is 1.

property stop

stop?: number;

The stopping index of the slice, exclusive.
Negative values are taken as an offset from the end of the array.
The default is n if step > 0 else -n - 1.

namespace StringExt

namespace StringExt {}

The namespace for string-specific algorithms.

function cmp

cmp: (a: string, b: string) => number;

A 3-way string comparison function.
Parameter a
The first string of interest.
Parameter b
The second string of interest.
Returns
-1 if a < b, else 1 if a > b, else 0.

function findIndices

findIndices: (source: string, query: string, start?: number) => number[] | null;

Find the indices of characters in a source text.
Parameter source
The source text which should be searched.
Parameter query
The characters to locate in the source text.
Parameter start
The index to start the search.
Returns
The matched indices, or null if there is no match.
#### Complexity Linear on sourceText.
#### Notes In order for there to be a match, all of the characters in query **must** appear in source in the order given by query.
Characters are matched using strict === equality.

function highlight

highlight: <T>(
    source: string,
    indices: ReadonlyArray<number>,
    fn: (chunk: string) => T
) => Array<string | T>;

Highlight the matched characters of a source text.
Parameter source
The text which should be highlighted.
Parameter indices
The indices of the matched characters. They must appear in increasing order and must be in bounds of the source.
Parameter fn
The function to apply to the matched chunks.
Returns
An array of unmatched and highlighted chunks.

function matchSumOfDeltas

matchSumOfDeltas: (
    source: string,
    query: string,
    start?: number
) => IMatchResult | null;

A string matcher which uses a sum-of-deltas algorithm.
Parameter source
The source text which should be searched.
Parameter query
The characters to locate in the source text.
Parameter start
The index to start the search.
Returns
The match result, or null if there is no match. A lower score represents a stronger match.
#### Complexity Linear on sourceText.
#### Notes This scoring algorithm uses a sum-of-deltas approach to determine the score. In order for there to be a match, all of the characters in query **must** appear in source in order. The delta between the indices are summed to create the score. This means that groups of matched characters are preferred, while fragmented matches are penalized.

function matchSumOfSquares

matchSumOfSquares: (
    source: string,
    query: string,
    start?: number
) => IMatchResult | null;

A string matcher which uses a sum-of-squares algorithm.
Parameter source
The source text which should be searched.
Parameter query
The characters to locate in the source text.
Parameter start
The index to start the search.
Returns
The match result, or null if there is no match. A lower score represents a stronger match.
#### Complexity Linear on sourceText.
#### Notes This scoring algorithm uses a sum-of-squares approach to determine the score. In order for there to be a match, all of the characters in query **must** appear in source in order. The index of each matching character is squared and added to the score. This means that early and consecutive character matches are preferred, while late matches are heavily penalized.

interface IMatchResult

interface IMatchResult {}

The result of a string match function.

property indices

indices: number[];

The indices of the matched characters in the source text.
The indices will appear in increasing order.

property score

score: number;

A score which indicates the strength of the match.
The documentation of a given match function should specify whether a lower or higher score is a stronger match.

Package Files (18)

Dependencies (0)

No dependencies.

Dev Dependencies (14)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@phosphor/algorithm.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@phosphor/algorithm)

HTML

<a href="https://www.jsdocs.io/package/@phosphor/algorithm"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 2 years ago.
Package analyzed in 7484 ms.
Missing or incorrect documentation? Open an issue for this package.

@phosphor/algorithm

Install

Overview

Index

Functions

Classes

Interfaces

Type Aliases

Namespaces

Functions

function chain

Parameter objects

Returns

function each

Parameter object

Parameter fn

function empty

Returns

function enumerate

Parameter object

Parameter start

Returns

function every

Parameter object

Parameter fn

Returns

function filter

Parameter object

Parameter fn

Returns

function find

Parameter object

Parameter fn

Returns

function findIndex

Parameter object

Parameter fn

Returns

function iter

Parameter object

Returns

function iterFn

Parameter fn

Returns

function iterItems

Parameter object

Returns

function iterKeys

Parameter object

Returns

function iterValues

Parameter object

Returns

function map

Parameter object

Parameter fn

Returns

function max

Parameter object

Parameter fn

Returns

function min

Parameter object

Parameter fn

Returns

function minmax

Parameter object

Parameter fn

Returns

function once

Parameter value

Returns

function range

Parameter start

Parameter stop

Parameter step

Returns

function reduce

Parameter object

Parameter fn