net.markenwerk.commons.collections.stacks

Interface Stack<Payload>

Type Parameters:

Payload - The payload type

All Superinterfaces:

Iterable<Payload>, ProtectedIterable<Payload>, Source<Payload>

All Known Implementing Classes:

AbstractLinkedStack, AbstractStack, LinkedStack

public interface Stack<Payload>
extends Source<Payload>

A Stack is a linear first-in-last-out data structure.

Since:

1.0.0

Author:

Torsten Krause (tk at markenwerk dot net)

Method Summary

Modifier and Type	Method and Description
Source<Payload>	clear() Removes all payload values.
boolean	equals(Object object) Compares the given object with this Stack for equality.
Optional<Integer>	firstIndexOf(Payload reference) Returns the index of the first occurrence, by equality, of the given reference payload value, where 0 is the index of most recently pushed value.
Optional<Integer>	firstIndexOfMatch(Predicate<? super Payload> predicate) Returns the index of the first occurrence of a reference payload value that satisfies the given Predicate, where 0 is the index of most recently pushed value.
Payload	get(int index) Returns the payload value at the given index, where 0 is the index of most recently pushed value.
Payload	getFirst() Returns the first (i.e.
Optional<Payload>	getFirst(Payload reference) Returns the first (i.e.
Optional<Payload>	getFirstMatch(Predicate<? super Payload> predicate) Returns the first i.e.
int	hashCode() Returns the hash code of this Stack.
ProtectedIterator<Payload>	iterator() Returns a fail-fast ProtectedIterator that starts with the first (i.e.
Payload	pop() Removes the first (i.e.
Source<Payload>	popAll(int number) Removes the given number of payload values.
Source<Payload>	popAllMatches(Predicate<? super Payload> predicate) Removes the first (i.e.
Stack<Payload>	push(Payload payload) Pushes the given payload value as the new first value.
Stack<Payload>	pushAll(Iterable<? extends Payload> payloads) Pushes the given payload values in the given order.
Stack<Payload>	pushAll(Payload... payloads) Pushes the given payload values in the given order.
Payload	replace(Payload payload) Replaces the first (i.e.

Methods inherited from interface net.markenwerk.commons.collections.sources.Source

contains, containsAll, containsAll, containsMatch, getAll, getAllMatches, isEmpty, size

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

push

Stack<Payload> push(Payload payload)
             throws IllegalArgumentException

Pushes the given payload value as the new first value.

Parameters:

payload - The payload value to be pushed.

Returns:

This Stack.

Throws:

IllegalArgumentException - If the given payload value is null and this Sequence doesn't allow a null to be added.

pushAll

Stack<Payload> pushAll(Payload... payloads)
                throws IllegalArgumentException

Pushes the given payload values in the given order.

This is a short hand for a multiple pushes.

Parameters:

payloads - The array of payload values to be pushed.

Returns:

This Stack.

Throws:

IllegalArgumentException - If the given array of payload values is null or if one of the given payload values is null and this Sequence doesn't allow a null to be added.

pushAll

Stack<Payload> pushAll(Iterable<? extends Payload> payloads)
                throws IllegalArgumentException

Pushes the given payload values in the given order.

This is a short hand for a multiple pushes.

Parameters:

payloads - The Iterable of payload values to be pushed.

Returns:

This Stack.

Throws:

IllegalArgumentException - If the given Iterable of payload values is null or if one of the given payload values is null and this Sequence doesn't allow a null to be added.

pop

Payload pop()
     throws NoSuchElementException

Removes the first (i.e. most recently pushed) payload value.

Returns:

The removed payload value.

Throws:

NoSuchElementException - If this Stack is empty.

popAll

Source<Payload> popAll(int number)
                throws IllegalArgumentException

Removes the given number of payload values.

Parameters:

number - The number of payload values to be popped.

Returns:

A Source yielding the removed payload values.

Throws:

IllegalArgumentException - If the given index is negative or if the given index is larger than the size of this Stack .

popAllMatches

Source<Payload> popAllMatches(Predicate<? super Payload> predicate)
                       throws IllegalArgumentException

Removes the first (i.e. most recently pushed) payload values as long as this Stack is not empty and the first payload value satisfies the given predicate.

Parameters:

predicate - The Predicate to be used.

Returns:

A Source yielding the removed payload values.

Throws:

IllegalArgumentException - If the given Predicate is null.

get

Payload get(int index)
     throws IndexOutOfBoundsException

Returns the payload value at the given index, where 0 is the index of most recently pushed value.

Parameters:

index - The index to be used.

Returns:

The payload value at the given index.

Throws:

IndexOutOfBoundsException - If the given index is negative or if the given index is equal to or larger than the size of this Stack.

getFirst

Payload getFirst()
          throws NoSuchElementException

Returns the first (i.e. most recently pushed) payload value.

Specified by:

getFirst in interface Source<Payload>

Returns:

The payload value.

Throws:

NoSuchElementException - If this IndexedSource is empty.

getFirst

Optional<Payload> getFirst(Payload reference)

Returns the first (i.e. most recently pushed) occurrences, by equality, of the given reference payload value.

Specified by:

getFirst in interface Source<Payload>

Parameters:

reference - The reference payload to be used.

Returns:

An Optional yielding the payload value.

getFirstMatch

Optional<Payload> getFirstMatch(Predicate<? super Payload> predicate)
                         throws IllegalArgumentException

Returns the first i.e. most recently pushed) payload value that satisfies the given Predicate.

Specified by:

getFirstMatch in interface Source<Payload>

Parameters:

predicate - The Predicate to be used.

Returns:

An Optional yielding the payload value.

Throws:

IllegalArgumentException - If the given Predicate is null.

replace

Payload replace(Payload payload)
         throws IllegalArgumentException,
                NoSuchElementException

Replaces the first (i.e. most recently pushed) payload value with the given payload value.

This is a short hand for a pop and a push.

Parameters:

payload - The payload value to be used.

Returns:

The replaced payload value.

Throws:

IllegalArgumentException - If the given payload value is null and this Sequence doesn't allow a null to be added.

NoSuchElementException - If this Stack is empty.

clear

Source<Payload> clear()

Removes all payload values.

This may be a bulk operation and not a short hand for a multiple pops.

Returns:

A Source yielding the removed payload values.

firstIndexOf

Optional<Integer> firstIndexOf(Payload reference)

Returns the index of the first occurrence, by equality, of the given reference payload value, where 0 is the index of most recently pushed value.

Parameters:

reference - The reference payload value to be used.

Returns:

An Optional yielding the index.

firstIndexOfMatch

Optional<Integer> firstIndexOfMatch(Predicate<? super Payload> predicate)
                             throws IllegalArgumentException

Returns the index of the first occurrence of a reference payload value that satisfies the given Predicate, where 0 is the index of most recently pushed value.

Parameters:

predicate - The Predicate value to be used.

Returns:

An Optional yielding the index.

Throws:

IllegalArgumentException - If the given Predicate is null.

iterator

ProtectedIterator<Payload> iterator()

Returns a fail-fast ProtectedIterator that starts with the first (i.e. most recently pushed) payload value.

Specified by:

iterator in interface Iterable<Payload>

Specified by:

iterator in interface ProtectedIterable<Payload>

Returns:

A fail-fast ProtectedIterator.

hashCode

int hashCode()

Returns the hash code of this Stack.

The hash code of a Stack is defined to be the result of the following calculation:

 int hashCode = 1;
 Iterator<Payload> iterator = stack.iterator();
 while (iterator.hasNext()) {
        Payload payload = iterator.next();
        hashCode = 31 * hashCode + (null == payload ? 0 : payload.hashCode());
 }
 

Overrides:

hashCode in class Object

Returns:

The hash code of this Stack.

equals

boolean equals(Object object)

Compares the given object with this Stack for equality.

Returns true if and only if the given object is also a Stack, both Stacks have the same size, and all corresponding pairs of elements in the two Stacks are equal.

Overrides:

equals in class Object

Parameters:

object - The object to be used.

Returns:

If the given object is equal to this Stack.