ReadOnlySpan<T> Support (#36)

Resolves #35 for comparison using byte[], or any scenarios where i.e. ReadOnlySpan might be preferred.

Author: paulirwin

.gitignore

@@ -243,3 +243,4 @@ ModelManifest.xml
 # FAKE - F# Make
 .fake/
 *.DS_Store
+.idea/

src/F23.StringSimilarity/Cosine.cs

@@ -32,7 +32,7 @@ namespace F23.StringSimilarity
     public class Cosine : ShingleBased, INormalizedStringSimilarity, INormalizedStringDistance
     {
         /// <summary>
-        /// Implements Cosine Similarity between strings.The strings are first
+        /// Implements Cosine Similarity between strings. The strings are first
         /// transformed in vectors of occurrences of k-shingles(sequences of k
         /// characters). In this n-dimensional space, the similarity between the two
         /// strings is the cosine of their respective vectors.
@@ -41,7 +41,7 @@ public class Cosine : ShingleBased, INormalizedStringSimilarity, INormalizedStri
         public Cosine(int k) : base(k) { }
 
         /// <summary>
-        /// Implements Cosine Similarity between strings.The strings are first
+        /// Implements Cosine Similarity between strings. The strings are first
         /// transformed in vectors of occurrences of k-shingles(sequences of k
         /// characters). In this n-dimensional space, the similarity between the two
         /// strings is the cosine of their respective vectors.

src/F23.StringSimilarity/Damerau.cs

@@ -41,7 +41,7 @@ namespace F23.StringSimilarity
     /// This is not to be confused with the optimal string alignment distance, which
     /// is an extension where no substring can be edited more than once.
     /// </summary>
-    public class Damerau : IMetricStringDistance
+    public class Damerau : IMetricStringDistance, IMetricSpanDistance
     {
         /// <summary>
         /// Compute the distance between strings: the minimum number of operations
@@ -54,6 +54,10 @@ public class Damerau : IMetricStringDistance
         /// <returns>The computed distance.</returns>
         /// <exception cref="ArgumentNullException">If s1 or s2 is null.</exception>
         public double Distance(string s1, string s2)
+            => Distance(s1.AsSpan(), s2.AsSpan());
+
+        public double Distance<T>(ReadOnlySpan<T> s1, ReadOnlySpan<T> s2)
+            where T : IEquatable<T>
         {
             if (s1 == null)
             {
@@ -65,7 +69,7 @@ public double Distance(string s1, string s2)
                 throw new ArgumentNullException(nameof(s2));
             }
 
-            if (s1.Equals(s2))
+            if (s1.SequenceEqual(s2))
             {
                 return 0;
             }
@@ -74,7 +78,7 @@ public double Distance(string s1, string s2)
             int inf = s1.Length + s2.Length;
 
             // Create and initialize the character array indices
-            var da = new Dictionary<char, int>();
+            var da = new Dictionary<T, int>();
 
             for (int d = 0; d < s1.Length; d++)
             {
@@ -115,7 +119,7 @@ public double Distance(string s1, string s2)
                     int j1 = db;
 
                     int cost = 1;
-                    if (s1[i - 1] == s2[j - 1])
+                    if (s1[i - 1].Equals(s2[j - 1]))
                     {
                         cost = 0;
                         db = j;

src/F23.StringSimilarity/F23.StringSimilarity.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFrameworks>netstandard2.0</TargetFrameworks>
+    <TargetFramework>netstandard2.0</TargetFramework>
     <PackageId>F23.StringSimilarity</PackageId>
     <PackageTags>string;similarity;distance;levenshtein;jaro-winkler;lcs;cosine</PackageTags>
     <Title>StringSimilarity.NET</Title>

src/F23.StringSimilarity/Interfaces/IMetricSpanDistance.cs

@@ -0,0 +1,23 @@
+using System;
+
+namespace F23.StringSimilarity.Interfaces
+{
+    /// <summary>
+    /// Span distances that implement this interface are metrics, which means:
+    ///  - d(x, y) ≥ 0     (non-negativity, or separation axiom)
+    ///  - d(x, y) = 0   if and only if   x = y     (identity, or coincidence axiom)
+    ///  - d(x, y) = d(y, x)     (symmetry)
+    ///  - d(x, z) ≤ d(x, y) + d(y, z)     (triangle inequality).
+    /// </summary>
+    public interface IMetricSpanDistance : ISpanDistance
+    {
+        /// <summary>
+        /// Compute and return the metric distance.
+        /// </summary>
+        /// <param name="b1">The first span.</param>
+        /// <param name="b2">The second span.</param>
+        /// <returns>The metric distance.</returns>
+        new double Distance<T>(ReadOnlySpan<T> b1, ReadOnlySpan<T> b2)
+            where T : IEquatable<T>;
+    }
+}

src/F23.StringSimilarity/Interfaces/INormalizedSpanDistance.cs

@@ -0,0 +1,6 @@
+namespace F23.StringSimilarity.Interfaces
+{
+    public interface INormalizedSpanDistance : ISpanDistance
+    {
+    }
+}

src/F23.StringSimilarity/Interfaces/INormalizedSpanSimilarity.cs

@@ -0,0 +1,6 @@
+namespace F23.StringSimilarity.Interfaces
+{
+    public interface INormalizedSpanSimilarity : ISpanSimilarity
+    {
+    }
+}

src/F23.StringSimilarity/Interfaces/ISpanDistance.cs

@@ -0,0 +1,23 @@
+using System;
+
+namespace F23.StringSimilarity.Interfaces
+{
+    public interface ISpanDistance
+    {
+        /// <summary>
+        /// Compute and return a measure of distance.
+        /// Must be >= 0.
+        ///
+        /// This method operates on spans such as byte arrays.
+        /// Note that, when used on bytes, string encodings that
+        /// use more than one byte per codepoint (such as UTF-8)
+        /// are not supported and will most likely return
+        /// incorrect results.
+        /// </summary>
+        /// <param name="b1">The first span.</param>
+        /// <param name="b2">The second span.</param>
+        /// <returns>The measure of distance between the spans.</returns>
+        double Distance<T>(ReadOnlySpan<T> b1, ReadOnlySpan<T> b2)
+            where T : IEquatable<T>;
+    }
+}

src/F23.StringSimilarity/Interfaces/ISpanSimilarity.cs

@@ -0,0 +1,16 @@
+using System;
+
+namespace F23.StringSimilarity.Interfaces
+{
+    public interface ISpanSimilarity
+    {
+        /// <summary>
+        /// Compute and return a measure of similarity between 2 spans.
+        /// </summary>
+        /// <param name="s1">The first span</param>
+        /// <param name="s2">The second span</param>
+        /// <returns>Similarity (0 means both spans are completely different)</returns>
+        double Similarity<T>(ReadOnlySpan<T> s1, ReadOnlySpan<T> s2)
+            where T : IEquatable<T>;
+    }
+}

src/F23.StringSimilarity/JaroWinkler.cs

@@ -23,6 +23,7 @@
  */
 
 using System;
+using System.Data.SqlTypes;
 using System.Linq;
 using F23.StringSimilarity.Interfaces;
 // ReSharper disable SuggestVarOrType_Elsewhere
@@ -38,7 +39,7 @@ namespace F23.StringSimilarity
     /// Jaro-Winkler was developed in the area of record linkage (duplicate
     /// detection) (Winkler, 1990). It returns a value in the interval [0.0, 1.0].
     /// The distance is computed as 1 - Jaro-Winkler similarity.
-    public class JaroWinkler : INormalizedStringSimilarity, INormalizedStringDistance
+    public class JaroWinkler : INormalizedStringSimilarity, INormalizedStringDistance, INormalizedSpanSimilarity, INormalizedSpanDistance
     {
         private const double DEFAULT_THRESHOLD = 0.7;
         private const int THREE = 3;
@@ -75,6 +76,10 @@ public JaroWinkler(double threshold)
         /// <returns>The Jaro-Winkler similarity in the range [0, 1]</returns>
         /// <exception cref="ArgumentNullException">If s1 or s2 is null.</exception>
         public double Similarity(string s1, string s2)
+            => Similarity(s1.AsSpan(), s2.AsSpan());
+        
+        public double Similarity<T>(ReadOnlySpan<T> s1, ReadOnlySpan<T> s2)
+            where T : IEquatable<T>
         {
             if (s1 == null)
             {
@@ -86,7 +91,7 @@ public double Similarity(string s1, string s2)
                 throw new ArgumentNullException(nameof(s2));
             }
 
-            if (s1.Equals(s2))
+            if (s1.SequenceEqual(s2))
             {
                 return 1f;
             }
@@ -117,10 +122,15 @@ public double Similarity(string s1, string s2)
         /// <exception cref="ArgumentNullException">If s1 or s2 is null.</exception>
         public double Distance(string s1, string s2)
             => 1.0 - Similarity(s1, s2);
+        
+        public double Distance<T>(ReadOnlySpan<T> s1, ReadOnlySpan<T> s2)
+            where T : IEquatable<T>
+            => 1.0 - Similarity(s1, s2);
 
-        private static int[] Matches(string s1, string s2)
+        private static int[] Matches<T>(ReadOnlySpan<T> s1, ReadOnlySpan<T> s2)
+            where T : IEquatable<T>
         {
-            string max, min;
+            ReadOnlySpan<T> max, min;
             if (s1.Length > s2.Length)
             {
                 max = s1;
@@ -141,11 +151,11 @@ private static int[] Matches(string s1, string s2)
             int matches = 0;
             for (int mi = 0; mi < min.Length; mi++)
             {
-                char c1 = min[mi];
+                var c1 = min[mi];
                 for (int xi = Math.Max(mi - range, 0),
                         xn = Math.Min(mi + range + 1, max.Length); xi < xn; xi++)
                 {
-                    if (!match_flags[xi] && c1 == max[xi])
+                    if (!match_flags[xi] && c1.Equals(max[xi]))
                     {
                         match_indexes[mi] = xi;
                         match_flags[xi] = true;
@@ -154,8 +164,8 @@ private static int[] Matches(string s1, string s2)
                     }
                 }
             }
-            char[] ms1 = new char[matches];
-            char[] ms2 = new char[matches];
+            T[] ms1 = new T[matches];
+            T[] ms2 = new T[matches];
             for (int i = 0, si = 0; i < min.Length; i++)
             {
                 if (match_indexes[i] != -1)
@@ -175,15 +185,15 @@ private static int[] Matches(string s1, string s2)
             int transpositions = 0;
             for (int mi = 0; mi < ms1.Length; mi++)
             {
-                if (ms1[mi] != ms2[mi])
+                if (!ms1[mi].Equals(ms2[mi]))
                 {
                     transpositions++;
                 }
             }
             int prefix = 0;
             for (int mi = 0; mi < min.Length; mi++)
             {
-                if (s1[mi] == s2[mi])
+                if (s1[mi].Equals(s2[mi]))
                 {
                     prefix++;
                 }