Module org.tquadrat.foundation.util

Package org.tquadrat.foundation.util

Class Stack<T>

java.lang.Object

org.tquadrat.foundation.util.Stack<T>

Type Parameters:

T - The type for the stack entries.

@ClassVersion(sourceVersion="$Id: Stack.java 1061 2023-09-25 16:32:43Z tquadrat $")
@API(status=STABLE,
     since="0.0.5")
public final class Stack<T>
extends Object

A stand-alone implementation for stack, without the ballast from the Collections framework.

This implementation is not synchronised, but thread-safe.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: Stack.java 1061 2023-09-25 16:32:43Z tquadrat $

Since:

0.0.5

See Also:

• Stack

UML Diagram

⁠

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

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private final class	Stack.Entry	The stack entries.

Field Summary

Fields

Modifier and Type	Field	Description
static final Stack[]	EMPTY_Stack_ARRAY	An empty array of Stack objects.
private int	m_Count	The number of entries on the stack.
private Stack<T>.Entry	m_Entries	The entries.
private final AutoLock	m_ReadLock	The "read" lock.
private final AutoLock	m_WriteLock	The "write" lock.

Constructor Summary

Constructors

Constructor	Description
Stack()	Creates a new Stack object.

Method Summary

Modifier and Type	Method	Description
final void	clear()	Empties the whole stack in one go.
final boolean	hasMore()	Tests if the stack is not empty.
final boolean	isEmpty()	Tests if the stack is empty.
final Optional<T>	peek()	Returns the first entry from the stack without removing it from the stack.
final Optional<T>	pop()	Returns the first entry from the stack and removes it.
final void	push(T entry)	Add the given entry to the stack.
final void	push(T... entries)	Adds the given entries to the stack, in LIFO order.
final int	size()	Returns the number of entries on the stack.
final T[]	toArray(IntFunction<T[]> supplier)	Returns all entries that are currently on the stack as an array without removing them, with the top most entry as the first.
final T[]	toArray(T[] target)	Returns all entries that are currently on the stack as an array without removing them, with the top most entry as the first.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

EMPTY_Stack_ARRAY

public static final Stack[] EMPTY_Stack_ARRAY

An empty array of Stack objects.

m_Count

private int m_Count

The number of entries on the stack.

m_Entries

private Stack<T>.Entry m_Entries

The entries.

m_ReadLock

private final AutoLock m_ReadLock

The "read" lock.

m_WriteLock

private final AutoLock m_WriteLock

The "write" lock.

Constructor Details

Stack

public Stack()

Creates a new Stack object.

Method Details

clear

public final void clear()

Empties the whole stack in one go.

hasMore

public final boolean hasMore()

Tests if the stack is not empty.

If concurrent threads will access the stack, it is still possible that this method will return true, but a call to pop() immediately after returns null.

Returns:

true if there are still entries on the stack, false otherwise.

See Also:

• isEmpty()

isEmpty

public final boolean isEmpty()

Tests if the stack is empty.

If concurrent threads will access the stack, it is still possible that this method will return false, but a call to pop() immediately after returns null.

Returns:

true if there are no entries on the stack, false otherwise.

See Also:

• hasMore()

peek

public final Optional<T> peek()

Returns the first entry from the stack without removing it from the stack.

If concurrent threads will access the stack, it is still possible that this method will return a different value than a consecutive call to pop().

Returns:

An instance of Optional that holds the first entry; it will be empty if the stack is empty.

pop

public final Optional<T> pop()

Returns the first entry from the stack and removes it.

Returns:

An instance of Optional that holds the first entry; it will be empty if the stack is empty.

push

public final void push(T entry)

Add the given entry to the stack.

Parameters:

entry - The value to add.

push

@SafeVarargs
public final void push(T... entries)
                throws IllegalArgumentException

Adds the given entries to the stack, in LIFO order. Nothing happens, if the provided array is empty.

The provided array may not contain null elements.

If the push failed for anyone element of the array, the stack remained unchanged.

The method guarantees that the elements of the array are stored to the stack in consecutive order, even in a multithreaded environment.

Parameters:

entries - The values to add.

Throws:

IllegalArgumentException - At least one element of the provided array is null.

size

public final int size()

Returns the number of entries on the stack.

Returns:

The number of entries.

toArray

public final T[] toArray(T[] target)

Returns all entries that are currently on the stack as an array without removing them, with the top most entry as the first. Therefore, this is more or less a peek() on the whole stack.

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 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.

toArray

public final T[] toArray(IntFunction<T[]> supplier)

Returns all entries that are currently on the stack as an array without removing them, with the top most entry as the first. Therefore, this is more or less a peek() on the whole stack.

Parameters:

supplier - The supplier for the target array.

Returns:

An array with all entries on the stack; never null.