Module org.tquadrat.foundation.util

Package org.tquadrat.foundation.util

Interface HeadTailList<T>

Type Parameters:

T - The element type of the list.

All Superinterfaces:

Iterable<T>

All Known Implementing Classes:

HeadTailListImpl

@ClassVersion(sourceVersion="$Id: HeadTailList.java 1060 2023-09-24 19:21:40Z tquadrat $")
@API(status=STABLE,
     since="0.0.4")
public sealed interface HeadTailList<T>
extends Iterable<T>
permits HeadTailListImpl<T>

A HeadTailList is an unmodifiable list data structure.

Each modifying operation on it will create a new instance of the list, leaving the original list one unchanged.

But only the list itself is copied, not the entries in it – these are shared amongst all copies of the list. Consequently changes to the data stored in the list should be avoided.

To create a new instance of HeadTailList, call one of

• empty() for an empty list
• from(Object[]) to initialise the list with some elements
• from(Collection) to initialise the new list from a Collection

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: HeadTailList.java 1060 2023-09-24 19:21:40Z tquadrat $

Since:

0.0.4

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.util.HeadTailList"

⁠

Method Summary

Modifier and Type	Method	Description
HeadTailList<T>	add(T element)	Returns a new list with the given element as the head, and this list as the tail.
default HeadTailList<T>	append(Collection<T> list)	Returns a new list where the given list is appended to the end of this list.
default HeadTailList<T>	append(HeadTailList<T> list)	Returns a new list where the given list is appended to the end of this list.
default boolean	contains(T element)	Checks whether the list contains an element that is equal to the given one.
static <E> HeadTailList<E>	empty()	Returns an empty list.
boolean	equals(Object o)
void	forEachReverse(Consumer<? super T> action)	Does the same as Iterable.forEach(Consumer), but starting with last element first.
static <E> HeadTailList<E>	from(E... elements)	Creates a new list from the given elements.
static <E> HeadTailList<E>	from(Collection<E> source)	Creates a new list from the given Collection.
default T	get(int index)	Returns the element that is identified by the given index
int	hashCode()
Optional<T>	head()	Returns the head of the list.
boolean	isEmpty()	Checks whether the list is empty.
Iterator<T>	iterator()
default HeadTailList<T>	merge(HeadTailList<? extends T> list)	Returns a new list where the given list is merged into this list.
default HeadTailList<T>	prepend(Collection<T> list)	Returns a new list where the entries of the given list are placed before the first entry of this list.
default HeadTailList<T>	prepend(HeadTailList<T> list)	Returns a new list where this list is appended to the end of the given list.
default HeadTailList<T>	remove(T element)	Returns a copy of this list that does not contain the given element.
default HeadTailList<T>	replaceHead(T newHead)	Returns a new copy of this list where the head element is replaced by the given element.
default HeadTailList<T>	revert()	Revert the list; that means that the sequence of the elements in the new list is in reverse order that in this one.
int	size()	Returns the size of the list.
Stream<T>	stream()	Returns a Stream that is backed by this list.
HeadTailList<T>	tail()	Returns the tail of the list.
Object[]	toArray()	Returns the contents of this list as an array.
default T[]	toArray(IntFunction<T[]> supplier)	Returns the contents of this list in array that is provided by the given supplier.
T[]	toArray(T[] target)	Returns the contents of this list in the provided array.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Details

add

HeadTailList<T> add(T element)

Returns a new list with the given element as the head, and this list as the tail.

Parameters:

element - The head for the new list.

Returns:

The new list.

append

default HeadTailList<T> append(HeadTailList<T> list)

Returns a new list where the given list is appended to the end of this list.

Parameters:

list - The list to append.

Returns:

The new list.

append

default HeadTailList<T> append(Collection<T> list)

Returns a new list where the given list is appended to the end of this list.

Parameters:

list - The list to append.

Returns:

The new list.

contains

default boolean contains(T element)

Checks whether the list contains an element that is equal to the given one.

Parameters:

element - The element to look for.

Returns:

true if the element is in the list, false otherwise.

empty

static <E> HeadTailList<E> empty()

Returns an empty list.

Each call to this method will return the same instance.

Type Parameters:

E - The element type for the list.

Returns:

The empty list.

equals

boolean equals(Object o)

Overrides:

equals in class Object

forEachReverse

void forEachReverse(Consumer<? super T> action)

Does the same as Iterable.forEach(Consumer), but starting with last element first.

Parameters:

action - The action to perform.

from

static <E> HeadTailList<E> from(Collection<E> source)

Creates a new list from the given Collection.

Type Parameters:

E - The element type for the list.

Parameters:

source - The collection.

Returns:

The new list.

from

@SafeVarargs
static <E> HeadTailList<E> from(E... elements)

Creates a new list from the given elements.

Type Parameters:

E - The element type for the list.

Parameters:

elements - The elements.

Returns:

The new list.

get

default T get(int index)
       throws IndexOutOfBoundsException

Returns the element that is identified by the given index

The index is in reverse order of the insertion sequence; this means tha the element added first has the highest index value (size() - 1).

Parameters:

index - The index for the wanted element; 0 indicates the head.

Returns:

The element with the given index.

Throws:

IndexOutOfBoundsException - The given index is out of the range index < 0 || index >= size().

hashCode

int hashCode()

Overrides:

hashCode in class Object

head

Optional<T> head()

Returns the head of the list.

This will be empty only for the empty list.

Returns:

An instance of Optional that holds the head.

isEmpty

boolean isEmpty()

Checks whether the list is empty.

Returns:

true if the list is empty, false otherwise.

iterator

Iterator<T> iterator()

Specified by:

iterator in interface Iterable<T>

merge

default HeadTailList<T> merge(HeadTailList<? extends T> list)

Returns a new list where the given list is merged into this list.

This means that each element from this list is followed by an element of the other list; if one list is shorter than the other one, the elements of the longer one will just be appended to the end of the new list.

Parameters:

list - The list to merge into this one.

Returns:

The new list.

prepend

default HeadTailList<T> prepend(HeadTailList<T> list)

Returns a new list where this list is appended to the end of the given list.

Parameters:

list - The list to prepend.

Returns:

The new list.

prepend

default HeadTailList<T> prepend(Collection<T> list)

Returns a new list where the entries of the given list are placed before the first entry of this list.

Parameters:

list - The list to prepend.

Returns:

The new list.

remove

default HeadTailList<T> remove(T element)

Returns a copy of this list that does not contain the given element.

Parameters:

element - The element to be removed.

Returns:

The copy of the list.

replaceHead

default HeadTailList<T> replaceHead(T newHead)

Returns a new copy of this list where the head element is replaced by the given element.

Parameters:

newHead - The element that is the new head for the list.

Returns:

The copy with the new head.

revert

default HeadTailList<T> revert()

Revert the list; that means that the sequence of the elements in the new list is in reverse order that in this one.

Returns:

The new list with the reverted order of the elements.

size

int size()

Returns the size of the list.

Returns:

The size of the list.

stream

Stream<T> stream()

Returns a Stream that is backed by this list.

Returns:

The stream.

tail

HeadTailList<T> tail()

Returns the tail of the list.

Returns:

The tail list.

toArray

Object[] toArray()

Returns the contents of this list as an array.

Returns:

The array.

toArray

T[] toArray(T[] target)

Returns the contents of this list in the provided array.

If the provided array is larger that the number of elements on the stack, the exceeding entries on that array remained unchanged.

Parameters:

target - The target array; if this array has an insufficient size, a new array will be created.

Returns:

An array with all entries from the list; never null. If the provided array was large enough to take all elements, it will be returned, otherwise the returned array is a new one and the provided array is unchanged.

toArray

default T[] toArray(IntFunction<T[]> supplier)

Returns the contents of this list in array that is provided by the given supplier.

If the provided array is larger that the number of elements on the stack, the exceeding entries on that array remained unchanged.

If the array is too small, a new array will be created.

Parameters:

supplier - The supplier for the target array.

Returns:

An array with all entries on the stack; never null. If the provided array was large enough to take all elements, it will be returned, otherwise the returned array is a new one and the provided array is unchanged.