org.kynosarges.tektosyne

Class NodeList<T>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

java.util.AbstractSequentialList<T>

org.kynosarges.tektosyne.NodeList<T>

Type Parameters:

T - the type of all elements in the NodeList

All Implemented Interfaces:

java.lang.Iterable<T>, java.util.Collection<T>, java.util.Deque<T>, java.util.List<T>, java.util.Queue<T>

public class NodeList<T>
extends java.util.AbstractSequentialList<T>
implements java.util.Deque<T>

Provides a generic doubly-linked list that exposes its node structure. Provides a generic doubly-linked list like the standard LinkedList, but publicly exposes its NodeList.Node structure. This allows for O(1) navigation, insertion, and removal at arbitrary positions for which NodeList.Node instances have already been obtained, rather than performing an O(n) lookup each time.

Java Collections Framework features, including index access and direct access to element values stored in NodeList.Node, are provided by implementing Deque and extending AbstractSequentialList. Iterators “fail fast” by checking for concurrent modifications by non-iterator methods.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NodeList.Node<T> Provides a generic node within a NodeList.

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

Constructors

Constructor and Description
NodeList() Creates an empty NodeList.
NodeList(java.util.Collection<? extends T> collection) Creates a NodeList containing the elements of the specified Collection.

Method Summary

Modifier and Type	Method and Description
void	add(int index, T value) Adds the specified element at the specified position in the NodeList.
boolean	add(T value) Adds the specified element at the end of the NodeList.
void	addAfter(NodeList.Node<T> node, T value) Adds the specified element after the specified NodeList.Node.
boolean	addAll(int index, java.util.Collection<? extends T> collection) Adds all specified elements at the specified position in the NodeList.
void	addBefore(NodeList.Node<T> node, T value) Adds the specified element before the specified NodeList.Node.
void	addFirst(T value) Adds the specified element at the start of the NodeList.
void	addLast(T value) Adds the specified element at the end of the NodeList.
void	clear() Removes all elements from the NodeList.
boolean	contains(java.lang.Object obj) Determines whether the NodeList contains the specified element.
int	countNodes() Counts the number of elements in the NodeList.
java.util.Iterator<T>	descendingIterator() Returns an Iterator over the elements in the NodeList in reverse order, starting after the last element.
T	element() Retrieves, but does not remove, the first element in the NodeList.
NodeList.Node<T>	findFirstNode(T value) Finds the first NodeList.Node in the NodeList that contains the specified element.
NodeList.Node<T>	findLastNode(T value) Finds the last NodeList.Node in the NodeList that contains the specified element.
NodeList.Node<T>	first() Gets the first NodeList.Node in the NodeList.
T	get(int index) Gets the element at the specified position in the NodeList.
T	getFirst() Retrieves, but does not remove, the first element in the NodeList.
T	getLast() Retrieves, but does not remove, the last element in the NodeList.
NodeList.Node<T>	getNode(int index) Gets the NodeList.Node at the specified position in the NodeList.
boolean	isEmpty() Indicates whether the NodeList is empty.
NodeList.Node<T>	last() Gets the last NodeList.Node in the NodeList.
java.util.ListIterator<T>	listIterator(int index) Returns a ListIterator over the elements in the NodeList, starting at the specified position.
boolean	offer(T value) Adds the specified element at the end of the NodeList.
boolean	offerFirst(T value) Adds the specified element at the start of the NodeList.
boolean	offerLast(T value) Adds the specified element at the end of the NodeList.
T	peek() Retrieves, but does not remove, the first element in the NodeList.
T	peekFirst() Retrieves, but does not remove, the first element in the NodeList.
T	peekLast() Retrieves, but does not remove, the last element in the NodeList.
T	poll() Retrieves and removes the first element in the NodeList.
T	pollFirst() Retrieves and removes the first element in the NodeList.
T	pollLast() Retrieves and removes the last element in the NodeList.
T	pop() Retrieves and removes the first element from the NodeList.
void	push(T value) Adds the specified element at the start of the NodeList.
T	remove() Retrieves and removes the first element from the NodeList.
T	remove(int index) Removes the element at the specified position in the NodeList.
void	remove(NodeList.Node<T> node) Removes the specified NodeList.Node from the NodeList.
boolean	remove(java.lang.Object obj) Removes the first occurrence of the specified element from the NodeList.
T	removeFirst() Retrieves and removes the first element from the NodeList.
boolean	removeFirstOccurrence(java.lang.Object obj) Removes the first occurrence of the specified element from the NodeList.
T	removeLast() Retrieves and removes the last element from the NodeList.
boolean	removeLastOccurrence(java.lang.Object obj) Removes the last occurrence of the specified element from the NodeList.
protected void	removeRange(int fromIndex, int toIndex) Removes all elements within the specified index range from the NodeList.
T	set(int index, T value) Sets the specified position in the NodeList to the specified element.
int	size() Gets the number of elements in the NodeList.

Methods inherited from class java.util.AbstractSequentialList

iterator

Methods inherited from class java.util.AbstractList

equals, hashCode, indexOf, lastIndexOf, listIterator, subList

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Deque

iterator

Methods inherited from interface java.util.Collection

addAll, containsAll, equals, hashCode, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.List

addAll, containsAll, removeAll, replaceAll, retainAll, sort, spliterator, toArray, toArray

Constructor Detail

NodeList

public NodeList()

Creates an empty NodeList.

NodeList

public NodeList(java.util.Collection<? extends T> collection)

Creates a NodeList containing the elements of the specified Collection. All collection elements are added in iteration order.

Parameters:

collection - the Collection whose elements to add

Throws:

java.lang.NullPointerException - if collection is null or contains any null elements

Method Detail

first

public NodeList.Node<T> first()

Gets the first NodeList.Node in the NodeList. This is an O(1) operation.

Returns:

the first NodeList.Node in the NodeList, or null if the NodeList is empty

last

public NodeList.Node<T> last()

Gets the last NodeList.Node in the NodeList. This is an O(1) operation.

Returns:

the last NodeList.Node in the NodeList, or null if the NodeList is empty

addAfter

public void addAfter(NodeList.Node<T> node,
                     T value)

Adds the specified element after the specified NodeList.Node. This is an O(1) operation.

Parameters:

node - the NodeList.Node after which to add value

value - the element to add

Throws:

java.lang.IllegalArgumentException - if node is not part of the NodeList

java.lang.NullPointerException - if node or value is null

addBefore

public void addBefore(NodeList.Node<T> node,
                      T value)

Adds the specified element before the specified NodeList.Node. This is an O(1) operation.

Parameters:

node - the NodeList.Node before which to add value

value - the element to add

Throws:

java.lang.IllegalArgumentException - if node is not part of the NodeList

java.lang.NullPointerException - if node or value is null

countNodes

public int countNodes()

Counts the number of elements in the NodeList. This is an O(n) operation, counting each NodeList.Node from first() to last(). Intended for testing the internally tracked size().

Returns:

the number of elements in the NodeList

findFirstNode

public NodeList.Node<T> findFirstNode(T value)

Finds the first NodeList.Node in the NodeList that contains the specified element. Searches the NodeList from first() to last(), using Object.equals(java.lang.Object) to compare elements. This is an O(n) operation.

Parameters:

value - the element to search

Returns:

the first NodeList.Node in the NodeList whose NodeList.Node.value() equals value, or null if no such NodeList.Node exists

Throws:

java.lang.NullPointerException - if value is null

findLastNode

public NodeList.Node<T> findLastNode(T value)

Finds the last NodeList.Node in the NodeList that contains the specified element. Searches the NodeList from last() to first(), using Object.equals(java.lang.Object) to compare elements. This is an O(n) operation.

Parameters:

value - the element to search

Returns:

the last NodeList.Node in the NodeList whose NodeList.Node.value() equals value, or null if no such NodeList.Node exists

Throws:

java.lang.NullPointerException - if value is null

getNode

public NodeList.Node<T> getNode(int index)

Gets the NodeList.Node at the specified position in the NodeList. Uses the internally tracked size() to search from last() rather than first() if index is greater than size()/2. This is an O(min(index, size() – index)) operation.

Parameters:

index - the index of the NodeList.Node to get

Returns:

the NodeList.Node at index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero, or equal to or greater than size()

remove

public void remove(NodeList.Node<T> node)

Removes the specified NodeList.Node from the NodeList. This is an O(1) operation.

Parameters:

node - the NodeList.Node to remove

Throws:

java.lang.IllegalArgumentException - if node is not part of the NodeList

java.lang.NullPointerException - if node is null

add

public boolean add(T value)

Adds the specified element at the end of the NodeList. Calls addLast(T) with value. This is an O(1) operation.

Specified by:

add in interface java.util.Collection<T>

Specified by:

add in interface java.util.Deque<T>

Specified by:

add in interface java.util.List<T>

Specified by:

add in interface java.util.Queue<T>

Overrides:

add in class java.util.AbstractList<T>

Parameters:

value - the element to add

Throws:

java.lang.NullPointerException - if value is null

add

public void add(int index,
                T value)

Adds the specified element at the specified position in the NodeList. This is an O(1) operation if index equals size() in which case value is added at the end. Otherwise, this is an O(index) operation, as described in getNode(int).

Specified by:

add in interface java.util.List<T>

Overrides:

add in class java.util.AbstractSequentialList<T>

Parameters:

index - the index at which to add value

value - the element to add at index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than size()

java.lang.NullPointerException - if value is null

addAll

public boolean addAll(int index,
                      java.util.Collection<? extends T> collection)

Adds all specified elements at the specified position in the NodeList. This is an O(m) operation if index equals size() in which case collection is added at the end. Otherwise, this is an O(index + m) operation, as described in getNode(int). Here m represents the size of the collection. All collection elements are added in iteration order.

Specified by:

addAll in interface java.util.List<T>

Overrides:

addAll in class java.util.AbstractSequentialList<T>

Parameters:

index - the index at which to add collection

collection - the Collection to add at index

Returns:

true if collection contains any elements, else false

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than size()

java.lang.NullPointerException - if collection is null or contains any null elements

clear

public void clear()

Removes all elements from the NodeList. Does nothing if the NodeList is already empty. Otherwise this is an O(n) operation, as all node links are set to null.

Specified by:

clear in interface java.util.Collection<T>

Specified by:

clear in interface java.util.List<T>

Overrides:

clear in class java.util.AbstractList<T>

contains

public boolean contains(java.lang.Object obj)

Determines whether the NodeList contains the specified element. Attempts to cast obj to T, then calls findFirstNode(T) and succeeds exactly if a NodeList.Node was found. This is an O(n) operation.

Specified by:

contains in interface java.util.Collection<T>

Specified by:

contains in interface java.util.Deque<T>

Specified by:

contains in interface java.util.List<T>

Overrides:

contains in class java.util.AbstractCollection<T>

Parameters:

obj - the element to examine

Returns:

true if obj was found, else false

Throws:

java.lang.ClassCastException - if obj cannot be cast to T

java.lang.NullPointerException - if obj is null

get

public T get(int index)

Gets the element at the specified position in the NodeList. This is an O(index) operation, as described in getNode(int).

Specified by:

get in interface java.util.List<T>

Overrides:

get in class java.util.AbstractSequentialList<T>

Parameters:

index - the index of the element to get

Returns:

the element at index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero, or equal to or greater than size()

isEmpty

public boolean isEmpty()

Indicates whether the NodeList is empty. This is an O(1) operation.

Specified by:

isEmpty in interface java.util.Collection<T>

Specified by:

isEmpty in interface java.util.List<T>

Overrides:

isEmpty in class java.util.AbstractCollection<T>

Returns:

true if the NodeList is empty, else false

listIterator

public java.util.ListIterator<T> listIterator(int index)

Returns a ListIterator over the elements in the NodeList, starting at the specified position. The ListIterator is positioned after the last element if index equals size(). Otherwise, this is an O(index) operation, as described in getNode(int).

Specified by:

listIterator in interface java.util.List<T>

Specified by:

listIterator in class java.util.AbstractSequentialList<T>

Parameters:

index - the index of the first element to be returned by ListIterator.next()

Returns:

a ListIterator for the NodeList, starting at index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than size()

remove

public T remove(int index)

Removes the element at the specified position in the NodeList. This is an O(index) operation, as described in getNode(int).

Specified by:

remove in interface java.util.List<T>

Overrides:

remove in class java.util.AbstractSequentialList<T>

Parameters:

index - the index of the element to remove

Returns:

the removed element at index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero, or equal to or greater than size()

remove

public boolean remove(java.lang.Object obj)

Removes the first occurrence of the specified element from the NodeList. Returns removeFirstOccurrence(java.lang.Object). This is an O(n) operation.

Specified by:

remove in interface java.util.Collection<T>

Specified by:

remove in interface java.util.Deque<T>

Specified by:

remove in interface java.util.List<T>

Overrides:

remove in class java.util.AbstractCollection<T>

Parameters:

obj - the element to remove

Returns:

true if obj was found and removed, else false

Throws:

java.lang.ClassCastException - if obj cannot be cast to T

java.lang.NullPointerException - if obj is null

removeRange

protected void removeRange(int fromIndex,
                           int toIndex)

Removes all elements within the specified index range from the NodeList. This is an O(index) operation, as described in getNode(int), followed by an O(m) operation where m is the number of elements to remove.

Overrides:

removeRange in class java.util.AbstractList<T>

Parameters:

fromIndex - the index of the first element to remove (inclusive)

toIndex - the index of the last element to remove (exclusive)

Throws:

java.lang.IndexOutOfBoundsException - if fromIndex or toIndex is less than zero or greater than size()

set

public T set(int index,
             T value)

Sets the specified position in the NodeList to the specified element. This is an O(index) operation, as described in getNode(int). Calling set will not cause existing iterators to throw ConcurrentModificationException as it involves no structural change.

Specified by:

set in interface java.util.List<T>

Overrides:

set in class java.util.AbstractSequentialList<T>

Parameters:

index - the index at which to store value

value - the element to store at index

Returns:

the element previously stored at index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero, or equal to or greater than size()

java.lang.NullPointerException - if value is null

size

public int size()

Gets the number of elements in the NodeList. This is an O(1) operation, as the NodeList keeps a running count of its elements.

Specified by:

size in interface java.util.Collection<T>

Specified by:

size in interface java.util.Deque<T>

Specified by:

size in interface java.util.List<T>

Specified by:

size in class java.util.AbstractCollection<T>

Returns:

the number of elements in the NodeList

addFirst

public void addFirst(T value)

Adds the specified element at the start of the NodeList. This is an O(1) operation.

Specified by:

addFirst in interface java.util.Deque<T>

Parameters:

value - the element to add

Throws:

java.lang.NullPointerException - if value is null

addLast

public void addLast(T value)

Adds the specified element at the end of the NodeList. This is an O(1) operation.

Specified by:

addLast in interface java.util.Deque<T>

Parameters:

value - the element to add

Throws:

java.lang.NullPointerException - if value is null

descendingIterator

public java.util.Iterator<T> descendingIterator()

Returns an Iterator over the elements in the NodeList in reverse order, starting after the last element. This is an O(1) operation.

Specified by:

descendingIterator in interface java.util.Deque<T>

Returns:

an Iterator for the NodeList, in reverse order and starting after the last element

element

public T element()

Retrieves, but does not remove, the first element in the NodeList. Returns getFirst(). This is an O(1) operation.

Specified by:

element in interface java.util.Deque<T>

Specified by:

element in interface java.util.Queue<T>

Returns:

the first element in the NodeList

Throws:

java.util.NoSuchElementException - if the NodeList is empty

getFirst

public T getFirst()

Retrieves, but does not remove, the first element in the NodeList. This is an O(1) operation.

Specified by:

getFirst in interface java.util.Deque<T>

Returns:

the first element in the NodeList

Throws:

java.util.NoSuchElementException - if the NodeList is empty

getLast

public T getLast()

Retrieves, but does not remove, the last element in the NodeList. This is an O(1) operation.

Specified by:

getLast in interface java.util.Deque<T>

Returns:

the last element in the NodeList

Throws:

java.util.NoSuchElementException - if the NodeList is empty

offer

public boolean offer(T value)

Adds the specified element at the end of the NodeList. Calls addLast(T) with value. Always succeeds as the NodeList is not capacity-restricted. This is an O(1) operation.

Specified by:

offer in interface java.util.Deque<T>

Specified by:

offer in interface java.util.Queue<T>

Parameters:

value - the element to add

Throws:

java.lang.NullPointerException - if value is null

offerFirst

public boolean offerFirst(T value)

Adds the specified element at the start of the NodeList. Calls addFirst(T) with value. Always succeeds as the NodeList is not capacity-restricted. This is an O(1) operation.

Specified by:

offerFirst in interface java.util.Deque<T>

Parameters:

value - the element to add

Throws:

java.lang.NullPointerException - if value is null

offerLast

public boolean offerLast(T value)

Adds the specified element at the end of the NodeList. Calls addLast(T) with value. Always succeeds as the NodeList is not capacity-restricted. This is an O(1) operation.

Specified by:

offerLast in interface java.util.Deque<T>

Parameters:

value - the element to add

Throws:

java.lang.NullPointerException - if value is null

peek

public T peek()

Retrieves, but does not remove, the first element in the NodeList. Returns peekFirst(). This is an O(1) operation.

Specified by:

peek in interface java.util.Deque<T>

Specified by:

peek in interface java.util.Queue<T>

Returns:

the first element in the NodeList, or null if the NodeList is empty

peekFirst

public T peekFirst()

Retrieves, but does not remove, the first element in the NodeList. This is an O(1) operation.

Specified by:

peekFirst in interface java.util.Deque<T>

Returns:

the first element in the NodeList, or null if the NodeList is empty

peekLast

public T peekLast()

Retrieves, but does not remove, the last element in the NodeList. This is an O(1) operation.

Specified by:

peekLast in interface java.util.Deque<T>

Returns:

the last element in the NodeList, or null if the NodeList is empty

poll

public T poll()

Retrieves and removes the first element in the NodeList. Returns pollFirst(). This is an O(1) operation.

Specified by:

poll in interface java.util.Deque<T>

Specified by:

poll in interface java.util.Queue<T>

Returns:

the removed first element in the NodeList, or null if the NodeList is empty

pollFirst

public T pollFirst()

Retrieves and removes the first element in the NodeList. This is an O(1) operation.

Specified by:

pollFirst in interface java.util.Deque<T>

Returns:

the removed first element in the NodeList, or null if the NodeList is empty

pollLast

public T pollLast()

Retrieves and removes the last element in the NodeList. This is an O(1) operation.

Specified by:

pollLast in interface java.util.Deque<T>

Returns:

the removed last element in the NodeList, or null if the NodeList is empty

pop

public T pop()

Retrieves and removes the first element from the NodeList. Returns removeFirst(). This is an O(1) operation.

Specified by:

pop in interface java.util.Deque<T>

Returns:

the removed first element in the NodeList

Throws:

java.util.NoSuchElementException - if the NodeList is empty

push

public void push(T value)

Adds the specified element at the start of the NodeList. Calls addFirst(T) with value. This is an O(1) operation.

Specified by:

push in interface java.util.Deque<T>

Parameters:

value - the element to add

Throws:

java.lang.NullPointerException - if value is null

remove

public T remove()

Retrieves and removes the first element from the NodeList. Returns removeFirst(). This is an O(1) operation.

Specified by:

remove in interface java.util.Deque<T>

Specified by:

remove in interface java.util.Queue<T>

Returns:

the removed first element in the NodeList

Throws:

java.util.NoSuchElementException - if the NodeList is empty

removeFirst

public T removeFirst()

Retrieves and removes the first element from the NodeList. This is an O(1) operation.

Specified by:

removeFirst in interface java.util.Deque<T>

Returns:

the removed first element in the NodeList

Throws:

java.util.NoSuchElementException - if the NodeList is empty

removeFirstOccurrence

public boolean removeFirstOccurrence(java.lang.Object obj)

Removes the first occurrence of the specified element from the NodeList. Attempts to cast obj to T, then calls findFirstNode(T) and finally remove(org.kynosarges.tektosyne.NodeList.Node<T>) on success. This is an O(n) operation.

Specified by:

removeFirstOccurrence in interface java.util.Deque<T>

Parameters:

obj - the element to remove

Returns:

true if obj was found and removed, else false

Throws:

java.lang.ClassCastException - if obj cannot be cast to T

java.lang.NullPointerException - if obj is null

removeLast

public T removeLast()

Retrieves and removes the last element from the NodeList. This is an O(1) operation.

Specified by:

removeLast in interface java.util.Deque<T>

Returns:

the removed last element in the NodeList

Throws:

java.util.NoSuchElementException - if the NodeList is empty

removeLastOccurrence

public boolean removeLastOccurrence(java.lang.Object obj)

Removes the last occurrence of the specified element from the NodeList. Attempts to cast obj to T, then calls findLastNode(T) and finally remove(org.kynosarges.tektosyne.NodeList.Node<T>) on success. This is an O(n) operation.

Specified by:

removeLastOccurrence in interface java.util.Deque<T>

Parameters:

obj - the element to remove

Returns:

true if obj was found and removed, else false

Throws:

java.lang.ClassCastException - if obj cannot be cast to T

java.lang.NullPointerException - if obj is null