ktsu.FuzzySearch 1.2.4-pre.3
ktsu.FuzzySearch
A lightweight .NET library that provides fuzzy string matching capabilities, allowing for approximate string matching with intelligent scoring.
Introduction
FuzzySearch is a .NET library that provides fuzzy string matching capabilities with intelligent scoring. It's perfect for implementing search-as-you-type features, command palettes, or any application requiring flexible string matching. This library offers both basic contains-style matching and more sophisticated algorithms that can rank multiple potential matches by relevance.
Features
- Fuzzy String Matching: Match strings even when they contain typos or missing characters
- Intelligent Scoring: Rank matches by quality with a smart scoring algorithm
- Case Insensitivity: Optional case-insensitive matching
- Filtering Collections: Filter lists of strings and rank results
- Customizable Parameters: Adjust matching behavior to suit different needs
- Lightweight: Minimal dependencies, focused on performance
- Well-tested: Comprehensive test suite ensuring reliability
Installation
Package Manager Console
Install-Package ktsu.FuzzySearch
.NET CLI
dotnet add package ktsu.FuzzySearch
Package Reference
<PackageReference Include="ktsu.FuzzySearch" Version="x.y.z" />
Usage Examples
Basic Matching
The simplest way to check if a string contains characters from a pattern in sequence:
using ktsu.FuzzySearch;
class Program
{
static void Main()
{
string text = "Hello World";
string pattern = "hlo";
bool isMatch = Fuzzy.Contains(text, pattern); // Returns true
}
}
Matching with Scoring
To get both a match result and a score that indicates the quality of the match:
using ktsu.FuzzySearch;
class Program
{
static void Main()
{
string text = "Hello World";
string pattern = "hlo";
var result = Fuzzy.Match(text, pattern);
Console.WriteLine($"Is match: {result.IsMatch}"); // True
Console.WriteLine($"Score: {result.Score}"); // A value between 0-1
Console.WriteLine($"Character indices: {result.Indices}"); // Indices of matched characters
}
}
Filtering a Collection
Filter a list of strings and sort them by match quality:
using ktsu.FuzzySearch;
class Program
{
static void Main()
{
var items = new List<string>
{
"AppDataStorage",
"Application Settings",
"Data Store",
"File System",
"Storage Provider"
};
string pattern = "appstor";
// Filter and rank by match quality
var results = Fuzzy.Filter(items, pattern);
foreach (var result in results)
{
Console.WriteLine($"{result.Item} (Score: {result.Score})");
}
// Output might be:
// AppDataStorage (Score: 0.89)
// Application Settings (Score: 0.65)
// Storage Provider (Score: 0.52)
}
}
Advanced Options
Customize the matching behavior with options:
using ktsu.FuzzySearch;
class Program
{
static void Main()
{
var options = new FuzzyOptions
{
CaseSensitive = true, // Default is false
ScoreThreshold = 0.4, // Minimum score to consider a match
BonusConsecutiveChars = 1.5, // Bonus for consecutive matched characters
BonusStartOfWord = 2.0, // Bonus for matches at word boundaries
PenaltyUnmatched = 0.1, // Penalty for unmatched characters
MaxPatternLength = 64 // Maximum pattern length to consider
};
string text = "FileSystemWatcher";
string pattern = "FSW";
var result = Fuzzy.Match(text, pattern, options);
Console.WriteLine($"Score with custom options: {result.Score}");
}
}
Object Collections
Filter and match against object collections by providing a selector function:
using ktsu.FuzzySearch;
class Program
{
class FileItem
{
public string Name { get; set; }
public string Path { get; set; }
public long Size { get; set; }
}
static void Main()
{
var files = new List<FileItem>
{
new FileItem { Name = "Document.pdf", Path = "/documents/", Size = 1024 },
new FileItem { Name = "Presentation.pptx", Path = "/presentations/", Size = 2048 },
new FileItem { Name = "Spreadsheet.xlsx", Path = "/spreadsheets/", Size = 512 }
};
string pattern = "doc";
// Filter objects using a selector function
var results = Fuzzy.Filter(files, pattern, item => item.Name);
foreach (var result in results)
{
Console.WriteLine($"{result.Item.Name} (Score: {result.Score})");
}
}
}
API Reference
Fuzzy Static Class
The main class providing fuzzy matching functionality.
Methods
| Name | Parameters | Return Type | Description |
|---|---|---|---|
Contains |
string text, string pattern, bool caseSensitive = false |
bool |
Checks if the text contains the pattern in sequence |
Match |
string text, string pattern, FuzzyOptions options = null |
FuzzyResult |
Matches text against pattern with scoring |
Filter |
IEnumerable<string> items, string pattern, FuzzyOptions options = null |
IEnumerable<FuzzyItem<string>> |
Filters and ranks a collection of strings |
Filter<T> |
IEnumerable<T> items, string pattern, Func<T, string> selector, FuzzyOptions options = null |
IEnumerable<FuzzyItem<T>> |
Filters and ranks a collection of objects using a selector function |
FuzzyResult Class
Represents the result of a fuzzy match operation.
Properties
| Name | Type | Description |
|---|---|---|
IsMatch |
bool |
Indicates if the pattern matches the text |
Score |
double |
A value between 0 and 1 indicating match quality (1 is perfect) |
Indices |
int[] |
The indices in the text where pattern characters were matched |
FuzzyOptions Class
Configuration options for fuzzy matching.
Properties
| Name | Type | Default | Description |
|---|---|---|---|
CaseSensitive |
bool |
false |
Whether matching should be case-sensitive |
ScoreThreshold |
double |
0.3 |
Minimum score required to consider a match valid |
BonusConsecutiveChars |
double |
1.0 |
Score bonus for consecutive matched characters |
BonusStartOfWord |
double |
1.5 |
Score bonus for matches at word boundaries |
PenaltyUnmatched |
double |
0.1 |
Score reduction for unmatched characters |
Contributing
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please make sure to update tests as appropriate and adhere to the existing coding style.
License
This project is licensed under the MIT License - see the LICENSE.md file for details.