feat: add KeySorter and SortKind.RADIX

pom.xml

@@ -10,7 +10,7 @@
         <relativePath/>
     </parent>
     <artifactId>alda_sorting_api</artifactId>
-    <version>1.2.0</version>
+    <version>1.3.0</version>
     <packaging>jar</packaging>
     <name>Sorting Service API</name>
     <properties>

src/main/java/sortingservice/KeySorter.java

@@ -0,0 +1,37 @@
+package sortingservice;
+
+import java.util.function.ToIntFunction;
+
+/**
+ * A key sorter sorts its input on an integer key, without comparing elements.
+ *
+ * <p>
+ * Where a {@link Sorter} can only compare two elements with a
+ * {@link java.util.Comparator Comparator}, a key sorter gets access to the
+ * key of every element. This restriction on the input allows sorting in
+ * linear time, e.g. with radix sort.
+ * </p>
+ *
+ * The implementation is expected to return the <b>same</b> queue instance.
+ *
+ * @author Martijn Bonajo
+ * @param <T> type of elements in queue.
+ */
+@FunctionalInterface
+public interface KeySorter<T> {
+
+    /**
+     * Return the input queue in sorted order, based on the key of the elements.
+     *
+     * <p>
+     * The sort is <b>stable</b>: elements with equal keys keep their relative
+     * order.
+     * </p>
+     *
+     * @param queue to be sorted
+     * @param key extracts the key of an element, the key must be non-negative
+     * @return the queue with the elements in non-descending order of their key.
+     * @throws IllegalArgumentException if the key of an element is negative.
+     */
+    Queue<T> sort( Queue<T> queue, ToIntFunction<T> key );
+}

src/main/java/sortingservice/SortKind.java

@@ -23,5 +23,9 @@ public enum SortKind  {
     /**
      * Heap sort.
      */
-    HEAP;
+    HEAP,
+    /**
+     * Radix sort.
+     */
+    RADIX;
 }

src/main/java/sortingservice/SorterConfiguration.java

@@ -30,7 +30,8 @@ public interface SorterConfiguration {
     /**
      * Get queue for sorter.
      * @param <T> the type of elements in the queue
-     * @return queue for sorter
+     * @return queue for sorter, or null if configuration uses a priority
+     * queue (see {@link #getPriorityQueue(Comparator)}).
      */
     <T> Queue<T> getQueue();
 
@@ -44,12 +45,33 @@ public interface SorterConfiguration {
     <T> PriorityQueue<T> getPriorityQueue(Comparator<T> comparator);
 
     /**
-     * Get a sorter. 
+     * Get a sorter.
+     * A configuration that uses a priority queue returns a sorter that
+     * returns the queue as is, since the priority queue sorts by itself.
      * @param <T> the type of elements in the queue
-     * @return sorter
+     * @return sorter, or null if configuration uses a key sorter (see
+     * {@link #getKeySorter()}).
      */
     <T> Sorter<T> getSorter();
 
+    /**
+     * Indicates whether this sorter uses a key sorter.
+     * @return true if configuration uses key sorter, false by default.
+     */
+    default boolean usesKeySorter() {
+        return false;
+    }
+
+    /**
+     * Get a key sorter.
+     * @param <T> the type of elements in the queue
+     * @return key sorter or null if configuration does not use a key sorter,
+     * null by default.
+     */
+    default <T> KeySorter<T> getKeySorter() {
+        return null;
+    }
+
     /**
      * Indicates whether the teacher tests should test this configuration.
      * Your own tests should test all configurations.