diff options
Diffstat (limited to 'base/src/main/java/bjc/utils/funcdata/IList.java')
| -rw-r--r-- | base/src/main/java/bjc/utils/funcdata/IList.java | 251 |
1 files changed, 149 insertions, 102 deletions
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 <ContainedType> - * The type in this list + * The type in this list */ public interface IList<ContainedType> extends Iterable<ContainedType> { /** - * 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<ContainedType> items) { return items.map(this::add).anyMatch(bl -> bl == false); @@ -46,10 +49,11 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * 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<ContainedType> extends Iterable<ContainedType> { * 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<ContainedType> matcher); @@ -79,22 +85,27 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * 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<ContainedType> matcher); /** - * Reduce the contents of this list using a collector + * Reduce the contents of this list using a collector. * * @param <StateType> - * The intermediate accumulation type + * The intermediate accumulation type. + * * @param <ReducedType> - * 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 <StateType, ReducedType> ReducedType collect( final Collector<ContainedType, StateType, ReducedType> collector) { @@ -119,32 +130,39 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * list and the combined one. * * @param <OtherType> - * The type of the second list + * The type of the second list. + * * @param <CombinedType> - * 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. */ <OtherType, CombinedType> IList<CombinedType> combineWith(IList<OtherType> list, BiFunction<ContainedType, OtherType, CombinedType> 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<ContainedType> extends Iterable<ContainedType> { * Does not change the underlying list. * * @param <MappedType> - * 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. */ <MappedType> IList<MappedType> flatMap(Function<ContainedType, IList<MappedType>> 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<? super ContainedType> action); @@ -177,8 +197,7 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * 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<Integer, ContainedType> action); @@ -186,31 +205,37 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * 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<ContainedType> getMatching(Predicate<ContainedType> 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<ContainedType> extends Iterable<ContainedType> { * Does not change the underlying list. * * @param <MappedType> - * 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. */ <MappedType> IList<MappedType> map(Function<ContainedType, MappedType> transformer); /** - * Zip two lists into a list of pairs + * Zip two lists into a list of pairs. * * @param <OtherType> - * 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. */ <OtherType> IList<IPair<ContainedType, OtherType>> pairWith(IList<OtherType> 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<IList<ContainedType>> 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<ContainedType> extends Iterable<ContainedType> { * 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<ContainedType> extends Iterable<ContainedType> { /** * 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<ContainedType> extends Iterable<ContainedType> { * 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<Integer, Integer> rnd); @@ -297,20 +331,25 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * Reduce this list to a single value, using a accumulative approach. * * @param <StateType> - * The in-between type of the values + * The in-between type of the values + * * @param <ReducedType> - * 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. */ <StateType, ReducedType> ReducedType reduceAux(StateType initial, BiFunction<ContainedType, StateType, StateType> accumulator, @@ -320,16 +359,17 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * Reduce this list to a single value, using a accumulative approach. * * @param <StateType> - * 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> StateType reduceAux(StateType initial, BiFunction<ContainedType, StateType, StateType> accumulator) { @@ -337,25 +377,25 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { } /** - * 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<ContainedType> 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<ContainedType> extends Iterable<ContainedType> { * 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<ContainedType> comparator); @@ -381,31 +424,35 @@ public interface IList<ContainedType> extends Iterable<ContainedType> { * 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<ContainedType> 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<ContainedType> 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<ContainedType> toIterable(); |