fuzzy

String similarity: Levenshtein, Jaro-Winkler, Dice and Jaccard, plus best-match selection over a list. Pure - no capabilities.

ecko get github.com/ecko-lang/fuzzy
import fuzzy

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.39.0 - source - MIT.


levenshtein(a, b)

Returns the Levenshtein distance: the fewest single-character insertions, deletions or substitutions that turn a into b.

Computed with two rows rather than the full matrix, so the memory cost is the length of one string rather than the product of both.

errors: bug/bad_argument when a or b is not a string.

fuzzy.levenshtein("kitten", "sitting")   # 3

ratio(a, b)

Returns the Levenshtein distance normalised to 0.0 (nothing in common) through 1.0 (identical), against the longer of the two strings.

errors: bug/bad_argument when a or b is not a string.

fuzzy.ratio("kitten", "sitting")   # 0.5714285714285714

hamming(a, b)

Returns the Hamming distance: how many positions differ. Both strings must be the same length, which is the whole premise of the measure.

errors: fuzzy/length_mismatch when the strings differ in length; bug/bad_argument when a or b is not a string.

fuzzy.hamming("karolin", "kathrin")   # 3

jaro(a, b)

Returns the Jaro similarity, 0.0 to 1.0.

Two characters count as matching only if they are the same and fall within max(len_a, len_b) // 2 - 1 positions of each other; a transposition is a matched pair that arrived out of order, and counts half.

errors: bug/bad_argument when a or b is not a string.

fuzzy.jaro("MARTHA", "MARHTA")   # 0.9444444444444445

jaro_winkler(a, b)

Returns the Jaro-Winkler similarity, 0.0 to 1.0: Jaro, boosted for strings that share a prefix.

The prefix counts at most four characters, and the boost only applies when Jaro is already 0.7 or more. Without both limits a long shared prefix would drag every comparison toward 1.0. Comparison is case-sensitive.

errors: bug/bad_argument when a or b is not a string.

fuzzy.jaro_winkler("MARTHA", "MARHTA")   # 0.9611111111111111

bigrams(s)

Returns the bigrams of a string: every adjacent character pair, in order.

errors: bug/bad_argument when s is not a string.

fuzzy.bigrams("night")   # [ni, ig, gh, ht]

dice(a, b)

Returns the Sorensen-Dice coefficient over bigrams, 0.0 to 1.0.

Good for names and titles, where word order varies but letter pairs persist. Two different strings shorter than two characters score 0.0.

errors: bug/bad_argument when a or b is not a string.

fuzzy.dice("night", "nacht")   # 0.25

jaccard(a, b)

Returns the Jaccard index over character sets, 0.0 to 1.0: shared characters over distinct characters.

Order-blind and the cheapest of the four measures.

errors: bug/bad_argument when a or b is not a string.

fuzzy.jaccard("abc", "abd")   # 0.5

best_match(needle, candidates, cutoff = 0.0)

Returns the candidate closest to needle as { value, score }, scored with Jaro-Winkler, or null when there are no candidates or the best score is below cutoff.

Jaro-Winkler suits the typo-correction case this is usually reached for. With the default cutoff of 0.0 something is always returned; raise it (0.8 is a reasonable start) to get null rather than a poor match. On a tie the earlier candidate wins.

errors: bug/bad_argument when candidates is not a list of strings, needle is not a string, or cutoff is not a number.

fuzzy.best_match("instal", ["install", "uninstall"], cutoff: 0.8)   # {score: 0.9714285714285714, value: install}

best_match_by(needle, candidates, scorer, cutoff = 0.0)

Returns the candidate closest to needle by your own scorer(needle, candidate) (higher is closer) as { value, score }, or null when there are no candidates or the best score is below cutoff.

errors: bug/bad_argument when candidates is not a list, scorer is not a function, or cutoff is not a number.

fuzzy.best_match_by("kitten", ["sitting", "mitten"], fuzzy.ratio)

top_matches(needle, candidates, limit)

Returns the limit candidates closest to needle, best first, as { value, score } records scored with Jaro-Winkler.

Equal scores keep the candidates' order.

errors: bug/bad_argument when candidates is not a list of strings, needle is not a string, or limit is not a non-negative Int.

fuzzy.top_matches("instal", ["install", "uninstall", "list"], 2)

top_matches_by(needle, candidates, limit, scorer)

Returns the limit candidates closest to needle by your own scorer(needle, candidate) (higher is closer), best first, as { value, score } records.

errors: bug/bad_argument when candidates is not a list, scorer is not a function, or limit is not a non-negative Int.

fuzzy.top_matches_by("kitten", ["sitting", "mitten"], 1, fuzzy.ratio)