feat(search): add SearchTerm::exclude

Parenthesises both sides, as extend() does: unparenthesised, a
disjunction in the query bar binds so the exclusion covers only its last
term and leaves the excluded mail on screen, with nothing reporting an
error.

An empty existing query returns empty rather than the addition alone,
which is where this deliberately differs from extend(). Excluding from
nothing means the whole Maildir minus one value; the menus will grey the
entry out and this is the second layer.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 18 insertions, 0 deletions

diff --git a/src/searchterm.h b/src/searchterm.h
index d596676..646fd77 100644
--- a/src/searchterm.h
+++ b/src/searchterm.h
@@ -76,6 +76,24 @@ QString tag(const QString &name);
 /// matches nothing; an empty `addition` leaves `existing` untouched.
 QString extend(const QString &existing, const QString &addition);
 
+/// Narrows `existing` by everything that is NOT `addition`, as
+/// `(existing) AND NOT (addition)`.
+///
+/// **Both sides are parenthesised, for the same load-bearing reason as
+/// extend().** The query bar may hold a hand-written disjunction, and
+/// `a or b AND NOT c` binds as `a or (b AND NOT c)`: the exclusion would cover
+/// only the second term, leaving on screen exactly the mail the user asked to
+/// be rid of, with no error reported anywhere.
+///
+/// **An empty `existing` yields an EMPTY STRING, unlike extend().** Excluding
+/// from nothing would mean the entire Maildir minus one value: a legitimate
+/// query, and an implausible thing to have meant by right-clicking a value in
+/// a fresh window. The menus grey the entry out when the query bar is empty;
+/// this is the second layer, against a caller that forgets the guard.
+///
+/// An empty `addition` leaves `existing` untouched.
+QString exclude(const QString &existing, const QString &addition);
+
 }  // namespace SearchTerm
 
 /// One entry a context menu can offer: a finished query and the text naming it.