Merge pull request #4 from ZoftWhere/feature/release-3.0.0

Release 3.0.0

main-github/release-notes/3.0.0.md

@@ -0,0 +1,43 @@
+## Release Notes - Version 3.0.0
+
+* Updated Generator class.
+    * Added method to create empty permutations.
+    * Added check to ensure that the permutation size is zero or positive.
+    * Added check to ensure that the permutation k-sizes are smaller than size.
+* Updated N-Tuple and k-size semantics.
+    * Renamed n-tuple Permutation to multi-set Permutation.
+    * Updated description for k-size to denote permutation sequence length.
+* Added K-Tuple arrangements.
+    * Added tuple factory methods to generator class.
+    * Added tuple test classes.
+    * Added tuple example.
+* Added Calculator class.
+    * Added method for calculating a factorial.
+    * Added method for calculating a binomial coefficient.
+    * Added method for calculating permutation count for partial permutations.
+* Updated Permutation interface with method to calculate permutation count.
+    * Empty Permutation will always return a count of zero.
+    * Void Permutation will always return the permutation count for size and k-size.
+    * Basic Permutation will always return the permutation count for size and k-size.
+    * Multi-Set Permutation will only return a result if not k-permutation of multi-set.
+* Updated exception message keys.
+* Added example for calculating the upper-bound permutations for a Tic-Tac-Toe board.
+* Updated warning suppression.
+    * Updated warning suppression for permutation newInstance method.
+* Updated test classes.
+    * Updated PermutationTest with index check test.
+    * Updated assertClass method with expected class type first.
+    * Reworked Permutation Example.
+    * Updated Series Test.
+    * Added Series Example.
+    * Updated Sequence Test.
+    * Reworked Sequence Example.
+    * Removed CountPermutation example.
+* Updated code structure.
+    * Removed overridden next method from void permutation class.
+    * Renamed variable to indicate copy in abstract permutation class.
+    * Moved helper order array creator method to generator class.
+    * Updated base fields for void permutation from basic permutation class.
+    * Moved assert class method from permutation test to test helper class.
+* Updated JavaDoc.
+    * Added JavaDoc since tags.

main-java/app/zoftwhere/combinatoric/AbstractKTuple.java

@@ -0,0 +1,200 @@
+package app.zoftwhere.combinatoric;
+
+import java.math.BigInteger;
+import java.util.List;
+
+/**
+ * <p>Abstract Permutation.
+ * </p>
+ * <p>This is a package-private abstract class for generic functionality.
+ * </p>
+ *
+ * @author Osmund
+ * @since 3.0.0
+ */
+abstract class AbstractKTuple<T> implements KTuple<T> {
+
+    final int[] index;
+
+    private final int size;
+
+    final List<T> kSet;
+
+    private final int kSize;
+
+    /**
+     * Package-private constructor to initialize a new k-tuple.
+     *
+     * @param index index array
+     * @param kSet  ordered set of k-elements
+     * @param kSize count of k-tuple elements
+     * @since 3.0.0
+     */
+    AbstractKTuple(int[] index, List<T> kSet, int kSize) {
+        this.index = index;
+        this.size = index.length;
+        this.kSet = kSet;
+        this.kSize = kSize;
+    }
+
+    /**
+     * Returns an immutable instance with the values in the clone.
+     *
+     * @param index index array
+     * @param kSet  ordered set of k-elements
+     * @param kSize count of k-tuple elements
+     * @return immutable permutation instance.
+     * @since 3.0.0
+     */
+    protected abstract KTuple<T> newInstance(int[] index, List<T> kSet, int kSize);
+
+    /** {@inheritDoc} */
+    @Override
+    public int size() {
+        return size;
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public int kSize() {
+        return kSize;
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public boolean isEmpty() {
+        return size == 0;
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public boolean isPresent() {
+        return size != 0;
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public int[] index() {
+        int[] copy = new int[size];
+        System.arraycopy(index, 0, copy, 0, size);
+        return copy;
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public int index(int position) {
+        checkPosition(position);
+        return index[position];
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public abstract List<T> value();
+
+    /** {@inheritDoc} */
+    @Override
+    public abstract T value(int position);
+
+    /** {@inheritDoc} */
+    @Override
+    public KTuple<T> next() {
+        return next(size - 1);
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public KTuple<T> next(int position) {
+        checkPosition(position);
+
+        int[] next = advance(position);
+        if (next == null) {
+            return new KTupleEmpty<>();
+        }
+        for (int i = position + 1; i < size; i++) {
+            next[i] = 0;
+        }
+
+        return newInstance(next, kSet, kSize);
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public BigInteger count() {
+        if (size == 0 || kSize == 0) {
+            return BigInteger.ZERO;
+        }
+        return BigInteger.valueOf(kSize).pow(size);
+    }
+
+    /**
+     * Check the position.
+     *
+     * @param position position
+     * @since 3.0.0
+     */
+    final void checkPosition(int position) {
+        if (position < 0 || position >= size) {
+            String message = "tuple.check.position.invalid.position";
+            Exception cause = new Exception(String.format("size: %d position: %d", size, position));
+            throw new IllegalArgumentException(message, cause);
+        }
+    }
+
+    /**
+     * Helper method for advancing at a give position.
+     *
+     * @param position the index position to advance
+     * @return the index array after advancement
+     * @since 3.0.0
+     */
+    private int[] advance(int position) {
+        int[] copy = new int[size];
+        System.arraycopy(index, 0, copy, 0, size);
+
+        while (position >= 0) {
+            copy[position]++;
+            if (copy[position] != kSize) {
+                return copy;
+            }
+            copy[position] = 0;
+            position--;
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns string representation for the k-tuple.
+     *
+     * @return string representation for the k-tuple
+     */
+    @Override
+    public String toString() {
+
+        // Build string for empty k-tuple.
+        if (size == 0) {
+            return "[]";
+        }
+
+        // Build string for index-only k-tuple.
+        else if (kSet == null) {
+            StringBuilder builder = new StringBuilder("[");
+            builder.append(String.format("%d", index[0]));
+            for (int i = 1; i < size; i++) {
+                builder.append(String.format(", %d", index[i]));
+            }
+            return builder.append("]").toString();
+        }
+
+        // Build string for k-set k-tuple.
+        else {
+            StringBuilder builder = new StringBuilder("[");
+            builder.append(String.format("%d:%s", index[0], kSet.get(0)));
+            for (int i = 1; i < size; i++) {
+                builder.append(String.format(", %d:%s", index[i], kSet.get(index[i])));
+            }
+            return builder.append("]").toString();
+        }
+    }
+
+}

main-java/app/zoftwhere/combinatoric/AbstractPermutation.java

@@ -1,9 +1,10 @@
 package app.zoftwhere.combinatoric;
 
+import java.math.BigInteger;
 import java.util.Arrays;
 import java.util.List;
 
-import static app.zoftwhere.combinatoric.Generator.empty;
+import static app.zoftwhere.combinatoric.Generator.emptyPermutation;
 
 /**
  * <p>Abstract Permutation.
@@ -12,6 +13,7 @@
  * </p>
  *
  * @author Osmund
+ * @since 1.0.0
  */
 abstract class AbstractPermutation<T> implements Permutation<T> {
 
@@ -26,6 +28,7 @@ abstract class AbstractPermutation<T> implements Permutation<T> {
      *
      * @param index index array
      * @param kSize count of permutation elements
+     * @since 2.1.0
      */
     AbstractPermutation(int[] index, int kSize) {
         this.index = index;
@@ -40,7 +43,9 @@ abstract class AbstractPermutation<T> implements Permutation<T> {
      * @param list  list of elements
      * @param kSize count of permutation elements
      * @return immutable permutation instance.
+     * @since 2.0.0
      */
+    @SuppressWarnings("unused")
     protected abstract Permutation<T> newInstance(int[] index, List<T> list, int kSize);
 
     /** {@inheritDoc} */
@@ -68,10 +73,11 @@ public boolean isPresent() {
     }
 
     /** {@inheritDoc} */
+    @Override
     public int[] index() {
-        int[] push = new int[size];
-        System.arraycopy(index, 0, push, 0, size);
-        return push;
+        int[] copy = new int[size];
+        System.arraycopy(index, 0, copy, 0, size);
+        return copy;
     }
 
     /** {@inheritDoc} */
@@ -85,13 +91,14 @@ public int index(int position) {
     public abstract List<T> value();
 
     /** {@inheritDoc} */
+    @Override
     public abstract T value(int position);
 
     /** {@inheritDoc} */
     @Override
     public Permutation<T> next() {
         if (size < 2) {
-            return empty();
+            return emptyPermutation();
         }
         return next(Math.min(size - 2, kSize - 1));
     }
@@ -120,16 +127,23 @@ public Permutation<T> next(int position) {
     @Override
     public abstract Permutation<T> progress(int position);
 
+    /** {@inheritDoc} */
+    @Override
+    public abstract BigInteger count();
+
     /**
      * Check the position.
      *
      * @param position position
      * @return if check successful, false otherwise
+     * @since 2.0.0
      */
     boolean checkPosition(int position) {
         if (position < 0 || position >= size) {
-            final String template = "Index %d out of bounds for length %d";
-            throw new ArrayIndexOutOfBoundsException(String.format(template, position, size));
+            // @since 3.0.0
+            String message = "permutation.check.position.invalid.position";
+            Exception cause = new Exception(String.format("size: %d position: %d", size, position));
+            throw new IllegalArgumentException(message, cause);
         }
 
         return (position < size - 1) && (position < kSize);
@@ -142,6 +156,7 @@ boolean checkPosition(int position) {
      * @param left  the index position to advance
      * @param right the replacement position index array index
      * @return the index array after advancement
+     * @since 2.0.0
      */
     int[] advance(int[] index, int left, int right) {
         int[] push = new int[size];
@@ -152,18 +167,4 @@ int[] advance(int[] index, int left, int right) {
         return push;
     }
 
-    /**
-     * Creates an ordered index array for the permutation.
-     *
-     * @param size the size of the array
-     * @return an ordered index array
-     */
-    static int[] orderedArray(int size) {
-        final int[] index = new int[size];
-        for (int i = 0; i < size; i++) {
-            index[i] = i;
-        }
-        return index;
-    }
-
 }