diff options
Diffstat (limited to 'base/src/main/java/bjc/utils/esodata/Stack.java')
| -rw-r--r-- | base/src/main/java/bjc/utils/esodata/Stack.java | 221 |
1 files changed, 113 insertions, 108 deletions
diff --git a/base/src/main/java/bjc/utils/esodata/Stack.java b/base/src/main/java/bjc/utils/esodata/Stack.java index 9d74e9a..9bb61dc 100644 --- a/base/src/main/java/bjc/utils/esodata/Stack.java +++ b/base/src/main/java/bjc/utils/esodata/Stack.java @@ -4,10 +4,12 @@ import java.util.ArrayList; import java.util.List; import java.util.function.Consumer; +/* + * @TODO 10/11/17 Ben Culkin :StackCombinators + * Implement more combinators for the stack. + */ /** - * A stack, with support for combinators. - * - * A FILO stack with support for forth/factor style combinators. + * A stack, with support for forth/factor style stack combinators. * * <p> * <h2>Stack underflow</h2> @@ -19,7 +21,7 @@ import java.util.function.Consumer; * </p> * * @param <T> - * The datatype stored in the stack. + * The datatype stored in the stack. * * @author Ben Culkin */ @@ -29,13 +31,9 @@ public abstract class Stack<T> { * stack that isn't there. * * @author EVE - * */ public static class StackUnderflowException extends RuntimeException { - - /** - * - */ + /* The ID of the exception */ private static final long serialVersionUID = 1423867176204571539L; } @@ -43,14 +41,15 @@ public abstract class Stack<T> { * Push an element onto the stack. * * @param elm - * The element to insert. + * The element to insert. */ public abstract void push(T elm); /** * Pop an element off of the stack. * - * @return The element on top of the stack. + * @return + * The element on top of the stack. */ public abstract T pop(); @@ -58,28 +57,32 @@ public abstract class Stack<T> { * Retrieve the top element of this stack without removing it from the * stack. * - * @return The top element of this stack. + * @return + * The top element of this stack. */ public abstract T top(); /** * Get the number of elements in the stack. * - * @return the number of elements in the stack. + * @return + * the number of elements in the stack. */ public abstract int size(); /** * Check if the stack is empty. * - * @return Whether or not the stack is empty. + * @return + * Whether or not the stack is empty. */ public abstract boolean empty(); /** * Create a spaghetti stack branching off of this one. * - * @return A spaghetti stack with this stack as a parent. + * @return + * A spaghetti stack with this stack as a parent. */ public Stack<T> spaghettify() { return new SpaghettiStack<>(this); @@ -93,7 +96,7 @@ public abstract class Stack<T> { * Drop n items from the stack. * * @param n - * The number of items to drop. + * The number of items to drop. */ public void drop(final int n) { for (int i = 0; i < n; i++) { @@ -101,9 +104,7 @@ public abstract class Stack<T> { } } - /** - * Drop one item from the stack. - */ + /** Drop one item from the stack. */ public void drop() { drop(1); } @@ -112,7 +113,7 @@ public abstract class Stack<T> { * Delete n items below the current one. * * @param n - * The number of items below the top to delete. + * The number of items below the top to delete. */ public void nip(final int n) { final T elm = pop(); @@ -122,9 +123,7 @@ public abstract class Stack<T> { push(elm); } - /** - * Delete the second element in the stack. - */ + /** Delete the second element in the stack. */ public void nip() { nip(1); } @@ -133,9 +132,10 @@ public abstract class Stack<T> { * Replicate the top n items of the stack m times. * * @param n - * The number of items to duplicate. + * The number of items to duplicate. + * * @param m - * The number of times to duplicate items. + * The number of times to duplicate items. */ public void multidup(final int n, final int m) { final List<T> lst = new ArrayList<>(n); @@ -155,15 +155,13 @@ public abstract class Stack<T> { * Duplicate the top n items of the stack. * * @param n - * The number of items to duplicate. + * The number of items to duplicate. */ public void dup(final int n) { multidup(n, 2); } - /** - * Duplicate the top item on the stack. - */ + /** Duplicate the top item on the stack. */ public void dup() { dup(1); } @@ -172,9 +170,10 @@ public abstract class Stack<T> { * Replicate the n elements below the top one m times. * * @param n - * The number of items to duplicate. + * The number of items to duplicate. + * * @param m - * The number of times to duplicate items. + * The number of times to duplicate items. */ public void multiover(final int n, final int m) { final List<T> lst = new ArrayList<>(n); @@ -201,22 +200,18 @@ public abstract class Stack<T> { * Duplicate the n elements below the top one. * * @param n - * The number of items to duplicate. + * The number of items to duplicate. */ public void over(final int n) { multiover(n, 2); } - /** - * Duplicate the second item in the stack. - */ + /** Duplicate the second item in the stack. */ public void over() { over(1); } - /** - * Duplicate the third item in the stack. - */ + /** Duplicate the third item in the stack. */ public void pick() { final T z = pop(); final T y = pop(); @@ -228,9 +223,7 @@ public abstract class Stack<T> { push(x); } - /** - * Swap the top two items on the stack. - */ + /** Swap the top two items on the stack. */ public void swap() { final T y = pop(); final T x = pop(); @@ -239,9 +232,7 @@ public abstract class Stack<T> { push(x); } - /** - * Duplicate the second item below the first item. - */ + /** Duplicate the second item below the first item. */ public void deepdup() { final T y = pop(); final T x = pop(); @@ -251,9 +242,7 @@ public abstract class Stack<T> { push(y); } - /** - * Swap the second and third items in the stack. - */ + /** Swap the second and third items in the stack. */ public void deepswap() { final T z = pop(); final T y = pop(); @@ -264,9 +253,7 @@ public abstract class Stack<T> { push(z); } - /** - * Rotate the top three items on the stack - */ + /** Rotate the top three items on the stack */ public void rot() { final T z = pop(); final T y = pop(); @@ -277,9 +264,7 @@ public abstract class Stack<T> { push(x); } - /** - * Inversely rotate the top three items on the stack - */ + /** Inversely rotate the top three items on the stack */ public void invrot() { final T z = pop(); final T y = pop(); @@ -290,25 +275,32 @@ public abstract class Stack<T> { push(y); } + /* + * :StackCombinators + * Add a general rotate/roll operator. + */ + /* * Dataflow Combinators */ + /** - * Hides the top n elements on the stack from cons. + * Hides the top n elements on the stack from an action. * * @param n - * The number of elements to hide. - * @param cons - * The action to hide the elements from + * The number of elements to hide. + * + * @param action + * The action to hide the elements from */ - public void dip(final int n, final Consumer<Stack<T>> cons) { + public void dip(final int n, final Consumer<Stack<T>> action) { final List<T> elms = new ArrayList<>(n); for (int i = n; i > 0; i--) { elms.set(i - 1, pop()); } - cons.accept(this); + action.accept(this); for (final T elm : elms) { push(elm); @@ -316,75 +308,82 @@ public abstract class Stack<T> { } /** - * Hide the top element of the stack from cons. + * Hide the top element of the stack from an action. * - * @param cons - * The action to hide the top from + * @param action + * The action to hide the top from */ - public void dip(final Consumer<Stack<T>> cons) { - dip(1, cons); + public void dip(final Consumer<Stack<T>> action) { + dip(1, action); } /** - * Copy the top n elements on the stack, replacing them once cons is + * Copy the top n elements on the stack, replacing them once an action is * done. * * @param n - * The number of elements to copy. - * @param cons - * The action to execute. + * The number of elements to copy. + * + * @param action + * The action to execute. */ - public void keep(final int n, final Consumer<Stack<T>> cons) { + public void keep(final int n, final Consumer<Stack<T>> action) { + /* + * @NOTE + * Is this correct? + */ dup(n); - dip(n, cons); + dip(n, action); } /** - * Apply all the actions in conses to the top n elements of the stack. + * Apply all the actions in a list to the top n elements of the stack. * * @param n - * The number of elements to give to cons. - * @param conses - * The actions to execute. + * The number of elements to give to cons. + * + * @param actions + * The actions to execute. */ - public void multicleave(final int n, final List<Consumer<Stack<T>>> conses) { + public void multicleave(final int n, final List<Consumer<Stack<T>>> actions) { final List<T> elms = new ArrayList<>(n); for (int i = n; i > 0; i--) { elms.set(i - 1, pop()); } - for (final Consumer<Stack<T>> cons : conses) { + for (final Consumer<Stack<T>> action : actions) { for (final T elm : elms) { push(elm); } - cons.accept(this); + action.accept(this); } } /** - * Apply all the actions in conses to the top element of the stack. + * Apply all the actions in a list to the top element of the stack. * - * @param conses - * The actions to execute. + * @param actions + * The actions to execute. */ - public void cleave(final List<Consumer<Stack<T>>> conses) { - multicleave(1, conses); + public void cleave(final List<Consumer<Stack<T>>> actions) { + multicleave(1, actions); } /** - * Apply every action in cons to n arguments. + * Apply every action in a list of actions to n arguments. * * @param n - * The number of parameters each action takes. - * @param conses - * The actions to execute. + * The number of parameters each action takes. + * + * @param actions + * The actions to execute. */ - public void multispread(final int n, final List<Consumer<Stack<T>>> conses) { - final List<List<T>> nelms = new ArrayList<>(conses.size()); + public void multispread(final int n, final List<Consumer<Stack<T>>> actions) { + final List<List<T>> nelms = new ArrayList<>(actions.size()); - for (int i = conses.size(); i > 0; i--) { + for (int i = actions.size(); i > 0; i--) { final List<T> elms = new ArrayList<>(n); for (int j = n; j > 0; j--) { @@ -400,60 +399,66 @@ public abstract class Stack<T> { push(elm); } - conses.get(i).accept(this); + actions.get(i).accept(this); i += 1; } } /** - * Apply the actions in cons to corresponding elements from the stack. + * Apply the actions in a list of actions to corresponding elements from + * the stack. * * @param conses - * The actions to execute. + * The actions to execute. */ public void spread(final List<Consumer<Stack<T>>> conses) { multispread(1, conses); } /** - * Apply the action in cons to the first m groups of n arguments. + * Apply an action to the first m groups of n arguments. * * @param n - * The number of arguments cons takes. + * The number of arguments cons takes. + * * @param m - * The number of time to call cons. - * @param cons - * The action to execute. + * The number of time to call cons. + * + * @param action + * The action to execute. */ - public void multiapply(final int n, final int m, final Consumer<Stack<T>> cons) { - final List<Consumer<Stack<T>>> conses = new ArrayList<>(m); + public void multiapply(final int n, final int m, final Consumer<Stack<T>> action) { + final List<Consumer<Stack<T>>> actions = new ArrayList<>(m); for (int i = 0; i < m; i++) { - conses.add(cons); + actions.add(action); } - multispread(n, conses); + multispread(n, actions); } /** - * Apply cons n times to the corresponding elements in the stack. + * Apply an action n times to the corresponding elements in the stack. * * @param n - * The number of times to execute cons. - * @param cons - * The action to execute. + * The number of times to execute cons. + * + * @param action + * The action to execute. */ - public void apply(final int n, final Consumer<Stack<T>> cons) { - multiapply(1, n, cons); + public void apply(final int n, final Consumer<Stack<T>> action) { + multiapply(1, n, action); } /* * Misc. functions */ + /** * Get an array representing this stack. * - * @return The stack as an array. + * @return + * The stack as an array. */ public abstract T[] toArray(); } |