T
- element typepublic interface FStack<T>
extends java.lang.Iterable<T>
This implements a functional stack which itself is immutable.
Stack operations are defined in a way that most of the stack is
reused in copies of it. That means that when you change ony
element on the stack it will change in all copies of this
stack and the stacks created from it via pop()
and push(Object)
. If you don't change the elements
(preferable they are immutable, too) this stack is perfectly
thread-safe.
The only way to use this stack in multi-threaded
environments for potentially changeable objects
is by making copies of each element when it is pushed and when
it is requested via top()
. This stack can be used this
way by providing a copier or using copiable
elements.
See item list below for how this is done.
This stack also extends Iterable
. The returned Iterator
will traverse the stack from top to bottom.
Creating a stack from scratch is done by
empty()
which will return an empty stack with the required
type. Internally this is always the same object, but the Java type
system takes care of handling this correctly.
empty(Copier)
which will return an empty copying stack
with the required type. This is the only way to use a stack of
mutable elements securely in multi-threaded environments.
emptyCopyable()
which will return an empty copying stack with
the required copyable
type. This is the way to use
copyable elements securely in multi-threaded environments.
from(Iterable)
which will return a stack with the elements
from the given iterable. Because of the lifo characteristics of
stacks popping the elements one by one (or iterating over the stack)
will present the elements in the reverse order compared to the
iterable.
from(Copier, Iterable)
which will return a stack with the
copied elements from the given iterable. Because of the lifo characteristics of
stacks popping the elements one by one (or iterating over the stack)
will present the elements in the reverse order compared to the
iterable. This is a way to use a preinitialized stack of
mutable elements securely in multi-threaded environments.
fromCopyable(Iterable)
which will return a stack with the
copied elements from the given iterable. Because of the lifo characteristics of
stacks popping the elements one by one (or iterating over the stack)
will present the elements in the reverse order compared to the
iterable. This is a way to use a preinitialized stack of
copyable
mutable elements securely in multi-threaded environments.
reverseFrom(Iterable)
which will return a stack with the
elements from the given iterable, but take care that they are
pushed in reverse order. Therefore popping the elements one by
one (or iterating over the stack) will present the same order
of elements that the iterable provided.
reverseFrom(Copier, Iterable)
which will return a stack with the
copied elements from the given iterable but take care that they are
pushed in reverse order. Therefore popping the elements one by
one (or iterating over the stack) will present the same order
of elements that the iterable provided. This is a way to use a
preinitialized stack of mutable elements securely in
multi-threaded environments.
reverseFromCopyable(Iterable)
which will return a stack with
the copied elements from the given iterable but take care that they are pushed
in reverse order. Therefore popping the elements one by
one (or iterating over the stack) will present the same order
of elements that the iterable provided. This is a way to use a preinitialized stack of
copyable
mutable elements securely in multi-threaded environments.
Modifier and Type | Method and Description |
---|---|
static <E> FStack<E> |
empty()
Get an empty stack.
|
static <E> FStack<E> |
empty(Copier<E> copier)
Get an empty stack which uses a copier to allow using changeable elements
securely in multi-threaded environments.
|
static <E extends Copyable<E>> |
emptyCopyable()
Get an empty stack which can be used securely in multi-threaded environemnts
because it copies it copyable elements.
|
static <E> FStack<E> |
from(Copier<E> copier,
java.lang.Iterable<E> iterable)
Create a stack from pushing copies of all elements of an iterable to this stack.
|
static <E> FStack<E> |
from(java.lang.Iterable<E> iterable)
Create a stack from pushing all elements of an iterable to this stack.
|
static <E extends Copyable<E>> |
fromCopyable(java.lang.Iterable<E> iterable)
Create a stack from pushing copies of all elements of an iterable to this stack.
|
boolean |
isEmpty()
Is this stack empty?
|
default java.util.Iterator<T> |
iterator() |
FStack<T> |
pop()
Pop the stack.
|
FStack<T> |
push(T elem)
Push an element to the top of the stack.
|
default FStack<T> |
pushAll(java.lang.Iterable<? extends T> elements)
Get a stack which is the result of pushing all elements
to the top of this stack.
|
static <E> FStack<E> |
reverseFrom(Copier<E> copier,
java.lang.Iterable<E> iterable)
Create a stack from pushing copies of all elements of an iterable to this stack.
|
static <E> FStack<E> |
reverseFrom(java.lang.Iterable<E> iterable)
Create a stack from pushing all elements of an iterable to this stack.
|
static <E extends Copyable<E>> |
reverseFromCopyable(java.lang.Iterable<E> iterable)
Create a stack from pushing copies of all elements of an iterable to this stack.
|
default FStack<T> |
reversePushAll(java.lang.Iterable<? extends T> elements)
Get a stack which is the result of pushing all elements
to the top of this stack.
|
int |
size()
Get the size of this stack.
|
T |
top()
Get the top element of the stack.
|
T top()
java.util.EmptyStackException
- if this stack is empty
@NotNull FStack<T> push(T elem)
top()
.elem
- element to push to the stackelem
at the top
and the same elements as this stack below it@NotNull default FStack<T> pushAll(@NotNull java.lang.Iterable<? extends T> elements)
top()
.
Because of the lifo characteristics of stacks the order
of elements when popped from the returned stack is
the reverse of the order of the iterable. If you
prefer otherwise use reversePushAll(Iterable)
.
elements
- elements to push to this stack@NotNull default FStack<T> reversePushAll(@NotNull java.lang.Iterable<? extends T> elements)
top()
.
This method reverses the order of pushing so if
you pop the elements from the returned stack
they will have the same order as they had in the
iterable's sequence. If you
prefer otherwise use pushAll(Iterable)
.
elements
- elements to push to this stack@NotNull FStack<T> pop()
java.util.EmptyStackException
- if this stack is empty
boolean isEmpty()
top()
and pop()
are not allowed and
will result in EmptyStackException
sint size()
@NotNull default java.util.Iterator<T> iterator()
iterator
in interface java.lang.Iterable<T>
@NotNull static <E> FStack<E> empty()
E
- element type of the returned stack@NotNull static <E> FStack<E> empty(@NotNull Copier<E> copier)
The returned functional stack is itself immutable, and will copy elements when pushed and requested.
E
- element type of returned stackcopier
- copier applied on incoming and outgoing elementsempty()
,
emptyCopyable()
@NotNull static <E extends Copyable<E>> FStack<E> emptyCopyable()
E
- copyable element typeempty()
,
empty(Copier)
@NotNull static <E> FStack<E> from(@NotNull java.lang.Iterable<E> iterable)
iterable
.
If you prefer this the other way round use reverseFrom(Iterable)
.E
- element type of the iterable and the returned stackiterable
- iterable to push onto the stackfrom(Copier, Iterable)
,
fromCopyable(Iterable)
@NotNull static <E> FStack<E> from(@NotNull Copier<E> copier, @NotNull java.lang.Iterable<E> iterable)
iterable
.
If you prefer this the other way round use reverseFrom(Copier, Iterable)
.E
- element type of the iterable and the returned stackcopier
- copier applied to all incoming and outgoing elementsiterable
- iterable to push onto the stackfrom(Iterable)
,
from(Copier, Iterable)
@NotNull static <E extends Copyable<E>> FStack<E> fromCopyable(@NotNull java.lang.Iterable<E> iterable)
iterable
.
If you prefer this the other way round use reverseFromCopyable(Iterable)
.E
- copyable element type of the iterable and the returned stackiterable
- iterable to push onto the stackfrom(Iterable)
,
from(Copier, Iterable)
@NotNull static <E> FStack<E> reverseFrom(@NotNull java.lang.Iterable<E> iterable)
iterable
presents.
If you prefer this the other way round use from(Iterable)
.E
- element type of the iterable and the returned stackiterable
- iterable to push onto the stackreverseFrom(Copier, Iterable)
,
reverseFromCopyable(Iterable)
@NotNull static <E> FStack<E> reverseFrom(@NotNull Copier<E> copier, @NotNull java.lang.Iterable<E> iterable)
iterable
presents.
If you prefer this the other way round use from(Copier, Iterable)
.E
- element type of the iterable and the returned stackcopier
- copier applied to all incoming and outgoing stack elementsiterable
- iterable to push onto the stackreverseFrom(Iterable)
,
reverseFromCopyable(Iterable)
@NotNull static <E extends Copyable<E>> FStack<E> reverseFromCopyable(@NotNull java.lang.Iterable<E> iterable)
iterable
presents.
If you prefer this the other way round use fromCopyable(Iterable)
.E
- copyable element type of the iterable and the returned stackiterable
- iterable to push onto the stackreverseFrom(Iterable)
,
reverseFromCopyable(Iterable)