Utilities: lists

Utilities for working with different list implementations.

Legend for tables

• API
  • options - options object, which contains nextName and prevName link names with default values "next" and "prev".
    • Only doubly linked lists use prevName.
  • node - a node object in the list
  • list - a list object
  • ptr - a pointer to a node in the list
  • value - a value
  • values - an iterable that provides values
  • condition - a function that accepts a node and returns a boolean
  • adapter - a returned object with just enough properties to use as a list by some utilities
• Complexity
  • O - complexity of an operation
  • O(1) - constant time
  • O(n) - linear time proportional to the list size
  • O(k) - linear time proportional to the list/range argument size

list-utils.js

Common list operations.

import {pushValuesFront, pushValuesBack} from 'list-toolkit/list-utils.js';

Exported functions:

Function	Return value	Description	O
isValidList(list)	boolean	Check if the DLL list is valid.	O(n)
isValidSList(list)	boolean	Check if the SLL list is valid.	O(n)
pushValuesFront(list, values)	list	Add values to the front of the list sequentially.	O(k)
pushValuesBack(list, values)	list	Add values to the back of the list sequentially.	O(k)
appendValuesFront(list, values)	list	Add values to the front of the list in the given sequence.	O(k)
appendValuesBack(list, values)	list	Add values to the back of the list in the given sequence.	O(k)
addValuesBefore(ptr, values)	ptr	Add values before the pointer sequentially.	O(k)
addValuesAfter(ptr, values)	ptr	Add values after the pointer sequentially.	O(k)
insertValuesBefore(ptr, values)	ptr	Insert values before the pointer in the given sequence.	O(k)
insertValuesAfter(ptr, values)	ptr	Insert values after the pointer in the given sequence.	O(k)
findNodeBy(list, condition)	node or null	Find the first node that satisfies the condition.	O(n)
findPtrBy(list, condition)	ptr or null	Find the first pointer that satisfies the condition.	O(n)
removeNodeBy(list, condition)	node or null	Remove the first node that satisfies the condition.	O(n)
backPusher(ExtListClass, options)	adapter	Create a back pusher.	O(1)
frontPusher(ExtListClass, options)	adapter	Create a front pusher.	O(1)

isValidList() / isValidSList() traverse the list verifying link integrity. Return false on the first inconsistency.

pushValuesFront() / pushValuesBack() push values sequentially. pushValuesFront() reverses order. appendValuesFront() / appendValuesBack() preserve iterable order (appendValuesFront() buffers into an array first). appendValuesBack() may be more efficient than pushValuesBack() when the list supports bulk append.

addValuesBefore() / addValuesAfter() are pointer equivalents of pushValuesBack() / pushValuesFront(). insertValuesBefore() / insertValuesAfter() are pointer equivalents of appendValuesBack() / appendValuesFront().

findNodeBy() / findPtrBy() return the first node (or pointer) where condition(node) is true, or null. removeNodeBy() removes and returns that node.

backPusher() / frontPusher() create adapter objects for building external headless lists using hosted-list push semantics. The returned object exposes:

• nextName, prevName (optional for SLL)
• releaseList() — returns the ExtListClass instance and clears the internal list
• pushBackNode(node) (back pusher) or pushFrontNode(node) (front pusher)

Exports

All documented functions are exported by their names.