Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
FuzzyMatcher.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
5#include <PhosphorShellLauncher/phosphorshelllauncher_export.h>
6
7#include <QList>
8#include <QStringView>
9
10#include <optional>
11
12namespace PhosphorShellLauncher {
13
14// The score and matched positions of one pattern against one candidate.
15struct PHOSPHORSHELLLAUNCHER_EXPORT FuzzyMatch
16{
17 // Higher is better. Comparable across candidates for the same pattern
18 // and, because every provider scores through this one matcher, across
19 // providers for the same query too.
20 int score = 0;
21 // Indices into the candidate of the characters that matched the
22 // pattern, ascending. One per pattern character. For highlighting.
23 QList<int> positions;
24};
25
26// fzf's default scorer ("FuzzyMatchV2"), ported so results rank the way a
27// user who lives in fzf expects. Every pattern character must appear in
28// the candidate in order; the score rewards matches at word boundaries
29// (after whitespace, a delimiter, a non-word character, or at a camelCase
30// / letter-to-digit transition), rewards consecutive runs, and penalises
31// gaps. The first pattern character's boundary bonus is doubled, so
32// "fire" prefers "Firefox" over "sunfire".
33//
34// Constants and the bonus table are fzf's own, so the ordering of any two
35// candidates here matches fzf's ordering for the same input.
36//
37// Case-insensitive by default (fzf's smart-case is the caller's business:
38// pass caseSensitive when the pattern contains an upper-case character).
39class PHOSPHORSHELLLAUNCHER_EXPORT FuzzyMatcher
40{
41public:
42 // Empty pattern matches everything with score 0 and no positions.
43 // Note that no provider relies on this: each one decides for itself
44 // whether an empty query lists anything (listsOnEmptyQuery) and skips
45 // the matcher entirely in that case. The behaviour is kept because it
46 // is the sane answer for a general-purpose matcher, not because a
47 // caller depends on it. Empty candidate never matches a non-empty
48 // pattern.
49 [[nodiscard]] static std::optional<FuzzyMatch> match(QStringView pattern, QStringView candidate,
50 bool caseSensitive = false);
51
58 [[nodiscard]] static bool patternIsCaseSensitive(QStringView pattern);
59
60 // fzf's score constants, public so a provider that answers a query
61 // exactly (the calculator) can pick a score that outranks any fuzzy
62 // match without guessing at the scale.
63 static constexpr int ScoreMatch = 16;
64 static constexpr int ScoreGapStart = -3;
65 static constexpr int ScoreGapExtension = -1;
66 static constexpr int BonusBoundary = ScoreMatch / 2;
67 static constexpr int BonusNonWord = ScoreMatch / 2;
70 static constexpr int BonusFirstCharMultiplier = 2;
71 static constexpr int BonusBoundaryWhite = BonusBoundary + 2;
72 static constexpr int BonusBoundaryDelimiter = BonusBoundary + 1;
73
74 // The best score a pattern of `length` characters can reach: every
75 // character matched, consecutively, at a whitespace boundary, first
76 // character doubled. A provider returning an exact answer can add to
77 // this to guarantee it sorts first.
78 [[nodiscard]] static int perfectScore(int length);
79};
80
81} // namespace PhosphorShellLauncher
Definition FuzzyMatcher.h:40
static constexpr int ScoreGapStart
Definition FuzzyMatcher.h:64
static constexpr int BonusCamel123
Definition FuzzyMatcher.h:68
static bool patternIsCaseSensitive(QStringView pattern)
fzf's smart case, as a decision a caller can make in one line.
static constexpr int BonusBoundaryDelimiter
Definition FuzzyMatcher.h:72
static constexpr int BonusNonWord
Definition FuzzyMatcher.h:67
static constexpr int ScoreMatch
Definition FuzzyMatcher.h:63
static std::optional< FuzzyMatch > match(QStringView pattern, QStringView candidate, bool caseSensitive=false)
static constexpr int ScoreGapExtension
Definition FuzzyMatcher.h:65
static constexpr int BonusBoundaryWhite
Definition FuzzyMatcher.h:71
static constexpr int BonusFirstCharMultiplier
Definition FuzzyMatcher.h:70
static constexpr int BonusConsecutive
Definition FuzzyMatcher.h:69
static constexpr int BonusBoundary
Definition FuzzyMatcher.h:66
static int perfectScore(int length)
Definition AppsProvider.h:19
Definition FuzzyMatcher.h:16
QList< int > positions
Definition FuzzyMatcher.h:23
int score
Definition FuzzyMatcher.h:20