Expand description
CLDR-ordered emoji data and a pure search function, for building an emoji picker on top.
Follows the same split the D-Bus-backed modules in this workspace use
(see CLAUDE.md, “The shape a D-Bus-backed module takes”): even
though there is no D-Bus here, the same rule applies — the model is
plain data, and the decisions are pure functions over it. Emoji
is a flat struct, all and groups hand back slices, and
search is a pure function from a query and a table to a ranked
Vec. Nothing in this crate touches the filesystem, a network, a
runtime, or Hyprland — a picker UI is built on this, not the other
way round. The long-press interaction that would let a person pick a
tone, and where their chosen default tone is stored, are both that
picker’s job, not this crate’s — this crate only makes both easy: see
Emoji::tone and Emoji::tone_variants.
§Where the data comes from
data/emoji-test.txt
is a verbatim copy of Unicode’s emoji-test.txt (UTS #51 test data,
Unicode 17.0), which the file itself describes as being “in CLDR
order… recommended (but not required) for keyboard palettes.” That
is the order all and search’s tie-breaking preserve: it is
not sorted alphabetically or by codepoint, because CLDR order is what
makes a picker’s default view look intentional rather than random.
src/generated.rs
is generated from that file and committed alongside it — see
src/bin/generate.rs for the generator, exactly how it derives the
table below, and how to re-run it. Nothing in this crate reads
data/emoji-test.txt at build time or runtime; only the generator
does, and only when a human runs it deliberately.
§What made it into the table
The source file marks every entry component, fully-qualified,
minimally-qualified, or unqualified. Only fully-qualified
entries are considered at all:
minimally-qualifiedandunqualifiedare the same emoji as afully-qualifiedentry elsewhere in the file, just missing a variation selector (see UTS #51 ED-18a/ED-19). Keeping them would put visual duplicates of the same character in the table under the same name.componententries (9 of them: the five Fitzpatrick skin-tone modifiers and four hair-style modifiers) are modifier codepoints, not standalone emoji a person picks from a grid. Excluding them also happens to empty out the file’s “Component” group entirely — seegroupsfor why that group is still listed.
§The skin-tone relationship
The fully-qualified set is 3944 entries, and 2030 of those are tone
variants: the same gesture or person repeated once per Fitzpatrick
modifier (U+1F3FB..=U+1F3FF), sometimes twice per entry for
two-person sequences like a handshake. This crate does not
flatten those away, and does not synthesise a base character by
appending a modifier codepoint at the call site either — that is
wrong in general, because a ZWJ sequence can carry an independent
tone on each human component, and where the modifier belongs in the
sequence is not something to guess. Instead, Emoji models the
relationship, derived entirely from grouping what
data/emoji-test.txt actually contains:
- The grid (
all) holds one entry per emoji concept, in CLDR order, exactly as before. Emoji::supports_tonessays whether that concept has tone variants, andEmoji::tone/Emoji::tone_variantshand back the real, already-qualified character for eachTone— never a sequence built by this crate.- Two-person sequences (19 families: “handshake” via the newer
directional-hands ZWJ combo, “people holding hands”, “kiss: woman,
man”, and similar) are not modeled as tone-capable, because one
Tonecannot pick between two independent people’s tones. Where such a family has a neutral, toneless form (7 of the 19 — e.g. “kiss: woman, man” itself), that form is kept in the grid withsupports_tones() == false. Where it does not (12 of the 19 — e.g. the two-person “people wrestling” ZWJ combo, as opposed to the older single-glyph 🤼 pictograph, which does get tones — see below), the family is dropped from the grid entirely rather than picking one arbitrary two-tone combination to stand in for a concept Unicode never gave a neutral rendering. - A handful of single-person symbols (e.g. “index pointing up”,
“hand with fingers splayed”) need a variation selector
(
U+FE0F) to render as an emoji when shown alone, but Unicode omits that selector from the toned sequences for the very same emoji, since the tone modifier already forces emoji presentation. Naively, that makes the neutral and toned forms hash to different “family keys” and look like unrelated entries; the generator stripsU+FE0Fbefore grouping so they merge correctly. As of Unicode 17.0, every single-person tone family turns out to have a genuine neutral form once this is accounted for — none currently need a same-tone-as-canonical stand-in — but the generator still has a documented fallback (themedium skin tonemember, itself a real, already-qualified emoji, never a synthesised one) for the day a future Unicode release adds a tone-only family, so that case fails loudly rather than silently if it does.
After all of this, all returns 1914 entries, of which 323
support tones. EMOJI_COUNT and tone_capable_count are both
asserted against the generated table’s own contents in this crate’s
tests, so this doc comment cannot silently drift from the data.
§Search
search ranks by how good a name match is, not by table order:
exact name match, then a whole leading word, then a whole word
anywhere else in the name, then any other substring. Ties within a
tier keep CLDR order. Because the table already holds one row per
concept rather than one per tone, searching by name naturally finds
that one row — there is nothing tone-specific for search to filter,
since a query like “wave” is answered by “waving hand” once, not five
times. See search’s doc comment for the full ranking rule.
Structs§
- Emoji
- One emoji: its character(s), its name, where it sits in the Unicode CLDR grouping, and — if it has any — its skin-tone variants.
Enums§
- Tone
- A skin tone a tone-capable
Emojican be shown at, per the five Fitzpatrick modifiers UTS #51 defines (U+1F3FB..=U+1F3FF).
Constants§
- EMOJI_
COUNT - The number of emoji
allreturns: one row per concept, tone families collapsed per the crate doc comment’s rules. Asserted against the generated table’s actual length inentry_count_matches_the_number_this_crate_documents. - TONES
- All five tones, in the same order
Emoji::tone_variantsreturns them and the generated table stores them.
Functions§
- all
- Every emoji this crate knows about, in CLDR order (the order the source file itself recommends for keyboard palettes). See the crate doc comment for what is and is not included, and how tone variants are represented.
- groups
- The ten Unicode CLDR groups, in the file’s own order — e.g. for a picker’s tabs or section headers.
- search
- Search
tableforquery, returning matches best-first. - tone_
capable_ count - How many of
all’s entries support tones, i.e.all().iter().filter(Emoji::supports_tones).count()— computed here too soentry_count_matches_the_number_this_crate_documentscan pin both numbers the doc comment states without walking the table twice at doc-comment-writing time and hoping they stay in sync by hand.