phosphor-arrays

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+

Bundle for the Browser

Follow the package install instructions first.

npm install --save-dev browserify
browserify myapp.js -o mybundle.js

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
let 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
let 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
let 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
let 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
let 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
let 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
let 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
let 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
let 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
let 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
let 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
let 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
let 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
let 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