diff options
Diffstat (limited to 'base/src/main/java/bjc/utils/data')
27 files changed, 611 insertions, 390 deletions
diff --git a/base/src/main/java/bjc/utils/data/BooleanToggle.java b/base/src/main/java/bjc/utils/data/BooleanToggle.java index 12e3b2e..280b90d 100644 --- a/base/src/main/java/bjc/utils/data/BooleanToggle.java +++ b/base/src/main/java/bjc/utils/data/BooleanToggle.java @@ -7,6 +7,7 @@ package bjc.utils.data; * */ public class BooleanToggle implements Toggle<Boolean> { + /* The contained value. */ private boolean val; /** @@ -20,7 +21,7 @@ public class BooleanToggle implements Toggle<Boolean> { * Create a flip-flop with the specified initial value. * * @param initial - * The initial value of the flip-flop. + * The initial value of the flip-flop. */ public BooleanToggle(final boolean initial) { val = initial; @@ -73,4 +74,4 @@ public class BooleanToggle implements Toggle<Boolean> { public String toString() { return String.format("BooleanToggle [val=%s]", val); } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/CircularIterator.java b/base/src/main/java/bjc/utils/data/CircularIterator.java index a708eba..60f815c 100644 --- a/base/src/main/java/bjc/utils/data/CircularIterator.java +++ b/base/src/main/java/bjc/utils/data/CircularIterator.java @@ -8,18 +8,14 @@ import java.util.Iterator; * @author EVE * * @param <E> - * The type of the iterable. + * The type of the iterable. */ public class CircularIterator<E> implements Iterator<E> { - /* - * The iterable, and our current iterator into it. - */ + /* The iterable, and our current iterator into it. */ private Iterable<E> source; private Iterator<E> curr; - /* - * Our current element. - */ + /* Our current element. */ private E curElm; /* @@ -32,11 +28,11 @@ public class CircularIterator<E> implements Iterator<E> { * Create a new circular iterator. * * @param src - * The iterable to iterate from. + * The iterable to iterate from. * * @param circ - * Should we actually do circular iteration, or just - * repeat the terminal element? + * Should we actually do circular iteration, or just + * repeat the terminal element? */ public CircularIterator(final Iterable<E> src, final boolean circ) { source = src; @@ -49,7 +45,7 @@ public class CircularIterator<E> implements Iterator<E> { * Create a new circular iterator that does actual circular iteration. * * @param src - * The iterable to iterate from. + * The iterable to iterate from. */ public CircularIterator(final Iterable<E> src) { this(src, true); @@ -57,7 +53,7 @@ public class CircularIterator<E> implements Iterator<E> { @Override public boolean hasNext() { - // We always have something + /* We always have something. */ return true; } diff --git a/base/src/main/java/bjc/utils/data/Either.java b/base/src/main/java/bjc/utils/data/Either.java index 36b3324..2b64feb 100644 --- a/base/src/main/java/bjc/utils/data/Either.java +++ b/base/src/main/java/bjc/utils/data/Either.java @@ -4,52 +4,64 @@ import java.util.function.BiFunction; import java.util.function.Function; /** - * Represents a pair where only one side has a value + * Represents a pair where only one side has a value. * * @author ben + * * @param <LeftType> - * The type that could be on the left + * The type that could be on the left. + * * @param <RightType> - * The type that could be on the right + * The type that could be on the right. * */ public class Either<LeftType, RightType> implements IPair<LeftType, RightType> { /** - * Create a new either with the left value occupied + * Create a new either with the left value occupied. * * @param <LeftType> - * The type of the left value + * The type of the left value. + * * @param <RightType> - * The type of the empty right value + * The type of the empty right value. + * * @param left - * The value to put on the left - * @return An either with the left side occupied + * The value to put on the left. + * + * @return + * An either with the left side occupied. */ public static <LeftType, RightType> Either<LeftType, RightType> left(final LeftType left) { return new Either<>(left, null); } /** - * Create a new either with the right value occupied + * Create a new either with the right value occupied. * * @param <LeftType> - * The type of the empty left value + * The type of the empty left value. + * * @param <RightType> - * The type of the right value + * The type of the right value. + * * @param right - * The value to put on the right - * @return An either with the right side occupied + * The value to put on the right. + * + * @return + * An either with the right side occupied. */ public static <LeftType, RightType> Either<LeftType, RightType> right(final RightType right) { return new Either<>(null, right); } + /* The left value of the either. */ private LeftType leftVal; - + /* The right value of the either. */ private RightType rightVal; - + /* Whether the left value is the one filled out. */ private boolean isLeft; + /* Create a new either with specifed values. */ private Either(final LeftType left, final RightType right) { if (left == null) { rightVal = right; @@ -93,19 +105,27 @@ public class Either<LeftType, RightType> implements IPair<LeftType, RightType> { final IPair<OtherLeft, OtherRight> otherPair, final BiFunction<LeftType, OtherLeft, CombinedLeft> leftCombiner, final BiFunction<RightType, OtherRight, CombinedRight> rightCombiner) { - if (otherPair == null) + if (otherPair == null) { throw new NullPointerException("Other pair must not be null"); - else if (leftCombiner == null) + } else if (leftCombiner == null) { throw new NullPointerException("Left combiner must not be null"); - else if (rightCombiner == null) throw new NullPointerException("Right combiner must not be null"); + } else if (rightCombiner == null) { + throw new NullPointerException("Right combiner must not be null"); + } - if (isLeft) return otherPair.bind((otherLeft, otherRight) -> { - return new Either<>(leftCombiner.apply(leftVal, otherLeft), null); - }); + if (isLeft) { + return otherPair.bind((otherLeft, otherRight) -> { + CombinedLeft cLeft = leftCombiner.apply(leftVal, otherLeft); - return otherPair.bind((otherLeft, otherRight) -> { - return new Either<>(null, rightCombiner.apply(rightVal, otherRight)); - }); + return new Either<>(cLeft, null); + }); + } else { + return otherPair.bind((otherLeft, otherRight) -> { + CombinedRight cRight = rightCombiner.apply(rightVal, otherRight); + + return new Either<>(null, cRight); + }); + } } @Override @@ -170,4 +190,4 @@ public class Either<LeftType, RightType> implements IPair<LeftType, RightType> { public String toString() { return String.format("Either [leftVal='%s', rightVal='%s', isLeft=%s]", leftVal, rightVal, isLeft); } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/GeneratingIterator.java b/base/src/main/java/bjc/utils/data/GeneratingIterator.java index 9abca7c..92d10a5 100644 --- a/base/src/main/java/bjc/utils/data/GeneratingIterator.java +++ b/base/src/main/java/bjc/utils/data/GeneratingIterator.java @@ -10,27 +10,28 @@ import java.util.function.UnaryOperator; * @author bjculkin * * @param <E> - * The type of element generated. + * The type of element generated. */ public class GeneratingIterator<E> implements Iterator<E> { + /* Our current state. */ private E state; - + /* The function to use to transition states. */ private UnaryOperator<E> transtion; - + /* The predicate to indicate where to stop. */ private Predicate<E> stpper; /** * Create a new generative iterator. * * @param initial - * The initial state of the generator. + * The initial state of the generator. * * @param transition - * The function to apply to the state. + * The function to apply to the state. * * @param stopper - * The predicate applied to the current state to - * determine when to stop. + * The predicate applied to the current state to + * determine when to stop. */ public GeneratingIterator(E initial, UnaryOperator<E> transition, Predicate<E> stopper) { state = initial; @@ -43,11 +44,16 @@ public class GeneratingIterator<E> implements Iterator<E> { return stpper.test(state); } + /* + * @NOTE + * As this currently is, it only works correctly assuming that + * next() is only called when hasNext() is true. Should we + * safeguard against people who are not doing the right thing? + */ @Override public E next() { state = transtion.apply(state); return state; } - } diff --git a/base/src/main/java/bjc/utils/data/IHolder.java b/base/src/main/java/bjc/utils/data/IHolder.java index ca0b2ba..0b0cfd2 100644 --- a/base/src/main/java/bjc/utils/data/IHolder.java +++ b/base/src/main/java/bjc/utils/data/IHolder.java @@ -16,25 +16,28 @@ import bjc.utils.funcdata.theory.Functor; * @author ben * * @param <ContainedType> - * The type of value held + * The type of value held. */ public interface IHolder<ContainedType> extends Functor<ContainedType> { /** - * Bind a function across the value in this container + * Bind a function across the value in this container. * * @param <BoundType> - * The type of value in this container + * The type of value in this container. + * * @param binder - * The function to bind to the value - * @return A holder from binding the value + * The function to bind to the value. + * + * @return + * A holder from binding the value. */ public <BoundType> IHolder<BoundType> bind(Function<ContainedType, IHolder<BoundType>> binder); /** - * Apply an action to the value + * Apply an action to the value. * * @param action - * The action to apply to the value + * The action to apply to the value. */ public default void doWith(final Consumer<? super ContainedType> action) { transform(value -> { @@ -66,38 +69,44 @@ public interface IHolder<ContainedType> extends Functor<ContainedType> { } /** - * Lifts a function to bind over this holder + * Lifts a function to bind over this holder. * * @param <NewType> - * The type of the functions return + * The type of the functions return. + * * @param func - * The function to lift over the holder - * @return The function lifted over the holder + * The function to lift over the holder. + * + * @return + * The function lifted over the holder. */ public <NewType> Function<ContainedType, IHolder<NewType>> lift(Function<ContainedType, NewType> func); /** - * Make this holder lazy + * Make this holder lazy. * - * @return A lazy version of this holder + * @return + * A lazy version of this holder. */ public default IHolder<ContainedType> makeLazy() { return new WrappedLazy<>(this); } /** - * Make this holder a list + * Make this holder a list. * - * @return A list version of this holder + * @return + * A list version of this holder. */ public default IHolder<ContainedType> makeList() { return new BoundListHolder<>(new FunctionalList<>(this)); } /** - * Make this holder optional + * Make this holder optional. * - * @return An optional version of this holder + * @return + * An optional version of this holder. */ public default IHolder<ContainedType> makeOptional() { return new WrappedOption<>(this); @@ -107,22 +116,27 @@ public interface IHolder<ContainedType> extends Functor<ContainedType> { * Create a new holder with a mapped version of the value in this * holder. * - * Does not change the internal state of this holder + * Does not change the internal state of this holder. * * @param <MappedType> - * The type of the mapped value + * The type of the mapped value. + * * @param mapper - * The function to do mapping with - * @return A holder with the mapped value + * The function to do mapping with. + * + * @return + * A holder with the mapped value */ public <MappedType> IHolder<MappedType> map(Function<ContainedType, MappedType> mapper); /** - * Replace the held value with a new one + * Replace the held value with a new one. * * @param newValue - * The value to hold instead - * @return The holder itself + * The value to hold instead. + * + * @return + * The holder itself. */ public default IHolder<ContainedType> replace(final ContainedType newValue) { return transform(oldValue -> { @@ -131,23 +145,28 @@ public interface IHolder<ContainedType> extends Functor<ContainedType> { } /** - * Transform the value held in this holder + * Transform the value held in this holder. * * @param transformer - * The function to transform the value with - * @return The holder itself, for easy chaining + * The function to transform the value with. + * + * @return + * The holder itself, for easy chaining. */ public IHolder<ContainedType> transform(UnaryOperator<ContainedType> transformer); /** * Unwrap the value contained in this holder so that it is no longer - * held + * held. * * @param <UnwrappedType> - * The type of the unwrapped value + * The type of the unwrapped value. + * * @param unwrapper - * The function to use to unwrap the value - * @return The unwrapped held value + * The function to use to unwrap the value. + * + * @return + * The unwrapped held value. */ public <UnwrappedType> UnwrappedType unwrap(Function<ContainedType, UnwrappedType> unwrapper); } diff --git a/base/src/main/java/bjc/utils/data/IPair.java b/base/src/main/java/bjc/utils/data/IPair.java index db8a1cb..75b092d 100644 --- a/base/src/main/java/bjc/utils/data/IPair.java +++ b/base/src/main/java/bjc/utils/data/IPair.java @@ -7,64 +7,80 @@ import java.util.function.Function; import bjc.utils.funcdata.theory.Bifunctor; /** - * Represents a pair of values + * Represents a pair of values. * * @author ben + * * @param <LeftType> - * The type of the left side of the pair + * The type of the left side of the pair. + * * @param <RightType> - * The type of the right side of the pair + * The type of the right side of the pair. * */ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightType> { /** - * Bind a function across the values in this pair + * Bind a function across the values in this pair. * * @param <BoundLeft> - * The type of the bound left + * The type of the bound left. + * * @param <BoundRight> - * The type of the bound right + * The type of the bound right. + * * @param binder - * The function to bind with - * @return The bound pair + * The function to bind with. + * + * @return + * The bound pair. */ public <BoundLeft, BoundRight> IPair<BoundLeft, BoundRight> bind( BiFunction<LeftType, RightType, IPair<BoundLeft, BoundRight>> binder); /** - * Bind a function to the left value in this pair + * Bind a function to the left value in this pair. * * @param <BoundLeft> - * The type of the bound value + * The type of the bound value. + * * @param leftBinder - * The function to use to bind - * @return A pair with the left type bound + * The function to use to bind. + * + * @return + * A pair with the left type bound. */ public <BoundLeft> IPair<BoundLeft, RightType> bindLeft( Function<LeftType, IPair<BoundLeft, RightType>> leftBinder); /** - * Bind a function to the right value in this pair + * Bind a function to the right value in this pair. * * @param <BoundRight> - * The type of the bound value + * The type of the bound value. + * * @param rightBinder - * The function to use to bind - * @return A pair with the right type bound + * The function to use to bind. + * + * @return + * A pair with the right type bound. */ public <BoundRight> IPair<LeftType, BoundRight> bindRight( Function<RightType, IPair<LeftType, BoundRight>> rightBinder); /** - * Pairwise combine two pairs together + * Pairwise combine two pairs together. * * @param <OtherLeft> - * The left type of the other pair + * The left type of the other pair. + * * @param <OtherRight> - * The right type of the other pair + * The right type of the other pair. + * * @param otherPair - * The pair to combine with - * @return The pairs, pairwise combined together + * The pair to combine with. + * + * @return + * The pairs, pairwise combined together. */ public default <OtherLeft, OtherRight> IPair<IPair<LeftType, OtherLeft>, IPair<RightType, OtherRight>> combine( final IPair<OtherLeft, OtherRight> otherPair) { @@ -72,21 +88,31 @@ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightTyp } /** - * Combine the contents of two pairs together + * Combine the contents of two pairs together. * * @param <OtherLeft> - * The type of the left value of the other pair + * The type of the left value of the other pair. + * * @param <OtherRight> - * The type of the right value of the other pair + * The type of the right value of the other pair. + * * @param <CombinedLeft> - * The type of the left value of the combined pair + * The type of the left value of the combined pair. + * * @param <CombinedRight> - * The type of the right value of the combined pair + * The type of the right value of the combined pair. + * * @param otherPair - * The other pair to combine with + * The other pair to combine with. + * * @param leftCombiner + * The function to combine the left values with. + * * @param rightCombiner - * @return A pair with its values combined + * The function to combine the right values with. + * + * @return + * A pair with its values combined. */ public <OtherLeft, OtherRight, CombinedLeft, CombinedRight> IPair<CombinedLeft, CombinedRight> combine( IPair<OtherLeft, OtherRight> otherPair, @@ -95,10 +121,10 @@ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightTyp /** * Immediately perfom the specified action with the contents of this - * pair + * pair. * * @param consumer - * The action to perform on the pair + * The action to perform on the pair. */ public default void doWith(final BiConsumer<LeftType, RightType> consumer) { merge((leftValue, rightValue) -> { @@ -109,8 +135,8 @@ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightTyp } @Override - default <OldLeft, OldRight, NewLeft> LeftBifunctorMap<OldLeft, OldRight, NewLeft> fmapLeft( - final Function<OldLeft, NewLeft> func) { + default <OldLeft, OldRight, NewLeft> LeftBifunctorMap<OldLeft, OldRight, NewLeft> + fmapLeft(final Function<OldLeft, NewLeft> func) { return argumentPair -> { if (!(argumentPair instanceof IPair<?, ?>)) { final String msg = "This function can only be applied to instances of IPair"; @@ -125,8 +151,7 @@ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightTyp } @Override - default <OldLeft, OldRight, NewRight> RightBifunctorMap<OldLeft, OldRight, NewRight> - + default <OldLeft, OldRight, NewRight> RightBifunctorMap<OldLeft, OldRight, NewRight> fmapRight(final Function<OldRight, NewRight> func) { return argumentPair -> { if (!(argumentPair instanceof IPair<?, ?>)) { @@ -142,9 +167,10 @@ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightTyp } /** - * Get the value on the left side of the pair + * Get the value on the left side of the pair. * - * @return The value on the left side of the pair + * @return + * The value on the left side of the pair. */ @Override public default LeftType getLeft() { @@ -152,9 +178,10 @@ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightTyp } /** - * Get the value on the right side of the pair + * Get the value on the right side of the pair. * - * @return The value on the right side of the pair + * @return + * The value on the right side of the pair. */ @Override public default RightType getRight() { @@ -162,39 +189,50 @@ public interface IPair<LeftType, RightType> extends Bifunctor<LeftType, RightTyp } /** - * Transform the value on the left side of the pair. Doesn't modify the - * pair + * Transform the value on the left side of the pair. + * + * Doesn't modify the pair. * * @param <NewLeft> - * The new type of the left part of the pair + * The new type of the left part of the pair. + * * @param mapper - * The function to use to transform the left part of the - * pair - * @return The pair, with its left part transformed + * The function to use to transform the left part of the + * pair. + * + * @return + * The pair, with its left part transformed. */ public <NewLeft> IPair<NewLeft, RightType> mapLeft(Function<LeftType, NewLeft> mapper); /** - * Transform the value on the right side of the pair. Doesn't modify the - * pair + * Transform the value on the right side of the pair. + * + * Doesn't modify the pair. * * @param <NewRight> - * The new type of the right part of the pair + * The new type of the right part of the pair. + * * @param mapper - * The function to use to transform the right part of the - * pair - * @return The pair, with its right part transformed + * The function to use to transform the right part of the + * pair. + * + * @return + * The pair, with its right part transformed. */ public <NewRight> IPair<LeftType, NewRight> mapRight(Function<RightType, NewRight> mapper); /** - * Merge the two values in this pair into a single value + * Merge the two values in this pair into a single value. * * @param <MergedType> - * The type of the single value + * The type of the single value. + * * @param merger - * The function to use for merging - * @return The pair, merged into a single value + * The function to use for merging. + * + * @return + * The pair, merged into a single value. */ public <MergedType> MergedType merge(BiFunction<LeftType, RightType, MergedType> merger); } diff --git a/base/src/main/java/bjc/utils/data/ITree.java b/base/src/main/java/bjc/utils/data/ITree.java index ff374e8..450905b 100644 --- a/base/src/main/java/bjc/utils/data/ITree.java +++ b/base/src/main/java/bjc/utils/data/ITree.java @@ -14,7 +14,7 @@ import bjc.utils.functypes.ListFlattener; * @author ben * * @param <ContainedType> - * The type of data contained in the tree nodes. + * The type of data contained in the tree nodes. * */ public interface ITree<ContainedType> { @@ -22,7 +22,7 @@ public interface ITree<ContainedType> { * Append a child to this node. * * @param child - * The child to append to this node. + * The child to append to this node. */ void addChild(ITree<ContainedType> child); @@ -30,7 +30,7 @@ public interface ITree<ContainedType> { * Prepend a child to this node. * * @param child - * The child to prepend to this node. + * The child to prepend to this node. */ void prependChild(ITree<ContainedType> child); @@ -38,23 +38,24 @@ public interface ITree<ContainedType> { * Collapse a tree into a single version. * * @param <NewType> - * The intermediate type being folded. + * The intermediate type being folded. * * @param <ReturnedType> - * The type that is the end result. + * The type that is the end result. * * @param leafTransform - * The function to use to convert leaf values. + * The function to use to convert leaf values. * * @param nodeCollapser - * The function to use to convert internal nodes and - * their children. + * The function to use to convert internal nodes and + * their children. * * @param resultTransformer - * The function to use to convert a state to the returned - * version. + * The function to use to convert a state to the returned + * version. * - * @return The final transformed state. + * @return + * The final transformed state. */ <NewType, ReturnedType> ReturnedType collapse(Function<ContainedType, NewType> leafTransform, Function<ContainedType, ListFlattener<NewType>> nodeCollapser, @@ -64,7 +65,7 @@ public interface ITree<ContainedType> { * Execute a given action for each of this tree's children. * * @param action - * The action to execute for each child. + * The action to execute for each child. */ void doForChildren(Consumer<ITree<ContainedType>> action); @@ -73,9 +74,10 @@ public interface ITree<ContainedType> { * those trees into a single tree. * * @param mapper - * The function to use to map values into trees. + * The function to use to map values into trees. * - * @return A tree, with some nodes expanded into trees. + * @return + * A tree, with some nodes expanded into trees. */ default ITree<ContainedType> flatMapTree(final Function<ContainedType, ITree<ContainedType>> mapper) { return topDownTransform(dat -> TopDownTransformResult.PUSHDOWN, node -> { @@ -95,9 +97,10 @@ public interface ITree<ContainedType> { * Get the specified child of this tree. * * @param childNo - * The number of the child to get. + * The number of the child to get. * - * @return The specified child of this tree. + * @return + * The specified child of this tree. */ default ITree<ContainedType> getChild(final int childNo) { return transformChild(childNo, child -> child); @@ -106,14 +109,16 @@ public interface ITree<ContainedType> { /** * Get a count of the number of direct children this node has. * - * @return The number of direct children this node has. + * @return + * The number of direct children this node has. */ int getChildrenCount(); /** * Get the data stored in this node. * - * @return The data stored in this node. + * @return + * The data stored in this node. */ default ContainedType getHead() { return transformHead(head -> head); @@ -123,27 +128,28 @@ public interface ITree<ContainedType> { * Rebuild the tree with the same structure, but different nodes. * * @param <MappedType> - * The type of the new tree. + * The type of the new tree. * * @param leafTransformer - * The function to use to transform leaf tokens. + * The function to use to transform leaf tokens. * - * @param operatorTransformer - * The function to use to transform internal tokens. + * @param internalTransformer + * The function to use to transform internal tokens. * - * @return The tree, with the nodes changed. + * @return + * The tree, with the nodes changed. */ <MappedType> ITree<MappedType> rebuildTree(Function<ContainedType, MappedType> leafTransformer, - Function<ContainedType, MappedType> operatorTransformer); + Function<ContainedType, MappedType> internalTransformer); /** * Transform some of the nodes in this tree. * * @param nodePicker - * The predicate to use to pick nodes to transform. + * The predicate to use to pick nodes to transform. * * @param transformer - * The function to use to transform picked nodes. + * The function to use to transform picked nodes. */ void selectiveTransform(Predicate<ContainedType> nodePicker, UnaryOperator<ContainedType> transformer); @@ -151,12 +157,13 @@ public interface ITree<ContainedType> { * Do a top-down transform of the tree. * * @param transformPicker - * The function to use to pick how to progress. + * The function to use to pick how to progress. * * @param transformer - * The function used to transform picked subtrees. + * The function used to transform picked subtrees. * - * @return The tree with the transform applied to picked subtrees. + * @return + * The tree with the transform applied to picked subtrees. */ ITree<ContainedType> topDownTransform(Function<ContainedType, TopDownTransformResult> transformPicker, UnaryOperator<ITree<ContainedType>> transformer); @@ -165,19 +172,20 @@ public interface ITree<ContainedType> { * Transform one of this nodes children. * * @param <TransformedType> - * The type of the transformed value. + * The type of the transformed value. * * @param childNo - * The number of the child to transform. + * The number of the child to transform. * * @param transformer - * The function to use to transform the value. + * The function to use to transform the value. * - * @return The transformed value. + * @return + * The transformed value. * * @throws IllegalArgumentException - * if the childNo is out of bounds (0 <= childNo <= - * childCount()). + * if the childNo is out of bounds (0 <= childNo <= + * childCount()). */ <TransformedType> TransformedType transformChild(int childNo, Function<ITree<ContainedType>, TransformedType> transformer); @@ -186,12 +194,13 @@ public interface ITree<ContainedType> { * Transform the value that is the head of this node. * * @param <TransformedType> - * The type of the transformed value. + * The type of the transformed value. * * @param transformer - * The function to use to transform the value. + * The function to use to transform the value. * - * @return The transformed value. + * @return + * The transformed value. */ <TransformedType> TransformedType transformHead(Function<ContainedType, TransformedType> transformer); @@ -199,12 +208,13 @@ public interface ITree<ContainedType> { * Transform the tree into a tree with a different type of token. * * @param <MappedType> - * The type of the new tree. + * The type of the new tree. * * @param transformer - * The function to use to transform tokens. + * The function to use to transform tokens. * - * @return A tree with the token types transformed. + * @return + * A tree with the token types transformed. */ default <MappedType> ITree<MappedType> transformTree(final Function<ContainedType, MappedType> transformer) { return rebuildTree(transformer, transformer); @@ -214,10 +224,10 @@ public interface ITree<ContainedType> { * Perform an action on each part of the tree. * * @param linearizationMethod - * The way to traverse the tree. + * The way to traverse the tree. * * @param action - * The action to perform on each tree node. + * The action to perform on each tree node. */ void traverse(TreeLinearizationMethod linearizationMethod, Consumer<ContainedType> action); @@ -225,10 +235,11 @@ public interface ITree<ContainedType> { * Find the farthest to right child that satisfies the given predicate. * * @param childPred - * The predicate to satisfy. + * The predicate to satisfy. * - * @return The index of the right-most child that satisfies the - * predicate, or -1 if one doesn't exist. + * @return + * The index of the right-most child that satisfies the predicate, + * or -1 if one doesn't exist. */ int revFind(Predicate<ITree<ContainedType>> childPred); } diff --git a/base/src/main/java/bjc/utils/data/Identity.java b/base/src/main/java/bjc/utils/data/Identity.java index a8c8d70..3acb5aa 100644 --- a/base/src/main/java/bjc/utils/data/Identity.java +++ b/base/src/main/java/bjc/utils/data/Identity.java @@ -4,33 +4,27 @@ import java.util.function.Function; import java.util.function.UnaryOperator; /** - * @author ben - * - * @param <ContainedType> - */ -/** - * Simple implementation of IHolder that has no hidden behavior + * Simple implementation of IHolder that has no hidden behavior. * * @author ben * * @param <ContainedType> - * The type contained in the holder + * The type contained in the holder. */ public class Identity<ContainedType> implements IHolder<ContainedType> { + /* The held value. */ private ContainedType heldValue; - /** - * Create a holder holding null - */ + /** Create a holder holding null */ public Identity() { heldValue = null; } /** - * Create a holder holding the specified value + * Create a holder holding the specified value. * * @param value - * The value to hold + * The value to hold. */ public Identity(final ContainedType value) { heldValue = value; @@ -99,9 +93,10 @@ public class Identity<ContainedType> implements IHolder<ContainedType> { * Create a new identity container. * * @param val - * The contained value. + * The contained value. * - * @return A new identity container. + * @return + * A new identity container. */ public static <ContainedType> Identity<ContainedType> id(final ContainedType val) { return new Identity<>(val); @@ -110,9 +105,10 @@ public class Identity<ContainedType> implements IHolder<ContainedType> { /** * Create a new empty identity container. * - * @return A new empty identity container. + * @return + * A new empty identity container. */ public static <ContainedType> Identity<ContainedType> id() { return new Identity<>(); } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/Lazy.java b/base/src/main/java/bjc/utils/data/Lazy.java index ca41b62..fcebb70 100644 --- a/base/src/main/java/bjc/utils/data/Lazy.java +++ b/base/src/main/java/bjc/utils/data/Lazy.java @@ -10,26 +10,29 @@ import bjc.utils.funcdata.IList; /** * A holder that holds a means to create a value, but doesn't actually compute - * the value until it's needed + * the value until it's needed. * * @author ben * * @param <ContainedType> + * The type of the value being held. */ public class Lazy<ContainedType> implements IHolder<ContainedType> { + /* The supplier of the type. */ private Supplier<ContainedType> valueSupplier; - - private IList<UnaryOperator<ContainedType>> actions = new FunctionalList<>(); - + /* The actual type value. */ + private ContainedType heldValue; + /* Whether the value has been created. */ private boolean valueMaterialized; - private ContainedType heldValue; + /* The list of pending actions on the value. */ + private IList<UnaryOperator<ContainedType>> actions = new FunctionalList<>(); /** - * Create a new lazy value from the specified seed value + * Create a new lazy value from the specified seed value. * * @param value - * The seed value to use + * The seed value to use. */ public Lazy(final ContainedType value) { heldValue = value; @@ -38,10 +41,10 @@ public class Lazy<ContainedType> implements IHolder<ContainedType> { } /** - * Create a new lazy value from the specified value source + * Create a new lazy value from the specified value source. * * @param supp - * The source of a value to use + * The source of a value to use. */ public Lazy(final Supplier<ContainedType> supp) { valueSupplier = new SingleSupplier<>(supp); @@ -49,6 +52,7 @@ public class Lazy<ContainedType> implements IHolder<ContainedType> { valueMaterialized = false; } + /* Create a new value from a supplier and a list of actions. */ private Lazy(final Supplier<ContainedType> supp, final IList<UnaryOperator<ContainedType>> pendingActions) { valueSupplier = supp; @@ -171,9 +175,10 @@ public class Lazy<ContainedType> implements IHolder<ContainedType> { * Create a new lazy container with an already present value. * * @param val - * The value for the lazy container. + * The value for the lazy container. * - * @return A new lazy container holding that value. + * @return + * A new lazy container holding that value. */ public static <ContainedType> Lazy<ContainedType> lazy(final ContainedType val) { return new Lazy<>(val); @@ -183,10 +188,11 @@ public class Lazy<ContainedType> implements IHolder<ContainedType> { * Create a new lazy container with a suspended value. * * @param supp - * The suspended value for the lazy container. + * The suspended value for the lazy container. * - * @return A new lazy container that will un-suspend the value when - * necessary. + * @return + * A new lazy container that will un-suspend the value when + * necessary. */ public static <ContainedType> Lazy<ContainedType> lazy(final Supplier<ContainedType> supp) { return new Lazy<>(supp); diff --git a/base/src/main/java/bjc/utils/data/LazyPair.java b/base/src/main/java/bjc/utils/data/LazyPair.java index 5cb85f3..548a09e 100644 --- a/base/src/main/java/bjc/utils/data/LazyPair.java +++ b/base/src/main/java/bjc/utils/data/LazyPair.java @@ -8,56 +8,63 @@ import bjc.utils.data.internals.BoundLazyPair; import bjc.utils.data.internals.HalfBoundLazyPair; /** - * A lazy implementation of a pair + * A lazy implementation of a pair. * * @author ben * * @param <LeftType> - * The type on the left side of the pair - * @param <RightType> - * The type on the right side of the pair + * The type on the left side of the pair. * + * @param <RightType> + * The type on the right side of the pair. */ public class LazyPair<LeftType, RightType> implements IPair<LeftType, RightType> { - private LeftType leftValue; - private RightType rightValue; - - private Supplier<LeftType> leftSupplier; - private Supplier<RightType> rightSupplier; - + /* The supplier for the left value. */ + private Supplier<LeftType> leftSupplier; + /* The left value. */ + private LeftType leftValue; + /* Whether the left value has been created. */ private boolean leftMaterialized; + + /* The supplier for the right value. */ + private Supplier<RightType> rightSupplier; + /* The right value. */ + private RightType rightValue; + /* Whether the right value has been created. */ private boolean rightMaterialized; /** - * Create a new lazy pair, using the set values + * Create a new lazy pair, using the set values. * * @param leftVal - * The value for the left side of the pair + * The value for the left side of the pair. + * * @param rightVal - * The value for the right side of the pair + * The value for the right side of the pair. */ public LazyPair(final LeftType leftVal, final RightType rightVal) { - leftValue = leftVal; + leftValue = leftVal; rightValue = rightVal; - leftMaterialized = true; + leftMaterialized = true; rightMaterialized = true; } /** - * Create a new lazy pair from the given value sources + * Create a new lazy pair from the given value sources. * * @param leftSupp - * The source for a value on the left side of the pair + * The source for a value on the left side of the pair. + * * @param rightSupp - * The source for a value on the right side of the pair + * The source for a value on the right side of the pair. */ public LazyPair(final Supplier<LeftType> leftSupp, final Supplier<RightType> rightSupp) { - // Use single suppliers to catch double-instantiation bugs - leftSupplier = new SingleSupplier<>(leftSupp); + /* Use single suppliers to catch double-instantiation bugs. */ + leftSupplier = new SingleSupplier<>(leftSupp); rightSupplier = new SingleSupplier<>(rightSupp); - leftMaterialized = false; + leftMaterialized = false; rightMaterialized = false; } @@ -98,7 +105,7 @@ public class LazyPair<LeftType, RightType> implements IPair<LeftType, RightType> final BiFunction<RightType, OtherRight, CombinedRight> rightCombiner) { return otherPair.bind((otherLeft, otherRight) -> { return bind((leftVal, rightVal) -> { - final CombinedLeft left = leftCombiner.apply(leftVal, otherLeft); + final CombinedLeft left = leftCombiner.apply(leftVal, otherLeft); final CombinedRight right = rightCombiner.apply(rightVal, otherRight); return new LazyPair<>(left, right); diff --git a/base/src/main/java/bjc/utils/data/ListHolder.java b/base/src/main/java/bjc/utils/data/ListHolder.java index 142057c..4564466 100644 --- a/base/src/main/java/bjc/utils/data/ListHolder.java +++ b/base/src/main/java/bjc/utils/data/ListHolder.java @@ -8,21 +8,21 @@ import bjc.utils.funcdata.FunctionalList; import bjc.utils.funcdata.IList; /** - * A holder that represents a set of non-deterministic computations + * A holder that represents a set of non-deterministic computations. * * @author ben * * @param <ContainedType> - * The type of contained value + * The type of contained value. */ public class ListHolder<ContainedType> implements IHolder<ContainedType> { private IList<ContainedType> heldValues; /** - * Create a new list holder + * Create a new list holder. * * @param values - * The possible values for the computation + * The possible values for the computation. */ @SafeVarargs public ListHolder(final ContainedType... values) { @@ -35,6 +35,7 @@ public class ListHolder<ContainedType> implements IHolder<ContainedType> { } } + /* Create a new holder with values. */ private ListHolder(final IList<ContainedType> toHold) { heldValues = toHold; } diff --git a/base/src/main/java/bjc/utils/data/Option.java b/base/src/main/java/bjc/utils/data/Option.java index 37e0cde..6eae21f 100644 --- a/base/src/main/java/bjc/utils/data/Option.java +++ b/base/src/main/java/bjc/utils/data/Option.java @@ -4,21 +4,21 @@ import java.util.function.Function; import java.util.function.UnaryOperator; /** - * A holder that may or may not contain a value + * A holder that may or may not contain a value. * * @author ben * * @param <ContainedType> - * The type of the value that may or may not be held + * The type of the value that may or may not be held. */ public class Option<ContainedType> implements IHolder<ContainedType> { private ContainedType held; /** - * Create a new optional, using the given initial value + * Create a new optional, using the given initial value. * * @param seed - * The initial value for the optional + * The initial value for the optional. */ public Option(final ContainedType seed) { held = seed; diff --git a/base/src/main/java/bjc/utils/data/Pair.java b/base/src/main/java/bjc/utils/data/Pair.java index e6796ba..fb81e17 100644 --- a/base/src/main/java/bjc/utils/data/Pair.java +++ b/base/src/main/java/bjc/utils/data/Pair.java @@ -9,34 +9,33 @@ import java.util.function.Function; * @author ben * * @param <LeftType> - * The type of the left value + * The type of the left value. + * * @param <RightType> - * The type of the right value + * The type of the right value. */ public class Pair<LeftType, RightType> implements IPair<LeftType, RightType> { - // The left value + /* The left value. */ private LeftType leftValue; - - // The right value + /* The right value. */ private RightType rightValue; - /** - * Create a new pair with both sides set to null - */ + /** Create a new pair with both sides set to null. */ public Pair() { } /** - * Create a new pair with both sides set to the specified values + * Create a new pair with both sides set to the specified values. * * @param left - * The value of the left side + * The value of the left side. + * * @param right - * The value of the right side + * The value of the right side. */ public Pair(final LeftType left, final RightType right) { - leftValue = left; + leftValue = left; rightValue = right; } @@ -70,7 +69,7 @@ public class Pair<LeftType, RightType> implements IPair<LeftType, RightType> { final BiFunction<LeftType, OtherLeft, CombinedLeft> leftCombiner, final BiFunction<RightType, OtherRight, CombinedRight> rightCombiner) { return otherPair.bind((otherLeft, otherRight) -> { - final CombinedLeft left = leftCombiner.apply(leftValue, otherLeft); + final CombinedLeft left = leftCombiner.apply(leftValue, otherLeft); final CombinedRight right = rightCombiner.apply(rightValue, otherRight); return new Pair<>(left, right); diff --git a/base/src/main/java/bjc/utils/data/SingleIterator.java b/base/src/main/java/bjc/utils/data/SingleIterator.java index 4069c3f..1241a68 100644 --- a/base/src/main/java/bjc/utils/data/SingleIterator.java +++ b/base/src/main/java/bjc/utils/data/SingleIterator.java @@ -8,18 +8,19 @@ import java.util.Iterator; * @author EVE * * @param <T> - * The type of the item. + * The type of the item. */ public class SingleIterator<T> implements Iterator<T> { + /* The item being held. */ private final T itm; - + /* Whether we've yielded the item yet. */ private boolean yielded; /** * Create a iterator that yields a single item. * * @param item - * The item to yield. + * The item to yield. */ public SingleIterator(final T item) { itm = item; diff --git a/base/src/main/java/bjc/utils/data/SingleSupplier.java b/base/src/main/java/bjc/utils/data/SingleSupplier.java index c675ebf..60f9136 100644 --- a/base/src/main/java/bjc/utils/data/SingleSupplier.java +++ b/base/src/main/java/bjc/utils/data/SingleSupplier.java @@ -10,28 +10,33 @@ import java.util.function.Supplier; * @author ben * * @param <T> - * The supplied type + * The supplied type */ public class SingleSupplier<T> implements Supplier<T> { + /* The next supplier ID. */ private static long nextID = 0; - + /* The supplier to yield from. */ private final Supplier<T> source; - + /* Whether this value has been retrieved yet. */ private boolean gotten; - + /* The ID of this supplier. */ private final long id; /* - * This is bad practice, but I want to know where the single - * instantiation was, in case of duplicate initiations. + * The place where the supplier was instantiated. + * + * @NOTE + * This is both slow to create, and generally bad practice to keep + * exceptions around without throwing them. However, it is very + * useful to find where the first instantiation was. */ private Exception instSite; /** - * Create a new single supplier from an existing value + * Create a new single supplier from an existing value. * * @param supp - * The supplier to give a single value from + * The supplier to give a single value from. */ public SingleSupplier(final Supplier<T> supp) { source = supp; diff --git a/base/src/main/java/bjc/utils/data/Toggle.java b/base/src/main/java/bjc/utils/data/Toggle.java index 1e10dae..a1467e4 100644 --- a/base/src/main/java/bjc/utils/data/Toggle.java +++ b/base/src/main/java/bjc/utils/data/Toggle.java @@ -6,21 +6,23 @@ package bjc.utils.data; * @author EVE * * @param <E> - * The value stored in the toggle. + * The value stored in the toggle. */ public interface Toggle<E> { /** * Retrieve the currently-aligned value of this toggle, and swap the - * alignment. + * value to the new one. * - * @return The previously-aligned value. + * @return + * The previously-aligned value. */ E get(); /** * Retrieve the currently-aligned value without altering the alignment. * - * @return The currently-aligned value. + * @return + * The currently-aligned value. */ E peek(); @@ -28,8 +30,7 @@ public interface Toggle<E> { * Change the alignment of the toggle. * * @param isLeft - * Whether the toggle should be left-aligned or not. + * Whether the toggle should be left-aligned or not. */ void set(boolean isLeft); - -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/TopDownTransformIterator.java b/base/src/main/java/bjc/utils/data/TopDownTransformIterator.java index 1b87e52..c6b7d31 100644 --- a/base/src/main/java/bjc/utils/data/TopDownTransformIterator.java +++ b/base/src/main/java/bjc/utils/data/TopDownTransformIterator.java @@ -11,7 +11,9 @@ import java.util.function.Consumer; import java.util.function.Function; /* - * FIXME something is broken in here. fix it. + * @TODO 10/11/17 Ben Culkin :TopDownStep + * Figure out what is broken with this, and fix it so that step-wise + * iteration works correctly. */ public class TopDownTransformIterator<ContainedType> implements Iterator<ITree<ContainedType>> { private final Function<ContainedType, TopDownTransformResult> picker; diff --git a/base/src/main/java/bjc/utils/data/TopDownTransformResult.java b/base/src/main/java/bjc/utils/data/TopDownTransformResult.java index ed41eae..3907df2 100644 --- a/base/src/main/java/bjc/utils/data/TopDownTransformResult.java +++ b/base/src/main/java/bjc/utils/data/TopDownTransformResult.java @@ -1,34 +1,22 @@ package bjc.utils.data; /** - * Represents the results for doing a top-down transform of a tree + * Represents the results for doing a top-down transform of a tree. * * @author ben * */ public enum TopDownTransformResult { - /** - * Do not do anything to this node, and ignore its children - */ + /** Do not do anything to this node, and ignore its children. */ SKIP, - /** - * Transform this node, and don't touch its children - */ + /** Transform this node, and don't touch its children. */ TRANSFORM, - /** - * Transform this node, then do a top-down transform on the result - */ + /** Transform this node, then recursively transform the result. */ RTRANSFORM, - /** - * Ignore this node, and traverse its children - */ + /** Ignore this node, and traverse its children. */ PASSTHROUGH, - /** - * Traverse the nodes of this children, then transform it - */ + /** Traverse the nodes of this children, then transform it. */ PUSHDOWN, - /** - * Transform this node, then traverse its children - */ + /** Transform this node, then traverse its children. */ PULLUP; } diff --git a/base/src/main/java/bjc/utils/data/TransformIterator.java b/base/src/main/java/bjc/utils/data/TransformIterator.java index 50f28b1..5a6ac85 100644 --- a/base/src/main/java/bjc/utils/data/TransformIterator.java +++ b/base/src/main/java/bjc/utils/data/TransformIterator.java @@ -9,24 +9,25 @@ import java.util.function.Function; * @author EVE * * @param <S> - * The source iterator type. + * The source iterator type. * * @param <D> - * The destination iterator type. + * The destination iterator type. */ public class TransformIterator<S, D> implements Iterator<D> { + /* Our source of values. */ private final Iterator<S> source; - + /* Transform function. */ private final Function<S, D> transform; /** * Create a new transform iterator. * * @param source - * The source iterator to use. + * The source iterator to use. * * @param transform - * The transform to apply. + * The transform to apply. */ public TransformIterator(final Iterator<S> source, final Function<S, D> transform) { this.source = source; @@ -42,5 +43,4 @@ public class TransformIterator<S, D> implements Iterator<D> { public D next() { return transform.apply(source.next()); } - } diff --git a/base/src/main/java/bjc/utils/data/Tree.java b/base/src/main/java/bjc/utils/data/Tree.java index a52f699..386153b 100644 --- a/base/src/main/java/bjc/utils/data/Tree.java +++ b/base/src/main/java/bjc/utils/data/Tree.java @@ -16,22 +16,35 @@ import bjc.utils.functypes.ListFlattener; * @author ben * * @param <ContainedType> + * The type contained in the tree. */ public class Tree<ContainedType> implements ITree<ContainedType> { + /* The data/label for this node. */ private ContainedType data; - private IList<ITree<ContainedType>> children; - private boolean hasChildren; - private int childCount = 0; + /* The children of this node. */ + private IList<ITree<ContainedType>> children; - private int ID; - private static int nextID = 0; + /* Whether this node has children. */ + /* @NOTE + * Why have both this boolean and childCount? Why not just do a + * childCount == 0 + * whenever you'd check hasChildren? + */ + private boolean hasChildren; + /* The number of children this node has. */ + private int childCount = 0; + + /* The ID of this node. */ + private int ID; + /* The next ID to assign to a node. */ + private static int nextID = 0; /** * Create a new leaf node in a tree. * * @param leaf - * The data to store as a leaf node. + * The data to store as a leaf node. */ public Tree(final ContainedType leaf) { data = leaf; @@ -45,10 +58,10 @@ public class Tree<ContainedType> implements ITree<ContainedType> { * Create a new tree node with the specified children. * * @param leaf - * The data to hold in this node. + * The data to hold in this node. * * @param childrn - * A list of children for this node. + * A list of children for this node. */ public Tree(final ContainedType leaf, final IList<ITree<ContainedType>> childrn) { this(leaf); @@ -64,10 +77,10 @@ public class Tree<ContainedType> implements ITree<ContainedType> { * Create a new tree node with the specified children. * * @param leaf - * The data to hold in this node. + * The data to hold in this node. * * @param childrn - * A list of children for this node. + * A list of children for this node. */ @SafeVarargs public Tree(final ContainedType leaf, final ITree<ContainedType>... childrn) { @@ -126,15 +139,15 @@ public class Tree<ContainedType> implements ITree<ContainedType> { @Override public int revFind(final Predicate<ITree<ContainedType>> childPred) { - if (childCount == 0) + if (childCount == 0) { return -1; - else { + } else { for (int i = childCount - 1; i >= 0; i--) { if (childPred.test(getChild(i))) return i; } - } - return -1; + return -1; + } } @Override @@ -188,7 +201,7 @@ public class Tree<ContainedType> implements ITree<ContainedType> { final IList<ITree<ContainedType>> mappedChildren = children .map(child -> child.flatMapTree(mapper)); - mappedChildren.forEach(child -> flatMappedData.addChild(child)); + mappedChildren.forEach(flatMappedData::addChild); return flatMappedData; } @@ -196,6 +209,14 @@ public class Tree<ContainedType> implements ITree<ContainedType> { return mapper.apply(data); } + /* + * Do a collapse of this tree. + * + * @NOTE + * Why is this protected? I can't see any good reason someone'd + * want to override it. + */ + protected <NewType> NewType internalCollapse(final Function<ContainedType, NewType> leafTransform, final Function<ContainedType, ListFlattener<NewType>> nodeCollapser) { if (hasChildren) { @@ -236,7 +257,9 @@ public class Tree<ContainedType> implements ITree<ContainedType> { builder.append(">\t"); } - builder.append("Unknown node\n"); + builder.append("Unknown node of type "); + builder.append(child.getClass().getName()); + builder.append("\n"); } }); } @@ -250,7 +273,8 @@ public class Tree<ContainedType> implements ITree<ContainedType> { return child.rebuildTree(leafTransformer, operatorTransformer); }); - return new Tree<>(operatorTransformer.apply(data), mappedChildren); + final MappedType mapData = operatorTransformer.apply(data); + return new Tree<>(mapData, mappedChildren); } return new Tree<>(leafTransformer.apply(data)); @@ -318,7 +342,7 @@ public class Tree<ContainedType> implements ITree<ContainedType> { return result; default: - final String msg = String.format("Recieved unknown transform result %s", transformResult); + final String msg = String.format("Recieved unknown transform result type %s", transformResult); throw new IllegalArgumentException(msg); } @@ -362,6 +386,7 @@ public class Tree<ContainedType> implements ITree<ContainedType> { internalToString(builder, 1, true); + /* Delete a trailing nl. */ builder.deleteCharAt(builder.length() - 1); return builder.toString(); @@ -387,4 +412,4 @@ public class Tree<ContainedType> implements ITree<ContainedType> { return true; } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/ValueToggle.java b/base/src/main/java/bjc/utils/data/ValueToggle.java index 9193896..54c7a57 100644 --- a/base/src/main/java/bjc/utils/data/ValueToggle.java +++ b/base/src/main/java/bjc/utils/data/ValueToggle.java @@ -6,12 +6,14 @@ package bjc.utils.data; * @author EVE * * @param <E> - * The type of value to toggle between. + * The type of value to toggle between. */ public class ValueToggle<E> implements Toggle<E> { + /* Our left value. */ private final E lft; + /* Our right value. */ private final E rght; - + /* Our alignment. */ private final BooleanToggle alignment; /** @@ -20,10 +22,10 @@ public class ValueToggle<E> implements Toggle<E> { * All toggles start right-aligned. * * @param left - * The value when the toggle is left-aligned. + * The value when the toggle is left-aligned. * * @param right - * The value when the toggle is right-aligned. + * The value when the toggle is right-aligned. */ public ValueToggle(final E left, final E right) { lft = left; @@ -35,16 +37,20 @@ public class ValueToggle<E> implements Toggle<E> { @Override public E get() { - if (alignment.get()) + if (alignment.get()) { return lft; - else return rght; + } else { + return rght; + } } @Override public E peek() { - if (alignment.peek()) + if (alignment.peek()) { return lft; - else return rght; + } else { + return rght; + } } @Override diff --git a/base/src/main/java/bjc/utils/data/internals/BoundLazy.java b/base/src/main/java/bjc/utils/data/internals/BoundLazy.java index f71d32b..b160c0c 100644 --- a/base/src/main/java/bjc/utils/data/internals/BoundLazy.java +++ b/base/src/main/java/bjc/utils/data/internals/BoundLazy.java @@ -9,37 +9,35 @@ import bjc.utils.data.Lazy; import bjc.utils.funcdata.FunctionalList; import bjc.utils.funcdata.IList; -/* - * Implements a lazy holder that has been bound +/** + * Implements a lazy holder that has been bound. + * + * @author Ben Culkin */ public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundContainedType> { - /* - * The old value - */ + /* The old value. */ private final Supplier<IHolder<OldType>> oldSupplier; - /* - * The function to use to transform the old value into a new value - */ + /* The function to use to transform the old value into a new value. */ private final Function<OldType, IHolder<BoundContainedType>> binder; - /* - * The bound value being held - */ + /* The bound value being held. */ private IHolder<BoundContainedType> boundHolder; - /* - * Whether the bound value has been actualized or not - */ + /* Whether the bound value has been actualized or not. */ private boolean holderBound; - /* - * Transformations currently pending on the bound value - */ + /* Transformations currently pending on the bound value. */ private final IList<UnaryOperator<BoundContainedType>> actions = new FunctionalList<>(); - /* - * Create a new bound lazy value + /** + * Create a new bound lazy value. + * + * @param supp + * The supplier of the old value. + * + * @param binder + * The function to use to bind the old value to the new one. */ public BoundLazy(final Supplier<IHolder<OldType>> supp, final Function<OldType, IHolder<BoundContainedType>> binder) { @@ -51,28 +49,20 @@ public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundCont public <BoundType> IHolder<BoundType> bind(final Function<BoundContainedType, IHolder<BoundType>> bindr) { if (bindr == null) throw new NullPointerException("Binder must not be null"); - /* - * Prepare a list of pending actions - */ + /* Prepare a list of pending actions. */ final IList<UnaryOperator<BoundContainedType>> pendingActions = new FunctionalList<>(); actions.forEach(pendingActions::add); - /* - * Create the new supplier of a value - */ + /* Create the new supplier of a value. */ final Supplier<IHolder<BoundContainedType>> typeSupplier = () -> { IHolder<BoundContainedType> oldHolder = boundHolder; - /* - * Bind the value if it hasn't been bound before - */ + /* Bind the value if it hasn't been bound before. */ if (!holderBound) { oldHolder = oldSupplier.get().unwrap(binder); } - /* - * Apply all the pending actions - */ + /* Apply all the pending actions. */ return pendingActions.reduceAux(oldHolder, (action, state) -> { return state.transform(action); }, (value) -> value); @@ -95,19 +85,20 @@ public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundCont public <MappedType> IHolder<MappedType> map(final Function<BoundContainedType, MappedType> mapper) { if (mapper == null) throw new NullPointerException("Mapper must not be null"); - // Prepare a list of pending actions + /* Prepare a list of pending actions. */ final IList<UnaryOperator<BoundContainedType>> pendingActions = new FunctionalList<>(); actions.forEach(pendingActions::add); - // Prepare the new supplier + /* Prepare the new supplier. */ final Supplier<MappedType> typeSupplier = () -> { IHolder<BoundContainedType> oldHolder = boundHolder; - // Bound the value if it hasn't been bound + /* Bound the value if it hasn't been bound. */ if (!holderBound) { oldHolder = oldSupplier.get().unwrap(binder); } + /* Apply pending actions. */ return pendingActions.reduceAux(oldHolder.getValue(), (action, state) -> { return action.apply(state); }, (value) -> mapper.apply(value)); @@ -142,4 +133,4 @@ public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundCont return boundHolder.unwrap(unwrapper); } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java b/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java index df6e60b..df2f0d8 100644 --- a/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java +++ b/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java @@ -9,34 +9,38 @@ import bjc.utils.data.IPair; import bjc.utils.data.Identity; import bjc.utils.data.LazyPair; -/* - * Implements a lazy pair that has been bound +/** + * Implements a lazy pair that has been bound. + * + * @author Ben Culkin */ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPair<NewLeft, NewRight> { - /* - * The supplier of the left value - */ + /* The supplier of the left value. */ private final Supplier<OldLeft> leftSupplier; - /* - * The supplier of the right value - */ + /* The supplier of the right value. */ private final Supplier<OldRight> rightSupplier; - /* - * The binder to transform values - */ + /* The binder to transform values. */ private final BiFunction<OldLeft, OldRight, IPair<NewLeft, NewRight>> binder; - /* - * The bound pair - */ + /* The bound pair. */ private IPair<NewLeft, NewRight> boundPair; - /* - * Whether the pair has been bound yet - */ + /* Whether the pair has been bound yet. */ private boolean pairBound; + /** + * Create a new bound lazy pair. + * + * @param leftSupp + * The supplier for the left value. + * + * @param rightSupp + * The supplier for the right value. + * + * @param bindr + * The function to use to bind the left and right into a new pair. + */ public BoundLazyPair(final Supplier<OldLeft> leftSupp, final Supplier<OldRight> rightSupp, final BiFunction<OldLeft, OldRight, IPair<NewLeft, NewRight>> bindr) { leftSupplier = leftSupp; @@ -50,10 +54,14 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai if (bindr == null) throw new NullPointerException("Binder must not be null"); final IHolder<IPair<NewLeft, NewRight>> newPair = new Identity<>(boundPair); - final IHolder<Boolean> newPairMade = new Identity<>(pairBound); + final IHolder<Boolean> newPairMade = new Identity<>(pairBound); final Supplier<NewLeft> leftSupp = () -> { if (!newPairMade.getValue()) { + /* + * If the pair hasn't been bound before, bind + * it. + */ newPair.replace(binder.apply(leftSupplier.get(), rightSupplier.get())); newPairMade.replace(true); @@ -64,6 +72,10 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai final Supplier<NewRight> rightSupp = () -> { if (!newPairMade.getValue()) { + /* + * If the pair hasn't been bound before, bind + * it. + */ newPair.replace(binder.apply(leftSupplier.get(), rightSupplier.get())); newPairMade.replace(true); @@ -84,6 +96,10 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai IPair<NewLeft, NewRight> newPair = boundPair; if (!pairBound) { + /* + * If the pair hasn't been bound before, bind + * it. + */ newPair = binder.apply(leftSupplier.get(), rightSupplier.get()); } @@ -102,6 +118,10 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai IPair<NewLeft, NewRight> newPair = boundPair; if (!pairBound) { + /* + * If the pair hasn't been bound before, bind + * it. + */ newPair = binder.apply(leftSupplier.get(), rightSupplier.get()); } @@ -116,16 +136,20 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai final IPair<OtherLeft, OtherRight> otherPair, final BiFunction<NewLeft, OtherLeft, CombinedLeft> leftCombiner, final BiFunction<NewRight, OtherRight, CombinedRight> rightCombiner) { - if (otherPair == null) + if (otherPair == null) { throw new NullPointerException("Other pair must not be null"); - else if (leftCombiner == null) + } else if (leftCombiner == null) { throw new NullPointerException("Left combiner must not be null"); - else if (rightCombiner == null) throw new NullPointerException("Right combiner must not be null"); + } else if (rightCombiner == null) { + throw new NullPointerException("Right combiner must not be null"); + } return otherPair.bind((otherLeft, otherRight) -> { return bind((leftVal, rightVal) -> { - return new LazyPair<>(leftCombiner.apply(leftVal, otherLeft), - rightCombiner.apply(rightVal, otherRight)); + CombinedLeft cLeft = leftCombiner.apply(leftVal, otherLeft); + CombinedRight cRight = rightCombiner.apply(rightVal, otherRight); + + return new LazyPair<>(cLeft, cRight); }); }); } @@ -182,6 +206,9 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai if (merger == null) throw new NullPointerException("Merger must not be null"); if (!pairBound) { + /* + * If the pair isn't bound yet, bind it. + */ boundPair = binder.apply(leftSupplier.get(), rightSupplier.get()); pairBound = true; @@ -196,4 +223,4 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai return "(un-materialized)"; } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java b/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java index f3799fd..8f9e87f 100644 --- a/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java +++ b/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java @@ -7,12 +7,21 @@ import bjc.utils.data.IHolder; import bjc.utils.data.ListHolder; import bjc.utils.funcdata.IList; -/* - * Holds a list, converted into a holder +/** + * Holds a list, converted into a holder. + * + * @author Ben Culkin */ public class BoundListHolder<ContainedType> implements IHolder<ContainedType> { + /* The list of contained holders. */ private final IList<IHolder<ContainedType>> heldHolders; + /** + * Create a new list of holders. + * + * @param toHold + * The list of holders to, well, hold. + */ public BoundListHolder(final IList<IHolder<ContainedType>> toHold) { heldHolders = toHold; } @@ -63,6 +72,10 @@ public class BoundListHolder<ContainedType> implements IHolder<ContainedType> { public <UnwrappedType> UnwrappedType unwrap(final Function<ContainedType, UnwrappedType> unwrapper) { if (unwrapper == null) throw new NullPointerException("Unwrapper must not be null"); + /* + * @NOTE + * Is there another way we could want to do this? + */ return heldHolders.randItem().unwrap(unwrapper); } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java b/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java index 8cac38b..c3606ef 100644 --- a/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java +++ b/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java @@ -10,16 +10,39 @@ import bjc.utils.data.Identity; import bjc.utils.data.LazyPair; /* - * A lazy pair, with only one side bound + * @NOTE + * I am not convinced that this code works correctly. Tests should be + * written to make sure things only ever get instantiated once. + * + * Namely, my main concern is to whether the places that bind the pair + * without setting pairBound are doing the right thing. + */ +/** + * A lazy pair, with only one side bound. + * + * @author Ben Culkin */ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewLeft, NewRight> { + /* The supplier of the old value. */ private final Supplier<OldType> oldSupplier; + /* The function to transform the old value into a new pair. */ private final Function<OldType, IPair<NewLeft, NewRight>> binder; + /* The new bound pair. */ private IPair<NewLeft, NewRight> boundPair; + /* Has the pair been bound yet or not? */ private boolean pairBound; + /** + * Create a new half-bound lazy pair. + * + * @param oldSupp + * The supplier of the old value. + * + * @param bindr + * The function to use to create the pair from the old value. + */ public HalfBoundLazyPair(final Supplier<OldType> oldSupp, final Function<OldType, IPair<NewLeft, NewRight>> bindr) { oldSupplier = oldSupp; @@ -34,6 +57,7 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL final Supplier<NewLeft> leftSupp = () -> { if (!newPairMade.getValue()) { + /* Bind the pair if it hasn't been bound yet. */ newPair.replace(binder.apply(oldSupplier.get())); newPairMade.replace(true); } @@ -43,6 +67,7 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL final Supplier<NewRight> rightSupp = () -> { if (!newPairMade.getValue()) { + /* Bind the pair if it hasn't been bound yet. */ newPair.replace(binder.apply(oldSupplier.get())); newPairMade.replace(true); } @@ -92,8 +117,10 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL final BiFunction<NewRight, OtherRight, CombinedRight> rightCombiner) { return otherPair.bind((otherLeft, otherRight) -> { return bind((leftVal, rightVal) -> { - return new LazyPair<>(leftCombiner.apply(leftVal, otherLeft), - rightCombiner.apply(rightVal, otherRight)); + CombinedLeft cLeft = leftCombiner.apply(leftVal, otherLeft); + CombinedRight cRight = rightCombiner.apply(rightVal, otherRight); + + return new LazyPair<>(cLeft, cRight); }); }); } @@ -146,4 +173,4 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL return boundPair.merge(merger); } -}
\ No newline at end of file +} diff --git a/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java b/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java index 4175724..a5c8130 100644 --- a/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java +++ b/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java @@ -6,15 +6,33 @@ import java.util.function.UnaryOperator; import bjc.utils.data.IHolder; import bjc.utils.data.Lazy; +/** + * A wrapped lazy value. + * + * @author Ben Culkin + */ public class WrappedLazy<ContainedType> implements IHolder<ContainedType> { + /* Held value. */ private final IHolder<IHolder<ContainedType>> held; + /** + * Create a new wrapped lazy value. + * + * @param wrappedHolder + * The holder to make lazy. + */ public WrappedLazy(final IHolder<ContainedType> wrappedHolder) { held = new Lazy<>(wrappedHolder); } - // This has an extra parameter, because otherwise it erases to the same - // as the public one + /* + * This has an extra parameter, because otherwise it erases to the same + * as the public one. + * + * This is a case where reified generics would be useful, because then + * the compiler could know which one we meant without the dummy + * parameter. + */ private WrappedLazy(final IHolder<IHolder<ContainedType>> wrappedHolder, final boolean dummy) { held = wrappedHolder; } diff --git a/base/src/main/java/bjc/utils/data/internals/WrappedOption.java b/base/src/main/java/bjc/utils/data/internals/WrappedOption.java index 512c699..872295f 100644 --- a/base/src/main/java/bjc/utils/data/internals/WrappedOption.java +++ b/base/src/main/java/bjc/utils/data/internals/WrappedOption.java @@ -6,13 +6,30 @@ import java.util.function.UnaryOperator; import bjc.utils.data.IHolder; import bjc.utils.data.Option; +/** + * A wrapped optional value. + * + * @author Ben Culkin. + */ public class WrappedOption<ContainedType> implements IHolder<ContainedType> { + /* The held value. */ private final IHolder<IHolder<ContainedType>> held; + /** + * Create a new wrapped option. + * + * @param seedValue + * The value to wrap. + */ public WrappedOption(final IHolder<ContainedType> seedValue) { held = new Option<>(seedValue); } + /* + * The dummy parameter is to ensure the compiler can pick the right + * method, because without this method erases to the same type as the + * public one. + */ private WrappedOption(final IHolder<IHolder<ContainedType>> toHold, final boolean dummy) { held = toHold; } |