phosphor-arrays

A collection of array utility functions.

API Docs

Package Install

Prerequisites

• node

npm install --save phosphor-arrays

Source Build

Prerequisites

• git
• node

git clone https://github.com/phosphorjs/phosphor-arrays.git
cd phosphor-arrays
npm install

Rebuild

npm run clean
npm run build

Run Tests

Follow the source build instructions first.

npm test

Build Docs

Follow the source build instructions first.

npm run docs

Navigate to docs/index.html.

Supported Runtimes

The runtime versions which are currently known to work are listed below. Earlier versions may also work, but come with no guarantees.

• Node 0.12.7+
• IE 11+
• Firefox 32+
• Chrome 38+

Usage Examples

Note: This module is fully compatible with Node/Babel/ES6/ES5. Simply omit the type declarations when using a language other than TypeScript.

import * as arrays from 'phosphor-arrays';


function logger(value: number): void {
  console.log(value);
}


// for-each with optional start index and wrap around
var data = [1, 2, 3, 4];
arrays.forEach(data, logger);           // logs 1, 2, 3, 4
arrays.forEach(data, logger, 2);        // logs 3, 4
arrays.forEach(data, logger, 2, true);  // logs 3, 4, 1, 2
arrays.forEach(data, (v, i) => {        // 2
  if (v === 3) return i;
});


// reverse for-each with optional start index and wrap around
var data = [1, 2, 3, 4];
arrays.rforEach(data, logger);           // logs 4, 3, 2, 1
arrays.rforEach(data, logger, 2);        // logs 3, 2, 1
arrays.rforEach(data, logger, 2, true);  // logs 3, 2, 1, 4
arrays.rforEach(data, (v, i) => {        // 2
  if (v === 3) return i;
});


function isEven(value: number): boolean {
  return value % 2 === 0;
}


// find-index with optional start index and wrap around
var data = [1, 2, 3, 4, 3, 2, 1];
arrays.findIndex(data, isEven);           // 1
arrays.findIndex(data, isEven, 4);        // 5
arrays.findIndex(data, isEven, 6);        // -1
arrays.findIndex(data, isEven, 6, true);  // 1


// reverse find-index with optional start index and wrap around
var data = [1, 2, 3, 4, 3, 2, 1];
arrays.rfindIndex(data, isEven);           // 5
arrays.rfindIndex(data, isEven, 4);        // 3
arrays.rfindIndex(data, isEven, 0);        // -1
arrays.rfindIndex(data, isEven, 0, true);  // 5


// find-value with optional start index and wrap around
var data = [1, 2, 3, 4, 3, 2, 1];
arrays.find(data, isEven);           // 2
arrays.find(data, isEven, 4);        // 2
arrays.find(data, isEven, 6);        // undefined
arrays.find(data, isEven, 6, true);  // 2


// reverse find-value with optional start index and wrap around
var data = [1, 2, 3, 4, 3, 2, 1];
arrays.rfind(data, isEven);           // 2
arrays.rfind(data, isEven, 4);        // 4
arrays.rfind(data, isEven, 0);        // undefined
arrays.rfind(data, isEven, 0, true);  // 2


// insert value at a specified index
var data = [0, 1, 2, 3, 4];
arrays.insert(data, 0, 12);  // 0
arrays.insert(data, 3, 42);  // 3
arrays.insert(data, -9, 9);  // 0
arrays.insert(data, 12, 8);  // 8
console.log(data);           // [9, 12, 0, 1, 42, 2, 3, 4, 8]


// move value from one index to another
var data = [0, 1, 2, 3, 4];
arrays.move(data, 1, 2);   // true
arrays.move(data, -1, 0);  // false
arrays.move(data, 4, 2);   // true
arrays.move(data, 10, 0);  // false
console.log(data);         // [0, 2, 4, 1, 3]


// remove value at a specified index
var data = [0, 1, 2, 3, 4];
arrays.removeAt(data, 1);   // 1
arrays.removeAt(data, 3);   // 4
arrays.removeAt(data, 10);  // undefined
console.log(data);          // [0, 2, 3]


// remove first occurrence of a value
var data = [0, 1, 2, 3, 4];
arrays.remove(data, 1);  // 1
arrays.remove(data, 3);  // 2
arrays.remove(data, 7);  // -1
console.log(data);       // [0, 2, 4]


// reverse items subject to an optional range
var data = [0, 1, 2, 3, 4];
arrays.reverse(data, 1, 3);    // [0, 3, 2, 1, 4]
arrays.reverse(data, 3);       // [0, 3, 2, 4, 1]
arrays.reverse(data);          // [1, 4, 2, 3, 0]


// rotate items by positive or negative delta
var data = [0, 1, 2, 3, 4];
arrays.rotate(data, 2);    // [2, 3, 4, 0, 1]
arrays.rotate(data, -2);   // [0, 1, 2, 3, 4]
arrays.rotate(data, 10);   // [0, 1, 2, 3, 4]
arrays.rotate(data, 9);    // [4, 0, 1, 2, 3]


function numberCmp(a: number, b: number): number {
  return a < b;
}


// binary search for first item >= to a value
var data = [0, 3, 4, 7, 7, 9];
arrays.lowerBound(data, 0, numberCmp);   // 0
arrays.lowerBound(data, 6, numberCmp);   // 3
arrays.lowerBound(data, 7, numberCmp);   // 3
arrays.lowerBound(data, -1, numberCmp);  // 0
arrays.lowerBound(data, 10, numberCmp);  // 6


// binary search for first item > than a value
var data = [0, 3, 4, 7, 7, 9];
arrays.upperBound(data, 0, numberCmp);   // 1
arrays.upperBound(data, 6, numberCmp);   // 3
arrays.upperBound(data, 7, numberCmp);   // 5
arrays.upperBound(data, -1, numberCmp);  // 0
arrays.upperBound(data, 10, numberCmp);  // 6