Raffinert.FuzzySharp 5.0.2

👁 Stand With Ukraine

Terms of use^?

By using this project or its source code, for any purpose and in any shape or form, you grant your implicit agreement to all the following statements:

• You condemn Russia and its military aggression against Ukraine
• You recognize that Russia is an occupant that unlawfully invaded a sovereign state
• You support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas
• You reject false narratives perpetuated by Russian state propaganda

To learn more about the war and how you can help, click here. Glory to Ukraine! 🇺🇦

Raffinert.FuzzySharp

👁 nuget version
👁 nuget downloads

C# .NET fast fuzzy string matching implementation of Seat Geek's well known python FuzzyWuzzy algorithm.

Bit-parallel accelerated version of the original FuzzySharp with multiple bugs fixed in the partial_ratio implementation.

Benchmark comparison of naive DP Levenshtein distance calculation (baseline), FuzzySharp, Fastenshtein and Quickenshtein:

Random words of 3 to 1024 random chars (LevenshteinLarge.cs):

Installation

Install-Package Raffinert.FuzzySharp

or

dotnet add package Raffinert.FuzzySharp

Usage

Simple Ratios

<p align="right"><a href="https://dotnetfiddle.net/9JpFTQ">Run .NET fiddle</a></p>

Fuzz.Ratio("mysmilarstring", "myawfullysimilarstirng");
// 72
Fuzz.Ratio("mysmilarstring", "mysimilarstring");
// 97

Partial Ratio

<p align="right"><a href="https://dotnetfiddle.net/rk0dIO">Run .NET fiddle</a></p>

Fuzz.PartialRatio("similar", "somewhresimlrbetweenthisstring");
// 71

Token Sort Ratio

<p align="right"><a href="https://dotnetfiddle.net/b5RVp2">Run .NET fiddle</a></p>

Fuzz.TokenSortRatio("order words out of", " words out of order");
// 100
Fuzz.PartialTokenSortRatio("order words out of", " words out of order");
// 100

Token Set Ratio

<p align="right"><a href="https://dotnetfiddle.net/ZfZRGb">Run .NET fiddle</a></p>

Fuzz.TokenSetRatio("fuzzy was a bear", "fuzzy fuzzy fuzzy bear");
// 100
Fuzz.PartialTokenSetRatio("fuzzy was a bear", "fuzzy fuzzy fuzzy bear");
// 100

Token Initialism Ratio

<p align="right"><a href="https://dotnetfiddle.net/87181A">Run .NET fiddle</a></p>

Fuzz.TokenInitialismRatio("NASA", "National Aeronautics and Space Administration");
// 89
Fuzz.TokenInitialismRatio("NASA", "National Aeronautics Space Administration");
// 100

Fuzz.TokenInitialismRatio("NASA", "National Aeronautics Space Administration, Kennedy Space Center, Cape Canaveral, Florida 32899");
// 53
Fuzz.PartialTokenInitialismRatio("NASA", "National Aeronautics Space Administration, Kennedy Space Center, Cape Canaveral, Florida 32899");
// 100

Token Abbreviation Ratio

<p align="right"><a href="https://dotnetfiddle.net/MVlwrW">Run .NET fiddle</a></p>

Fuzz.TokenAbbreviationRatio("bl 420", "Baseline section 420", StringPreprocessor.Full);
// 40
Fuzz.PartialTokenAbbreviationRatio("bl 420", "Baseline section 420", StringPreprocessor.Full);
// 67

Weighted Ratio

<p align="right"><a href="https://dotnetfiddle.net/n9QxAk">Run .NET fiddle</a></p>

Fuzz.WeightedRatio("The quick brown fox jimps ofver the small lazy dog", "the quick brown fox jumps over the small lazy dog");
// 95

Process Extraction

Find the best match(es) from a collection of choices.

<p align="right"><a href="https://dotnetfiddle.net/8lEzk3">Run .NET fiddle</a></p>

Process.ExtractOne("cowboys", new[] { "Atlanta Falcons", "New York Jets", "New York Giants", "Dallas Cowboys" });
// (string: Dallas Cowboys, score: 90, index: 3)

Process.ExtractTop("goolge", new[] { "google", "bing", "facebook", "linkedin", "twitter", "googleplus", "bingnews", "plexoogl" }, limit: 3);
// [(string: google, score: 83, index: 0), (string: googleplus, score: 75, index: 5), (string: plexoogl, score: 43, index: 7)]

Process.ExtractAll("goolge", new[] { "google", "bing", "facebook", "linkedin", "twitter", "googleplus", "bingnews", "plexoogl" });
// [(string: google, score: 83, index: 0), (string: bing, score: 36, index: 1), ...]

// With score cutoff
Process.ExtractAll("goolge", new[] { "google", "bing", "facebook", "linkedin", "twitter", "googleplus", "bingnews", "plexoogl" }, cutoff: 40);
// [(string: google, score: 83, index: 0), (string: googleplus, score: 75, index: 5), (string: plexoogl, score: 43, index: 7)]

Process.ExtractSorted("goolge", new[] { "google", "bing", "facebook", "linkedin", "twitter", "googleplus", "bingnews", "plexoogl" });
// [(string: google, score: 83, index: 0), (string: googleplus, score: 75, index: 5), (string: plexoogl, score: 43, index: 7), ...]

Extraction uses WeightedRatio and Full preprocessing by default. Override these in the method parameters to use different scorers and processing:

Process.ExtractOne("cowboys", new[] { "Atlanta Falcons", "New York Jets", "New York Giants", "Dallas Cowboys" }, s => s, ScorerCache.Get<DefaultRatioScorer>());
// (string: Dallas Cowboys, score: 57, index: 3)

Generic Type Extraction

<p align="right"><a href="https://dotnetfiddle.net/YDtl6k">Run .NET fiddle</a></p>

Extraction can operate on objects of any type. Use the extractor parameter to reduce the object to the string it should be compared on:

var events = new[]
{
 new[] { "chicago cubs vs new york mets", "CitiField", "2011-05-11", "8pm" },
 new[] { "new york yankees vs boston red sox", "Fenway Park", "2011-05-11", "8pm" },
 new[] { "atlanta braves vs pittsburgh pirates", "PNC Park", "2011-05-11", "8pm" },
};
var query = new[] { "new york mets vs chicago cubs", "CitiField", "2017-03-19", "8pm" };
var best = Process.ExtractOneBy(query, events, strings => strings[0]);
// (value: { "chicago cubs vs new york mets", "CitiField", "2011-05-11", "8pm" }, score: 95, index: 0)

If the query is already a string, it can be matched directly against generic choices by providing only a choice extractor:

var events = new[]
{
 new { Name = "new york mets vs chicago cubs", Venue = "CitiField" },
 new { Name = "chicago cubs vs chicago white sox", Venue = "Wrigley Field" },
 new { Name = "philadelphia phillies vs atlanta braves", Venue = "Citizens Bank Park" },
};

var query = "new york mets at chicago cubs";

var best = Process.ExtractOneBy(query, events, e => e.Name);
// best.Value.Name == "new york mets vs chicago cubs"

var top = Process.ExtractTopBy(query, events, e => e.Name, limit: 2);

Fluent Pipeline API

The Process.Configure() fluent builder creates reusable, immutable pipelines with preconfigured scoring, caching, and parallel execution.

Basic Pipeline

Equivalent to the static Process methods, but reusable across multiple queries:

<p align="right"><a href="https://dotnetfiddle.net/KEFXxm">Run .NET fiddle</a></p>

var pipeline = Process.Configure().Build();

var result1 = pipeline.ExtractOne("cowboys", new[] { "Atlanta Falcons", "New York Jets", "New York Giants", "Dallas Cowboys" });
//(string: Dallas Cowboys, score: 90, index: 3)
var result2 = pipeline.ExtractOne(
 "chicago cubs",
 new[]
 {
 "Boston Red Sox",
 "Los Angeles Dodgers",
 "New York Yankees",
 "San Francisco Giants",
 "St. Louis Cardinals",
 "Houston Astros"
 });
//(string: San Francisco Giants, score: 45, index: 3)

Custom Scorer

<p align="right"><a href="https://dotnetfiddle.net/6JVmU9">Run .NET fiddle</a></p>

var pipeline = Process.Configure()
 .WithScorer(ScorerCache.Get<DefaultRatioScorer>())
 .Build();

var result = pipeline.ExtractOne("cowboys", new[] { "Atlanta Falcons", "New York Jets", "New York Giants", "Dallas Cowboys" });
//(string: Dallas Cowboys, score: 67, index: 3)

Parallel Execution

Enable multi-threaded processing for large choice sets:

var pipeline = Process.Configure()
 .Parallel()
 .Build();

var results = pipeline.ExtractAll("goolge", largeChoicesList);

With ParallelOptions for fine-grained control:

var pipeline = Process.Configure()
 .Parallel(new ParallelOptions { MaxDegreeOfParallelism = Environment.ProcessorCount })
 .Build();

Cached Execution

<p align="right"><a href="https://dotnetfiddle.net/y6qMJm">Run .NET fiddle</a></p>

Automatic caching creates a CachedWeightedRatioScorer per extraction call, pre-initializing internal data structures for the query string:

var pipeline = Process.Configure()
 .Cached()
 .Build();

var result = pipeline.ExtractOne("cowboys", new[] { "Atlanta Falcons", "New York Jets", "New York Giants", "Dallas Cowboys" });

Cached + Parallel

Combine caching and parallelism. Builder methods are order independent -- .Cached().Parallel() and .Parallel().Cached() produce identical results:

var pipeline = Process.Configure()
 .Cached()
 .Parallel(new ParallelOptions { MaxDegreeOfParallelism = Environment.ProcessorCount })
 .Build();

var results = pipeline.ExtractAll("goolge", largeChoicesList);

External Cached Scorer (Across-Run Caching)

For maximum performance when running the same query against different choice sets, provide an externally managed ICachedRatioScorer. The scorer pre-initializes once and is reused across all extraction calls:

using var scorer = new CachedWeightedRatioScorer("new york mets at atlanta braves");

var pipeline = Process.Configure()
 .Cached(scorer)
 .Parallel()
 .Build();

var results1 = pipeline.ExtractAll(choiceSet1);
var results2 = pipeline.ExtractAll(choiceSet2);

Note: External cached scorers implement IDisposable. Use using to ensure proper cleanup.

CancellationToken Support

Pass a CancellationToken via ParallelOptions to cancel long-running parallel extractions:

var cts = new CancellationTokenSource();

var pipeline = Process.Configure()
 .Cached()
 .Parallel(new ParallelOptions { CancellationToken = cts.Token })
 .Build();

// Throws OperationCanceledException if cancelled
var results = pipeline.ExtractAll(query, largeChoicesList).ToList();

Using Different Scorers

Non-Cached Scorers (IRatioScorer)

Stateless scorers for use with Process static methods and the WithScorer() builder method:

var ratio = ScorerCache.Get<DefaultRatioScorer>();
var partialRatio = ScorerCache.Get<PartialRatioScorer>();
var tokenSet = ScorerCache.Get<TokenSetScorer>();
var partialTokenSet = ScorerCache.Get<PartialTokenSetScorer>();
var tokenSort = ScorerCache.Get<TokenSortScorer>();
var partialTokenSort = ScorerCache.Get<PartialTokenSortScorer>();
var tokenAbbreviation = ScorerCache.Get<TokenAbbreviationScorer>();
var partialTokenAbbrev = ScorerCache.Get<PartialTokenAbbreviationScorer>();
var weighted = ScorerCache.Get<WeightedRatioScorer>();

Cached Scorers (ICachedRatioScorer)

<p align="right"><a href="https://dotnetfiddle.net/Ykr94M">Run .NET fiddle</a></p>

Pre-initialize with a query string for repeated comparisons. These implement IDisposable:

using var scorer = new CachedWeightedRatioScorer("search query");
int score = scorer.Score("candidate string");

Available cached scorers:

• CachedWeightedRatioScorer -- weighted combination (default for .Cached())
• CachedDefaultRatioScorer -- simple Levenshtein ratio
• CachedTokenSortScorer -- token sort ratio
• CachedTokenSetScorer -- token set ratio
• CachedPartialTokenSetScorer -- partial token set ratio
• CachedTokenDifferenceScorer -- token difference ratio

Levenshtein Distance API

<p align="right"><a href="https://dotnetfiddle.net/JzzcwS">Run .NET fiddle</a></p>

Low-level access to the bit-parallel Levenshtein distance implementation:

// Edit distance
int distance = Levenshtein.Distance("kitten", "sitting");
// 3

// Normalized similarity (1.0 = identical, 0.0 = completely different)
double similarity = Levenshtein.NormalizedSimilarity("kitten", "sitting");
// 0.5714285714285714

// Edit operations to transform one string into another
EditOp[] ops = Levenshtein.GetEditOps("kitten", "sitting");
// [REPLACE(0, 0), REPLACE(4, 4), INSERT(6, 6)]

Instance Distance Classes

The Levenshtein, Indel, and LongestCommonSubsequence classes also offer an instance API for one-to-many comparisons. The constructor pre-computes a bit-parallel pattern match vector from the source string, which is then reused across all subsequent calls. This avoids rebuilding the internal data structure on every comparison, giving a significant speedup when comparing one source against many targets.

All three implement IDisposable -- use using to return pooled arrays.

Levenshtein Instance

<p align="right"><a href="https://dotnetfiddle.net/hxUB72">Run .NET fiddle</a></p>

using var lev = new Levenshtein("chicago cubs vs new york mets");

int d1 = lev.DistanceFrom("new york mets vs chicago cubs");
// 22
int d2 = lev.DistanceFrom("atlanta braves vs pittsburgh pirates");
// 26

Indel Instance

<p align="right"><a href="https://dotnetfiddle.net/UkyXk2">Run .NET fiddle</a></p>

Indel distance counts only insertions and deletions (no replacements). NormalizedSimilarityWith returns a value between 0.0 (completely different) and 1.0 (identical):

using var indel = new Indel("chicago cubs");

int distance = indel.DistanceFrom("chicago white sox");
// 11
double similarity = indel.NormalizedSimilarityWith("chicago white sox");
// 0.6206896551724138

A generic variant IndelT<T> is available for comparing sequences of any IEquatable<T>:

using var indel = new IndelT<string>(new[] { "hello", "world" });

int distance = indel.DistanceFrom(new[] { "hello", "there" });
// 2
double similarity = indel.NormalizedSimilarityWith(new[] { "hello", "there" });
// 0.5

LongestCommonSubsequence Instance

<p align="right"><a href="https://dotnetfiddle.net/s60rZT">Run .NET fiddle</a></p>

LCS distance is defined as max(len1, len2) - LCS_length:

using var lcs = new LongestCommonSubsequence("chicago cubs");

int distance = lcs.DistanceFrom("chicago white sox");
// 8

String Preprocessors

<p align="right"><a href="https://dotnetfiddle.net/cIQ6PB">Run .NET fiddle</a></p>

By default, Fuzz methods compare strings as-is. Pass StringPreprocessor.Full to normalize whitespace, lowercase, and strip non-alphanumeric characters before comparing:

Fuzz.Ratio("new york mets", "NEW YORK METS");
// < 100 (case sensitive)

Fuzz.Ratio("new york mets", "NEW YORK METS", StringPreprocessor.Full);
// 100 (case insensitive after preprocessing)

Process extraction methods use StringPreprocessor.Full by default. Pass StringPreprocessor.None (or a custom processor function) to override this behavior.

Credits

• Adam Cohen (seatgeek/fuzzywuzzy)
• Antti Haapala (python-Levenshtein)
• David Necas (python-Levenshtein)
• Jacob Bayer (original FuzzySharp library)
• Max Bachmann (RapidFuzz)
• Mikko Ohtamaa (python-Levenshtein)
• Panayiotis (Java implementation)

Support

Support the project through GitHub Sponsors or via PayPal.

See for release history.