Merge pull request #343 from cicirello/deprecate

Deprecated double-valued costs constructor of EditDistance for arrays and other sequences

Author: cicirello

CHANGELOG.md

@@ -4,13 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - 2023-05-15
+## [Unreleased] - 2023-05-30
 
 ### Added
 
 ### Changed
 
 ### Deprecated
+* Deprecated double-valued costs constructor of EditDistance for arrays and other sequences, with the existing EditDistanceDouble class as its replacement. This constructor will be removed in the next major release, most likely sometime in the Fall of 2023. 
 
 ### Removed
 

src/main/java/org/cicirello/sequences/distance/EditDistance.java

@@ -1,6 +1,6 @@
 /*
  * JavaPermutationTools: A Java library for computation on permutations and sequences
- * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * Copyright 2005-2023 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
  *
@@ -29,17 +29,13 @@
  *
  * <p>Edit distance is the minimum cost to transform one string (or sequence) into the other, which
  * is the sum of the costs of the edit operations necessary to do so. This edit distance considers 3
- * edit operations: Inserts which insert a new element into the sequence, Deletes which remove an
+ * edit operations: Inserts which inserts a new element into the sequence, Deletes which removes an
  * element from the sequence, and Changes which replace an element with a different element.
  *
- * <p>The edit distance is parameterized by costs for the edit operations. We provide two
- * constructors which enable you to specify 3 costs, 1 for each type of edit operation. One of the
- * constructors expects integer costs, and the other double valued costs. If you specify costs as
- * integers, then all of the distance and distancef methods from the {@link
- * org.cicirello.sequences.distance.SequenceDistanceMeasurer SequenceDistanceMeasurer} and {@link
- * org.cicirello.sequences.distance.SequenceDistanceMeasurerDouble SequenceDistanceMeasurerDouble}
- * interfaces are available. If costs are specified as doubles, then only the distancef methods will
- * function, while the distance methods will throw exceptions.
+ * <p>The edit distance is parameterized by costs for the edit operations. The class provides a
+ * constructor which enables you to specify 3 costs as ints, 1 for each type of edit operation. If
+ * your application requires non-integer costs, then use the {@link EditDistanceDouble} class which
+ * defines the costs as doubles, but is otherwise an implementation of the same algorithm.
  *
  * <p>This class supports computing EditDistance for Java String objects or arrays of any of the
  * primitive types, or arrays of objects. It makes no assumptions about the contents of the Strings
@@ -80,7 +76,9 @@ public class EditDistance extends EditDistanceDouble implements SequenceDistance
    * @param deleteCost Cost of an deletion operation. Must be non-negative.
    * @param changeCost Cost of an change operation. Must be non-negative.
    * @throws IllegalArgumentException if any of the costs are negative.
+   * @deprecated For double-valued costs, use the {@link EditDistanceDouble} class instead.
    */
+  @Deprecated
   public EditDistance(double insertCost, double deleteCost, double changeCost) {
     super(insertCost, deleteCost, changeCost);
     if (isIntAsDouble(insertCost) && isIntAsDouble(deleteCost) && isIntAsDouble(changeCost)) {
@@ -95,8 +93,7 @@ public EditDistance(double insertCost, double deleteCost, double changeCost) {
   }
 
   /**
-   * Constructs an edit distance measure with the specified edit operation costs. With integer
-   * costs, all of the distance and distancef methods are available.
+   * Constructs an edit distance measure with the specified edit operation costs.
    *
    * @param insertCost Cost of an insertion operation. Must be non-negative.
    * @param deleteCost Cost of an deletion operation. Must be non-negative.

src/main/java/org/cicirello/sequences/distance/EditDistanceDouble.java

@@ -1,6 +1,6 @@
 /*
  * JavaPermutationTools: A Java library for computation on permutations and sequences
- * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * Copyright 2005-2023 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
  *
@@ -26,9 +26,8 @@
 /**
  * EditDistanceDouble is an implementation of Wagner and Fischer's dynamic programming algorithm for
  * computing string edit distance. This class supports double-valued costs, while the {@link
- * EditDistance} class supports both double-valued as well as int-valued costs. If your costs are
- * int-valued, the {@link EditDistance} class may be slightly faster, but not asymptotically faster.
- * If your costs are double-valued, there should be no difference (one is a subclass of the other).
+ * EditDistance} class supports int-valued costs. If your costs are int-valued, the {@link
+ * EditDistance} class may be slightly faster, but not asymptotically faster.
  *
  * <p>Edit distance is the minimum cost to transform one string (or sequence) into the other, which
  * is the sum of the costs of the edit operations necessary to do so. This edit distance considers 3

src/main/java/org/cicirello/sequences/distance/LongestCommonSubsequenceDistance.java

@@ -1,6 +1,6 @@
 /*
  * JavaPermutationTools: A Java library for computation on permutations and sequences
- * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * Copyright 2005-2023 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
  *
@@ -42,7 +42,7 @@
  * length, common set of elements, and unique elements properties of permutations to more
  * efficiently (in O(n lg n) time) compute the longest common subpermutation (i.e., that class does
  * not delegate the work to the edit distance algorithm). However, the result of ReinsertionDistance
- * is half of what LongestCommonSunsequenceDistance would compute. This is because for permutations
+ * is half of what LongestCommonSubsequenceDistance would compute. This is because for permutations
  * the elements that would be inserted are exactly the same as those that would be deleted by the
  * edit operations, and ReinsertionDistance is defined as an edit distance with one edit operation,
  * removal/reinsertion (i.e., a deletion is only half the operation, and the insertion is the other

src/test/java/org/cicirello/sequences/distance/EditDistanceTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * Copyright 2018-2023 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
  *
@@ -30,6 +30,7 @@
 public class EditDistanceTests extends InternalTestHelpersSequenceDistance {
 
   @Test
+  @SuppressWarnings("deprecation")
   public void testEditDistanceExceptions() {
     final EditDistance d = new EditDistance(1.5, 1.5, 1.5);
     UnsupportedOperationException thrown =
@@ -118,6 +119,7 @@ public void testEditObjectSequences() {
   }
 
   @Test
+  @SuppressWarnings("deprecation")
   public void testIdentical() {
     EditDistance d = new EditDistance(1, 2, 10);
     identicalSequences(d);
@@ -145,6 +147,7 @@ public void testIdentical() {
   }
 
   @Test
+  @SuppressWarnings("deprecation")
   public void testEditDistance() {
     int cost_i = 1;
     int cost_d = 1;