emojis

✨ Lookup emoji in O(1) time, access metadata and GitHub shortcodes, iterate over all emoji.

Features

• Lookup up emoji by Unicode value
• Lookup up emoji by GitHub shortcode (gemoji v4.1.0)
• Access emoji metadata: name, unicode version, group, skin tone, gemoji shortcodes
• Iterate over emojis in Unicode CLDR order
• Iterate over emojis in an emoji group, e.g. “Smileys & Emotion” or “Flags”
• Iterate over the skin tones for an emoji
• Select a specific skin tone for an emoji
• Uses Unicode v17.0 emoji specification

Getting started

First, add the emojis crate to your Cargo manifest.

cargo add emojis

Simply use the get() function to lookup emojis by Unicode value.

let rocket = emojis::get("🚀").unwrap();

Or the get_by_shortcode() function to lookup emojis by gemoji shortcode.

let rocket = emojis::get_by_shortcode("rocket").unwrap();

These operations take Ο(1) time.

MSRV

Currently the minimum supported Rust version is 1.66 due to the dependency on phf. The policy of this crate is to only increase the MSRV in a breaking release.

Breaking changes

When gemoji or the Unicode version is upgraded this is not considered a breaking change, instead you should make sure to use unicode_version() to filter out newer versions.

Examples

See examples/replace.rs for an example that replaces :gemoji: names with real emojis in text.

$ echo "launch :rocket:" | cargo run --example replace
launch 🚀

get() and get_by_shortcode() return an Emoji struct which contains various metadata regarding the emoji.

let hand = emojis::get("🤌").unwrap();
assert_eq!(hand.as_str(), "\u{1f90c}");
assert_eq!(hand.as_bytes(), &[0xf0, 0x9f, 0xa4, 0x8c]);
assert_eq!(hand.name(), "pinched fingers");
assert_eq!(hand.unicode_version(), emojis::UnicodeVersion::new(13, 0));
assert_eq!(hand.group(), emojis::Group::PeopleAndBody);
assert_eq!(hand.skin_tone(), Some(emojis::SkinTone::Default));
assert_eq!(hand.shortcode(), Some("pinched_fingers"));

Use skin_tones() to iterate over the skin tones of an emoji.

let raised_hands = emojis::get("🙌🏼").unwrap();
let skin_tones: Vec<_> = raised_hands.skin_tones().unwrap().map(|e| e.as_str()).collect();
assert_eq!(skin_tones, ["🙌", "🙌🏻", "🙌🏼", "🙌🏽", "🙌🏾", "🙌🏿"]);

You can use the iter() function to iterate over all emojis. This only includes the default skin tone versions.

let faces: Vec<_> = emojis::iter().map(|e| e.as_str()).take(5).collect();
assert_eq!(faces, ["😀", "😃", "😄", "😁", "😆"]);

It is recommended to filter the list by the maximum Unicode version that you wish to support.

let iter = emojis::iter().filter(|e| {
    e.unicode_version() < emojis::UnicodeVersion::new(13, 0)
});

Using the Group enum you can iterate over all emojis in a group.

let fruit: Vec<_> = emojis::Group::FoodAndDrink.emojis().map(|e| e.as_str()).take(5).collect();
assert_eq!(fruit, ["🍇", "🍈", "🍉", "🍊", "🍋"]);

Storing the Emoji type

If you want to store the Emoji type in a data structure, you should store it as static reference: &'static Emoji. This crate intentionally does not provide any constructors or implement Clone or Copy for Emoji. &'static Emoji supports serde serialization and deserialization, not Emoji.

For example:

#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
enum Example {
    Rocket {
        value: &'static emojis::Emoji
    },
}

Example::Rocket { value: emojis::get("🚀").unwrap() };

License

This project is licensed under (MIT OR Apache-2.0) AND Unicode-3.0.

All intellectual property within this crate that is not generated from Unicode data is dual-licensed under either the MIT License or the Apache License, Version 2.0, at your option.

This crate makes use of data derived from the Unicode Character Database and related Unicode sources. All generated files and data derived from Unicode, including but not limited to emoji names, ordering, group classifications, skin tone metadata, Unicode version metadata, and lookup tables in src/gen/, are additionally governed by the Unicode License, Version 3.0.

When using or redistributing generated files that incorporate Unicode data, you must comply with the terms of both the Unicode License and either the MIT or Apache-2.0 license.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual-licensed under the same terms, without additional conditions.

See LICENSE-APACHE, LICENSE-MIT, and LICENSE-UNICODE for full license texts.