Concepts: pointers

Pointers in list-toolkit.

Concepts

Pointers wrap a node reference and expose an API to remove, insert before/after, and navigate forward/backward.

Minimally supported API

Method	Description	Complexity	List	SList
list	return the list it points to	O(1)	✔	✔
node	return the node it points to	O(1)	✔	✔
nextNode	return the next node	O(1)	✔	✔
prevNode	return the previous node	O(1)	✔	✔
isPrevNodeValid()	return a boolean value indicating whether the previous node is available	O(1)	✔	✔
next()	move the pointer to the next node	O(1)	✔	✔
prev()	move the pointer to the previous node	O(1)	✔	✔

Supported by pointers of List, SList, ExtList, ExtSList, and their value-based variants.

When pointers are invalidated

A pointer becomes invalid when its node is removed from the list or moved to another list. This can happen through the list API, the pointer itself, or another pointer to the same list.

Pointers remain valid as long as the list is unmodified. When mutating via a node, that pointer updates correctly but other pointers do not — use caution.

SLL pointer notes

Many operations require the previous node, supplied at construction and updated by some operations. If unavailable, those operations throw. Check with isPrevNodeValid().

Without a valid previous node: no backward movement, no insert-before, no previous-node access.

DLL pointer notes

isPrevNodeValid() is always true.

Full API

Supported by pointers of List, SList, and their value-based variants:

Method	Description	Complexity	List	SList
isHead	return a boolean value indicating whether the pointer points to the head	O(1)	✔	✔
clone()	return a copy of the pointer	O(1)	✔	✔
removeCurrent()	remove the node the pointer points to	O(1)	✔	✔
addBefore(value)	insert a value/node before the current one	O(1)	✔	✔
addAfter(value)	insert a value/node after the current one	O(1)	✔	✔
addNodeBefore(node)	insert a node before the current one	O(1)	✔	✔
addNodeAfter(node)	insert a node after the current one	O(1)	✔	✔
insertBefore(list)	insert a compatible list before the current node	O(1)	✔	✔
insertAfter(list)	insert a compatible list after the current node	O(1)	✔	✔

External list pointers do not support these methods.