2020-11-28 15:05:28 +01:00
|
|
|
package speiger.src.collections.utils;
|
|
|
|
|
2020-12-06 09:32:22 +01:00
|
|
|
|
2021-09-25 20:23:01 +02:00
|
|
|
import org.jetbrains.annotations.NotNull;
|
|
|
|
|
2020-12-06 09:32:22 +01:00
|
|
|
/**
|
2021-04-25 21:37:22 +02:00
|
|
|
* The Stack Interface represents the Last-In-First-Out layout (LIFO).
|
2020-12-06 09:32:22 +01:00
|
|
|
* It provides a simple {@link #push(Object)}, {@link #pop()} function,
|
|
|
|
* with a fast {@link #clear()} function.
|
|
|
|
* The {@link #peek(int)} function allows to view the contents of the stack (top to bottom).
|
2021-04-24 17:37:06 +02:00
|
|
|
* @param <T> the type of elements maintained by this Collection
|
2020-12-06 09:32:22 +01:00
|
|
|
*/
|
2020-11-28 15:05:28 +01:00
|
|
|
public interface Stack<T>
|
|
|
|
{
|
2020-12-06 09:32:22 +01:00
|
|
|
/**
|
|
|
|
* Inserts a given Object on top of the stack
|
|
|
|
* @param e the Object to insert
|
|
|
|
*/
|
2021-09-25 20:23:01 +02:00
|
|
|
void push(@NotNull T e);
|
2020-11-28 15:05:28 +01:00
|
|
|
|
2020-12-06 09:32:22 +01:00
|
|
|
/**
|
|
|
|
* Removes the Object on top of the stack.
|
|
|
|
* @return the element that is on top of the stack
|
|
|
|
* @throws ArrayIndexOutOfBoundsException if the stack is empty
|
|
|
|
*/
|
2021-09-25 20:23:01 +02:00
|
|
|
@NotNull T pop();
|
2020-11-28 15:05:28 +01:00
|
|
|
|
2020-12-06 09:32:22 +01:00
|
|
|
/**
|
|
|
|
* Provides the amount of elements currently in the stack
|
|
|
|
* @return amount of elements in the list
|
|
|
|
*/
|
2021-09-25 20:23:01 +02:00
|
|
|
int size();
|
2020-11-28 15:05:28 +01:00
|
|
|
|
2021-06-23 18:38:23 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @return if the stack is empty
|
|
|
|
*/
|
2021-09-25 20:23:01 +02:00
|
|
|
default boolean isEmpty() {
|
2021-06-23 18:38:23 +02:00
|
|
|
return size() == 0;
|
|
|
|
}
|
|
|
|
|
2020-12-06 09:32:22 +01:00
|
|
|
/**
|
|
|
|
* Clears the stack
|
|
|
|
*/
|
2021-09-25 20:23:01 +02:00
|
|
|
void clear();
|
2020-11-28 15:05:28 +01:00
|
|
|
|
2020-12-06 09:32:22 +01:00
|
|
|
/**
|
|
|
|
* Provides the Object on top of the stack
|
|
|
|
* @return the element that is on top of the stack
|
|
|
|
* @throws ArrayIndexOutOfBoundsException if the stack is empty
|
|
|
|
*/
|
2021-09-25 20:23:01 +02:00
|
|
|
default @NotNull T top() {
|
2020-11-28 15:05:28 +01:00
|
|
|
return peek(0);
|
|
|
|
}
|
|
|
|
|
2020-12-06 09:32:22 +01:00
|
|
|
/**
|
|
|
|
* Provides the Selected Object from the stack.
|
|
|
|
* Top to bottom
|
|
|
|
* @param index of the element that should be provided
|
|
|
|
* @return the element that was requested
|
|
|
|
* @throws ArrayIndexOutOfBoundsException if the index is out of bounds
|
|
|
|
*/
|
2021-09-25 20:23:01 +02:00
|
|
|
@NotNull T peek(int index);
|
2020-11-28 15:05:28 +01:00
|
|
|
}
|