Copyright 2018 Jared Boice (MIT License / Open Source)

List-Runner - Summarized Documentation

"Within Cells Interlinked"

get the full documentation at gitHub.

Donations - Bitcoin: 19XgiRojJnv9VDhyW9HmF6oKQeVc7k9McU

(use this address until 2022)

this codebase has survived 65 unit tests

Description

List-Runner is a lightweight linked-list implementation that offers both Singly (next) and Doubly data structures (next and previous).

Nodes are referred to as cells and the list is referred to as a stem.

Singly cell instances have getNext() and setNext() methods. Doubly cell instances additionally have getPrev() and setPrev() methods. All other operations are controlled by the Stem instance. There are two types of stems, one for singly data structures and one for doubly data structures.

Install, Import & Instantiate

Install

npm install --save list-runner

Import

importing the commonly needed classes

import { CellSingly, CellDoubly, StemSingly, StemDoubly } from 'list-runner';

importing the constants

import { SENTINEL, CELL, SINGLY, DOUBLY } from 'list-runner';

importing the sidekick functions

import { initializeStem, findForward, findBackward, runForward, runBackward, countForward, countBackward } from 'list-runner';

importing less commonly needed classes

import { SentinelSingly, SentinelDoubly } from 'list-runner';

Instantiate

solo instantiation

const cell = new CellDoubly();    
const stem = new StemDoubly(cell);

connective instantiation

const cell1 = new CellDoubly();    
const cell2 = new CellDoubly();    
const cell3 = new CellDoubly();    
const stemCells = [cell1, cell2, cell3];    
const structureType = DOUBLY; // imported constant    
const stem = initializeStem(stemCells, structureType);

code examples: stem and cell classes

// assume the following are not strings
const baseline = 'some arbitrary cell on the stem'; // substitute a cell on the stem
const cell = 'some new cell'; // substitute a newly instantiated cell
const cells = 'an array of cells'; // substitute an array of unlinked cells

/* CELL OPERATIONS */
const nextCell = cell.getNext();
const prevCell = cell.getPrev(); // only DOUBLY data-structure

/* STEM OPERATIONS */
const head = stem.getHead();
const tail = stem.getTail(); // only DOUBLY data-structure
insert(cell, baseline); // returns true || false based on success
extract(baseline); // returns extracted cell || false based on success
unshift(cell); // returns true || false based on success
shift(); // returns extracted cell || false based on success
push(cell); // only DOUBLY data-structure / returns true || false based on success
pop(); // only DOUBLY data-structure / returns extracted cell || false based on success
replace(cell, baseline); // returns true || false based on success
delete(baseline); // returns true || false based on success

code examples: sidekick functions

// assume the following are not strings
const comparator = 'a callback function that returns true when the right cell is found'; // receives each cell
const callBackParams = 'any kind of parameters that you want to pass to the callBack function';
const callBack = 'a custom callback function that will receive each cell from a loop and also callBackParams'; // receives each cell and callBackParams

/* SIDEKICK FUNCTIONS */
interlink(cells);
const foundCell1 = findForward(baseline, comparator);
const foundCell2 = findBackward(baseline, comparator);
// lastCellInLoop1 will be cell.type === SENTINEL if it loops to the edge of the stem (by not triggering a custom short-circuit condition)
const lastCellInLoop1 = runForward(baseline, callBack, callBackParams);
const lastCellInLoop2 = runBackward(baseline, callBack, callBackParams);
const totalCount1 = countForward(baseline);
const totalCount2 = countBackward(baseline);

/* findForward / findBackward comparator callback examples */

// standard
export const findComparator1 = (cell) => {
  return cell.id === 'KD6-3.7';
};

// curried
export const findComparator2 = (id) => {
    return (cell) => {
        return cell.id === id;
    };
};

const myComparator = findComparator2('KD6-3.7');
const foundCell3 = findForward(baseline, myComparator);

/* runForward / runBackward callback examples */

// standard
export const runCallBack1 = (cell, callBackParams) => {
    // do stuff
    const continueLoop = cell.id !== id;
    return continueLoop;
};

// curried
export const runCallBack2 = (id) => {
    return (cell, callBackParams) => {
      // do stuff
      const continueLoop = cell.id !== id;
      return continueLoop;
    };
};

const myCallBack = runCallBack2('KD6-3.7', 'any other arbitrary parameters');
// lastCellInLoop3 will be cell.type === SENTINEL if it loops to the edge of the stem (by not triggering a custom short-circuit condition)
const lastCellInLoop3 = runForward(baseline, myCallBack, callBackParams);