matchr

matchr is a lightweight and efficient fuzzy matching library written in Rust.
It helps you score and sort candidate strings by how well they match a query,
with a focus on CLI tools, search features, and quick approximate matching.

Features

• Position-weighted scoring - Characters matched earlier in the query get higher scores
• Exact match detection - Perfect matches always score 100
• Batch matching - Score and sort multiple candidates at once
• Zero dependencies - Pure Rust implementation
• Simple API - Just two main functions to get started

Installation

Add this to your Cargo.toml:

[dependencies]
matchr = "0.1.0"

Usage

Basic Scoring

use matchr::score;

let query = "fefe";
let candidate = "feature";
let match_score = score(query, candidate);
println!("Score: {}", match_score); // Score: 25

Matching Multiple Items

use matchr::match_items;

let query = "fefe";
let candidates = ["fefe", "fefete", "feature", "banana", "effort"];
let results = match_items(query, &candidates);

for (item, score) in results {
    println!("{} => score: {}", item, score);
}
// Output:
// fefe => score: 100
// fefete => score: 70
// feature => score: 25
// effort => score: 15
// banana => score: 0

API Reference

Functions

score(query: &str, candi: &str) -> usize

Scores how well a candidate string matches the query.

Parameters:

• query - The search query string
• candi - The candidate string to match against

Returns: A score between 0 and 100, where higher means better match

Scoring Logic:

• Characters at position 0 in query: +20 points
• Characters at position 1 in query: +15 points
• Characters at position 2 in query: +10 points
• Characters at position 3+: +5 points
• Non-matching characters: -5 points (with saturation)
• Exact matches always return 100

match_items<'a>(query: &str, items: &[&'a str]) -> Vec<(&'a str, usize)>

Matches multiple items against a query and returns them sorted by score.

Parameters:

• query - The search query string
• items - Slice of candidate strings

Returns: Vector of (item, score) tuples, sorted by descending score

Examples

CLI Tool Integration

use matchr::match_items;

fn search_commands(query: &str) -> Vec<String> {
    let commands = ["git commit", "git push", "git pull", "git status", "grep"];
    let results = match_items(query, &commands);
    
    results
        .into_iter()
        .filter(|(_, score)| *score > 10)
        .map(|(cmd, _)| cmd.to_string())
        .collect()
}

let matches = search_commands("git");
// Returns: ["git commit", "git push", "git pull", "git status"]

File Search

use matchr::match_items;

let query = "cfg";
let files = ["config.toml", "Cargo.toml", "src/cfg.rs", "README.md"];
let results = match_items(query, &files);

for (file, score) in results.iter().take(3) {
    if *score > 0 {
        println!("📁 {} (score: {})", file, score);
    }
}

Performance

matchr is designed to be fast and memory-efficient:

• No heap allocations during scoring
• O(n×m) time complexity where n = query length, m = candidate length
• Suitable for interactive applications and real-time search

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Created by 0l3d