From 6f4b8dfed09c13eaed57f2426bce3a83ef6bf9a1 Mon Sep 17 00:00:00 2001 From: Speiger Date: Sun, 6 Dec 2020 09:32:22 +0100 Subject: [PATCH] Added Loads of documentation to almost everything --- .../src/builder/base/ConditionedSegment.java | 6 +- .../speiger/src/builder/base/Segment.java | 4 +- .../speiger/src/builder/base/Template.java | 3 +- .../src/builder/conditions/ICondition.java | 1 + .../src/builder/example/GlobalVariables.java | 7 +- .../speiger/src/collections/utils/IArray.java | 12 + .../src/collections/utils/ITrimmable.java | 11 + .../src/collections/utils/SanityChecks.java | 58 ++- .../speiger/src/collections/utils/Stack.java | 35 ++ .../collections/AbstractCollection.template | 107 +++- .../BidirectionalIterator.template | 29 +- .../templates/collections/Collection.template | 91 +++- .../templates/collections/Iterable.template | 25 + .../templates/collections/Iterator.template | 41 +- .../templates/collections/Stack.template | 53 +- .../templates/functions/Comparator.template | 13 + .../templates/functions/Consumer.template | 48 +- .../templates/lists/AbstractList.template | 4 +- .../templates/lists/ArrayList.template | 4 +- .../collections/templates/lists/List.template | 228 ++++++++- .../templates/lists/ListIterator.template | 24 + .../templates/utils/Arrays.template | 482 +++++++++++++++++- .../templates/utils/Collections.template | 35 ++ .../templates/utils/IArray.template | 23 + .../templates/utils/Iterators.template | 113 +++- .../templates/utils/Lists.template | 45 +- 26 files changed, 1434 insertions(+), 68 deletions(-) diff --git a/src/main/java/speiger/src/builder/base/ConditionedSegment.java b/src/main/java/speiger/src/builder/base/ConditionedSegment.java index 2610c536..7e5ba4fe 100644 --- a/src/main/java/speiger/src/builder/base/ConditionedSegment.java +++ b/src/main/java/speiger/src/builder/base/ConditionedSegment.java @@ -31,12 +31,12 @@ public class ConditionedSegment { baseIndex += index; int length = builder.length(); - for(int i = 0,offset=0,m=segments.size();i entry = segments.get(i); if(entry.getKey().isValid(parsePool)) { - offset += entry.getValue().build(parsePool, builder, baseIndex+offset); + entry.getValue().build(parsePool, builder, baseIndex); break; } } @@ -77,7 +77,7 @@ public class ConditionedSegment } else if(trimmed.startsWith("#if")) { - i+= parse(trimmed.substring(3).trim(), lines, i, segmentText.length(), childSegments); + i += parse(trimmed.substring(3).trim(), lines, i, segmentText.length(), childSegments); } continue; } diff --git a/src/main/java/speiger/src/builder/base/Segment.java b/src/main/java/speiger/src/builder/base/Segment.java index 51addc07..3543104e 100644 --- a/src/main/java/speiger/src/builder/base/Segment.java +++ b/src/main/java/speiger/src/builder/base/Segment.java @@ -15,14 +15,12 @@ public class Segment this.segments = segments; } - public int build(Set parsePool, StringBuilder builder, int index) + public void build(Set parsePool, StringBuilder builder, int index) { - int length = builder.length(); builder.insert(index, text); for(int i = 0,offset=0,m=segments.size();i parsePool); + public default boolean canContinue() { return false; } public static ICondition parse(String condition) { diff --git a/src/main/java/speiger/src/builder/example/GlobalVariables.java b/src/main/java/speiger/src/builder/example/GlobalVariables.java index 3a7cafc1..660285c6 100644 --- a/src/main/java/speiger/src/builder/example/GlobalVariables.java +++ b/src/main/java/speiger/src/builder/example/GlobalVariables.java @@ -27,7 +27,6 @@ public class GlobalVariables public GlobalVariables createVariables() { addSimpleMapper("PACKAGE", type.getPathType()); - addDeprication("@Primitive"); addSimpleMapper("CLASS_TYPE", type.getClassType()); addSimpleMapper("KEY_TYPE", type.getKeyType()); addSimpleMapper("EMPTY_VALUE", type.getEmptyValue()); @@ -43,12 +42,16 @@ public class GlobalVariables addSimpleMapper("JAVA_TYPE", type.getCustomJDKType().getKeyType()); addSimpleMapper("SANITY_CAST", "castTo"+type.getFileType()); } + addSimpleMapper("@PrimitiveDoc", ""); + addDeprication("@Primitive"); return this; } + + public GlobalVariables createHelperVariables() { - addArgumentMapper("EQUALS_KEY_TYPE", type.isObject() ? "Objects.equals(%1$s, %2$s)" : "Objects.equals(KEY_TO_OBJ(%1$s), %2$s)").removeBraces(); + addArgumentMapper("EQUALS_KEY_TYPE", type.isObject() ? "Objects.equals(%2$s, %1$s)" : "Objects.equals(%2$s, KEY_TO_OBJ(%1$s))").removeBraces(); addArgumentMapper("EQUALS", type.getEquals()).removeBraces(); addArgumentMapper("COMPARE_TO", type.isObject() ? "%1$s.compareTo(%2$s)" : type.getClassType()+".compare(%1$s, %2$s)").removeBraces(); addInjectMapper("KEY_TO_OBJ", type.isObject() ? "%s" : type.getClassType()+".valueOf(%s)").removeBraces(); diff --git a/src/main/java/speiger/src/collections/utils/IArray.java b/src/main/java/speiger/src/collections/utils/IArray.java index 2d0b5747..826e9baf 100644 --- a/src/main/java/speiger/src/collections/utils/IArray.java +++ b/src/main/java/speiger/src/collections/utils/IArray.java @@ -2,7 +2,19 @@ package speiger.src.collections.utils; import java.util.RandomAccess; +/** + * A Helper interface that allows to detect if the Underlying implementation is + * using a Array. This allows to read methods through synchronization layers. + * Also it implements {@link RandomAccess} and {@link ITrimmable} + */ public interface IArray extends RandomAccess, ITrimmable { + /** + * Increases the capacity of this implementation instance, if necessary, + * to ensure that it can hold at least the number of elements specified by + * the minimum capacity argument. + * + * @param size the desired minimum capacity + */ public void ensureCapacity(int size); } diff --git a/src/main/java/speiger/src/collections/utils/ITrimmable.java b/src/main/java/speiger/src/collections/utils/ITrimmable.java index 06358c2b..24d55d3c 100644 --- a/src/main/java/speiger/src/collections/utils/ITrimmable.java +++ b/src/main/java/speiger/src/collections/utils/ITrimmable.java @@ -1,10 +1,21 @@ package speiger.src.collections.utils; +/** + * Interface that allows to test for if a collection is trimmable. + * This also allows that synchronization-wrappers are trimmable without extracting the original collection. + */ public interface ITrimmable { + /** + * Trims the original collection down to the size of the current elements + */ public default void trim() { trim(0); } + /** + * Trims the original collection down to the size of the current elements or the requested size depending which is bigger + * @param size the requested trim size. + */ public void trim(int size); } diff --git a/src/main/java/speiger/src/collections/utils/SanityChecks.java b/src/main/java/speiger/src/collections/utils/SanityChecks.java index 57caadfd..cf0fa8cd 100644 --- a/src/main/java/speiger/src/collections/utils/SanityChecks.java +++ b/src/main/java/speiger/src/collections/utils/SanityChecks.java @@ -3,26 +3,54 @@ package speiger.src.collections.utils; import java.util.concurrent.ForkJoinPool; import java.util.concurrent.ForkJoinTask; +/** + * Helper class that provides functions that are shared within the library. + * On top of that it provides some helper functions that allow control of some internals of the Library + */ public class SanityChecks { public static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8; private static ForkJoinPool WORK_POOL = ForkJoinPool.commonPool(); + /** + * Internal function to cast a Integer to a Byte + * @param value that should be turned into a byte + * @return the value as a byte + * @throws IllegalStateException if the value does not fit within a byte + */ public static byte castToByte(int value) { if(value > Byte.MAX_VALUE || value < Byte.MIN_VALUE) throw new IllegalStateException("Value ["+value+"] out of Byte[-128,127] range"); return (byte)value; } + /** + * Internal function to cast a Integer to a Short + * @param value that should be turned into a short + * @return the value as a short + * @throws IllegalStateException if the value does not fit within a short + */ public static short castToShort(int value) { if(value > Short.MAX_VALUE || value < Short.MIN_VALUE) throw new IllegalStateException("Value ["+value+"] out of Short[-32768,32767] range"); return (short)value; } + /** + * Internal function to cast a Integer to a Character + * @param value that should be turned into a char + * @return the value as a char + * @throws IllegalStateException if the value does not fit within a char + */ public static char castToChar(int value) { if(value > Character.MAX_VALUE || value < Character.MIN_VALUE) throw new IllegalStateException("Value ["+value+"] out of Character[0,65535] range"); return (char)value; } + /** + * Internal function to cast a Double to a Double + * @param value that should be turned into a float + * @return the value as a float + * @throws IllegalStateException if the value does not fit within a float + */ public static float castToFloat(double value) { if(Double.isNaN(value)) return Float.NaN; if(Double.isInfinite(value)) return value > 0 ? Float.POSITIVE_INFINITY : Float.NEGATIVE_INFINITY; @@ -30,20 +58,48 @@ public class SanityChecks return (float)value; } + /** + * Internal function that checks if the given array-size is big enough for the access. + * @param arraySize the size of the Array + * @param offset the offset of the access + * @param accessSize the lenght of the access + * @throws IllegalStateException if offset or accessSize is negative or the range goes out of the array-size + */ public static void checkArrayCapacity(int arraySize, int offset, int accessSize) { if(offset < 0) throw new IllegalStateException("Offset is negative ("+offset+")"); else if(accessSize < 0) throw new IllegalStateException("Size is negative ("+accessSize+")"); else if(arraySize < offset + accessSize) throw new IndexOutOfBoundsException("Index (" + offset + accessSize + ") is not in size (" + arraySize + ")"); } + /** + * Returns if the current thread-pool can handle multi-threading tasks + * @return true if the threadcount is bigger the 1 + */ public static boolean canParallelTask() { return WORK_POOL.getParallelism() > 1; } + /** + * Helper method to start a ForkJoinTask. This method will await the finalization of said task + * @param task the Task to invoke + */ public static void invokeTask(ForkJoinTask task) { - WORK_POOL.invoke(task); + WORK_POOL.invoke(task);//TODO implement a way to decide if the task should be awaited or not. Maybe even on a per Thread basis. } + /** + * Helper method to start a ForkJoinTask. This method will not await the finalization of said task + * @param task the Task to invoke + */ + public static void invokeAsyncTask(ForkJoinTask task) { + WORK_POOL.execute(task); + } + + /** + * Helper method to control what ForkJoinPool is being used for any given task. + * @Note this method is not thread-save. It is only there to provide control over how Library specific Threaded tasks are handled. + * @param pool The ForkJoinPool that should receive the tasks. If null {@link ForkJoinPool#commonPool()} is set instead + */ public static void setWorkPool(ForkJoinPool pool) { WORK_POOL = pool == null ? ForkJoinPool.commonPool() : pool; } diff --git a/src/main/java/speiger/src/collections/utils/Stack.java b/src/main/java/speiger/src/collections/utils/Stack.java index ec08db98..36f88d0e 100644 --- a/src/main/java/speiger/src/collections/utils/Stack.java +++ b/src/main/java/speiger/src/collections/utils/Stack.java @@ -1,18 +1,53 @@ package speiger.src.collections.utils; + +/** + * The Stack Interface represents the Last-In-First-Out layout (LIFO). + * It provides a simple {@link #push(Object)}, {@link #pop()} function, + * with a fast {@link #clear()} function. + * The {@link #peek(int)} function allows to view the contents of the stack (top to bottom). + */ public interface Stack { + /** + * Inserts a given Object on top of the stack + * @param e the Object to insert + */ public void push(T e); + /** + * Removes the Object on top of the stack. + * @return the element that is on top of the stack + * @throws ArrayIndexOutOfBoundsException if the stack is empty + */ public T pop(); + /** + * Provides the amount of elements currently in the stack + * @return amount of elements in the list + */ public int size(); + /** + * Clears the stack + */ public void clear(); + /** + * Provides the Object on top of the stack + * @return the element that is on top of the stack + * @throws ArrayIndexOutOfBoundsException if the stack is empty + */ public default T top() { return peek(0); } + /** + * Provides the Selected Object from the stack. + * Top to bottom + * @param index of the element that should be provided + * @return the element that was requested + * @throws ArrayIndexOutOfBoundsException if the index is out of bounds + */ public T peek(int index); } diff --git a/src/main/resources/speiger/assets/collections/templates/collections/AbstractCollection.template b/src/main/resources/speiger/assets/collections/templates/collections/AbstractCollection.template index 08ff9b56..16274031 100644 --- a/src/main/resources/speiger/assets/collections/templates/collections/AbstractCollection.template +++ b/src/main/resources/speiger/assets/collections/templates/collections/AbstractCollection.template @@ -1,6 +1,7 @@ package speiger.src.collections.PACKAGE.collections; import java.util.Collection; +import java.util.Objects; import java.util.AbstractCollection; import speiger.src.collections.PACKAGE.collections.COLLECTION; @@ -14,6 +15,10 @@ public abstract class ABSTRACT_COLLECTION KEY_GENERIC_TYPE extends AbstractColle public abstract ITERATOR KEY_GENERIC_TYPE iterator(); #if !TYPE_OBJECT + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public boolean add(CLASS_TYPE e) { return COLLECTION.super.add(e); } @@ -29,75 +34,132 @@ public abstract class ABSTRACT_COLLECTION KEY_GENERIC_TYPE extends AbstractColle } #if !TYPE_OBJECT + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public boolean contains(Object e) { return COLLECTION.super.contains(e); } + /** + * A Type-Specific implementation of contains. This implementation iterates over the elements and returns true if the value match. + * @param value that should be searched for. + * @return true if the value was found. + */ @Override public boolean contains(KEY_TYPE e) { - for(KEY_TYPE entry : this) { if(entry == e) return true; } + for(KEY_TYPE entry : this) { if(EQUALS(entry, e)) return true; } return false; } #endif + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public boolean containsAll(Collection c) { return c instanceof COLLECTION ? containsAll((COLLECTION KEY_GENERIC_TYPE)c) : super.containsAll(c); } - + + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public boolean addAll(Collection c) { return c instanceof COLLECTION ? addAll((COLLECTION KEY_GENERIC_TYPE)c) : super.addAll(c); } - + + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override - @Deprecated + @Primitive public boolean removeAll(Collection c) { return c instanceof COLLECTION ? removeAll((COLLECTION KEY_GENERIC_TYPE)c) : super.removeAll(c); } - + + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override - @Deprecated + @Primitive public boolean retainAll(Collection c) { return c instanceof COLLECTION ? retainAll((COLLECTION KEY_GENERIC_TYPE)c) : super.retainAll(c); } + /** + * A Type-Specific implementation of containsAll. This implementation iterates over all elements and checks all elements are present in the other collection. + * @param the collection that should be checked if it contains all elements. + * @return true if all elements were found in the collection + * @throws NullPointerException if the collection is null + */ @Override public boolean containsAll(COLLECTION KEY_GENERIC_TYPE c) { - for(KEY_TYPE e : c) - if(!contains(e)) + Objects.requireNonNull(c); + for(KEY_TYPE e : this) + if(!c.contains(e)) return false; return true; } + /** + * This implementation iterates over the elements of the collection and checks if they are stored in this collection + * @param c the elements that should be checked for + * @return true if any element is in this collection + * @deprecated if this is a primitive collection + * @throws NullPointerException if the collection is null + */ @Override @Primitive public boolean containsAny(Collection c) { + Objects.requireNonNull(c); for(KEY_TYPE e : this) - if(contains(KEY_TO_OBJ(e))) + if(c.contains(KEY_TO_OBJ(e))) return true; return false; } + /** + * This implementation iterates over the elements of the collection and checks if they are stored in this collection. + * @param c the elements that should be checked for + * @return true if any element is in this collection + * @throws NullPointerException if the collection is null + */ @Override public boolean containsAny(COLLECTION KEY_GENERIC_TYPE c) { - for(KEY_TYPE e : c) - if(contains(e)) + Objects.requireNonNull(c); + for(KEY_TYPE e : this) + if(c.contains(e)) return true; return false; } #if !TYPE_OBJECT + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public boolean remove(Object e) { return COLLECTION.super.remove(e); } + /** + * A Type-Specific implementation of remove. This implementation iterates over the elements until it finds the element that is searched for or it runs out of elements. + * It stops after finding the first element + * @param e the element that is searched for + * @return true if the element was found and removed. + */ @Override public boolean REMOVE_KEY(KEY_TYPE e) { for(ITERATOR KEY_GENERIC_TYPE iter = iterator();iter.hasNext();) { @@ -110,8 +172,15 @@ public abstract class ABSTRACT_COLLECTION KEY_GENERIC_TYPE extends AbstractColle } #endif + /** + * A Type-Specific implementation of removeAll. This Implementation iterates over all elements and removes them as they were found in the other collection. + * @param c the elements that should be deleted + * @return true if the collection was modified. + * @throws NullPointerException if the collection is null + */ @Override public boolean removeAll(COLLECTION KEY_GENERIC_TYPE c) { + Objects.requireNonNull(c); boolean modified = false; for(ITERATOR KEY_GENERIC_TYPE iter = iterator();iter.hasNext();) { if(c.contains(iter.NEXT())) { @@ -122,8 +191,15 @@ public abstract class ABSTRACT_COLLECTION KEY_GENERIC_TYPE extends AbstractColle return modified; } + /** + * A Type-Specific implementation of retainAll. This Implementation iterates over all elements and removes them as they were not found in the other collection. + * @param c the elements that should be kept + * @return true if the collection was modified. + * @throws NullPointerException if the collection is null + */ @Override public boolean retainAll(COLLECTION KEY_GENERIC_TYPE c) { + Objects.requireNonNull(c); boolean modified = false; for(ITERATOR KEY_GENERIC_TYPE iter = iterator();iter.hasNext();) { if(!c.contains(iter.NEXT())) { @@ -135,11 +211,20 @@ public abstract class ABSTRACT_COLLECTION KEY_GENERIC_TYPE extends AbstractColle } #if !TYPE_OBJECT + /** + * A Type-Specific implementation of toArray that links to {@link #TO_ARRAY(KEY_TYPE[])} with a newly created array. + * @return an array containing all of the elements in this collection + */ @Override public KEY_TYPE[] TO_ARRAY() { return TO_ARRAY(new KEY_TYPE[size()]); } + /** + * A Type-Specific implementation of toArray. This implementation iterates over all elements and unwraps them into primitive type. + * @param a array that the elements should be injected to. If null or to small a new array with the right size is created + * @return an array containing all of the elements in this collection + */ @Override public KEY_TYPE[] TO_ARRAY(KEY_TYPE[] a) { if(a == null || a.length < size()) a = new KEY_TYPE[size()]; diff --git a/src/main/resources/speiger/assets/collections/templates/collections/BidirectionalIterator.template b/src/main/resources/speiger/assets/collections/templates/collections/BidirectionalIterator.template index 6e7e107e..4bfeddf9 100644 --- a/src/main/resources/speiger/assets/collections/templates/collections/BidirectionalIterator.template +++ b/src/main/resources/speiger/assets/collections/templates/collections/BidirectionalIterator.template @@ -2,23 +2,45 @@ package speiger.src.collections.PACKAGE.collections; #if !TYPE_OBJECT import speiger.src.collections.objects.collections.ObjectBidirectionalIterator; - +/** + * A Type-Specific {@link ObjectBidirectionalIterator} to reduce (un)boxing + */ public interface BI_ITERATOR KEY_GENERIC_TYPE extends ITERATOR KEY_GENERIC_TYPE, ObjectBidirectionalIterator #else +/** + * This is a basically a {@link ListIterator} without the index functions. + * Allowing to have a simple Bidirectional Iterator without having to keep track of the Iteration index. + */ public interface BI_ITERATOR KEY_GENERIC_TYPE extends ITERATOR KEY_GENERIC_TYPE #endif { + /** + * Returns true if the Iterator has a Previous element + * @return true if the Iterator has a Previouse element + */ public boolean hasPrevious(); + /** + * Returns the Previous element of the iterator. + * @return the Previous element of the iterator. + * @throws NoSuchElementException if the iteration has no more elements + */ public KEY_TYPE PREVIOUS(); #if !TYPE_OBJECT + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default CLASS_TYPE previous() { return KEY_TO_OBJ(PREVIOUS()); } + /** + * {@inheritDoc} + */ @Override default int skip(int amount) { @@ -26,6 +48,11 @@ public interface BI_ITERATOR KEY_GENERIC_TYPE extends ITERATOR KEY_GENERIC_TYPE } #endif + /** + * Reverses the Given amount of elements if possible. A Optimization function to reverse elements faster if the implementation allows it. + * @param amount the amount of elements that should be reversed + * @return the amount of elements that were reversed + */ public default int back(int amount) { if(amount < 0) throw new IllegalStateException("Can't go forward"); int i = 0; diff --git a/src/main/resources/speiger/assets/collections/templates/collections/Collection.template b/src/main/resources/speiger/assets/collections/templates/collections/Collection.template index a176c63d..9493cc51 100644 --- a/src/main/resources/speiger/assets/collections/templates/collections/Collection.template +++ b/src/main/resources/speiger/assets/collections/templates/collections/Collection.template @@ -11,39 +11,104 @@ import java.util.function.Predicate; import speiger.src.collections.utils.SanityChecks; #endif +/** + * A Type-Specific {@link Collection} that reduces (un)boxing + */ public interface COLLECTION KEY_GENERIC_TYPE extends Collection, ITERABLE KEY_GENERIC_TYPE { #if !TYPE_OBJECT + /** + * A Type-Specific add function to reduce (un)boxing + * @see Collection#add(Object) + * @return true if the element was added to the collection + */ public boolean add(KEY_TYPE o); #endif + /** + * A Type-Specific addAll function to reduce (un)boxing + * @see Collection#addAll(Collection) + * @return true if elements were added into the collection + */ public boolean addAll(COLLECTION KEY_GENERIC_TYPE c); #if !TYPE_OBJECT + /** + * A Type-Specific contains function to reduce (un)boxing + * @see Collection#contains(Object) + * @return true if the element is found in the collection + */ public boolean contains(KEY_TYPE o); #endif + /** + * A Type-Specific containsAll function to reduce (un)boxing + * @see Collection#containsAll(Object) + * @return true if all the element is found in the collection + */ public boolean containsAll(COLLECTION KEY_GENERIC_TYPE c); - + + /** + * A Type-Specific containsAny function to reduce (un)boxing + * @see #containsAny(Collection) + * @return true if any element was found + */ public boolean containsAny(COLLECTION KEY_GENERIC_TYPE c); + /** + * Returns true if any element of the Collection is found in the provided collection. + * A Small Optimization method to find out of any element is present when comparing collections and not all of them. + * @return true if any element was found. + */ + @Primitive public boolean containsAny(Collection c); #if !TYPE_OBJECT + /** + * A Type-Specific remove function that reduces (un)boxing. + * @return true if the element was removed + * @see Collection#remove(Object) + */ public boolean REMOVE_KEY(KEY_TYPE o); #endif + /** + * A Type-Specific removeAll function that reduces (un)boxing. + * @return true if any element was removed + * @see Collection#removeAll(Collection) + */ public boolean removeAll(COLLECTION KEY_GENERIC_TYPE c); + /** + * A Type-Specific retainAll function that reduces (un)boxing. + * @return true if any element was removed + * @see Collection#retainAll(Collection) + */ public boolean retainAll(COLLECTION KEY_GENERIC_TYPE c); #if !TYPE_OBJECT + /** + * A Type-Specific toArray function that delegates to {@link #TO_ARRAY(KEY_TYPE[])} with a newly created array. + * @return an array containing all of the elements in this collection + * @see Collection#toArray() + */ public KEY_TYPE[] TO_ARRAY(); + /** + * A Type-Specific toArray function that reduces (un)boxing. + * @param a array that the elements should be injected to. If null or to small a new array with the right size is created + * @return an array containing all of the elements in this collection + * @see Collection#toArray(Object[]) + */ public KEY_TYPE[] TO_ARRAY(KEY_TYPE[] a); #if PRIMITIVES + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override + @Deprecated public default boolean removeIf(Predicate filter) { Objects.requireNonNull(filter); #if TYPE_BYTE || TYPE_SHORT || TYPE_CHAR || TYPE_FLOAT @@ -53,6 +118,13 @@ public interface COLLECTION KEY_GENERIC_TYPE extends Collection, ITE #endif } + /** + * A Type-Specific removeIf function to reduce (un)boxing. + *

Removes elements that were selected by the filter + * @see Collection#removeIf(Predicate) + * @param filter Filters the elements that should be removed + * @throws NullPointerException if filter is null + */ public default boolean remIf(JAVA_PREDICATE filter) { Objects.requireNonNull(filter); boolean removed = false; @@ -67,19 +139,36 @@ public interface COLLECTION KEY_GENERIC_TYPE extends Collection, ITE } #endif + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default boolean add(CLASS_TYPE o) { return add(OBJ_TO_KEY(o)); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default boolean contains(Object o) { return o != null && contains(CLASS_TO_KEY(o)); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default boolean remove(Object o) { return o != null && REMOVE_KEY(CLASS_TO_KEY(o)); } #endif + /** + * Returns a Type-Specific Iterator to reduce (un)boxing + * @return a iterator of the collection + * @see Collection#iterator() + */ @Override public ITERATOR KEY_GENERIC_TYPE iterator(); } \ No newline at end of file diff --git a/src/main/resources/speiger/assets/collections/templates/collections/Iterable.template b/src/main/resources/speiger/assets/collections/templates/collections/Iterable.template index 2a5f4511..973f273e 100644 --- a/src/main/resources/speiger/assets/collections/templates/collections/Iterable.template +++ b/src/main/resources/speiger/assets/collections/templates/collections/Iterable.template @@ -7,17 +7,42 @@ import java.util.function.Consumer; import speiger.src.collections.PACKAGE.functions.CONSUMER; #endif +/** + * A Type-Specific {@link Iterable} that reduces (un)boxing + */ public interface ITERABLE KEY_GENERIC_TYPE extends Iterable { + /** + * Returns an iterator over elements of type {@code T}. + * + * @return an Iterator. + */ @Override ITERATOR KEY_GENERIC_TYPE iterator(); #if !TYPE_OBJECT + /** + * A Type Specific foreach method that reduces (un)boxing + * + * @implSpec + *

The default implementation behaves as if: + * 

{@code
+     *     iterator().forEachRemaining(action);
+     * }
+ * + * @param action The action to be performed for each element + * @throws NullPointerException if the specified action is null + * @see Iterable#forEach(Consumer) + */ default void forEach(CONSUMER action) { Objects.requireNonNull(action); iterator().forEachRemaining(action); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Deprecated @Override default void forEach(Consumer action) { diff --git a/src/main/resources/speiger/assets/collections/templates/collections/Iterator.template b/src/main/resources/speiger/assets/collections/templates/collections/Iterator.template index f8a3cf98..c5e0f07a 100644 --- a/src/main/resources/speiger/assets/collections/templates/collections/Iterator.template +++ b/src/main/resources/speiger/assets/collections/templates/collections/Iterator.template @@ -9,20 +9,54 @@ import speiger.src.collections.PACKAGE.functions.CONSUMER; #endif +/** + * A Type-Specific {@link Iterator} that reduces (un)boxing + */ public interface ITERATOR KEY_GENERIC_TYPE extends Iterator { #if !TYPE_OBJECT + /** + * Returns the next element in the iteration. + * + * @return the next element in the iteration + * @throws NoSuchElementException if the iteration has no more elements + * @see Iterator#next() + */ public KEY_TYPE NEXT(); - @Deprecated + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override + @Deprecated public default CLASS_TYPE next() { return KEY_TO_OBJ(NEXT()); } + /** + * Performs the given action for each remaining element until all elements + * have been processed or the action throws an exception. Actions are + * performed in the order of iteration, if that order is specified. + * Exceptions thrown by the action are relayed to the caller. + * + * @implSpec + *

The default implementation behaves as if: + * 

{@code
+     *     while (hasNext()) action.accept(NEXT());
+     * }
+ * + * @param action The action to be performed for each element + * @throws NullPointerException if the specified action is null + * @see Iterator#forEachRemaining(Consumer) + */ public default void forEachRemaining(CONSUMER action) { Objects.requireNonNull(action); while(hasNext()) { action.accept(NEXT()); } } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Deprecated @Override default void forEachRemaining(Consumer action) { @@ -31,6 +65,11 @@ public interface ITERATOR KEY_GENERIC_TYPE extends Iterator } #endif + /** + * Skips the Given amount of elements if possible. A Optimization function to skip elements faster if the implementation allows it. + * @param amount the amount of elements that should be skipped + * @return the amount of elements that were skipped + */ default int skip(int amount) { if(amount < 0) throw new IllegalStateException("Negative Numbers are not allowed"); int i = 0; diff --git a/src/main/resources/speiger/assets/collections/templates/collections/Stack.template b/src/main/resources/speiger/assets/collections/templates/collections/Stack.template index 996edcf9..46016828 100644 --- a/src/main/resources/speiger/assets/collections/templates/collections/Stack.template +++ b/src/main/resources/speiger/assets/collections/templates/collections/Stack.template @@ -2,35 +2,78 @@ package speiger.src.collections.PACKAGE.collections; import speiger.src.collections.utils.Stack; +/** + * A Type-Specific {@link Stack} that reduces (un)boxing + */ public interface STACK extends Stack { + /** + * Inserts a given Object on top of the stack + * @param e the Object to insert + * @see Stack#push(Object) + */ public void PUSH(KEY_TYPE e); + /** + * Removes the Object on top of the stack. + * @return the element that is on top of the stack + * @throws ArrayIndexOutOfBoundsException if the stack is empty + * @see Stack#pop() + */ public KEY_TYPE POP(); + /** + * Provides the Object on top of the stack + * @return the element that is on top of the stack + * @throws ArrayIndexOutOfBoundsException if the stack is empty + * @see Stack#top() + */ public default KEY_TYPE TOP() { return PEEK(0); } + /** + * Provides the Selected Object from the stack. + * Top to bottom + * @param index of the element that should be provided + * @return the element that was requested + * @throws ArrayIndexOutOfBoundsException if the index is out of bounds + * @see Stack#peek(int) + */ public KEY_TYPE PEEK(int index); #if !OBJECT_TYPE + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ + @Override @Deprecated public default void push(CLASS_TYPE e) { PUSH(OBJ_TO_KEY(e)); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ + @Override @Deprecated public default CLASS_TYPE pop() { return KEY_TO_OBJ(POP()); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ + @Override @Deprecated public default CLASS_TYPE top() { return peek(size() - 1); } - @Deprecated - public default CLASS_TYPE bottom() { - return peek(0); - } - + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ + @Override @Deprecated public default CLASS_TYPE peek(int index) { return KEY_TO_OBJ(PEEK(index)); } #endif diff --git a/src/main/resources/speiger/assets/collections/templates/functions/Comparator.template b/src/main/resources/speiger/assets/collections/templates/functions/Comparator.template index 29985e7c..c894c4e4 100644 --- a/src/main/resources/speiger/assets/collections/templates/functions/Comparator.template +++ b/src/main/resources/speiger/assets/collections/templates/functions/Comparator.template @@ -2,10 +2,23 @@ package speiger.src.collections.PACKAGE.functions; import java.util.Comparator; +/** + * Type-Specific Class for Comparator to reduce (un)boxing + */ public interface COMPARATOR extends Comparator { + /** + * Type-Specific compare function to reduce (un)boxing + * @see Comparator#compare(Object, Object) + */ int compare(KEY_TYPE o1, KEY_TYPE o2); + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ + @Override + @Deprecated default int compare(CLASS_TYPE o1, CLASS_TYPE o2) { return compare(OBJ_TO_KEY(o1), OBJ_TO_KEY(o2)); } diff --git a/src/main/resources/speiger/assets/collections/templates/functions/Consumer.template b/src/main/resources/speiger/assets/collections/templates/functions/Consumer.template index b80a39f8..926f2598 100644 --- a/src/main/resources/speiger/assets/collections/templates/functions/Consumer.template +++ b/src/main/resources/speiger/assets/collections/templates/functions/Consumer.template @@ -8,40 +8,70 @@ import speiger.src.collections.utils.SanityChecks; #endif +/** + * Type-Specific Consumer interface that reduces (un)boxing and allows to merge other consumer types into this interface + */ public interface CONSUMER extends Consumer, JAVA_CONSUMER #else +/** + * Type-Specific Consumer interface that reduces (un)boxing and allows to merge other consumer types into this interface + */ public interface CONSUMER extends Consumer #endif { + /** + * Type-Specific method to reduce (un)boxing. + * Performs this operation on the given argument. + * + * @param t the input argument + */ void accept(KEY_TYPE t); + #if !JDK_CONSUMER - + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override + @Deprecated default void accept(JAVA_TYPE t) { accept(SanityChecks.SANITY_CAST(t)); } -#endif +#endif + public default CONSUMER andThen(CONSUMER after) { + Objects.requireNonNull(after); + return T -> {accept(T); after.accept(T);}; + } + + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override + @Deprecated default void accept(CLASS_TYPE t) { accept(OBJ_TO_KEY(t)); } - @Deprecated + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override + @Deprecated default CONSUMER andThen(Consumer after) { Objects.requireNonNull(after); return T -> {accept(T); after.accept(KEY_TO_OBJ(T));}; } #if PRIMITIVES - @Deprecated + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override + @Deprecated default CONSUMER andThen(JAVA_CONSUMER after) { Objects.requireNonNull(after); return T -> {accept(T); after.accept(T);}; } - #endif - default CONSUMER andThen(CONSUMER after) { - Objects.requireNonNull(after); - return T -> {accept(T); after.accept(T);}; - } } \ No newline at end of file diff --git a/src/main/resources/speiger/assets/collections/templates/lists/AbstractList.template b/src/main/resources/speiger/assets/collections/templates/lists/AbstractList.template index 13e1bc85..930324b2 100644 --- a/src/main/resources/speiger/assets/collections/templates/lists/AbstractList.template +++ b/src/main/resources/speiger/assets/collections/templates/lists/AbstractList.template @@ -246,10 +246,10 @@ public abstract class ABSTRACT_LIST KEY_GENERIC_TYPE extends ABSTRACT_COLLECTION #if TYPE_OBJECT @Override - public KEY_TYPE[] extractElements(int from, int to, Class clz) { + public K[] extractElements(int from, int to, Class clz) { checkRange(from); checkRange(to); - KEY_TYPE[] a = l.extractElements(from + offset, to + offset, clz); + K[] a = l.extractElements(from + offset, to + offset, clz); size -= to - from; return a; } diff --git a/src/main/resources/speiger/assets/collections/templates/lists/ArrayList.template b/src/main/resources/speiger/assets/collections/templates/lists/ArrayList.template index 3e97e143..eeba8d8f 100644 --- a/src/main/resources/speiger/assets/collections/templates/lists/ArrayList.template +++ b/src/main/resources/speiger/assets/collections/templates/lists/ArrayList.template @@ -218,11 +218,11 @@ public class ARRAY_LIST KEY_GENERIC_TYPE extends ABSTRACT_LIST KEY_GENERIC_TYPE #if TYPE_OBJECT @Override - public KEY_TYPE[] extractElements(int from, int to, Class type) { + public K[] extractElements(int from, int to, Class type) { checkRange(from); checkAddRange(to); int length = to - from; - KEY_TYPE[] a = ARRAYS.newArray(type, length); + K[] a = ARRAYS.newArray(type, length); if(length <= 0) return a; System.arraycopy(data, from, a, 0, length); if(to != size) System.arraycopy(data, to, data, from, size - to); diff --git a/src/main/resources/speiger/assets/collections/templates/lists/List.template b/src/main/resources/speiger/assets/collections/templates/lists/List.template index 652aeb43..a2a47246 100644 --- a/src/main/resources/speiger/assets/collections/templates/lists/List.template +++ b/src/main/resources/speiger/assets/collections/templates/lists/List.template @@ -5,6 +5,9 @@ import java.util.List; import java.util.Objects; import java.util.function.UNARY_OPERATOR; import java.util.function.UnaryOperator; +#else if TYPE_OBJECT +import java.util.Objects; +import java.util.function.UnaryOperator; #endif import java.util.Comparator; @@ -20,30 +23,98 @@ import speiger.src.collections.utils.SanityChecks; public interface LIST KEY_GENERIC_TYPE extends COLLECTION KEY_GENERIC_TYPE, List { #if !TYPE_OBJECT + /** + * A Type-Specific add Function to reduce (un)boxing + * @param e the element to add + * @return true if the list was modified + * @see List#add(Object) + */ @Override public boolean add(KEY_TYPE e); + /** + * A Type-Specific add Function to reduce (un)boxing + * @param e the element to add + * @param index index at which the specified element is to be inserted + * @see List#add(int, Object) + */ public void add(int index, KEY_TYPE e); #endif + /** + * A Type-Specific addAll Function to reduce (un)boxing + * @param c the elements that need to be added + * @param index index at which the specified elements is to be inserted + * @return true if the list was modified + * @see List#addAll(int, Object) + */ public boolean addAll(int index, COLLECTION KEY_GENERIC_TYPE c); + /** + * A Type-Specific and optimized addAll function that allows a faster transfer of elements + * @param c the elements that need to be added + * @return true if the list was modified + */ public boolean addAll(LIST KEY_GENERIC_TYPE c); + /** + * A Type-Specific and optimized addAll function that allows a faster transfer of elements + * @param c the elements that need to be added + * @param index index at which the specified elements is to be inserted + * @return true if the list was modified + */ public boolean addAll(int index, LIST KEY_GENERIC_TYPE c); #if !TYPE_OBJECT + /** + * A Type-Specific get function to reduce (un)boxing + * @param index the index of the value that is requested + * @return the value at the given index + * @throws IndexOutOfBoundsException if the index is not within the list range + * @see List#get(int) + */ public KEY_TYPE GET_KEY(int index); + /** + * A Type-Specific set function to reduce (un)boxing + * @param index index of the element to replace + * @param element element to be stored at the specified position + * @return the element previously at the specified position + * @throws IndexOutOfBoundsException if the index is not within the list range + * @see List#set(int, Object) + */ public KEY_TYPE set(int index, KEY_TYPE e); + /** + * A Type-Specific remove function to reduce (un)boxing + * @param index the index of the element to be removed + * @return the element previously at the specified position + * @see List#remove(int) + */ public KEY_TYPE REMOVE(int index); + /** + * A Type-Specific indexOf function to reduce (un)boxing + * @param e the element that is searched for + * @return the index of the element if found. (if not found then -1) + * @note does not support null values + */ public int indexOf(KEY_TYPE e); + /** + * A Type-Specific lastIndexOf function to reduce (un)boxing + * @param e the element that is searched for + * @return the lastIndex of the element if found. (if not found then -1) + * @note does not support null values + */ public int lastIndexOf(KEY_TYPE e); #if !TYPE_BOOLEAN + /** + * A Type-Specific replace function to reduce (un)boxing + * @param o the action to replace the values + * @throws NullPointerException if o is null + */ public default void REPLACE(UNARY_OPERATOR o) { Objects.requireNonNull(o); LIST_ITERATOR iter = listIterator(); @@ -56,20 +127,85 @@ public interface LIST KEY_GENERIC_TYPE extends COLLECTION KEY_GENERIC_TYPE, List } #endif +#else + /** + * A function to replace all values in the list + * @param o the action to replace the values + * @throws NullPointerException if o is null + */ + @Override + public default void replaceAll(UnaryOperator o) { + Objects.requireNonNull(o); + LIST_ITERATOR KEY_GENERIC_TYPE iter = listIterator(); + while (iter.hasNext()) iter.set(o.apply(iter.NEXT())); + } + #endif + /** + * A method to fast add elements to the list + * @param from the index where the elements should be added into the list + * @param a the elements that should be added + * @throws IndexOutOfBoundsException if from is outside of the lists range + */ public default void addElements(int from, KEY_TYPE[] a) { addElements(from, a, 0, a.length); } + /** + * A method to fast add elements to the list + * @param from the index where the elements should be added into the list + * @param a the elements that should be added + * @param offset the start index of the array should be read from + * @param length how many elements should be read from + * @throws IndexOutOfBoundsException if from is outside of the lists range + * @throws IllegalStateException if offset or length are smaller then 0 or exceed the array length + */ public void addElements(int from, KEY_TYPE[] a, int offset, int length); + /** + * A method to fast fetch elements from the list + * @param from index where the list should be fetching elements from + * @param a the array where the values should be inserted to + * @returns the inputArray + * @throws NullPointerException if the array is null + * @throws IndexOutOfBoundsException if from is outside of the lists range + * @throws IllegalStateException if offset or length are smaller then 0 or exceed the array length + */ public default KEY_TYPE[] getElements(int from, KEY_TYPE[] a) { return getElements(from, a, 0, a.length); } + /** + * A method to fast fetch elements from the list + * @param from index where the list should be fetching elements from + * @param a the array where the values should be inserted to + * @param offset the startIndex of where the array should be written to + * @param length the number of elements the values should be fetched from + * @returns the inputArray + * @throws NullPointerException if the array is null + * @throws IndexOutOfBoundsException if from is outside of the lists range + * @throws IllegalStateException if offset or length are smaller then 0 or exceed the array length + */ public KEY_TYPE[] getElements(int from, KEY_TYPE[] a, int offset, int length); + /** + * a method to fast remove elements from the list. + * @param from the start index of where the elements should be removed from (inclusive) + * @param to the end index of where the elements should be removed to (exclusive) + */ public void removeElements(int from, int to); #if TYPE_OBJECT - public KEY_TYPE[] extractElements(int from, int to, Class type); + /** + * A method to fast extract elements out of the list, this removes the elements that were fetched. + * @param from the start index of where the elements should be fetched from (inclusive) + * @param to the end index of where the elements should be fetched to (exclusive) + * @param type the type of the OutputArray + * @return a array of the elements that were fetched + */ + public K[] extractElements(int from, int to, Class type); + /** + * Sorts the elements specified by the Natural order either by using the Comparator or the elements + * @see List#sort(Comparator) + * @see ARRAYS#stableSort(KEY_TYPE[], Comparator) + */ @Override public default void sort(Comparator c) { KEY_TYPE[] array = (KEY_TYPE[])TO_ARRAY(); @@ -82,6 +218,11 @@ public interface LIST KEY_GENERIC_TYPE extends COLLECTION KEY_GENERIC_TYPE, List } } + /** + * Sorts the elements specified by the Natural order either by using the Comparator or the elements using a unstable sort + * @see List#sort(Comparator) + * @see ARRAYS#unstableSort(KEY_TYPE[], Comparator) + */ public default void unstableSort(Comparator c) { KEY_TYPE[] array = (KEY_TYPE[])TO_ARRAY(); if(c != null) ARRAYS.unstableSort(array, c); @@ -94,13 +235,29 @@ public interface LIST KEY_GENERIC_TYPE extends COLLECTION KEY_GENERIC_TYPE, List } #else + /** + * A method to fast extract elements out of the list, this removes the elements that were fetched. + * @param from the start index of where the elements should be fetched from (inclusive) + * @param to the end index of where the elements should be fetched to (exclusive) + * @return a array of the elements that were fetched + */ public KEY_TYPE[] extractElements(int from, int to); + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override + @Deprecated default void sort(Comparator c) { sort((K, V) -> c.compare(KEY_TO_OBJ(K), KEY_TO_OBJ(V))); } - + + /** + * Sorts the elements specified by the Natural order either by using the Comparator or the elements + * @see List#sort(Comparator) + * @see ARRAYS#stableSort(KEY_TYPE[], Comparator) + */ public default void sort(COMPARATOR c) { KEY_TYPE[] array = TO_ARRAY(); if(c != null) ARRAYS.stableSort(array, c); @@ -112,10 +269,20 @@ public interface LIST KEY_GENERIC_TYPE extends COLLECTION KEY_GENERIC_TYPE, List } } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ + @Deprecated public default void unstableSort(Comparator c) { unstableSort((K, V) -> c.compare(KEY_TO_OBJ(K), KEY_TO_OBJ(V))); } + /** + * Sorts the elements specified by the Natural order either by using the Comparator or the elements using a unstable sort + * @see List#sort(Comparator) + * @see ARRAYS#unstableSort(KEY_TYPE[], Comparator) + */ public default void unstableSort(COMPARATOR c) { KEY_TYPE[] array = TO_ARRAY(); if(c != null) ARRAYS.unstableSort(array, c); @@ -128,60 +295,111 @@ public interface LIST KEY_GENERIC_TYPE extends COLLECTION KEY_GENERIC_TYPE, List } #endif + /** + * A Type-Specific Iterator of listIterator + * @see List#listIterator + */ @Override public LIST_ITERATOR KEY_GENERIC_TYPE listIterator(); + /** + * A Type-Specific Iterator of listIterator + * @see List#listIterator(int) + */ @Override public LIST_ITERATOR KEY_GENERIC_TYPE listIterator(int index); + /** + * A Type-Specific List of subList + * @see List#subList(int, int) + */ @Override public LIST KEY_GENERIC_TYPE subList(int from, int to); + /** + * A Method to ensure the elements are within the requested size. + * If smaller then the stored elements they get removed as needed. + * If bigger it is ensured that enough room is provided depending on the implementation + * @param size the requested amount of elements/room for elements + */ public void size(int size); #if !TYPE_OBJECT + + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default boolean add(CLASS_TYPE e) { return COLLECTION.super.add(e); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default CLASS_TYPE get(int index) { return KEY_TO_OBJ(GET_KEY(index)); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default CLASS_TYPE set(int index, CLASS_TYPE e) { return KEY_TO_OBJ(set(index, OBJ_TO_KEY(e))); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default int indexOf(Object o) { return indexOf(CLASS_TO_KEY(o)); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default int lastIndexOf(Object o) { - return indexOf(CLASS_TO_KEY(o)); + return lastIndexOf(CLASS_TO_KEY(o)); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default boolean contains(Object o) { return COLLECTION.super.contains(o); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default boolean remove(Object o) { return COLLECTION.super.remove(o); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default CLASS_TYPE remove(int index) { @@ -189,6 +407,10 @@ public interface LIST KEY_GENERIC_TYPE extends COLLECTION KEY_GENERIC_TYPE, List } #if !TYPE_BOOLEAN + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default void replaceAll(UnaryOperator o) { diff --git a/src/main/resources/speiger/assets/collections/templates/lists/ListIterator.template b/src/main/resources/speiger/assets/collections/templates/lists/ListIterator.template index 620b1968..70e5560e 100644 --- a/src/main/resources/speiger/assets/collections/templates/lists/ListIterator.template +++ b/src/main/resources/speiger/assets/collections/templates/lists/ListIterator.template @@ -7,28 +7,52 @@ import speiger.src.collections.PACKAGE.collections.BI_ITERATOR; public interface LIST_ITERATOR KEY_GENERIC_TYPE extends ListIterator, BI_ITERATOR KEY_GENERIC_TYPE { #if !TYPE_OBJECT + /** + * A Primitive set function to reduce (un)boxing + * @see ListIterator#set(Object) + */ public void set(KEY_TYPE e); + /** + * A Primitive set function to reduce (un)boxing + * @see ListIterator#set(Object) + */ public void add(KEY_TYPE e); + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default CLASS_TYPE previous() { return BI_ITERATOR.super.previous(); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default CLASS_TYPE next() { return BI_ITERATOR.super.next(); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default void set(CLASS_TYPE e) { set(OBJ_TO_KEY(e)); } + /** {@inheritDoc} + *

This default implementation delegates to the corresponding type-specific method. + * @deprecated Please use the corresponding type-specific method instead. + */ @Override @Deprecated public default void add(CLASS_TYPE e) { diff --git a/src/main/resources/speiger/assets/collections/templates/utils/Arrays.template b/src/main/resources/speiger/assets/collections/templates/utils/Arrays.template index c61349e3..05fcaf7c 100644 --- a/src/main/resources/speiger/assets/collections/templates/utils/Arrays.template +++ b/src/main/resources/speiger/assets/collections/templates/utils/Arrays.template @@ -11,6 +11,9 @@ import java.util.Comparator; #endif import speiger.src.collections.utils.SanityChecks; +/** + * A Helper class for Arrays + */ public class ARRAYS { public static final int BASE_THRESHOLD = 16; @@ -19,14 +22,32 @@ public class ARRAYS #if !TYPE_OBJECT public static final KEY_TYPE[] EMPTY_ARRAY = new KEY_TYPE[0]; + /** + * A Helper function to convert a Primitive Array to a CLASS_TYPE Array. + * @param a the array that should be converted + * @return a CLASS_TYPE Array of the input array. + */ public static CLASS_TYPE[] wrap(KEY_TYPE[] a) { return wrap(a, 0, a.length); } + /** + * A Helper function to convert a Primitive Array to a CLASS_TYPE Array. + * @param a the array that should be converted + * @param length the maximum length that should be coverted + * @return a CLASS_TYPE Array of the input array. + */ public static CLASS_TYPE[] wrap(KEY_TYPE[] a, int length) { return wrap(a, 0, length); } + /** + * A Helper function to convert a Primitive Array to a CLASS_TYPE Array. + * @param a the array that should be converted + * @param offset the starting offset of the inputarray + * @param length the maximum length that should be coverted + * @return a CLASS_TYPE Array of the input array. + */ public static CLASS_TYPE[] wrap(KEY_TYPE[] a, int offset, int length) { SanityChecks.checkArrayCapacity(a.length, offset, length); CLASS_TYPE[] result = new CLASS_TYPE[length]; @@ -35,14 +56,32 @@ public class ARRAYS return result; } + /** + * A Helper function to convert a CLASS_TYPE Array to a KEY_TYPE Array. + * @param a the array that should be converted + * @return a KEY_TYPE Array of the input array. + */ public static KEY_TYPE[] unwrap(CLASS_TYPE[] a) { return unwrap(a, 0, a.length); } + /** + * A Helper function to convert a CLASS_TYPE Array to a KEY_TYPE Array. + * @param a the array that should be converted + * @param length the maximum length that should be coverted + * @return a KEY_TYPE Array of the input array. + */ public static KEY_TYPE[] unwrap(CLASS_TYPE[] a, int length) { return unwrap(a, 0, length); } + /** + * A Helper function to convert a CLASS_TYPE Array to a KEY_TYPE Array. + * @param a the array that should be converted + * @param offset the starting offset of the inputarray + * @param length the maximum length that should be coverted + * @return a KEY_TYPE Array of the input array. + */ public static KEY_TYPE[] unwrap(CLASS_TYPE[] a, int offset, int length) { SanityChecks.checkArrayCapacity(a.length, offset, length); KEY_TYPE[] result = new KEY_TYPE[length]; @@ -54,69 +93,182 @@ public class ARRAYS #else public static final Object[] EMPTY_ARRAY = new Object[0]; + /** + * Function to create a new Array of a given size + * @param clz the class type of array that is requested + * @param length the lenght the array should be. + * @return a Array with the requested type and length + */ public static KEY_GENERIC_TYPE KEY_TYPE[] newArray(Class clz, int length) { if(clz == Object.class) return (KEY_TYPE[])new Object[length]; return (KEY_TYPE[]) java.lang.reflect.Array.newInstance(clz, length); } #endif - + /** + * Sorts the specified range of elements according to the order induced by the specified comparator, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Stable sort referres to Mergesort or Insertionsort + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void stableSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { stableSort(array, 0, array.length, comp); } - + + /** + * Sorts the specified range of elements according to the order induced by the specified comparator, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Stable sort referres to Mergesort or Insertionsort + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void stableSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { stableSort(array, 0, length, comp); } - + + /** + * Sorts the specified range of elements according to the order induced by the specified comparator, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Stable sort referres to Mergesort or Insertionsort + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void stableSort(KEY_TYPE[] array, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { mergeSort(array, null, from, to, comp); } + /** + * Sorts an array according to the natural ascending order, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Stable sort referres to Mergesort or Insertionsort + * @param array the array that needs to be sorted + */ public static COMPAREABLE_BRACES void stableSort(KEY_TYPE[] array) { stableSort(array, 0, array.length); } - + + /** + * Sorts an array according to the natural ascending order, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Stable sort referres to Mergesort or Insertionsort + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + */ public static COMPAREABLE_BRACES void stableSort(KEY_TYPE[] array, int length) { stableSort(array, 0, length); } - + + /** + * Sorts an array according to the natural ascending order, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Stable sort referres to Mergesort or Insertionsort + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + */ public static COMPAREABLE_BRACES void stableSort(KEY_TYPE[] array, int from, int to) { mergeSort(array, null, from, to); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Unstable sort referres to QuickSort or SelectionSort + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void unstableSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { unstableSort(array, 0, array.length, comp); } - + + /** + * Sorts the specified range of elements according to the order induced by the specified comparator, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Unstable sort referres to QuickSort or SelectionSort + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void unstableSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { unstableSort(array, 0, length, comp); } - + + /** + * Sorts the specified range of elements according to the order induced by the specified comparator, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Unstable sort referres to QuickSort or SelectionSort + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void unstableSort(KEY_TYPE[] array, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { quickSort(array, from, to, comp); } + /** + * Sorts an array according to the natural ascending order, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Unstable sort referres to QuickSort or SelectionSort + * @param array the array that needs to be sorted + */ public static COMPAREABLE_BRACES void unstableSort(KEY_TYPE[] array) { unstableSort(array, 0, array.length); } - + + /** + * Sorts an array according to the natural ascending order, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Unstable sort referres to QuickSort or SelectionSort + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + */ public static COMPAREABLE_BRACES void unstableSort(KEY_TYPE[] array, int length) { unstableSort(array, 0, length); } - + + /** + * Sorts an array according to the natural ascending order, + * potentially dynamically choosing an appropriate algorithm given the type and size of the array. + * Unstable sort referres to QuickSort or SelectionSort + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + */ public static COMPAREABLE_BRACES void unstableSort(KEY_TYPE[] array, int from, int to) { quickSort(array, from, to); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Insertion Sort, + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void insertionSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { insertionSort(array, 0, array.length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Insertion Sort, + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void insertionSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { insertionSort(array, 0, length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Insertion Sort, + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void insertionSort(KEY_TYPE[] array, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { for (int i = from+1;iFastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void mergeSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { mergeSort(array, null, 0, array.length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void mergeSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { mergeSort(array, null, 0, length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void mergeSort(KEY_TYPE[] array, KEY_TYPE[] supp, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { if(to - from < BASE_THRESHOLD) { insertionSort(array, from, to, comp); @@ -223,14 +442,32 @@ public class ARRAYS } } + /** + * Sorts an array according to the natural ascending order using Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + */ public static COMPAREABLE_BRACES void mergeSort(KEY_TYPE[] array) { mergeSort(array, null, 0, array.length); } + /** + * Sorts an array according to the natural ascending order using Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + */ public static COMPAREABLE_BRACES void mergeSort(KEY_TYPE[] array, int length) { mergeSort(array, null, 0, length); } + /** + * Sorts an array according to the natural ascending order using Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + */ public static COMPAREABLE_BRACES void mergeSort(KEY_TYPE[] array, KEY_TYPE[] supp, int from, int to) { if(to - from < BASE_THRESHOLD) { insertionSort(array, from, to); @@ -251,14 +488,38 @@ public class ARRAYS } } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using a Parallel Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelMergeSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { parallelMergeSort(array, null, 0, array.length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelMergeSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { parallelMergeSort(array, null, 0, length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelMergeSort(KEY_TYPE[] array, KEY_TYPE[] supp, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { if(SanityChecks.canParallelTask() && to - from >= PARALLEL_THRESHOLD) { SanityChecks.invokeTask(new MergeSortActionCompBRACES(array, supp, from, to, comp)); @@ -267,14 +528,35 @@ public class ARRAYS mergeSort(array, supp, from, to, comp); } + /** + * Sorts an array according to the natural ascending order using Parallel Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelMergeSort(KEY_TYPE[] array) { parallelMergeSort(array, null, 0, array.length); } + /** + * Sorts an array according to the natural ascending order using Parallel Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelMergeSort(KEY_TYPE[] array, int length) { parallelMergeSort(array, null, 0, length); } + /** + * Sorts an array according to the natural ascending order using Parallel Merge Sort, + * This implementation was copied from FastUtil with a couple custom optimizations + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelMergeSort(KEY_TYPE[] array, KEY_TYPE[] supp, int from, int to) { if(SanityChecks.canParallelTask() && to - from >= PARALLEL_THRESHOLD) { SanityChecks.invokeTask(new MergeSortActionBRACES(array, supp, from, to)); @@ -283,14 +565,35 @@ public class ARRAYS mergeSort(array, supp, from, to); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void memFreeMergeSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { memFreeMergeSort(array, 0, array.length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void memFreeMergeSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { memFreeMergeSort(array, 0, length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void memFreeMergeSort(KEY_TYPE[] array, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { if(to - from < BASE_THRESHOLD) { insertionSort(array, from, to, comp); @@ -318,14 +621,32 @@ public class ARRAYS } } + /** + * Sorts an array according to the natural ascending order using Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + */ public static COMPAREABLE_BRACES void memFreeMergeSort(KEY_TYPE[] array) { memFreeMergeSort(array, 0, array.length); } + /** + * Sorts an array according to the natural ascending order using Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + */ public static COMPAREABLE_BRACES void memFreeMergeSort(KEY_TYPE[] array, int length) { memFreeMergeSort(array, 0, length); } + /** + * Sorts an array according to the natural ascending order using Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + */ public static COMPAREABLE_BRACES void memFreeMergeSort(KEY_TYPE[] array, int from, int to) { if(to - from < BASE_THRESHOLD) { insertionSort(array, from, to); @@ -353,14 +674,38 @@ public class ARRAYS } } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelMemFreeMergeSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { parallelMemFreeMergeSort(array, 0, array.length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelMemFreeMergeSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { parallelMemFreeMergeSort(array, 0, length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelMemFreeMergeSort(KEY_TYPE[] array, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { if(SanityChecks.canParallelTask() && to - from >= PARALLEL_THRESHOLD) { SanityChecks.invokeTask(new MemFreeMergeSortActionCompBRACES(array, from, to, comp)); @@ -369,14 +714,35 @@ public class ARRAYS memFreeMergeSort(array, from, to, comp); } + /** + * Sorts an array according to the natural ascending order using Parallel Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelMemFreeMergeSort(KEY_TYPE[] array) { parallelMemFreeMergeSort(array, 0, array.length); } + /** + * Sorts an array according to the natural ascending order using Parallel Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelMemFreeMergeSort(KEY_TYPE[] array, int length) { parallelMemFreeMergeSort(array, 0, length); } + /** + * Sorts an array according to the natural ascending order using Parallel Memory Free Merge Sort, + * This implementation is inspired by FastUtil original merge sort, but without the need to allocate a copy of the original Array. It is in Very Unsorted Instances 50% slower then Mergesort, otherwise it as fast. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelMemFreeMergeSort(KEY_TYPE[] array, int from, int to) { if(SanityChecks.canParallelTask() && to - from >= PARALLEL_THRESHOLD) { SanityChecks.invokeTask(new MemFreeMergeSortActionBRACES(array, from, to)); @@ -385,14 +751,38 @@ public class ARRAYS memFreeMergeSort(array, from, to); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void quickSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { quickSort(array, 0, array.length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void quickSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { quickSort(array, 0, length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + */ public static GENERIC_BRACES void quickSort(KEY_TYPE[] array, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { int length = to - from; if(length <= 0) return; @@ -417,14 +807,35 @@ public class ARRAYS if((length = d - c) > 1) quickSort(array, to - length, to, comp); } + /** + * Sorts an array according to the natural ascending order using Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + */ public static COMPAREABLE_BRACES void quickSort(KEY_TYPE[] array) { quickSort(array, 0, array.length); } + /** + * Sorts an array according to the natural ascending order using Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + */ public static COMPAREABLE_BRACES void quickSort(KEY_TYPE[] array, int length) { quickSort(array, 0, length); } + /** + * Sorts an array according to the natural ascending order using Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + */ public static COMPAREABLE_BRACES void quickSort(KEY_TYPE[] array, int from, int to) { int length = to - from; if(length <= 0) return; @@ -449,14 +860,41 @@ public class ARRAYS if((length = d - c) > 1) quickSort(array, to - length, to); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelQuickSort(KEY_TYPE[] array, COMPARATOR KEY_GENERIC_TYPE comp) { parallelQuickSort(array, 0, array.length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelQuickSort(KEY_TYPE[] array, int length, COMPARATOR KEY_GENERIC_TYPE comp) { parallelQuickSort(array, 0, length, comp); } + /** + * Sorts the specified range of elements according to the order induced by the specified comparator using Parallel Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @param comp the Comparator that decides the sorting order + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static GENERIC_BRACES void parallelQuickSort(KEY_TYPE[] array, int from, int to, COMPARATOR KEY_GENERIC_TYPE comp) { if(SanityChecks.canParallelTask() && to - from >= PARALLEL_THRESHOLD) { SanityChecks.invokeTask(new QuickSortActionCompBRACES(array, from, to, comp)); @@ -465,14 +903,38 @@ public class ARRAYS quickSort(array, from, to, comp); } + /** + * Sorts an array according to the natural ascending order using Parallel Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelQuickSort(KEY_TYPE[] array) { parallelQuickSort(array, 0, array.length); } + /** + * Sorts an array according to the natural ascending order using Parallel Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param length the maxmium size of the array to be sorted + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelQuickSort(KEY_TYPE[] array, int length) { parallelQuickSort(array, 0, length); } + /** + * Sorts an array according to the natural ascending order using Parallel Quick Sort, + * This implementation is a custom of FastUtil quicksort but with a different code structure, + * and that sorting Algorithm is based on the tuned quicksort adapted from Jon L. Bentley and M. DouglasMcIlroy, “Engineering a Sort Function”, Software: Practice and Experience, 23(11), pages1249−1265, 1993. + * @param array the array that needs to be sorted + * @param from where the array should be sorted from + * @param to where the array should be sorted to + * @Note This parallelization is invoked through {@link SanityChecks#invokeTask} which the threadpool can be changed as needed + */ public static COMPAREABLE_BRACES void parallelQuickSort(KEY_TYPE[] array, int from, int to) { if(SanityChecks.canParallelTask() && to - from >= PARALLEL_THRESHOLD) { SanityChecks.invokeTask(new QuickSortActionBRACES(array, from, to)); @@ -481,7 +943,7 @@ public class ARRAYS quickSort(array, from, to); } - public static GENERIC_BRACES void swap(KEY_TYPE[] a, int from, int to) { + static GENERIC_BRACES void swap(KEY_TYPE[] a, int from, int to) { KEY_TYPE t = a[from]; a[from] = a[to]; a[to] = t; diff --git a/src/main/resources/speiger/assets/collections/templates/utils/Collections.template b/src/main/resources/speiger/assets/collections/templates/utils/Collections.template index dd750e59..0a1638bb 100644 --- a/src/main/resources/speiger/assets/collections/templates/utils/Collections.template +++ b/src/main/resources/speiger/assets/collections/templates/utils/Collections.template @@ -14,10 +14,17 @@ import speiger.src.collections.objects.utils.ObjectArrays; import speiger.src.collections.PACKAGE.utils.ARRAYS; #endif +/** + * A Helper class for Collections + */ public class COLLECTIONS { public static final COLLECTION NO_GENERIC_TYPE EMPTY = new EmptyCollectionBRACES(); + /** + * Returns a Immutable EmptyCollection instance that is automatically casted. + * @return an empty collection + */ public static GENERIC_BRACES COLLECTION KEY_GENERIC_TYPE emptyCollection() { #if TYPE_OBJECT return (COLLECTION)EMPTY; @@ -26,14 +33,30 @@ public class COLLECTIONS #endif } + /** + * Returns a Immutable Collection instance based on the instance given. + * @param l that should be made immutable/unmodifyable + * @return a unmodifiable collection wrapper. If the Collection already a unmodifyable wrapper then it just returns itself. + */ public static GENERIC_BRACES COLLECTION KEY_GENERIC_TYPE unmodifiableCollection(COLLECTION KEY_GENERIC_TYPE c) { return c instanceof UnmodifiableCollection ? c : new UnmodifiableCollectionBRACES(c); } + /** + * Returns a synchronized Collection instance based on the instance given. + * @param l that should be synchronized + * @return a synchronized collection wrapper. If the Collection already a synchronized wrapper then it just returns itself. + */ public static GENERIC_BRACES COLLECTION KEY_GENERIC_TYPE synchronizedCollection(COLLECTION KEY_GENERIC_TYPE c) { return c instanceof SynchronizedCollection ? c : new SynchronizedCollectionBRACES(c); } + /** + * Returns a synchronized Collection instance based on the instance given. + * @param l that should be synchronized + * @param mutex is the controller of the synchronization block. + * @return a synchronized collection wrapper. If the Collection already a synchronized wrapper then it just returns itself. + */ public static GENERIC_BRACES COLLECTION KEY_GENERIC_TYPE synchronizedCollection(COLLECTION KEY_GENERIC_TYPE c, Object mutex) { return c instanceof SynchronizedCollection ? c : new SynchronizedCollectionBRACES(c, mutex); } @@ -70,9 +93,11 @@ public class COLLECTIONS #endif @Override + @Primitive public boolean containsAll(Collection c) { synchronized(mutex) { return this.c.containsAll(c); } } @Override + @Primitive public boolean containsAny(Collection c) { synchronized(mutex) { return this.c.containsAny(c); } } @Override @@ -96,8 +121,10 @@ public class COLLECTIONS @Primitive public boolean remove(Object o) { synchronized(mutex) { return c.remove(o); } } @Override + @Primitive public boolean removeAll(Collection c) { synchronized(mutex) { return this.c.removeAll(c); } } @Override + @Primitive public boolean retainAll(Collection c) { synchronized(mutex) { return this.c.retainAll(c); } } #if !TYPE_OBJECT @Override @@ -170,11 +197,13 @@ public class COLLECTIONS } @Override + @Primitive public boolean containsAny(Collection c) { return this.c.containsAny(c); } @Override + @Primitive public boolean containsAll(Collection c) { return this.c.containsAll(c); } @@ -198,8 +227,10 @@ public class COLLECTIONS @Deprecated public boolean remove(Object o) { throw new UnsupportedOperationException(); } @Override + @Primitive public boolean removeAll(Collection c) { throw new UnsupportedOperationException(); } @Override + @Primitive public boolean retainAll(Collection c) { throw new UnsupportedOperationException(); } @Override @Primitive @@ -280,11 +311,13 @@ public class COLLECTIONS #endif @Override + @Primitive public boolean containsAny(Collection c) { return false; } @Override + @Primitive public boolean containsAll(Collection c) { return false; } @@ -305,8 +338,10 @@ public class COLLECTIONS @Deprecated public boolean remove(Object o) { throw new UnsupportedOperationException(); } @Override + @Primitive public boolean removeAll(Collection c) { throw new UnsupportedOperationException(); } @Override + @Primitive public boolean retainAll(Collection c) { throw new UnsupportedOperationException(); } @Override @Primitive diff --git a/src/main/resources/speiger/assets/collections/templates/utils/IArray.template b/src/main/resources/speiger/assets/collections/templates/utils/IArray.template index 9b24ddf3..2ced7f9c 100644 --- a/src/main/resources/speiger/assets/collections/templates/utils/IArray.template +++ b/src/main/resources/speiger/assets/collections/templates/utils/IArray.template @@ -1,8 +1,31 @@ package speiger.src.collections.PACKAGE.utils; +import java.util.Objects; +import java.util.function.Consumer; + import speiger.src.collections.utils.IArray; +/** + * Type-Specific Helper class to get the underlying array of array implementations. + * @see speiger.src.collections.PACKAGE.lists.ARRAY_LIST + */ public interface IARRAY KEY_GENERIC_TYPE extends IArray { + /** + * Provides the Underlying Array in the Implementation + * @return underlying Array + * @throws ClassCastException if the return type does not match the underlying array. (Only for Object Implementations) + */ public KEY_TYPE[] elements(); + + /** + * Provides the Underlying Array in the Implementation. This method exists purely because of Synchronization wrappers to help run Synchronized Code + * @param action the action that handles the array + * @throws NullPointerException if action is null + * @throws ClassCastException if the return type does not match the underlying array. (Only for Object Implementations) + */ + public default void elements(Consumer action) { + Objects.requireNonNull(action); + action.accept(elements()); + } } diff --git a/src/main/resources/speiger/assets/collections/templates/utils/Iterators.template b/src/main/resources/speiger/assets/collections/templates/utils/Iterators.template index 607e82a2..a2ef972c 100644 --- a/src/main/resources/speiger/assets/collections/templates/utils/Iterators.template +++ b/src/main/resources/speiger/assets/collections/templates/utils/Iterators.template @@ -4,10 +4,17 @@ import java.util.Iterator; import speiger.src.collections.PACKAGE.collections.ITERATOR; import speiger.src.collections.PACKAGE.lists.LIST_ITERATOR; +/** + * A Helper class for Iterators + */ public class ITERATORS { public static final EmptyIterator NO_GENERIC_TYPE EMPTY = new EmptyIteratorBRACES(); + /** + * Returns a Immutable EmptyIterator instance that is automatically casted. + * @return an empty iterator + */ public static GENERIC_BRACES EmptyIterator KEY_GENERIC_TYPE emptyIterator() { #if TYPE_OBJECT return (EmptyIterator)EMPTY; @@ -16,30 +23,74 @@ public class ITERATORS #endif } + /** + * Returns a Immutable Iterator instance based on the instance given. + * @param l that should be made immutable/unmodifyable + * @return a unmodifiable iterator wrapper. If the Iterator already a unmodifyable wrapper then it just returns itself. + */ public static GENERIC_BRACES ITERATOR KEY_GENERIC_TYPE unmodifiable(ITERATOR KEY_GENERIC_TYPE iterator) { - return new UnmodifiableIteratorBRACES(iterator); + return iterator instanceof UnmodifiableIterator ? iterator : new UnmodifiableIteratorBRACES(iterator); } + /** + * Returns a Immutable ListIterator instance based on the instance given. + * @param l that should be made immutable/unmodifyable + * @return a unmodifiable listiterator wrapper. If the ListIterator already a unmodifyable wrapper then it just returns itself. + */ public static GENERIC_BRACES LIST_ITERATOR KEY_GENERIC_TYPE unmodifiable(LIST_ITERATOR KEY_GENERIC_TYPE iterator) { - return new UnmodifiableListIteratorBRACES(iterator); + return iterator instanceof UnmodifiableListIterator ? iterator : new UnmodifiableListIteratorBRACES(iterator); } + /** + * Returns a Array Wrapping iterator + * @param a the array that should be wrapped + * @return a Iterator that is wrapping a array. + */ public static GENERIC_BRACES ArrayIterator KEY_GENERIC_TYPE wrap(KEY_TYPE[] a) { return wrap(a, 0, a.length); } + /** + * Returns a Array Wrapping iterator + * @param a the array that should be wrapped. + * @param start the index to be started from. + * @param end the index that should be ended. + * @return a Iterator that is wrapping a array. + */ public static GENERIC_BRACES ArrayIterator KEY_GENERIC_TYPE wrap(KEY_TYPE[] a, int start, int end) { return new ArrayIteratorBRACES(a, start, end); } + /** + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @return the amount of elements that were inserted into the array. + */ public static GENERIC_BRACES int unwrap(KEY_TYPE[] a, Iterator i) { return unwrap(a, i, 0, a.length); } + /** + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @param offset the array offset where the start should be + * @return the amount of elements that were inserted into the array. + */ public static GENERIC_BRACES int unwrap(KEY_TYPE[] a, Iterator i, int offset) { - return unwrap(a, i, offset, a.length); + return unwrap(a, i, offset, a.length - offset); } - + + /** + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @param offset the array offset where the start should be + * @param max the maximum values that should be extracted from the source + * @return the amount of elements that were inserted into the array. + * @throws IllegalStateException if max is smaller the 0 or if the maximum index is larger then the array + */ public static GENERIC_BRACES int unwrap(KEY_TYPE[] a, Iterator i, int offset, int max) { if(max < 0) throw new IllegalStateException("The max size is smaller then 0"); if(offset + max >= a.length) throw new IllegalStateException("largest array index exceeds array size"); @@ -48,14 +99,39 @@ public class ITERATORS return index; } + /** + * A Primitive iterator variant of the {@link #unwrap(KEY_TYPE[], Iterator)} function + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @return the amount of elements that were inserted into the array. + */ public static GENERIC_BRACES int unwrap(KEY_TYPE[] a, ITERATOR KEY_GENERIC_TYPE i) { return unwrap(a, i, 0, a.length); } + /** + * A Primitive iterator variant of the {@link #unwrap(KEY_TYPE[], Iterator, int)} function + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @param offset the array offset where the start should be + * @return the amount of elements that were inserted into the array. + */ public static GENERIC_BRACES int unwrap(KEY_TYPE[] a, ITERATOR KEY_GENERIC_TYPE i, int offset) { - return unwrap(a, i, offset, a.length); + return unwrap(a, i, offset, a.length - offset); } + /** + * A Primitive iterator variant of the {@link #unwrap(KEY_TYPE[], Iterator, int, int)} function + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @param offset the array offset where the start should be + * @param max the maximum values that should be extracted from the source + * @return the amount of elements that were inserted into the array. + * @throws IllegalStateException if max is smaller the 0 or if the maximum index is larger then the array + */ public static GENERIC_BRACES int unwrap(KEY_TYPE[] a, ITERATOR KEY_GENERIC_TYPE i, int offset, int max) { if(max < 0) throw new IllegalStateException("The max size is smaller then 0"); if(offset + max >= a.length) throw new IllegalStateException("largest array index exceeds array size"); @@ -65,14 +141,39 @@ public class ITERATORS } #if !TYPE_OBJECT + /** + * A Function to convert a Primitive Iterator to a Object array. + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @return the amount of elements that were inserted into the array. + */ public static GENERIC_BRACES int unwrap(CLASS_TYPE[] a, ITERATOR KEY_GENERIC_TYPE i) { return unwrap(a, i, 0, a.length); } + /** + * A Function to convert a Primitive Iterator to a Object array. + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @param offset the array offset where the start should be + * @return the amount of elements that were inserted into the array. + */ public static GENERIC_BRACES int unwrap(CLASS_TYPE[] a, ITERATOR KEY_GENERIC_TYPE i, int offset) { - return unwrap(a, i, offset, a.length); + return unwrap(a, i, offset, a.length - offset); } + /** + * A Function to convert a Primitive Iterator to a Object array. + * Iterates over a iterator and inserts the values into the array and returns the amount that was inserted + * @param a where the elements should be inserted + * @param i the source iterator + * @param offset the array offset where the start should be + * @param max the maximum values that should be extracted from the source + * @return the amount of elements that were inserted into the array. + * @throws IllegalStateException if max is smaller the 0 or if the maximum index is larger then the array + */ public static GENERIC_BRACES int unwrap(CLASS_TYPE[] a, ITERATOR KEY_GENERIC_TYPE i, int offset, int max) { if(max < 0) throw new IllegalStateException("The max size is smaller then 0"); if(offset + max >= a.length) throw new IllegalStateException("largest array index exceeds array size"); diff --git a/src/main/resources/speiger/assets/collections/templates/utils/Lists.template b/src/main/resources/speiger/assets/collections/templates/utils/Lists.template index f113a8f6..176a79bf 100644 --- a/src/main/resources/speiger/assets/collections/templates/utils/Lists.template +++ b/src/main/resources/speiger/assets/collections/templates/utils/Lists.template @@ -1,10 +1,9 @@ package speiger.src.collections.PACKAGE.utils; import java.util.Collection; +import java.util.Objects; import java.util.RandomAccess; -#if TYPE_OBJECT import java.util.function.Consumer; -#endif import speiger.src.collections.PACKAGE.collections.COLLECTION; #if !TYPE_OBJECT @@ -13,10 +12,17 @@ import speiger.src.collections.PACKAGE.functions.CONSUMER; import speiger.src.collections.PACKAGE.lists.LIST; import speiger.src.collections.PACKAGE.lists.LIST_ITERATOR; +/** + * A Helper class for Lists + */ public class LISTS { public static final EmptyList NO_GENERIC_TYPE EMPTY = new EmptyListBRACES(); + /** + * Returns a Immutable EmptyList instance that is automatically casted. + * @return an empty list + */ public static GENERIC_BRACES EmptyList KEY_GENERIC_TYPE emptyList() { #if TYPE_OBJECT return (EmptyList)EMPTY; @@ -25,14 +31,30 @@ public class LISTS #endif } + /** + * Returns a Immutable List instance based on the instance given. + * @param l that should be made immutable/unmodifyable + * @return a unmodifiable list wrapper. If the list is implementing RandomAccess that is also transferred. If the List already a unmodifyable wrapper then it just returns itself. + */ public static GENERIC_BRACES LIST KEY_GENERIC_TYPE unmodifiableList(LIST KEY_GENERIC_TYPE l) { return l instanceof UnmodifiableList ? l : l instanceof RandomAccess ? new UnmodifiableRandomListBRACES(l) : new UnmodifiableListBRACES(l); } + /** + * Returns a synchronized List instance based on the instance given. + * @param l that should be synchronized + * @return a synchronized list wrapper. If the list is implementing RandomAccess or IARRAY that is also transferred. If the List already a synchronized wrapper then it just returns itself. + */ public static GENERIC_BRACES LIST KEY_GENERIC_TYPE synchronizedList(LIST KEY_GENERIC_TYPE l) { return l instanceof SynchronizedList ? l : (l instanceof IARRAY ? new SynchronizedArrayListBRACES(l) : (l instanceof RandomAccess ? new SynchronizedRandomAccessListBRACES(l) : new SynchronizedListBRACES(l))); } + /** + * Returns a synchronized List instance based on the instance given. + * @param l that should be synchronized + * @param mutex is the controller of the synchronization block. + * @return a synchronized list wrapper. If the list is implementing RandomAccess or IARRAY that is also transferred. If the List already a synchronized wrapper then it just returns itself. + */ public static GENERIC_BRACES LIST KEY_GENERIC_TYPE synchronizedList(LIST KEY_GENERIC_TYPE l, Object mutex) { return l instanceof SynchronizedList ? l : (l instanceof IARRAY ? new SynchronizedArrayListBRACES(l, mutex) : (l instanceof RandomAccess ? new SynchronizedRandomAccessListBRACES(l, mutex) : new SynchronizedListBRACES(l, mutex))); } @@ -51,11 +73,22 @@ public class LISTS this.l = (IARRAY KEY_GENERIC_TYPE)l; } + @Override public void ensureCapacity(int size) { synchronized(mutex) { l.ensureCapacity(size); } } + @Override public void trim(int size) { synchronized(mutex) { l.trim(size); } } + @Override public KEY_TYPE[] elements() { synchronized(mutex) { return l.elements(); } } + + @Override + public void elements(Consumer action) { + Objects.requireNonNull(action); + synchronized(mutex) { + action.accept(elements()); + } + } } public static class SynchronizedRandomAccessList KEY_GENERIC_TYPE extends SynchronizedList KEY_GENERIC_TYPE implements RandomAccess @@ -152,7 +185,7 @@ public class LISTS #else @Override - public KEY_TYPE[] extractElements(int from, int to, Class clz) { synchronized(mutex) { return l.extractElements(from, to, clz); } } + public K[] extractElements(int from, int to, Class clz) { synchronized(mutex) { return l.extractElements(from, to, clz); } } #endif @Override @@ -183,7 +216,7 @@ public class LISTS public static class UnmodifiableList KEY_GENERIC_TYPE extends COLLECTIONS.UnmodifiableCollection KEY_GENERIC_TYPE implements LIST KEY_GENERIC_TYPE { - LIST KEY_GENERIC_TYPE l; + final LIST KEY_GENERIC_TYPE l; UnmodifiableList(LIST KEY_GENERIC_TYPE l) { super(l); @@ -261,7 +294,7 @@ public class LISTS #else @Override - public KEY_TYPE[] extractElements(int from, int to, Class clz) { throw new UnsupportedOperationException(); } + public K[] extractElements(int from, int to, Class clz) { throw new UnsupportedOperationException(); } #endif @Override @@ -343,7 +376,7 @@ public class LISTS #else @Override - public KEY_TYPE[] extractElements(int from, int to, Class clz) { throw new UnsupportedOperationException(); } + public K[] extractElements(int from, int to, Class clz) { throw new UnsupportedOperationException(); } #endif @Override