Implement Optimal String Alignment (OSA) Distance Algorithm

Algorithms.Tests/Strings/Similarity/OptimalStringAlignmentTests.cs

@@ -0,0 +1,74 @@
+using Algorithms.Strings.Similarity;
+using FluentAssertions;
+using NUnit.Framework;
+using System;
+
+namespace Algorithms.Tests.Strings.Similarity
+{
+    [TestFixture]
+    public class OptimalStringAlignmentTests
+    {
+        [Test]
+        public void Calculate_IdenticalStrings_ReturnsZero()
+        {
+            var result = OptimalStringAlignment.Calculate("example", "example");
+            result.Should().Be(0.0);
+        }
+
+        [Test]
+        public void Calculate_FirstStringEmpty_ReturnsLengthOfSecondString()
+        {
+            var result = OptimalStringAlignment.Calculate("", "example");
+            result.Should().Be("example".Length);
+        }
+
+        [Test]
+        public void Calculate_SecondStringEmpty_ReturnsLengthOfFirstString()
+        {
+            var result = OptimalStringAlignment.Calculate("example", "");
+            result.Should().Be("example".Length);
+        }
+
+        [Test]
+        public void Calculate_BothStringsEmpty_ReturnsZero()
+        {
+            var result = OptimalStringAlignment.Calculate("", "");
+            result.Should().Be(0.0);
+        }
+
+        [Test]
+        public void Calculate_OneInsertion_ReturnsOne()
+        {
+            var result = OptimalStringAlignment.Calculate("example", "examples");
+            result.Should().Be(1.0);
+        }
+
+        [Test]
+        public void Calculate_OneDeletion_ReturnsOne()
+        {
+            var result = OptimalStringAlignment.Calculate("examples", "example");
+            result.Should().Be(1.0);
+        }
+
+        [Test]
+        public void Calculate_OneSubstitution_ReturnsOne()
+        {
+            var result = OptimalStringAlignment.Calculate("example", "exbmple");
+            result.Should().Be(1.0);
+        }
+
+        [Test]
+        public void Calculate_OneTransposition_ReturnsOne()
+        {
+            var result = OptimalStringAlignment.Calculate("example", "exmaple");
+            result.Should().Be(1.0);
+        }
+
+        [Test]
+        public void Calculate_MultipleOperations_ReturnsCorrectDistance()
+        {
+            var result = OptimalStringAlignment.Calculate("kitten", "sitting");
+            result.Should().Be(3.0);
+        }
+    }
+}

Algorithms/Strings/Similarity/OptimalStringAlignment.cs

@@ -0,0 +1,157 @@
+using System;
+
+namespace Algorithms.Strings.Similarity
+{
+    /// <summary>
+    /// Provides methods to calculate the Optimal String Alignment distance between two strings.
+    ///
+    /// The Optimal String Alignment distance, also known as the restricted Damerau-Levenshtein distance,
+    /// is a string metric used to measure the difference between two sequences. It is similar to the
+    /// Levenshtein distance, but it also considers transpositions (swapping of two adjacent characters)
+    /// as a single operation. This metric is particularly useful when adjacent characters are commonly
+    /// transposed, such as in typographical errors.
+    ///
+    /// The OSA distance between two strings is defined as the minimum number of operations required to
+    /// transform one string into the other, where the operations include:
+    ///
+    /// 1. Insertion: Adding a single character.
+    /// 2. Deletion: Removing a single character.
+    /// 3. Substitution: Replacing one character with another.
+    /// 4. Transposition: Swapping two adjacent characters (this is what distinguishes OSA from the
+    ///    traditional Levenshtein distance).
+    ///
+    /// The OSA distance algorithm ensures that no operation is applied more than once to the same
+    /// character in the same position. This is the main difference between the OSA and the more general
+    /// Damerau-Levenshtein distance, which does not have this restriction.
+    ///
+    /// <example>
+    /// Example Usage:
+    /// <code>
+    /// int distance = OptimalStringAlignmentDistance("example", "exmaple");
+    /// Console.WriteLine(distance); // Output: 1
+    /// </code>
+    /// In this example, the strings "example" and "exmaple" differ by one transposition of adjacent characters ('a' and 'm'),
+    /// so the OSA distance is 1.
+    ///
+    /// <code>
+    /// int distance = OptimalStringAlignmentDistance("kitten", "sitting");
+    /// Console.WriteLine(distance); // Output: 3
+    /// </code>
+    /// Here, the strings "kitten" and "sitting" have three differences (substitutions 'k' to 's', 'e' to 'i', and insertion of 'g'),
+    /// resulting in an OSA distance of 3.
+    /// </example>
+    /// </summary>
+    /// <remarks>
+    /// This algorithm has a time complexity of O(n * m), where n and m are the lengths of the two input strings.
+    /// It is efficient for moderate-sized strings but may become computationally expensive for very long strings.
+    /// </remarks>
+    public static class OptimalStringAlignment
+    {
+        /// <summary>
+        /// Calculates the Optimal String Alignment distance between two strings.
+        /// </summary>
+        /// <param name="firstString">The first string.</param>
+        /// <param name="secondString">The second string.</param>
+        /// <returns>The Optimal String Alignment distance between the two strings.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when either of the input strings is null.</exception>
+        public static double Calculate(string firstString, string secondString)
+        {
+            ArgumentNullException.ThrowIfNull(nameof(firstString));
+            ArgumentNullException.ThrowIfNull(nameof(secondString));
+
+            if (firstString == secondString)
+            {
+                return 0.0;
+            }
+
+            if (firstString.Length == 0)
+            {
+                return secondString.Length;
+            }
+
+            if (secondString.Length == 0)
+            {
+                return firstString.Length;
+            }
+
+            var distanceMatrix = GenerateDistanceMatrix(firstString.Length, secondString.Length);
+            distanceMatrix = CalculateDistance(firstString, secondString, distanceMatrix);
+
+            return distanceMatrix[firstString.Length, secondString.Length];
+        }
+
+        /// <summary>
+        /// Generates the initial distance matrix for the given lengths of the two strings.
+        /// </summary>
+        /// <param name="firstLength">The length of the first string.</param>
+        /// <param name="secondLength">The length of the second string.</param>
+        /// <returns>The initialized distance matrix.</returns>
+        private static int[,] GenerateDistanceMatrix(int firstLength, int secondLength)
+        {
+            var distanceMatrix = new int[firstLength + 2, secondLength + 2];
+
+            for (var i = 0; i <= firstLength; i++)
+            {
+                distanceMatrix[i, 0] = i;
+            }
+
+            for (var j = 0; j <= secondLength; j++)
+            {
+                distanceMatrix[0, j] = j;
+            }
+
+            return distanceMatrix;
+        }
+
+        /// <summary>
+        /// Calculates the distance matrix for the given strings using the Optimal String Alignment algorithm.
+        /// </summary>
+        /// <param name="firstString">The first string.</param>
+        /// <param name="secondString">The second string.</param>
+        /// <param name="distanceMatrix">The initial distance matrix.</param>
+        /// <returns>The calculated distance matrix.</returns>
+        private static int[,] CalculateDistance(string firstString, string secondString, int[,] distanceMatrix)
+        {
+            for (var i = 1; i <= firstString.Length; i++)
+            {
+                for (var j = 1; j <= secondString.Length; j++)
+                {
+                    var cost = 1;
+
+                    if (firstString[i - 1] == secondString[j - 1])
+                    {
+                        cost = 0;
+                    }
+
+                    distanceMatrix[i, j] = Minimum(
+                        distanceMatrix[i - 1, j - 1] + cost, // substitution
+                        distanceMatrix[i, j - 1] + 1, // insertion
+                        distanceMatrix[i - 1, j] + 1); // deletion
+
+                    if (i > 1 && j > 1
+                        && firstString[i - 1] == secondString[j - 2]
+                        && firstString[i - 2] == secondString[j - 1])
+                    {
+                        distanceMatrix[i, j] = Math.Min(
+                            distanceMatrix[i, j],
+                            distanceMatrix[i - 2, j - 2] + cost); // transposition
+                    }
+                }
+            }
+
+            return distanceMatrix;
+        }
+
+        /// <summary>
+        /// Returns the minimum of three integers.
+        /// </summary>
+        /// <param name="a">The first integer.</param>
+        /// <param name="b">The second integer.</param>
+        /// <param name="c">The third integer.</param>
+        /// <returns>The minimum of the three integers.</returns>
+        private static int Minimum(int a, int b, int c)
+        {
+            return Math.Min(a, Math.Min(b, c));
+        }
+    }
+}

README.md

@@ -183,6 +183,7 @@ find more than one implementation for the same objective but using different alg
       * [Hamming Distance](./Algorithms/Strings/Similarity/HammingDistance.cs)
       * [Jaro Similarity](./Algorithms/Strings/Similarity/JaroSimilarity.cs)
       * [Jaro-Winkler Distance](./Algorithms/Strings/Similarity/JaroWinklerDistance.cs)
+      * [Optimal String Alignment](./Algorithms/Strings/Similarity/OptimalStringAlignment.cs)
     * [Pattern Matching](./Algorithms/Strings/PatternMatching/)
       * [Bitop Pattern Matching](./Algorithms/Strings/PatternMatching/Bitap.cs)
       * [Naive String Search](./Algorithms/Strings/PatternMatching/NaiveStringSearch.cs)