From f7d311fd094fdd5916d7529ada268b93845ba2d4 Mon Sep 17 00:00:00 2001 From: Speiger Date: Mon, 26 Apr 2021 02:08:08 +0200 Subject: [PATCH] Added JavaDoc for PriorityQueues --- .../templates/queues/ArrayFIFOQueue.template | 41 +++++++- .../queues/ArrayPriorityQueue.template | 94 ++++++++++++++++++- .../queues/HeapPriorityQueue.template | 91 +++++++++++++++++- .../templates/queues/PriorityDequeue.template | 34 +++++++ .../templates/queues/PriorityQueue.template | 58 ++++++++++++ .../templates/utils/maps/Maps.template | 1 + .../collections/ints/utils/SortingTests.java | 3 + 7 files changed, 317 insertions(+), 5 deletions(-) diff --git a/src/builder/resources/speiger/assets/collections/templates/queues/ArrayFIFOQueue.template b/src/builder/resources/speiger/assets/collections/templates/queues/ArrayFIFOQueue.template index 5931f21a..6337a0e5 100644 --- a/src/builder/resources/speiger/assets/collections/templates/queues/ArrayFIFOQueue.template +++ b/src/builder/resources/speiger/assets/collections/templates/queues/ArrayFIFOQueue.template @@ -12,22 +12,49 @@ import speiger.src.collections.PACKAGE.functions.COMPARATOR; #endif import speiger.src.collections.utils.ITrimmable; +/** + * A Simple First In First Out Priority Queue that is a Good Replacement for a linked list (or ArrayDequeue) + * Its specific implementation uses a backing array that grows and shrinks as it is needed. + * @Type(T) + */ public class ARRAY_FIFO_QUEUE KEY_GENERIC_TYPE implements PRIORITY_DEQUEUE KEY_GENERIC_TYPE, ITrimmable { + /** Max Possible ArraySize without the JVM Crashing */ private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8; + /** The Minimum Capacity that is allowed */ public static final int MIN_CAPACITY = 4; + /** The Backing array */ protected transient KEY_TYPE[] array; + /** The First Index pointer */ protected int first; + /** The Last Index pointer */ protected int last; + /** + * Constructor using a initial array + * @param values the Array that should be used + */ public ARRAY_FIFO_QUEUE(KEY_TYPE[] values) { this(values, 0, values.length); } - + + /** + * Constructor using a initial array + * @param values the Array that should be used + * @param size the amount of elements that are in the initial array + * @throws IllegalStateException if values is smaller then size + */ public ARRAY_FIFO_QUEUE(KEY_TYPE[] values, int size) { this(values, 0, size); } - + + /** + * Constructor using a initial array + * @param values the Array that should be used + * @param offset where to begin in the initial array + * @param size the amount of elements that are in the initial array + * @throws IllegalStateException if values is smaller then size + */ public ARRAY_FIFO_QUEUE(KEY_TYPE[] values, int offset, int size) { if (values.length < size) throw new IllegalArgumentException("Initial array (" + values.length + ") is smaller then the expected size (" + size + ")"); if(values.length <= 0) values = NEW_KEY_ARRAY(1); @@ -37,11 +64,19 @@ public class ARRAY_FIFO_QUEUE KEY_GENERIC_TYPE implements PRIORITY_DEQUEUE KEY_G if(array.length == size) expand(); } + /** + * Constructor with a Min Capacity + * @param capacity the initial capacity of the backing array + * @throws IllegalStateException if the initial size is smaller 0 + */ public ARRAY_FIFO_QUEUE(int capacity) { if (capacity < 0) throw new IllegalArgumentException("Initial capacity (" + capacity + ") is negative"); array = NEW_KEY_ARRAY(Math.max(1, capacity)); } - + + /** + * Default Construtor + */ public ARRAY_FIFO_QUEUE() { this(MIN_CAPACITY); } diff --git a/src/builder/resources/speiger/assets/collections/templates/queues/ArrayPriorityQueue.template b/src/builder/resources/speiger/assets/collections/templates/queues/ArrayPriorityQueue.template index 810be10c..cff6cd04 100644 --- a/src/builder/resources/speiger/assets/collections/templates/queues/ArrayPriorityQueue.template +++ b/src/builder/resources/speiger/assets/collections/templates/queues/ArrayPriorityQueue.template @@ -14,61 +14,138 @@ import speiger.src.collections.PACKAGE.functions.COMPARATOR; #endif import speiger.src.collections.PACKAGE.utils.ARRAYS; +/** + * A Array Priority Queue, this is a very unoptimized implementation of the PriorityQueue for very specific usecases. + * It allows for duplicated entries and works like {@link java.util.List#indexOf(Object)} search. + * It is highly suggested to use HeapPriorityQueue otherwise, unless you know why you need this specific implementation + * @Type(T) + */ public class ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY_GENERIC_TYPE { + /** The Backing Array */ protected transient KEY_TYPE[] array = EMPTY_KEY_ARRAY; + /** The Amount of elements stored within the array */ protected int size; + /** The Last known first index pointer */ protected int firstIndex = -1; + /** The Sorter of the Array */ protected COMPARATOR KEY_SUPER_GENERIC_TYPE comparator; + /** + * Default Constructor + */ public ARRAY_PRIORITY_QUEUE() { this(0, null); } + /** + * Constructor using custom sorter + * @param comp Comparator to sort the Array. Can be null + */ public ARRAY_PRIORITY_QUEUE(COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { this(0, comp); } + /** + * Constructor with a Min Capacity + * @param size the initial capacity of the backing array + * @throws IllegalStateException if the initial size is smaller 0 + */ + public ARRAY_PRIORITY_QUEUE(int size) { + this(size, null); + } + + /** + * Constructor with a Min Capacity and custom Sorter + * @param size the initial capacity of the backing array + * @param comp Comparator to sort the Array. Can be null + * @throws IllegalStateException if the initial size is smaller 0 + */ public ARRAY_PRIORITY_QUEUE(int size, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { + if(size < 0) throw new IllegalAccessError("Size has to be 0 or positive"); if(size > 0) array = NEW_KEY_ARRAY(size); this.size = size; comparator = comp; } + /** + * Constructor using a initial array + * @param array the Array that should be used + */ public ARRAY_PRIORITY_QUEUE(KEY_TYPE[] array) { this(array, array.length); } + /** + * Constructor using a initial array + * @param array the Array that should be used + * @param size the amount of elements found within the array + * @throws NegativeArraySizeException if size is smaller then 0 + */ public ARRAY_PRIORITY_QUEUE(KEY_TYPE[] array, int size) { this.array = Arrays.copyOf(array, size); this.size = size; } + /** + * Constructor using a initial array and a custom sorter + * @param array the Array that should be used + * @param comp Comparator to sort the Array. Can be null + */ public ARRAY_PRIORITY_QUEUE(KEY_TYPE[] array, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { this(array, array.length, comp); } + /** + * Constructor using a initial array and a custom sorter + * @param array the Array that should be used + * @param size the amount of elements found within the array + * @param comp Comparator to sort the Array. Can be null + * @throws NegativeArraySizeException if size is smaller then 0 + */ public ARRAY_PRIORITY_QUEUE(KEY_TYPE[] array, int size, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { this.array = Arrays.copyOf(array, size); this.size = size; this.comparator = comp; } + /** + * Constructor using a Collection + * @param c the Collection that should be used + */ public ARRAY_PRIORITY_QUEUE(COLLECTION KEY_GENERIC_TYPE c) { array = CAST_KEY_ARRAY c.TO_ARRAY(); size = c.size(); } + /** + * Constructor using a Collection and a custom sorter + * @param c the Collection that should be used + * @param comp Comparator to sort the Array. Can be null + */ public ARRAY_PRIORITY_QUEUE(COLLECTION KEY_GENERIC_TYPE c, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { array = CAST_KEY_ARRAY c.TO_ARRAY(); size = c.size(); comparator = comp; } + /** + * Wrapping method to help serialization + * @param array the array that should be used + * @Type(T) + * @return a ArrayPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array) { return wrap(array, array.length); } + /** + * Wrapping method to help serialization + * @param array the array that should be used + * @param size the amount of elements within the array + * @Type(T) + * @return a ArrayPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array, int size) { ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE queue = new ARRAY_PRIORITY_QUEUEBRACES(); queue.array = array; @@ -76,10 +153,25 @@ public class ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY return queue; } + /** + * Wrapping method to help serialization, using a custom sorter + * @param array the array that should be used + * @param comp Comparator to sort the Array. Can be null + * @Type(T) + * @return a ArrayPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { return wrap(array, array.length, comp); } + /** + * Wrapping method to help serialization, using a custom sorter + * @param array the array that should be used + * @param size the amount of elements within the array + * @param comp Comparator to sort the Array. Can be null + * @Type(T) + * @return a ArrayPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array, int size, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE queue = new ARRAY_PRIORITY_QUEUEBRACES(comp); queue.array = array; @@ -206,7 +298,7 @@ public class ARRAY_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY return firstIndex; } - public class Iter implements ITERATOR KEY_GENERIC_TYPE { + private class Iter implements ITERATOR KEY_GENERIC_TYPE { @Override public boolean hasNext() { return !isEmpty(); diff --git a/src/builder/resources/speiger/assets/collections/templates/queues/HeapPriorityQueue.template b/src/builder/resources/speiger/assets/collections/templates/queues/HeapPriorityQueue.template index 569dd0d5..5d091a04 100644 --- a/src/builder/resources/speiger/assets/collections/templates/queues/HeapPriorityQueue.template +++ b/src/builder/resources/speiger/assets/collections/templates/queues/HeapPriorityQueue.template @@ -14,40 +14,92 @@ import speiger.src.collections.PACKAGE.functions.COMPARATOR; #endif import speiger.src.collections.PACKAGE.utils.ARRAYS; +/** + * A Simple Heap base Priority Queue implementation + * It is a ArrayBased Alternative to TreeSets that has less object allocations + * @Type(T) + */ public class HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY_GENERIC_TYPE { + /** The Backing Array */ protected transient KEY_TYPE[] array = EMPTY_KEY_ARRAY; + /** The Amount of elements stored within the array */ protected int size; + /** The Sorter of the Array */ protected COMPARATOR KEY_SUPER_GENERIC_TYPE comparator; + /** + * Default Constructor + */ public HEAP_PRIORITY_QUEUE() { this(0, null); } + /** + * Constructor using custom sorter + * @param comp Comparator to sort the Array. Can be null + */ public HEAP_PRIORITY_QUEUE(COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { this(0, comp); } + /** + * Constructor with a Min Capacity + * @param size the initial capacity of the backing array + * @throws IllegalStateException if the initial size is smaller 0 + */ + public HEAP_PRIORITY_QUEUE(int size) { + this(size, null); + } + + /** + * Constructor with a Min Capacity and custom Sorter + * @param size the initial capacity of the backing array + * @param comp Comparator to sort the Array. Can be null + * @throws IllegalStateException if the initial size is smaller 0 + */ public HEAP_PRIORITY_QUEUE(int size, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { if(size > 0) array = NEW_KEY_ARRAY(size); this.size = size; comparator = comp; } + /** + * Constructor using a initial array + * @param array the Array that should be used + */ public HEAP_PRIORITY_QUEUE(KEY_TYPE[] array) { this(array, array.length); } + /** + * Constructor using a initial array + * @param array the Array that should be used + * @param size the amount of elements found within the array + * @throws NegativeArraySizeException if size is smaller then 0 + */ public HEAP_PRIORITY_QUEUE(KEY_TYPE[] array, int size) { this.array = Arrays.copyOf(array, size); this.size = size; ARRAYS.heapify(array, size, null); } + /** + * Constructor using a initial array and a custom sorter + * @param array the Array that should be used + * @param comp Comparator to sort the Array. Can be null + */ public HEAP_PRIORITY_QUEUE(KEY_TYPE[] array, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { this(array, array.length, comp); } + /** + * Constructor using a initial array and a custom sorter + * @param array the Array that should be used + * @param size the amount of elements found within the array + * @param comp Comparator to sort the Array. Can be null + * @throws NegativeArraySizeException if size is smaller then 0 + */ public HEAP_PRIORITY_QUEUE(KEY_TYPE[] array, int size, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { this.array = Arrays.copyOf(array, size); this.size = size; @@ -55,12 +107,21 @@ public class HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY_ ARRAYS.heapify(array, size, comp); } + /** + * Constructor using a Collection + * @param c the Collection that should be used + */ public HEAP_PRIORITY_QUEUE(COLLECTION KEY_GENERIC_TYPE c) { array = CAST_KEY_ARRAY c.TO_ARRAY(); size = c.size(); ARRAYS.heapify(array, size, null); } + /** + * Constructor using a Collection and a custom sorter + * @param c the Collection that should be used + * @param comp Comparator to sort the Array. Can be null + */ public HEAP_PRIORITY_QUEUE(COLLECTION KEY_GENERIC_TYPE c, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { array = CAST_KEY_ARRAY c.TO_ARRAY(); size = c.size(); @@ -68,10 +129,23 @@ public class HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY_ ARRAYS.heapify(array, size, comp); } + /** + * Wrapping method to help serialization + * @param array the array that should be used + * @Type(T) + * @return a HeapPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array) { return wrap(array, array.length); } + /** + * Wrapping method to help serialization + * @param array the array that should be used + * @param size the amount of elements within the array + * @Type(T) + * @return a HeapPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array, int size) { HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE queue = new HEAP_PRIORITY_QUEUEBRACES(); queue.array = array; @@ -80,10 +154,25 @@ public class HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY_ return queue; } + /** + * Wrapping method to help serialization, using a custom sorter + * @param array the array that should be used + * @param comp Comparator to sort the Array. Can be null + * @Type(T) + * @return a HeapPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { return wrap(array, array.length, comp); } + /** + * Wrapping method to help serialization, using a custom sorter + * @param array the array that should be used + * @param size the amount of elements within the array + * @param comp Comparator to sort the Array. Can be null + * @Type(T) + * @return a HeapPriorityQueue containing the original input array + */ public static GENERIC_KEY_BRACES HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE wrap(KEY_TYPE[] array, int size, COMPARATOR KEY_SUPER_GENERIC_TYPE comp) { HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE queue = new HEAP_PRIORITY_QUEUEBRACES(comp); queue.array = array; @@ -185,7 +274,7 @@ public class HEAP_PRIORITY_QUEUE KEY_GENERIC_TYPE implements PRIORITY_QUEUE KEY_ } #endif - public class Iter implements ITERATOR KEY_GENERIC_TYPE { + private class Iter implements ITERATOR KEY_GENERIC_TYPE { @Override public boolean hasNext() { return !isEmpty(); diff --git a/src/builder/resources/speiger/assets/collections/templates/queues/PriorityDequeue.template b/src/builder/resources/speiger/assets/collections/templates/queues/PriorityDequeue.template index 9c77015d..c484685d 100644 --- a/src/builder/resources/speiger/assets/collections/templates/queues/PriorityDequeue.template +++ b/src/builder/resources/speiger/assets/collections/templates/queues/PriorityDequeue.template @@ -1,14 +1,48 @@ package speiger.src.collections.PACKAGE.queues; +/** + * A Type Speciifc PriorityDeque or Dequeue interface to allow implementations like FIFO queues. + * @Type(T) + */ public interface PRIORITY_DEQUEUE KEY_GENERIC_TYPE extends PRIORITY_QUEUE KEY_GENERIC_TYPE { + /** + * Method to insert a element into the first Index instead of the last. + * @param e the element that should be inserted into the first place + */ public void ENQUEUE_FIRST(KEY_TYPE e); + /** + * A Method to remove a element from the last place instead of the first + * @return the last element inserted + * @throws java.util.NoSuchElementException if no element is in the deque + */ public KEY_TYPE DEQUEUE_LAST(); + /** + * Peeking function for the last element + * @return the Last Element within the dequeue without deleting it + */ public default KEY_TYPE LAST_KEY() { return PEEK(size()-1); } #if !TYPE_OBJECT + /** + * Boxed Method for the enqueue first method + * @param e the boxed element that should be inserted + */ + @Deprecated public default void enqueueFirst(CLASS_TYPE e) { ENQUEUE_FIRST(OBJ_TO_KEY(e)); } + /** + * Boxed Method for the dequeue last method + * @return the last element of the Dequeue + * @throws java.util.NoSuchElementException if no element is in the dequeue + * + */ + @Deprecated public default CLASS_TYPE dequeueLast() { return KEY_TO_OBJ(DEQUEUE_LAST()); } + /** + * Peeking function for the last element + * @return the Last Element within the dequeue without deleting it as boxed element + */ + @Deprecated public default CLASS_TYPE last() { return peek(size()-1); } #endif } \ No newline at end of file diff --git a/src/builder/resources/speiger/assets/collections/templates/queues/PriorityQueue.template b/src/builder/resources/speiger/assets/collections/templates/queues/PriorityQueue.template index ddd52ca3..8ee734e4 100644 --- a/src/builder/resources/speiger/assets/collections/templates/queues/PriorityQueue.template +++ b/src/builder/resources/speiger/assets/collections/templates/queues/PriorityQueue.template @@ -8,6 +8,10 @@ import speiger.src.collections.PACKAGE.functions.COMPARATOR; import speiger.src.collections.objects.queues.ObjectPriorityQueue; #endif +/** + * A Simple PriorityQueue (or Queue) interface that provides with the nessesary functions to interact with it, without cluttering with the Collection interface. + * @Type(T) + */ #if TYPE_OBJECT public interface PRIORITY_QUEUE KEY_GENERIC_TYPE extends Iterable #else @@ -15,26 +19,80 @@ public interface PRIORITY_QUEUE KEY_GENERIC_TYPE extends ObjectPriorityQueue action) { diff --git a/src/test/java/speiger/src/collections/ints/utils/SortingTests.java b/src/test/java/speiger/src/collections/ints/utils/SortingTests.java index 6b272124..75aaf2f0 100644 --- a/src/test/java/speiger/src/collections/ints/utils/SortingTests.java +++ b/src/test/java/speiger/src/collections/ints/utils/SortingTests.java @@ -1,7 +1,10 @@ package speiger.src.collections.ints.utils; import java.util.Arrays; +import java.util.Spliterators; import java.util.stream.IntStream; +import java.util.stream.Stream; +import java.util.stream.StreamSupport; import org.junit.Assert; import org.junit.Test;