Interface FuzzyMatcher

All Known Implementing Classes:
FzfV2Matcher, GrammarMatcher
public interface FuzzyMatcher
Scores a query against candidate strings, fzf-style.

Implementations are stateless and thread-safe. The contract:

  • An empty query matches every candidate with score 0 and no positions.
  • A non-empty query matches only when it is a (fuzzy) subsequence of the candidate.
  • Returned MatchResult.positions() are ascending candidate indices.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    FuzzyMatcher.Scored<T>
    An item paired with its match result.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    SCORE_PER_CHAR
    Base score awarded per matched character.

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<MatchResult>
    match(String query, String candidate)
    Matches a query against a single candidate.
    default <T> List<FuzzyMatcher.Scored<T>>
    rank(String query, List<T> items, Function<T,String> toText)
    Ranks and filters a list of items by how well their text matches the query.

  • Field Details

    • SCORE_PER_CHAR

      static final int SCORE_PER_CHAR
      Base score awarded per matched character.
      See Also:

  • Method Details

    • match

      Optional<MatchResult> match(String query, String candidate)
      Matches a query against a single candidate.
      Parameters:
      query - the search query
      candidate - the candidate string to score
      Returns:
      a result when the candidate matches, otherwise Optional.empty(); never null

    • rank

      default <T> List<FuzzyMatcher.Scored<T>> rank(String query, List<T> items, Function<T,String> toText)
      Ranks and filters a list of items by how well their text matches the query.

      Non-matching items are dropped. Results are ordered by descending score, then (matching fzf's default tiebreak) by ascending candidate length, then by input order (stable sort). An empty query preserves input order, since every item scores equally and the length tiebreak would otherwise scramble it.

      Type Parameters:
      T - the item type
      Parameters:
      query - the search query
      items - the items to rank
      toText - extracts the matchable text from each item
      Returns:
      matching items paired with their scores, best first