textdistance Rust Library

To add textdistance to your project, use the following command:

cargo add textdistance

If you are working on an embedded system or a no_std project, install it without default features:

cargo add --no-default-features textdistance

By default, for_str and the str/nstr modules use String.chars, which treats combining characters (like é) as distinct code points.

To treat Unicode grapheme clusters as single symbols, use the unicode-segmentation crate and pass the graphemes as an iterator to the for_iter method.

use textdistance::{Algorithm, DamerauLevenshtein};
use unicode_segmentation::UnicodeSegmentation;

let s1 = "a̐éö̲\r\n";
let s2 = "éa̐ö̲\r\n";
let g1 = s1.graphemes(true);
let g2 = s2.graphemes(true);
let a = DamerauLevenshtein::default();
let r = a.for_iter(g1, g2);
assert!(r.val() == 1);

The Algorithm<R> trait defines a unified way to interact with various distance metrics. It is generic over the result type R.

Most implementations provide specialized methods for common data types like strings and vectors, but they all eventually resolve to the for_iter or for_vec logic. This allows you to use the same algorithm instance to compare raw characters, words, or even custom sequences by choosing the appropriate method call.

Note that for methods involving iterators or vectors (for_iter, for_vec), the elements must implement Eq + Hash.

The textdistance::str module provides shortcut functions for each algorithm to calculate the absolute distance between two strings.

The textdistance::nstr module provides the same functions but returns a normalized value between 0.0 and 1.0.

// Absolute distance
use textdistance::str::damerau_levenshtein;
assert!(damerau_levenshtein("abc", "acbd") == 2);

// Normalized distance (0.0 - 1.0)
use textdistance::nstr::damerau_levenshtein;
assert!(damerau_levenshtein("abc", "acbd") == 2./4.);

When using Sift4Common, you can tune its performance and behavior using two public fields:

• max_offset (usize): The number of characters to search for matching letters. The default value is 5.
• max_distance (usize): The distance threshold at which the algorithm stops computing and exits early (indicating the strings are too different). The default value is 0 (no early exit).

// Using default values
let default_algo = Sift4Common::default();

// Custom configuration
let custom_algo = Sift4Common {
    max_offset: 10,
    max_distance: 3,
};

You can customize how the Jaro-Winkler algorithm handles common prefixes using the following fields in the JaroWinkler struct:

• prefix_weight: A scaling factor for how much the Jaro score is adjusted for the common prefix. The default is 0.1. Constraint: This value must not be higher than 1/ℓ, where ℓ is the max_prefix value.
• max_prefix: The maximum length of the common prefix to consider. The default is 4.

let custom_jw = JaroWinkler {
    jaro: Jaro::default(),
    prefix_weight: 0.1,
    max_prefix: 4,
};

The library contains 20+ algorithms categorized as follows:

Edit-based:

• DamerauLevenshtein (optimal string alignment and restricted)
• Hamming
• Jaro
• JaroWinkler
• Levenshtein
• Sift4Common
• Sift4Simple
• SmithWaterman

Token-based:

• Bag
• Cosine (aka Orchini, Tucker, Otsuka–Ochiai)
• EntropyNCD (Entropy-based Normalized Compression Distance)
• Jaccard (aka Tanimoto, Critical Success Index)
• Overlap (aka Szymkiewicz–Simpson)
• Roberts
• SorensenDice (aka F1, Czekanowski, Zijdenbos)
• Tversky

Sequence-based:

• LCSSeq (Longest Common SubSequence)
• LCSStr (Longest Common SubString)
• RatcliffObershelp (aka Gestalt pattern matching)

Naive:

• Prefix
• Suffix
• Length

Normalization metrics:

• LIG3 (for Hamming by Levenshtein)
• MLIPNS (for Hamming)
• YujianBo (for Levenshtein)

For a convenient way to compare strings using the Jaccard index, you can use the jaccard function (typically available via the textdistance::str module). This function handles the string iteration and returns the similarity score directly.

use textdistance::str::jaccard;

let sim = jaccard("nelson", "neilsen");
// Expected similarity: 5/8 = 0.625
println!("Similarity: {}", sim);

The JaroWinkler struct implements a variation of the Jaro similarity algorithm that gives higher ratings to strings with matching prefixes. The similarity score is normalized between 0.0 and 1.0.

To use it, you can instantiate it with JaroWinkler::default() or configure the prefix weighting parameters. It implements the Algorithm<f64> trait, allowing it to be used with the for_vec method to compare slices of elements.

use textdistance::algorithms::jaro_winkler::JaroWinkler;
use textdistance::Algorithm;

let jaro_winkler = JaroWinkler::default();
let s1 = ["martha"];
let s2 = ["marhta"];

// Note: The implementation uses slices of elements (E: Eq + Hash)
let result = jaro_winkler.for_vec(&["martha"], &["marhta"]).unwrap();
println!("Similarity: {}", result.abs);