https://github.com/ktsu-dev/fuzzysearch
https://github.com/ktsu-dev/fuzzysearch
Last synced: 16 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/ktsu-dev/fuzzysearch
- Owner: ktsu-dev
- License: mit
- Created: 2024-04-04T01:16:07.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-30T02:50:49.000Z (4 months ago)
- Last Synced: 2026-01-30T17:55:55.593Z (4 months ago)
- Language: PowerShell
- Size: 460 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Authors: AUTHORS.md
- Copyright: COPYRIGHT.md
Awesome Lists containing this project
README
# ktsu.FuzzySearch
> A lightweight .NET library that provides fuzzy string matching capabilities, allowing for approximate string matching with intelligent scoring.
[](LICENSE.md)
[](https://nuget.org/packages/ktsu.FuzzySearch)
[](https://nuget.org/packages/ktsu.FuzzySearch)
[](https://nuget.org/packages/ktsu.FuzzySearch)
[](https://github.com/ktsu-dev/FuzzySearch/commits/main)
[](https://github.com/ktsu-dev/FuzzySearch/graphs/contributors)
[](https://github.com/ktsu-dev/FuzzySearch/actions)
## 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
```powershell
Install-Package ktsu.FuzzySearch
```
### .NET CLI
```bash
dotnet add package ktsu.FuzzySearch
```
### Package Reference
```xml
```
## Usage Examples
### Basic Matching
The simplest way to check if a string contains characters from a pattern in sequence:
```csharp
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:
```csharp
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:
```csharp
using ktsu.FuzzySearch;
class Program
{
static void Main()
{
var items = new List
{
"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:
```csharp
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:
```csharp
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
{
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 items, string pattern, FuzzyOptions options = null` | `IEnumerable>` | Filters and ranks a collection of strings |
| `Filter` | `IEnumerable items, string pattern, Func selector, FuzzyOptions options = null` | `IEnumerable>` | 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:
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. 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](LICENSE.md) file for details.