ktsu.FuzzySearch 1.2.2-pre.17

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

FuzzyResult Class

Represents the result of a fuzzy match operation.

Properties

FuzzyOptions Class

Configuration options for fuzzy matching.

Properties

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 file for details.