Added JavaDoc for PriorityQueues

This commit is contained in:
Speiger 2021-04-26 02:08:08 +02:00
parent 0017697b07
commit f7d311fd09
7 changed files with 317 additions and 5 deletions

View File

@ -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);
}

View File

@ -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();

View File

@ -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();

View File

@ -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
}

View File

@ -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<KEY_TYPE>
#else
@ -15,26 +19,80 @@ public interface PRIORITY_QUEUE KEY_GENERIC_TYPE extends ObjectPriorityQueue<CLA
#endif
{
#if TYPE_OBJECT
/**
* @return true if the PriorityQueue is empty
*/
public default boolean isEmpty() { return size() <= 0; }
/**
* @return the amount of elements that are stored in the PriorityQueue
*/
public int size();
/**
* clears all elements within the PriorityQueue,
* this does not resize the backing arrays
*/
public void clear();
#endif
/**
* Method to insert a element into the PriorityQueue
* @param e the element that should be inserted
*/
public void ENQUEUE(KEY_TYPE e);
/**
* Method to extract a element from the PriorityQueue
* @return a element from the Queue
* @throws java.util.NoSuchElementException if no element is present
*/
public KEY_TYPE DEQUEUE();
/**
* Peeking function to see whats inside the queue.
* @param index of the element that is requested to be viewed.
* @return the element that is requested
*/
public KEY_TYPE PEEK(int index);
/**
* Shows the element that is to be returned next
* @return the first element in the Queue
*/
public default KEY_TYPE FIRST_KEY() { return PEEK(0); }
/**
* Removes the first found element in the queue
* @param e the element that should be removed
* @return if a searched element was removed
*/
public boolean REMOVE(KEY_TYPE e);
/**
* Removes the last found element in the queue
* @param e the element that should be removed
* @return if a searched element was removed
*/
public boolean REMOVE_LAST(KEY_TYPE e);
/**
* Allows to notify the Queue to be revalidate its data
*/
public void onChanged();
/**
* @return the sorter of the Queue, can be null
*/
@PrimitiveOverride
public COMPARATOR KEY_SUPER_GENERIC_TYPE comparator();
/**
* A method to drop the contents of the Queue without clearing the queue
* @return the contents of the queue into a seperate array.
*/
public default KEY_TYPE[] TO_ARRAY() { return TO_ARRAY(NEW_KEY_ARRAY(size())); }
/**
* A method to drop the contents of the Queue without clearing the queue
* @param input where the elements should be inserted to. If it does not fit then it creates a new appropiatly created array
* @return the contents of the queue into a seperate array.
* @note if the Type is generic then a Object Array is created instead of a Type Array
*/
public KEY_TYPE[] TO_ARRAY(KEY_TYPE[] input);
#if !TYPE_OBJECT

View File

@ -88,6 +88,7 @@ public class MAPS
/**
* A Helper function that provides a faster forEach iterator implementation that recycles the entry to increase throughput
* @param map the map the fast forEach should be accessed from
* @param action the action that should be performed on each entry
* @note if the fast forEach is not supported will default to a normal forEach
*/
public static GENERIC_KEY_VALUE_BRACES void fastForEach(MAP KEY_VALUE_GENERIC_TYPE map, Consumer<MAP.Entry KEY_VALUE_GENERIC_TYPE> action) {

View File

@ -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;