Package: dart_helper_utils
File: string_similarity.dart

Purpose: Provides string similarity algorithms and utilities.

Class: StringSimilarityError
Purpose: Custom exception for string similarity errors.
Constructor: StringSimilarityError(String message)
Field: message: String. Error message.

Class: InvalidConfigurationError
Purpose: Exception for invalid string similarity configurations.
Extends: StringSimilarityError
Constructor: InvalidConfigurationError(String message)

Class: LRUCache<K, V>
Purpose: Generic Least Recently Used (LRU) cache.
Constructor: LRUCache(int capacity)
Field: capacity: int. Maximum cache size.
Methods:
  get(K key): V?. Returns value or null.  Marks entry as recently used.
  put(K key, V value): void. Adds/updates key-value. Evicts LRU if needed.
  containsKey(K key): bool.
  clear(): void.

Class: StringSimilarityConfig
Purpose: Configuration for string similarity operations.
Constructor: StringSimilarityConfig({bool normalize = true, bool removeSpaces = true, bool toLowerCase = true, bool removeSpecialChars = false, bool removeAccents = false, bool trimWhitespace = true, String? locale, bool enableCache = true, int cacheCapacity = 1000, int swMatchScore = 2, int swMismatchScore = -1, int swGapScore = -1, double jaroPrefixScale = 0.1, String Function(String)? preProcessor, String Function(String)? postProcessor})
  Constraints: jaroPrefixScale: [0, 0.25].
Fields: (Correspond to constructor parameters)
  normalize: bool.
  removeSpaces: bool.
  toLowerCase: bool.
  removeSpecialChars: bool.
  removeAccents: bool.
  trimWhitespace: bool.
  locale: String?.
  enableCache: bool.
  cacheCapacity: int.
  swMatchScore: int. Smith-Waterman match score.
  swMismatchScore: int. Smith-Waterman mismatch score.
  swGapScore: int. Smith-Waterman gap score.
  jaroPrefixScale: double. Jaro-Winkler prefix scale.
  preProcessor: String Function(String)?.
  postProcessor: String Function(String)?.
Static Method:
    get builder: StringSimilarityBuilder

Class: StringSimilarityBuilder
Purpose: Builder for StringSimilarityConfig.
Fields: (Same as StringSimilarityConfig, mutable, with defaults).
Methods: (Chainable setters for each field)
  setNormalize(bool value): StringSimilarityBuilder.
  setRemoveSpaces(bool value): StringSimilarityBuilder.
  setToLowerCase(bool value): StringSimilarityBuilder.
  setRemoveSpecialChars(bool value): StringSimilarityBuilder.
  setRemoveAccents(bool value): StringSimilarityBuilder.
  setTrimWhitespace(bool value): StringSimilarityBuilder.
  setLocale(String value): StringSimilarityBuilder.
  setEnableCache(bool value): StringSimilarityBuilder.
  setCacheCapacity(int value): StringSimilarityBuilder.
  setSwMatchScore(int value): StringSimilarityBuilder.
  setSwMismatchScore(int value): StringSimilarityBuilder.
  setSwGapScore(int value): StringSimilarityBuilder.
  setJaroPrefixScale(double value): StringSimilarityBuilder.
  setPreProcessor(String Function(String) func): StringSimilarityBuilder.
  setPostProcessor(String Function(String) func): StringSimilarityBuilder.
  build(): StringSimilarityConfig.

Enum: SimilarityAlgorithm
Purpose: Supported string similarity algorithms.
Values: diceCoefficient, levenshteinDistance, jaro, jaroWinkler, cosine, hammingDistance, smithWaterman, soundex.

Class: StringSimilarity
Purpose: Main utility class for string similarity calculations.
Constructor: StringSimilarity._() (Private constructor).
Static Fields:
Static Methods:
  clearCache(): void. Clears the bigram cache.
  diceCoefficient(String first, String second, [StringSimilarityConfig config = const StringSimilarityConfig()]): double.  [0, 1].
  hammingDistance(String s1, String s2, [StringSimilarityConfig config = const StringSimilarityConfig()]): int.  Throws StringSimilarityError if lengths differ.
  smithWaterman(String s1, String s2, [StringSimilarityConfig config = const StringSimilarityConfig()]): double. Normalized score [0, 1].
  soundex(String input, [StringSimilarityConfig config = const StringSimilarityConfig()]): String. Four-character code.
  levenshteinDistance(String s1, String s2, [StringSimilarityConfig config = const StringSimilarityConfig()]): int. Edit distance.
  jaro(String s1, String s2, [StringSimilarityConfig config = const StringSimilarityConfig()]): double.  [0, 1].
  jaroWinkler(String s1, String s2, {StringSimilarityConfig config = const StringSimilarityConfig()}): double.  [0, 1], boosted by prefix.
  cosine(String text1, String text2, [StringSimilarityConfig config = const StringSimilarityConfig()]): double. Treats strings as bags of words.
  compare(String first, String second, SimilarityAlgorithm algorithm, {StringSimilarityConfig config = const StringSimilarityConfig()}): double. Normalized score [0,1] for distance algorithms.
  compareAsync(String first, String second, SimilarityAlgorithm algorithm, {StringSimilarityConfig config = const StringSimilarityConfig()}): Future<double>. Asynchronous version of compare.
  compareBatch(List<List<String>> pairs, SimilarityAlgorithm algorithm, {StringSimilarityConfig config = const StringSimilarityConfig()}): List<double>.  Throws StringSimilarityError if pairs are invalid.
  generateReport(String first, String second, SimilarityAlgorithm algorithm, {StringSimilarityConfig config = const StringSimilarityConfig()}): String.
