Skip to main content

hyprforge_emoji/
lib.rs

1//! CLDR-ordered emoji data and a pure search function, for building an
2//! emoji picker on top.
3//!
4//! Follows the same split the D-Bus-backed modules in this workspace use
5//! (see `CLAUDE.md`, "The shape a D-Bus-backed module takes"): even
6//! though there is no D-Bus here, the same rule applies — **the model is
7//! plain data, and the decisions are pure functions over it.** [`Emoji`]
8//! is a flat struct, [`all`] and [`groups`] hand back slices, and
9//! [`search`] is a pure function from a query and a table to a ranked
10//! `Vec`. Nothing in this crate touches the filesystem, a network, a
11//! runtime, or Hyprland — a picker UI is built *on* this, not the other
12//! way round. The long-press interaction that would let a person pick a
13//! tone, and where their chosen default tone is stored, are both that
14//! picker's job, not this crate's — this crate only makes both easy: see
15//! [`Emoji::tone`] and [`Emoji::tone_variants`].
16//!
17//! # Where the data comes from
18//!
19//! [`data/emoji-test.txt`](https://github.com/hyprforge-suite/hyprforge/blob/main/crates/hyprforge-emoji/data/emoji-test.txt)
20//! is a verbatim copy of Unicode's `emoji-test.txt` (UTS #51 test data,
21//! Unicode 17.0), which the file itself describes as being "in CLDR
22//! order... recommended (but not required) for keyboard palettes." That
23//! is the order [`all`] and [`search`]'s tie-breaking preserve: it is
24//! not sorted alphabetically or by codepoint, because CLDR order is what
25//! makes a picker's default view look intentional rather than random.
26//!
27//! [`src/generated.rs`](https://github.com/hyprforge-suite/hyprforge/blob/main/crates/hyprforge-emoji/src/generated.rs)
28//! is generated from that file and committed alongside it — see
29//! `src/bin/generate.rs` for the generator, exactly how it derives the
30//! table below, and how to re-run it. Nothing in this crate reads
31//! `data/emoji-test.txt` at build time or runtime; only the generator
32//! does, and only when a human runs it deliberately.
33//!
34//! # What made it into the table
35//!
36//! The source file marks every entry `component`, `fully-qualified`,
37//! `minimally-qualified`, or `unqualified`. Only `fully-qualified`
38//! entries are considered at all:
39//!
40//! - `minimally-qualified` and `unqualified` are the *same* emoji as a
41//!   `fully-qualified` entry elsewhere in the file, just missing a
42//!   variation selector (see UTS #51 ED-18a/ED-19). Keeping them would
43//!   put visual duplicates of the same character in the table under the
44//!   same name.
45//! - `component` entries (9 of them: the five Fitzpatrick skin-tone
46//!   modifiers and four hair-style modifiers) are modifier codepoints,
47//!   not standalone emoji a person picks from a grid. Excluding them
48//!   also happens to empty out the file's "Component" group entirely —
49//!   see [`groups`] for why that group is still listed.
50//!
51//! # The skin-tone relationship
52//!
53//! The fully-qualified set is 3944 entries, and 2030 of those are tone
54//! variants: the same gesture or person repeated once per Fitzpatrick
55//! modifier (`U+1F3FB`..=`U+1F3FF`), sometimes twice per entry for
56//! two-person sequences like a handshake. This crate does **not**
57//! flatten those away, and does not synthesise a base character by
58//! appending a modifier codepoint at the call site either — that is
59//! wrong in general, because a ZWJ sequence can carry an independent
60//! tone on each human component, and where the modifier belongs in the
61//! sequence is not something to guess. Instead, [`Emoji`] models the
62//! *relationship*, derived entirely from grouping what
63//! `data/emoji-test.txt` actually contains:
64//!
65//! - The grid ([`all`]) holds **one entry per emoji concept**, in CLDR
66//!   order, exactly as before.
67//! - [`Emoji::supports_tones`] says whether that concept has tone
68//!   variants, and [`Emoji::tone`] / [`Emoji::tone_variants`] hand back
69//!   the real, already-qualified character for each [`Tone`] — never a
70//!   sequence built by this crate.
71//! - Two-person sequences (19 families: "handshake" via the newer
72//!   directional-hands ZWJ combo, "people holding hands", "kiss: woman,
73//!   man", and similar) are **not** modeled as tone-capable, because one
74//!   [`Tone`] cannot pick between two independent people's tones. Where
75//!   such a family has a neutral, toneless form (7 of the 19 — e.g.
76//!   "kiss: woman, man" itself), that form is kept in the grid with
77//!   `supports_tones() == false`. Where it does not (12 of the 19 —
78//!   e.g. the two-person "people wrestling" ZWJ combo, as opposed to the
79//!   older single-glyph 🤼 pictograph, which *does* get tones — see
80//!   below), the family is dropped from the grid entirely rather than
81//!   picking one arbitrary two-tone combination to stand in for a
82//!   concept Unicode never gave a neutral rendering.
83//! - A handful of single-person symbols (e.g. "index pointing up",
84//!   "hand with fingers splayed") need a variation selector
85//!   (`U+FE0F`) to render as an emoji when shown alone, but Unicode
86//!   omits that selector from the *toned* sequences for the very same
87//!   emoji, since the tone modifier already forces emoji presentation.
88//!   Naively, that makes the neutral and toned forms hash to different
89//!   "family keys" and look like unrelated entries; the generator
90//!   strips `U+FE0F` before grouping so they merge correctly. As of
91//!   Unicode 17.0, every single-person tone family turns out to have a
92//!   genuine neutral form once this is accounted for — none currently
93//!   need a same-tone-as-canonical stand-in — but the generator still
94//!   has a documented fallback (the `medium skin tone` member, itself a
95//!   real, already-qualified emoji, never a synthesised one) for the
96//!   day a future Unicode release adds a tone-only family, so that case
97//!   fails loudly rather than silently if it does.
98//!
99//! **After all of this, [`all`] returns 1914 entries, of which 323
100//! support tones.** [`EMOJI_COUNT`] and [`tone_capable_count`] are both
101//! asserted against the generated table's own contents in this crate's
102//! tests, so this doc comment cannot silently drift from the data.
103//!
104//! # Search
105//!
106//! [`search`] ranks by how good a name match is, not by table order:
107//! exact name match, then a whole leading word, then a whole word
108//! anywhere else in the name, then any other substring. Ties within a
109//! tier keep CLDR order. Because the table already holds one row per
110//! concept rather than one per tone, searching by name naturally finds
111//! that one row — there is nothing tone-specific for `search` to filter,
112//! since a query like "wave" is answered by "waving hand" once, not five
113//! times. See [`search`]'s doc comment for the full ranking rule.
114
115mod generated;
116
117/// A skin tone a tone-capable [`Emoji`] can be shown at, per the five
118/// Fitzpatrick modifiers UTS #51 defines (`U+1F3FB`..=`U+1F3FF`).
119///
120/// This is the "model the relationship as an enum, not raw codepoints
121/// at the call site" half of this crate's job: a consumer holding a
122/// `Tone` and an [`Emoji`] gets the right character via [`Emoji::tone`]
123/// without ever looking at a codepoint. There is deliberately no
124/// `Neutral`/`None` variant here — "no tone chosen" is
125/// [`Emoji::supports_tones`] being `false`, or a caller simply not
126/// calling [`Emoji::tone`] at all and using [`Emoji::emoji`] directly;
127/// modeling it as a sixth `Tone` would let code accidentally ask a
128/// non-tone-capable emoji for `Tone::Neutral` and get a misleading
129/// "success".
130#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
131pub enum Tone {
132    Light,
133    MediumLight,
134    Medium,
135    MediumDark,
136    Dark,
137}
138
139/// All five tones, in the same order [`Emoji::tone_variants`] returns
140/// them and the generated table stores them.
141pub const TONES: [Tone; 5] = [
142    Tone::Light,
143    Tone::MediumLight,
144    Tone::Medium,
145    Tone::MediumDark,
146    Tone::Dark,
147];
148
149/// One emoji: its character(s), its name, where it sits in the Unicode
150/// CLDR grouping, and — if it has any — its skin-tone variants.
151///
152/// `emoji` is a `&str`, not a `char`, because an emoji is frequently
153/// *several* Rust `char`s — a base codepoint plus a variation selector
154/// (`❤️` = `U+2764 U+FE0F`), or several codepoints joined by
155/// `U+200D` ZERO WIDTH JOINER (`🏳️‍⚧️` = five codepoints). Treating it as
156/// a single `char` would be simply wrong; treating it as bytes would
157/// make it possible to slice through the middle of one. Everything in
158/// this crate that looks at an emoji or a name iterates `chars()`, never
159/// byte offsets — see the tests named `_is_never_sliced_mid_character`.
160///
161/// `tones` is private: an [`Emoji`] can only be obtained from [`all`],
162/// never constructed by hand, so a consumer cannot fabricate a tone
163/// relationship this crate did not derive from the data file.
164#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
165pub struct Emoji {
166    /// The emoji itself, e.g. `"😀"` or `"🏳️‍⚧️"`.
167    pub emoji: &'static str,
168    /// CLDR's name for it, lowercase, e.g. `"grinning face"`.
169    pub name: &'static str,
170    /// The group it belongs to, e.g. `"Smileys & Emotion"`. One of the
171    /// entries in [`groups`].
172    pub group: &'static str,
173    /// The subgroup within the group, e.g. `"face-smiling"`.
174    pub subgroup: &'static str,
175    /// The five tone variants, indexed the same way [`TONES`] is
176    /// ordered, or `None` if this emoji has no tone relationship at
177    /// all. See [`Emoji::tone`] and [`Emoji::tone_variants`] rather than
178    /// reading this field's shape directly — it stays private so it can
179    /// only be populated by the generator.
180    tones: Option<[&'static str; 5]>,
181}
182
183impl Emoji {
184    /// Whether this emoji has skin-tone variants at all — e.g. a picker
185    /// deciding whether a long-press should open a tone palette.
186    pub fn supports_tones(&self) -> bool {
187        self.tones.is_some()
188    }
189
190    /// The character to show for `tone`. If this emoji has no tone
191    /// relationship, every `tone` returns [`Emoji::emoji`] unchanged —
192    /// asking a plain emoji for a tone is not an error, it just has
193    /// nothing to change. This is what lets a picker hold a `Tone` (the
194    /// user's chosen default) and call this on *every* grid entry
195    /// without checking [`supports_tones`](Self::supports_tones) first: a tone-incapable
196    /// entry simply ignores the request rather than producing a broken
197    /// sequence.
198    pub fn tone(&self, tone: Tone) -> &'static str {
199        match self.tones {
200            Some(variants) => variants[tone_index(tone)],
201            None => self.emoji,
202        }
203    }
204
205    /// Every tone variant, paired with which [`Tone`] it is, in
206    /// [`TONES`] order — e.g. for the palette a long-press opens.
207    /// `None` if this emoji has no tone relationship.
208    pub fn tone_variants(&self) -> Option<[(Tone, &'static str); 5]> {
209        self.tones.map(|variants| {
210            [
211                (Tone::Light, variants[0]),
212                (Tone::MediumLight, variants[1]),
213                (Tone::Medium, variants[2]),
214                (Tone::MediumDark, variants[3]),
215                (Tone::Dark, variants[4]),
216            ]
217        })
218    }
219}
220
221fn tone_index(tone: Tone) -> usize {
222    match tone {
223        Tone::Light => 0,
224        Tone::MediumLight => 1,
225        Tone::Medium => 2,
226        Tone::MediumDark => 3,
227        Tone::Dark => 4,
228    }
229}
230
231/// The number of emoji [`all`] returns: one row per concept, tone
232/// families collapsed per the crate doc comment's rules. Asserted
233/// against the generated table's actual length in
234/// `entry_count_matches_the_number_this_crate_documents`.
235pub const EMOJI_COUNT: usize = generated::EMOJIS.len();
236
237/// How many of [`all`]'s entries support tones, i.e.
238/// `all().iter().filter(Emoji::supports_tones).count()` — computed here
239/// too so `entry_count_matches_the_number_this_crate_documents` can pin
240/// both numbers the doc comment states without walking the table twice
241/// at doc-comment-writing time and hoping they stay in sync by hand.
242pub fn tone_capable_count() -> usize {
243    generated::EMOJIS.iter().filter(|e| e.tones.is_some()).count()
244}
245
246/// Every emoji this crate knows about, in CLDR order (the order the
247/// source file itself recommends for keyboard palettes). See the crate
248/// doc comment for what is and is not included, and how tone variants
249/// are represented.
250pub fn all() -> &'static [Emoji] {
251    generated::EMOJIS
252}
253
254/// The ten Unicode CLDR groups, in the file's own order — e.g. for a
255/// picker's tabs or section headers.
256///
257/// This lists all ten groups the source file defines, including
258/// "Component", even though [`all`] never returns an entry from it: the
259/// file's grouping is what it is, and a picker deciding to hide an empty
260/// tab is a UI choice, not a data one. As of Unicode 17.0 "Component" is
261/// the only group that ends up empty — every other group keeps at least
262/// one entry.
263pub fn groups() -> &'static [&'static str] {
264    generated::GROUPS
265}
266
267/// How well a name matched a query, best first. `search` sorts by this,
268/// then by CLDR order within a tier.
269#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
270enum MatchTier {
271    /// The whole (normalized) name equals the query: `"fire"` against
272    /// the emoji literally named "fire".
273    Exact,
274    /// The query is the name's first whole word: `"fire"` against
275    /// "fire engine", "fire extinguisher".
276    LeadingWord,
277    /// The query is some other whole word in the name: `"face"` against
278    /// "face with tears of joy" would land here if "face" were not also
279    /// the leading word (it is, so that example is `LeadingWord`) —
280    /// this tier is for a whole-word match anywhere past the start.
281    Word,
282    /// The query occurs as a substring but not as a whole word:
283    /// `"fire"` against "firefighter", "firecracker", "fireworks" — the
284    /// query is glued to other letters on at least one side.
285    Substring,
286}
287
288/// Lowercase and collapse whitespace runs to a single space, trimming
289/// the ends. Used on both the query and (implicitly, since the source
290/// data is already single-spaced) names, so `"  FIRE   ENGINE "` and
291/// `"fire engine"` compare equal — search is meant to be forgiving about
292/// how a query was typed, not about what the data says.
293fn normalize(s: &str) -> String {
294    s.split_whitespace()
295        .map(str::to_lowercase)
296        .collect::<Vec<_>>()
297        .join(" ")
298}
299
300/// Split a normalized name into its whole words, on the same boundary a
301/// person would read as a word break: whitespace and punctuation
302/// (`-`, `:`, `,`, `'`), never in the middle of a run of letters/digits.
303fn words(normalized_name: &str) -> impl Iterator<Item = &str> {
304    normalized_name
305        .split(|c: char| !c.is_alphanumeric())
306        .filter(|w| !w.is_empty())
307}
308
309/// Score a normalized name against a normalized, non-empty query.
310/// Returns `None` if the name does not match at all.
311fn score(normalized_name: &str, normalized_query: &str) -> Option<MatchTier> {
312    if normalized_name == normalized_query {
313        return Some(MatchTier::Exact);
314    }
315
316    let mut leading = true;
317    let mut any_word_match = false;
318    for word in words(normalized_name) {
319        if word == normalized_query {
320            if leading {
321                return Some(MatchTier::LeadingWord);
322            }
323            any_word_match = true;
324        }
325        leading = false;
326    }
327    if any_word_match {
328        return Some(MatchTier::Word);
329    }
330
331    if normalized_name.contains(normalized_query) {
332        return Some(MatchTier::Substring);
333    }
334
335    None
336}
337
338/// Search `table` for `query`, returning matches best-first.
339///
340/// Ranking, best to worst:
341///
342/// 1. **Exact** — the query is the whole name.
343/// 2. **Leading word** — the query is the name's first whole word
344///    (`"fire"` finds "fire engine" and "fire extinguisher" here).
345/// 3. **Word** — the query is some other whole word in the name.
346/// 4. **Substring** — the query occurs but not as a whole word
347///    (`"fire"` finds "firefighter", "firecracker" and "fireworks"
348///    here, after every emoji actually *called* "fire" or "fire
349///    something").
350///
351/// Ties within a tier keep `table`'s own order, which for [`all`] is
352/// CLDR order — so 🔥 ("fire") outranks "fire engine" and "fire
353/// extinguisher" (tier 2, in CLDR order relative to each other), which
354/// in turn outrank "firefighter", "firecracker" and "fireworks" (tier 4).
355/// That ordering is the entire point of ranking explicitly instead of
356/// trusting table order or a naive `contains` check: a flat substring
357/// search would put "firefighter" and "fire" on equal footing and let
358/// table order decide, which is exactly the "feels random" a picker
359/// should not have.
360///
361/// Matching is case- and whitespace-insensitive (see `normalize`). An
362/// empty or all-whitespace query returns every entry in `table`'s own
363/// order, rather than nothing — a picker with no query typed yet should
364/// show the full grid, not a blank one.
365pub fn search(query: &str, table: &[Emoji]) -> Vec<Emoji> {
366    let normalized_query = normalize(query);
367    if normalized_query.is_empty() {
368        return table.to_vec();
369    }
370
371    let mut scored: Vec<(MatchTier, usize, Emoji)> = table
372        .iter()
373        .enumerate()
374        .filter_map(|(index, entry)| {
375            let normalized_name = normalize(entry.name);
376            score(&normalized_name, &normalized_query).map(|tier| (tier, index, *entry))
377        })
378        .collect();
379
380    scored.sort_by(|a, b| a.0.cmp(&b.0).then(a.1.cmp(&b.1)));
381    scored.into_iter().map(|(_, _, entry)| entry).collect()
382}
383
384#[cfg(test)]
385mod tests {
386    use super::*;
387
388    // --- table integrity -------------------------------------------------
389
390    #[test]
391    fn every_entry_has_a_non_empty_character_and_name() {
392        for entry in all() {
393            assert!(
394                !entry.emoji.is_empty(),
395                "entry {:?} has an empty character",
396                entry.name
397            );
398            assert!(
399                !entry.name.is_empty(),
400                "entry with character {:?} has an empty name",
401                entry.emoji
402            );
403            assert!(!entry.group.is_empty());
404            assert!(!entry.subgroup.is_empty());
405        }
406    }
407
408    #[test]
409    fn entry_count_matches_the_number_this_crate_documents() {
410        // The crate doc comment states 1914 grid entries, 323 of which
411        // support tones. Pin both here so the doc comment and the
412        // generated table cannot silently drift apart.
413        assert_eq!(EMOJI_COUNT, 1914);
414        assert_eq!(all().len(), 1914);
415        assert_eq!(tone_capable_count(), 323);
416    }
417
418    #[test]
419    fn a_tone_incapable_entrys_grid_character_never_carries_a_skin_tone_modifier() {
420        // U+1F3FB..=U+1F3FF are the five Fitzpatrick modifiers. An
421        // entry with no tone relationship must show a plain,
422        // unmodified character — only a tone-capable entry may
423        // (rarely, via the documented medium-tone fallback) have one in
424        // its grid `emoji` field.
425        for entry in all().iter().filter(|e| !e.supports_tones()) {
426            for ch in entry.emoji.chars() {
427                let cp = ch as u32;
428                assert!(
429                    !(0x1F3FB..=0x1F3FF).contains(&cp),
430                    "{:?} ({}) has a skin-tone modifier despite supports_tones() == false",
431                    entry.name,
432                    entry.emoji
433                );
434            }
435        }
436    }
437
438    #[test]
439    fn no_entry_is_a_bare_skin_tone_or_hair_component() {
440        // The 9 `component` status entries (5 skin tones, 4 hair
441        // styles) are modifiers, not standalone picks, and must not
442        // have made it into the table via the fully-qualified filter.
443        let component_names = [
444            "light skin tone",
445            "medium-light skin tone",
446            "medium skin tone",
447            "medium-dark skin tone",
448            "dark skin tone",
449            "red hair",
450            "curly hair",
451            "white hair",
452            "bald",
453        ];
454        for entry in all() {
455            assert!(
456                !component_names.contains(&entry.name),
457                "bare component {:?} leaked into the table",
458                entry.name
459            );
460        }
461    }
462
463    #[test]
464    fn groups_lists_all_ten_cldr_groups_in_file_order() {
465        let g = groups();
466        assert_eq!(g.len(), 10);
467        assert_eq!(g[0], "Smileys & Emotion");
468        assert_eq!(g[1], "People & Body");
469        assert_eq!(g[2], "Component");
470        assert_eq!(g[9], "Flags");
471    }
472
473    #[test]
474    fn every_table_entry_group_is_one_of_the_listed_groups() {
475        let g = groups();
476        for entry in all() {
477            assert!(
478                g.contains(&entry.group),
479                "{:?} has group {:?}, not in groups()",
480                entry.name,
481                entry.group
482            );
483        }
484    }
485
486    #[test]
487    fn the_component_group_has_no_entries_after_filtering() {
488        assert!(
489            !all().iter().any(|e| e.group == "Component"),
490            "Component should be empty once component-status entries are excluded"
491        );
492    }
493
494    #[test]
495    fn table_order_is_cldr_order_not_alphabetical() {
496        // The very first entry in the source file is grinning face, not
497        // whatever is alphabetically first — confirms the generator
498        // preserved file order rather than sorting it.
499        assert_eq!(all()[0].name, "grinning face");
500        assert_eq!(all()[0].emoji, "😀");
501    }
502
503    // --- tone relationship -----------------------------------------------
504
505    #[test]
506    fn a_gesture_with_tones_reports_five_distinct_variants() {
507        let waving_hand = all()
508            .iter()
509            .find(|e| e.name == "waving hand")
510            .expect("waving hand should be in the table");
511        assert!(waving_hand.supports_tones());
512        let variants = waving_hand
513            .tone_variants()
514            .expect("supports_tones() said true");
515        let chars: std::collections::HashSet<&str> = variants.iter().map(|(_, c)| *c).collect();
516        assert_eq!(chars.len(), 5, "the five tone variants must be distinct");
517        // And every one of them differs from the neutral grid character.
518        for (_, variant) in variants {
519            assert_ne!(variant, waving_hand.emoji);
520        }
521    }
522
523    #[test]
524    fn an_emoji_without_tones_reports_none() {
525        let fire = all()
526            .iter()
527            .find(|e| e.name == "fire")
528            .expect("fire should be in the table");
529        assert!(!fire.supports_tones());
530        assert!(fire.tone_variants().is_none());
531    }
532
533    #[test]
534    fn asking_a_tone_incapable_emoji_for_a_tone_returns_the_plain_emoji() {
535        let fire = all().iter().find(|e| e.name == "fire").unwrap();
536        for tone in TONES {
537            assert_eq!(fire.tone(tone), fire.emoji);
538        }
539    }
540
541    #[test]
542    fn asking_a_tone_capable_emoji_for_each_tone_matches_its_variants_list() {
543        let waving_hand = all().iter().find(|e| e.name == "waving hand").unwrap();
544        let variants = waving_hand.tone_variants().unwrap();
545        for (tone, expected) in variants {
546            assert_eq!(waving_hand.tone(tone), expected);
547        }
548    }
549
550    #[test]
551    fn a_tone_family_whose_neutral_form_needs_a_variation_selector_still_merges_correctly() {
552        // "index pointing up"'s neutral form is "261D FE0F" but its
553        // toned forms are "261D <modifier>" with no FE0F at all (the
554        // modifier already forces emoji presentation). If the family
555        // key were not FE0F-insensitive, this would show up as two
556        // disconnected table rows instead of one entry with tones.
557        let entry = all()
558            .iter()
559            .find(|e| e.name == "index pointing up")
560            .expect("index pointing up should be a single, merged entry");
561        assert!(entry.supports_tones());
562        let variants = entry.tone_variants().unwrap();
563        // The neutral (FE0F-qualified) form is the grid character, and
564        // is distinct from every toned variant.
565        for (_, variant) in variants {
566            assert_ne!(variant, entry.emoji);
567        }
568    }
569
570    #[test]
571    fn a_two_person_family_with_a_neutral_form_is_kept_without_tones() {
572        // "kiss: woman, man" has a neutral form but its tone variants
573        // carry two independent modifiers (one per person) — a single
574        // Tone can't disambiguate those, so this crate does not model
575        // it as tone-capable at all.
576        let entry = all()
577            .iter()
578            .find(|e| e.name == "kiss: woman, man")
579            .expect("kiss: woman, man should be in the table");
580        assert!(!entry.supports_tones());
581    }
582
583    #[test]
584    fn a_two_person_family_with_no_neutral_form_is_excluded_entirely() {
585        // "kiss: person, person" and "couple with heart: person,
586        // person" exist in the source file only as two-modifier toned
587        // combinations (20 each) with no neutral rendering — they must
588        // not appear in the grid at all, rather than an arbitrary tone
589        // pair standing in for them.
590        //
591        // Note "people wrestling" is deliberately *not* used for this:
592        // the file has two unrelated encodings sharing that display
593        // name — the classic single-glyph 🤼 pictograph (which has a
594        // neutral form and legitimately gets tones) and a newer
595        // two-person ZWJ combo (which does not and is excluded) — so
596        // asserting the name's absence entirely would be wrong.
597        assert!(!all().iter().any(|e| e.name == "kiss: person, person"));
598        assert!(!all()
599            .iter()
600            .any(|e| e.name == "couple with heart: person, person"));
601    }
602
603    #[test]
604    fn search_still_finds_a_tone_capable_emoji_by_its_base_name_only_once() {
605        let results = search("waving hand", all());
606        let matches: Vec<_> = results.iter().filter(|e| e.name == "waving hand").collect();
607        assert_eq!(
608            matches.len(),
609            1,
610            "a tone-capable emoji must appear exactly once in the table, not once per tone"
611        );
612    }
613
614    // --- character safety --------------------------------------------------
615
616    #[test]
617    fn multi_codepoint_emoji_are_never_sliced_mid_character() {
618        // A ZWJ sequence like the transgender flag is five codepoints
619        // and far more than one byte; chars() must yield it whole, and
620        // re-collecting those chars must reproduce the exact string —
621        // which would fail if anything upstream had built it by slicing
622        // at a byte offset that landed inside a character instead of
623        // walking chars().
624        let flag = all()
625            .iter()
626            .find(|e| e.name == "transgender flag")
627            .expect("transgender flag should be in the table");
628        assert!(flag.emoji.chars().count() >= 4);
629        let rebuilt: String = flag.emoji.chars().collect();
630        assert_eq!(rebuilt, flag.emoji);
631    }
632
633    #[test]
634    fn a_query_containing_a_multi_byte_character_never_panics_and_finds_nothing() {
635        // Every name in this table is ASCII, so a query made of a
636        // multi-byte character (the emoji itself, not its name) cannot
637        // match anything — but it must not panic either, which is what
638        // would happen if search sliced by byte offset instead of
639        // walking chars() throughout normalize()/words()/contains().
640        let results = search("🔥", all());
641        assert!(results.is_empty());
642    }
643
644    // --- search ranking ------------------------------------------------
645
646    #[test]
647    fn exact_name_match_beats_a_leading_word_match() {
648        let results = search("fire", all());
649        assert!(!results.is_empty());
650        assert_eq!(results[0].name, "fire");
651    }
652
653    #[test]
654    fn leading_word_match_beats_a_glued_substring_match() {
655        let results = search("fire", all());
656        let pos = |name: &str| results.iter().position(|e| e.name == name).unwrap();
657        // "fire engine" / "fire extinguisher" (leading word) must come
658        // before "firefighter" / "firecracker" / "fireworks" (glued
659        // substring, not a whole word).
660        let engine = pos("fire engine");
661        let firefighter = pos("firefighter");
662        let firecracker = pos("firecracker");
663        let fireworks = pos("fireworks");
664        assert!(engine < firefighter);
665        assert!(engine < firecracker);
666        assert!(engine < fireworks);
667    }
668
669    #[test]
670    fn a_whole_word_match_after_the_first_word_beats_a_glued_substring_match() {
671        // score() is the unit the tiers are actually decided in, so
672        // assert the boundary directly rather than hunting for a real
673        // pair of table entries that happens to exercise it: "face" is
674        // a later whole word in "smiling face with heart-eyes" (Word
675        // tier), and merely a glued substring of "boldface" (Substring
676        // tier, if such a name existed) — Word must outrank Substring.
677        assert_eq!(
678            score("smiling face with heart-eyes", "face"),
679            Some(MatchTier::Word)
680        );
681        assert_eq!(score("boldface", "face"), Some(MatchTier::Substring));
682        assert!(MatchTier::Word < MatchTier::Substring);
683    }
684
685    #[test]
686    fn case_and_leading_or_trailing_whitespace_do_not_affect_matching() {
687        let a = search("Fire", all());
688        let b = search("  fire  ", all());
689        let c = search("FIRE", all());
690        assert_eq!(
691            a.iter().map(|e| e.name).collect::<Vec<_>>(),
692            b.iter().map(|e| e.name).collect::<Vec<_>>()
693        );
694        assert_eq!(
695            a.iter().map(|e| e.name).collect::<Vec<_>>(),
696            c.iter().map(|e| e.name).collect::<Vec<_>>()
697        );
698    }
699
700    #[test]
701    fn internal_whitespace_runs_are_collapsed_before_matching() {
702        let normal = search("fire engine", all());
703        let extra_spaces = search("fire    engine", all());
704        assert_eq!(
705            normal.iter().map(|e| e.name).collect::<Vec<_>>(),
706            extra_spaces.iter().map(|e| e.name).collect::<Vec<_>>()
707        );
708        assert!(normal.iter().any(|e| e.name == "fire engine"));
709    }
710
711    #[test]
712    fn empty_query_returns_everything_in_cldr_order() {
713        let results = search("", all());
714        assert_eq!(results.len(), all().len());
715        assert_eq!(
716            results.iter().map(|e| e.name).collect::<Vec<_>>(),
717            all().iter().map(|e| e.name).collect::<Vec<_>>()
718        );
719    }
720
721    #[test]
722    fn whitespace_only_query_also_returns_everything() {
723        let results = search("   ", all());
724        assert_eq!(results.len(), all().len());
725    }
726
727    #[test]
728    fn a_query_matching_nothing_returns_an_empty_vec() {
729        let results = search("this is definitely not an emoji name", all());
730        assert!(results.is_empty());
731    }
732
733    #[test]
734    fn substring_match_still_finds_a_glued_word() {
735        let results = search("cracker", all());
736        assert!(results.iter().any(|e| e.name == "firecracker"));
737    }
738
739    #[test]
740    fn search_over_an_empty_table_returns_nothing_and_does_not_panic() {
741        assert!(search("fire", &[]).is_empty());
742        assert_eq!(search("", &[]).len(), 0);
743    }
744}