From 8923edffdb36b790014ff47301e53f7ede93ea0d Mon Sep 17 00:00:00 2001 From: "Benjamin J. Culkin" Date: Wed, 11 Oct 2017 22:49:16 -0300 Subject: Cleanup more --- .../utils/funcdata/FunctionalStringTokenizer.java | 75 +++--- base/src/main/java/bjc/utils/funcdata/IList.java | 251 ++++++++++++--------- base/src/main/java/bjc/utils/funcdata/IMap.java | 82 ++++--- .../main/java/bjc/utils/funcdata/SentryList.java | 8 +- .../bjc/utils/funcdata/TransformedValueMap.java | 26 ++- 5 files changed, 261 insertions(+), 181 deletions(-) (limited to 'base/src/main/java/bjc/utils/funcdata') diff --git a/base/src/main/java/bjc/utils/funcdata/FunctionalStringTokenizer.java b/base/src/main/java/bjc/utils/funcdata/FunctionalStringTokenizer.java index e068b46..384572d 100644 --- a/base/src/main/java/bjc/utils/funcdata/FunctionalStringTokenizer.java +++ b/base/src/main/java/bjc/utils/funcdata/FunctionalStringTokenizer.java @@ -5,18 +5,19 @@ import java.util.function.Consumer; import java.util.function.Function; /** - * A string tokenizer that exposes a functional interface + * A string tokenizer that exposes a functional interface. * * @author ben - * */ public class FunctionalStringTokenizer { /** * Create a new tokenizer from the specified string. * * @param strang - * The string to create a tokenizer from. - * @return A new tokenizer that splits the provided string on spaces. + * The string to create a tokenizer from. + * + * @return + * A new tokenizer that splits the provided string on spaces. */ public static FunctionalStringTokenizer fromString(final String strang) { if (strang == null) throw new NullPointerException("String to tokenize must be non-null"); @@ -24,16 +25,14 @@ public class FunctionalStringTokenizer { return new FunctionalStringTokenizer(new StringTokenizer(strang, " ")); } - /* - * The string tokenizer being driven - */ + /* The string tokenizer being driven */ private final StringTokenizer input; /** - * Create a functional string tokenizer from a given string + * Create a functional string tokenizer from a given string. * * @param inp - * The string to tokenize + * The string to tokenize. */ public FunctionalStringTokenizer(final String inp) { if (inp == null) throw new NullPointerException("String to tokenize must be non-null"); @@ -43,26 +42,29 @@ public class FunctionalStringTokenizer { /** * Create a functional string tokenizer from a given string and set of - * separators + * separators. * * @param input - * The string to tokenize + * The string to tokenize. + * * @param seperators - * The set of separating tokens to use for splitting + * The set of separating tokens to use for splitting. */ public FunctionalStringTokenizer(final String input, final String seperators) { - if (input == null) + if (input == null) { throw new NullPointerException("String to tokenize must not be null"); - else if (seperators == null) throw new NullPointerException("Tokens to split on must not be null"); + } else if (seperators == null) { + throw new NullPointerException("Tokens to split on must not be null"); + } this.input = new StringTokenizer(input, seperators); } /** - * Create a functional string tokenizer from a non-functional one + * Create a functional string tokenizer from a non-functional one. * * @param toWrap - * The non-functional string tokenizer to wrap + * The non-functional string tokenizer to wrap. */ public FunctionalStringTokenizer(final StringTokenizer toWrap) { if (toWrap == null) throw new NullPointerException("Wrapped tokenizer must not be null"); @@ -71,10 +73,10 @@ public class FunctionalStringTokenizer { } /** - * Execute a provided action for each of the remaining tokens + * Execute a provided action for each of the remaining tokens. * * @param action - * The action to execute for each token + * The action to execute for each token. */ public void forEachToken(final Consumer action) { if (action == null) throw new NullPointerException("Action must not be null"); @@ -85,18 +87,20 @@ public class FunctionalStringTokenizer { } /** - * Get the string tokenizer encapsulated by this tokenizer + * Get the string tokenizer encapsulated by this tokenizer. * - * @return The encapsulated tokenizer + * @return + * The encapsulated tokenizer. */ public StringTokenizer getInternal() { return input; } /** - * Check if this tokenizer has more tokens + * Check if this tokenizer has more tokens. * - * @return Whether or not this tokenizer has more tokens + * @return + * Whether or not this tokenizer has more tokens. */ public boolean hasMoreTokens() { return input.hasMoreTokens(); @@ -105,22 +109,25 @@ public class FunctionalStringTokenizer { /** * Return the next token from the tokenizer. * - * Returns null if no more tokens are available - * - * @return The next token from the tokenizer + * @return + * The next token from the tokenizer, or null if no more tokens are + * available. */ public String nextToken() { - if (input.hasMoreTokens()) // Return the next available token + if (input.hasMoreTokens()) { + /* Return the next available token. */ return input.nextToken(); + } - // Return no token + /* Return no token. */ return null; } /** - * Convert this tokenizer into a list of strings + * Convert this tokenizer into a list of strings. * - * @return This tokenizer, converted into a list of strings + * @return + * This tokenizer, converted into a list of strings. */ public IList toList() { return toList((final String element) -> element); @@ -131,18 +138,20 @@ public class FunctionalStringTokenizer { * the input from this tokenizer. * * @param - * The type of the converted tokens + * The type of the converted tokens. * * @param transformer - * The function to use to convert tokens. - * @return A list containing all of the converted tokens. + * The function to use to convert tokens. + * + * @return + * A list containing all of the converted tokens. */ public IList toList(final Function transformer) { if (transformer == null) throw new NullPointerException("Transformer must not be null"); final IList returned = new FunctionalList<>(); - // Add each token to the list after transforming it + /* Add each token to the list after transforming it. */ forEachToken(token -> { final E transformedToken = transformer.apply(token); diff --git a/base/src/main/java/bjc/utils/funcdata/IList.java b/base/src/main/java/bjc/utils/funcdata/IList.java index 28c09d0..4dd2b1a 100644 --- a/base/src/main/java/bjc/utils/funcdata/IList.java +++ b/base/src/main/java/bjc/utils/funcdata/IList.java @@ -18,25 +18,28 @@ import bjc.utils.functypes.ID; * @author ben * * @param - * The type in this list + * The type in this list */ public interface IList extends Iterable { /** - * Add an item to this list + * Add an item to this list. * * @param item - * The item to add to this list. - * @return Whether the item was added to the list successfully. + * The item to add to this list. + * + * @return + * Whether the item was added to the list successfully.. */ boolean add(ContainedType item); /** - * Add all of the elements in the provided list to this list + * Add all of the elements in the provided list to this list. * * @param items - * The list of items to add - * @return True if every item was successfully added to the list, false - * otherwise + * The list of items to add. + * + * @return + * True if every item was successfully added to the list, false otherwise. */ default boolean addAll(final IList items) { return items.map(this::add).anyMatch(bl -> bl == false); @@ -46,10 +49,11 @@ public interface IList extends Iterable { * Add all of the elements in the provided array to this list. * * @param items - * The array of items to add. + * The array of items to add. * - * @return True if every item was successfully added to the list, false - * otherwise. + * @return + * True if every item was successfully added to the list, false + * otherwise. */ @SuppressWarnings("unchecked") default boolean addAll(final ContainedType... items) { @@ -69,9 +73,11 @@ public interface IList extends Iterable { * predicate. * * @param matcher - * The predicate to use for checking. - * @return Whether all of the elements of the list match the specified - * predicate. + * The predicate to use for checking. + * + * @return + * Whether all of the elements of the list match the specified + * predicate. */ boolean allMatch(Predicate matcher); @@ -79,22 +85,27 @@ public interface IList extends Iterable { * Check if any of the elements in this list match the specified list. * * @param matcher - * The predicate to use for checking. - * @return Whether any element in the list matches the provided - * predicate. + * The predicate to use for checking. + * + * @return + * Whether any element in the list matches the provided predicate. */ boolean anyMatch(Predicate matcher); /** - * Reduce the contents of this list using a collector + * Reduce the contents of this list using a collector. * * @param - * The intermediate accumulation type + * The intermediate accumulation type. + * * @param - * The final, reduced type + * The final, reduced type. + * * @param collector - * The collector to use for reduction - * @return The reduced list + * The collector to use for reduction. + * + * @return + * The reduced list. */ default ReducedType collect( final Collector collector) { @@ -119,32 +130,39 @@ public interface IList extends Iterable { * list and the combined one. * * @param - * The type of the second list + * The type of the second list. + * * @param - * The type of the combined list + * The type of the combined list. * * @param list - * The list to combine with + * The list to combine with. + * * @param combiner - * The function to use for combining element pairs. - * @return A new list containing the merged pairs of lists. + * The function to use for combining element pairs. + * + * @return + * A new list containing the merged pairs of lists. */ IList combineWith(IList list, BiFunction combiner); /** - * Check if the list contains the specified item + * Check if the list contains the specified item. * * @param item - * The item to see if it is contained - * @return Whether or not the specified item is in the list + * The item to see if it is contained. + * + * @return + * Whether or not the specified item is in the list. */ boolean contains(ContainedType item); /** - * Get the first element in the list + * Get the first element in the list. * - * @return The first element in this list. + * @return + * The first element in this list. */ ContainedType first(); @@ -155,20 +173,22 @@ public interface IList extends Iterable { * Does not change the underlying list. * * @param - * The type of the flattened list + * The type of the flattened list. * * @param expander - * The function to apply to each member of the list. - * @return A new list containing the flattened results of applying the - * provided function. + * The function to apply to each member of the list. + * + * @return + * A new list containing the flattened results of applying the + * provided function. */ IList flatMap(Function> expander); /** - * Apply a given action for each member of the list + * Apply a given action for each member of the list. * * @param action - * The action to apply to each member of the list. + * The action to apply to each member of the list. */ @Override void forEach(Consumer action); @@ -177,8 +197,7 @@ public interface IList extends Iterable { * Apply a given function to each element in the list and its index. * * @param action - * The function to apply to each element in the list and - * its index. + * The function to apply to each element in the list and its index. */ void forEachIndexed(BiConsumer action); @@ -186,31 +205,37 @@ public interface IList extends Iterable { * Retrieve a value in the list by its index. * * @param index - * The index to retrieve a value from. - * @return The value at the specified index in the list. + * The index to retrieve a value from. + * + * @return + * The value at the specified index in the list. */ ContainedType getByIndex(int index); /** - * Retrieve a list containing all elements matching a predicate + * Retrieve a list containing all elements matching a predicate. * * @param predicate - * The predicate to match by - * @return A list containing all elements that match the predicate + * The predicate to match by. + * + * @return + * A list containing all elements that match the predicate. */ IList getMatching(Predicate predicate); /** - * Retrieve the size of the wrapped list + * Retrieve the size of the wrapped list. * - * @return The size of the wrapped list + * @return + * The size of the wrapped list. */ int getSize(); /** * Check if this list is empty. * - * @return Whether or not this list is empty. + * @return + * Whether or not this list is empty. */ boolean isEmpty(); @@ -221,42 +246,48 @@ public interface IList extends Iterable { * Does not change the underlying list. * * @param - * The type of the transformed list + * The type of the transformed list. * * @param transformer - * The function to apply to each element in the list - * @return A new list containing the mapped elements of this list. + * The function to apply to each element in the list. + * + * @return + * A new list containing the mapped elements of this list. */ IList map(Function transformer); /** - * Zip two lists into a list of pairs + * Zip two lists into a list of pairs. * * @param - * The type of the second list + * The type of the second list. * * @param list - * The list to use as the left side of the pair - * @return A list containing pairs of this element and the specified - * list + * The list to use as the left side of the pair. + * + * @return + * A list containing pairs of this element and the specified list. */ IList> pairWith(IList list); /** - * Partition this list into a list of sublists + * Partition this list into a list of sublists. * * @param partitionSize - * The size of elements to put into each one of the - * sublists - * @return A list partitioned into partitions of size nPerPart + * The size of elements to put into each one of the sublists. + * + * @return + * A list partitioned into partitions of size partitionSize. The last + * partition may not be completely full if the size of the list is + * not a multiple of partitionSize. */ IList> partition(int partitionSize); /** - * Prepend an item to the list + * Prepend an item to the list. * * @param item - * The item to prepend to the list + * The item to prepend to the list. */ void prepend(ContainedType item); @@ -264,7 +295,7 @@ public interface IList extends Iterable { * Prepend an array of items to the list. * * @param items - * The items to prepend to the list. + * The items to prepend to the list. */ @SuppressWarnings("unchecked") default void prependAll(final ContainedType... items) { @@ -275,9 +306,10 @@ public interface IList extends Iterable { /** * Select a random item from the list, using a default random number - * generator + * generator. * - * @return A random item from the list + * @return + * A random item from the list */ default ContainedType randItem() { return randItem(num -> (int) (Math.random() * num)); @@ -288,8 +320,10 @@ public interface IList extends Iterable { * generator. * * @param rnd - * The random number generator to use. - * @return A random element from this list. + * The random number generator to use. + * + * @return + * A random element from this list. */ ContainedType randItem(Function rnd); @@ -297,20 +331,25 @@ public interface IList extends Iterable { * Reduce this list to a single value, using a accumulative approach. * * @param - * The in-between type of the values + * The in-between type of the values + * * @param - * The final value type + * The final value type * * @param initial - * The initial value of the accumulative state. + * The initial value of the accumulative state. + * * @param accumulator - * The function to use to combine a list element with the - * accumulative state. + * The function to use to combine a list element with the + * accumulative state. + * * @param transformer - * The function to use to convert the accumulative state - * into a final result. - * @return A single value condensed from this list and transformed into - * its final state. + * The function to use to convert the accumulative state into a + * final result. + * + * @return + * A single value condensed from this list and transformed into its + * final state. */ ReducedType reduceAux(StateType initial, BiFunction accumulator, @@ -320,16 +359,17 @@ public interface IList extends Iterable { * Reduce this list to a single value, using a accumulative approach. * * @param - * The in-between type of the values. + * The in-between type of the values. * * @param initial - * The initial value of the accumulative state. + * The initial value of the accumulative state. * * @param accumulator - * The function to use to combine a list element with the - * accumulative state. + * The function to use to combine a list element with the + * accumulative state. * - * @return A single value condensed from this list. + * @return + * A single value condensed from this list. */ default StateType reduceAux(StateType initial, BiFunction accumulator) { @@ -337,25 +377,25 @@ public interface IList extends Iterable { } /** - * Remove all elements that match a given predicate + * Remove all elements that match a given predicate. * * @param predicate - * The predicate to use to determine elements to delete - * @return Whether there was anything that satisfied the predicate + * The predicate to use to determine elements to delete. + * + * @return + * Whether there was anything that satisfied the predicate. */ boolean removeIf(Predicate predicate); /** - * Remove all parameters that match a given parameter + * Remove all parameters that match a given parameter. * * @param element - * The object to remove all matching copies of + * The object to remove all matching copies of. */ void removeMatching(ContainedType element); - /** - * Reverse the contents of this list in place - */ + /** Reverse the contents of this list in place. */ void reverse(); /** @@ -366,11 +406,14 @@ public interface IList extends Iterable { * hand. * * @param key - * The key to search for. + * The key to search for. + * * @param comparator - * The way to compare elements for searching. Pass null - * to use the natural ordering for E - * @return The element if it is in this list, or null if it is not. + * The way to compare elements for searching. Pass null to use the + * natural ordering for E. + * + * @return + * The element if it is in this list, or null if it is not. */ ContainedType search(ContainedType key, Comparator comparator); @@ -381,31 +424,35 @@ public interface IList extends Iterable { * Does change the underlying list. * * @param comparator - * The way to compare elements for sorting. Pass null to - * use E's natural ordering + * The way to compare elements for sorting. Pass null to use E's + * natural ordering */ void sort(Comparator comparator); /** - * Get the tail of this list (the list without the first element + * Get the tail of this list (the list without the first element). * - * @return The list without the first element + * @return + * The list without the first element. */ IList tail(); /** - * Convert this list into an array + * Convert this list into an array. * * @param type - * The type of array to return - * @return The list, as an array + * The type of array to return. + * + * @return + * The list, as an array. */ ContainedType[] toArray(ContainedType[] type); /** - * Convert the list into a Iterable + * Convert the list into a Iterable. * - * @return An iterable view onto the list + * @return + * An iterable view onto the list. */ Iterable toIterable(); diff --git a/base/src/main/java/bjc/utils/funcdata/IMap.java b/base/src/main/java/bjc/utils/funcdata/IMap.java index 0ee7375..0262c13 100644 --- a/base/src/main/java/bjc/utils/funcdata/IMap.java +++ b/base/src/main/java/bjc/utils/funcdata/IMap.java @@ -10,17 +10,17 @@ import java.util.function.Function; * @author ben * * @param - * The type of this map's keys. + * The type of this map's keys. * * @param - * The type of this map's values. + * The type of this map's values. */ public interface IMap { /** * Execute an action for each entry in the map. * * @param action - * the action to execute for each entry in the map. + * The action to execute for each entry in the map. */ void forEach(BiConsumer action); @@ -28,7 +28,7 @@ public interface IMap { * Perform an action for each key in the map. * * @param action - * The action to perform on each key in the map. + * The action to perform on each key in the map. */ default void forEachKey(final Consumer action) { forEach((key, val) -> action.accept(key)); @@ -38,7 +38,7 @@ public interface IMap { * Perform an action for each value in the map. * * @param action - * The action to perform on each value in the map. + * The action to perform on each value in the map. */ default void forEachValue(final Consumer action) { forEach((key, val) -> action.accept(val)); @@ -48,9 +48,10 @@ public interface IMap { * Check if this map contains the specified key. * * @param key - * The key to check. + * The key to check. * - * @return Whether or not the map contains the key. + * @return + * Whether or not the map contains the key. */ boolean containsKey(KeyType key); @@ -58,9 +59,10 @@ public interface IMap { * Get the value assigned to the given key. * * @param key - * The key to look for a value under. + * The key to look for a value under. * - * @return The value of the key. + * @return + * The value of the key. */ ValueType get(KeyType key); @@ -69,13 +71,14 @@ public interface IMap { * doesn't exist. * * @param key - * The key to attempt to retrieve. + * The key to attempt to retrieve. * * @param defaultValue - * The value to return if the key doesn't exist. + * The value to return if the key doesn't exist. * - * @return The value associated with the key, or the default value if - * the key doesn't exist. + * @return + * The value associated with the key, or the default value if the + * key doesn't exist. */ default ValueType getOrDefault(final KeyType key, final ValueType defaultValue) { try { @@ -93,24 +96,22 @@ public interface IMap { * Add an entry to the map. * * @param key - * The key to put the value under. + * The key to put the value under. * * @param val - * The value to add. + * The value to add. * - * @return The previous value of the key in the map, or null if the key - * wasn't in the map. However, note that it may also return null - * if the key was set to null. + * @return + * The previous value of the key in the map, or null if the key + * wasn't in the map. However, note that it may also return null if + * the key was set to null. * * @throws UnsupportedOperationException - * if the map implementation doesn't support modifying - * the map + * If the map implementation doesn't support modifying the map. */ ValueType put(KeyType key, ValueType val); - /** - * Delete all the values in the map. - */ + /** Delete all the values in the map. */ default void clear() { keyList().forEach(key -> remove(key)); } @@ -118,12 +119,18 @@ public interface IMap { /** * Get the number of entries in this map. * - * @return The number of entries in this map. + * @return + * The number of entries in this map. */ default int size() { return keyList().getSize(); } + /* @NOTE + * Do we want this to be the semantics for transform, or do we want + * to go to semantics using something like Isomorphism, or doing a + * one-time bulk conversion of the values? + */ /** * Transform the values returned by this map. * @@ -132,12 +139,13 @@ public interface IMap { * likely not work as expected. * * @param - * The new type of returned values. + * The new type of returned values. * * @param transformer - * The function to use to transform values. + * The function to use to transform values. * - * @return The map where each value will be transformed after lookup. + * @return + * The map where each value will be transformed after lookup. */ default IMap transform(final Function transformer) { return new TransformedValueMap<>(this, transformer); @@ -147,7 +155,8 @@ public interface IMap { * Extends this map, creating a new map that will delegate queries to * the map, but store any added values itself. * - * @return An extended map. + * @return + * An extended map. */ IMap extend(); @@ -155,26 +164,29 @@ public interface IMap { * Remove the value bound to the key. * * @param key - * The key to remove from the map. + * The key to remove from the map. * - * @return The previous value for the key in the map, or null if the key - * wasn't in the class. NOTE: Just because you received null, - * doesn't mean the map wasn't changed. It may mean that someone - * put a null value for that key into the map. + * @return + * The previous value for the key in the map, or null if the key + * wasn't in the class. NOTE: Just because you received null, + * doesn't mean the map wasn't changed. It may mean that someone + * put a null value for that key into the map. */ ValueType remove(KeyType key); /** * Get a list of all the keys in this map. * - * @return A list of all the keys in this map. + * @return + * A list of all the keys in this map. */ IList keyList(); /** * Get a list of the values in this map. * - * @return A list of values in this map. + * @return + * A list of values in this map. */ default IList valueList() { final IList returns = new FunctionalList<>(); diff --git a/base/src/main/java/bjc/utils/funcdata/SentryList.java b/base/src/main/java/bjc/utils/funcdata/SentryList.java index c322743..1040328 100644 --- a/base/src/main/java/bjc/utils/funcdata/SentryList.java +++ b/base/src/main/java/bjc/utils/funcdata/SentryList.java @@ -8,12 +8,10 @@ import java.util.List; * @author bjculkin * * @param - * The type of item in the list. + * The type of item in the list. */ public class SentryList extends FunctionalList { - /** - * Create a new sentry list. - */ + /** Create a new sentry list. */ public SentryList() { super(); } @@ -22,7 +20,7 @@ public class SentryList extends FunctionalList { * Create a new sentry list backed by an existing list. * * @param backing - * The backing list. + * The backing list. */ public SentryList(final List backing) { super(backing); diff --git a/base/src/main/java/bjc/utils/funcdata/TransformedValueMap.java b/base/src/main/java/bjc/utils/funcdata/TransformedValueMap.java index 0ca1fdc..a8cb762 100644 --- a/base/src/main/java/bjc/utils/funcdata/TransformedValueMap.java +++ b/base/src/main/java/bjc/utils/funcdata/TransformedValueMap.java @@ -10,16 +10,30 @@ import java.util.function.Function; * @author ben * * @param - * The type of the map's keys + * The type of the map's keys + * * @param - * The type of the map's values + * The type of the map's values + * * @param - * The type of the transformed values + * The type of the transformed values + * */ final class TransformedValueMap implements IMap { - private final IMap backing; - private final Function transformer; - + /* Our backing map. */ + private final IMap backing; + /* Our transforming function. */ + private final Function transformer; + + /** + * Create a new transformed-value loop. + * + * @param backingMap + * The map to use as backing. + * + * @param transform + * The function to use for the transform. + */ public TransformedValueMap(final IMap backingMap, final Function transform) { backing = backingMap; -- cgit v1.2.3