Skip to content

Repository files navigation

string_similarity

pub package license: MIT

A fast, dependency-free Dart package for measuring the similarity between two strings with the Sørensen–Dice coefficient.

Use it for fuzzy search, spelling suggestions, duplicate detection, and ranking the closest match from a list.

✨ Why string_similarity?

  • Simple extension methods and static methods
  • Scores from 0.0 (completely different) to 1.0 (identical)
  • Best-match search with individual ratings and the winning index
  • No runtime dependencies
  • Works on every platform supported by Dart and Flutter

📦 Installation

dart pub add string_similarity

Then import the package:

import 'package:string_similarity/string_similarity.dart';

🚀 Compare two strings

final score = 'healed'.similarityTo('sealed');

print(score); // 0.8

The equivalent static method is:

final score = StringSimilarity.compareTwoStrings('healed', 'sealed');

🏆 Find the best match

final result = 'healed'.bestMatch([
  'edward',
  'sealed',
  'theatre',
]);

print(result.bestMatch.target); // sealed
print(result.bestMatch.rating); // 0.8
print(result.bestMatchIndex); // 1

Every candidate and its score remain available in result.ratings.

The equivalent static method is:

final result = StringSimilarity.findBestMatch(
  'healed',
  ['edward', 'sealed', 'theatre'],
);

🧠 How it works

The package compares adjacent character pairs (bigrams) using the Sørensen–Dice coefficient. Whitespace is removed before comparison. Letter case and diacritics are kept, so Cote, cote, and côte are different values.

🔡 Case-insensitive comparison

Normalize both strings before comparing them:

final score = 'DART'.toLowerCase().similarityTo('dart'.toLowerCase());

print(score); // 1.0

🧩 Available methods

API Returns Description
value.similarityTo(other) double Compares two nullable strings.
value.bestMatch(targets) BestMatch Rates every nullable target and selects the best one.
StringSimilarity.compareTwoStrings(first, second) double Static alternative to similarityTo.
StringSimilarity.findBestMatch(value, targets) BestMatch Static alternative to bestMatch.

BestMatch provides:

  • ratings: every target and its score
  • bestMatch: the highest-rated target
  • bestMatchIndex: the winning target's original index

⚙️ Behavior and edge cases

Input Result
Two identical values, including null or '' 1.0
Only one value is null or empty 0.0
Different values where either has fewer than two characters 0.0
Several targets share the highest score The first one wins
The target list is empty Throws ArgumentError

🔎 Comparison details

  • Whitespace is ignored, but punctuation is not.
  • Comparison is case-sensitive and diacritic-sensitive.
  • The algorithm works on UTF-16 code units rather than grapheme clusters, so some emoji and combined Unicode characters may not behave like visible characters.
  • Sørensen–Dice measures shared bigrams. It is not a drop-in replacement for edit-distance algorithms such as Levenshtein distance.

📄 License

Licensed under the permissive MIT License.

About

Finds degree of similarity between two strings, based on Dice's Coefficient, which is mostly better than Levenshtein distance.

Topics

Resources

Stars

35 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages