Concepts: value list API

Conceptual API for value lists.

Concepts

List and SList inject link properties onto objects. To store primitives or avoid modifying objects, use value lists that wrap values in ValueNode.

Lists and their value counterparts:

List	Value list
List	ValueList
SList	ValueSList
ExtList	ExtValueList
ExtSList	ExtValueSList

All use ValueNode, which stores the payload in its value property.

Hosted value list methods:

Method	Description	Complexity	ValueList	ValueSList
pushFront(value)	add a new node at the beginning	O(1)	✔	✔
pushBack(value)	add a new node at the end	O(1)	✔	✔
popFront()	remove and return the value of first node	O(1)	✔	✔
popBack()	remove and return the value of last node	O(1)	✔

External value list methods:

Method	Description	Complexity	ExtValueList	ExtValueSList
addBefore(value)	add a new node before the current head	O(1)	✔
addAfter(value)	add a new node after the current head	O(1)	✔	✔

Common value list methods:

Method	Description	Complexity
clone()	shallow clone (a new list with the same nodes / values)	O(n)
adoptValue(value)	adopt a value by creating a value node	O(1)
[Symbol.iterator]()	create a value iterator	O(1)
getValueIterator()	create a value iterator	O(1)
getReverseValueIterator()	create a reversed value iterator	O(1)

ValueSList and ExtValueSList don't support getReverseValueIterator().

Short aliases:

Method	Alias
push(value)	pushBack(value)
pop()	popFront()
add(value)	addAfter(value)
getIterator()	getValueIterator()
getReverseIterator()	getReverseValueIterator()

Adopting a value

adoptValue(value) wraps the value in a new ValueNode unless it already is one, in which case it delegates to adoptNode(node).

Aliasing for node-based lists

Node-based lists also expose value methods, aliased to their node counterparts:

Method	Alias
pushFront(value)	pushFrontNode(node)
pushBack(value)	pushBackNode(node)
popFront()	popFrontNode()
popBack()	popBackNode()
addBefore(value)	addNodeBefore(node)
addAfter(value)	addNodeAfter(node)
adoptValue(value)	adoptNode(node)
getValueIterator()	getNodeIterator()
getReverseValueIterator()	getReverseNodeIterator()