Crate twemoji_assets

source ·
Expand description

A sophisticated crate that provides the assets from Twemoji.

Twemoji used to be an open-source project by Twitter that provided Recommended for General Interchange (RGI) emoji images in both SVG and PNG formats. Since the acquisition of Twitter by Elon Musk, the project has moved to its original creators (source). This crate makes it easy to use these assets in Rust projects.

The PNGs are embedded using the include_bytes macro and the SVGs are embedded using the include_str macro. Assets can be accessed either by their Unicode representation in the svg::codes and png::codes modules or by their human-readable names from Emojibase in the svg::names and png::names modules. The from_emoji and from_name methods in the SvgTwemojiAsset and PngTwemojiAsset modules provide convenient ways to select the correct asset at runtime, and the crate’s macros allow the selection of the right emojis at compile time.

§Feature Flags

For a better documentation experience, it is recommended to use the search feature. Additionally, you can locally generate documentation and select the appropriate features to declutter the search results and improve results found by IntelliSense. This crate uses three feature flags: svg, png, and names. The svg and png flags include the respective file formats, while the names flag includes the modules with human-readable names provided by Emojibase. By default, the svg and names flags are selected.

§Example

Here’s a simple example that shows how to use this crate to retrieve the SVG and PNG assets for the 🦆 (duck) emoji:

use twemoji_assets::svg::SvgTwemojiAsset;

let svg_asset: &SvgTwemojiAsset = SvgTwemojiAsset::from_emoji("🦆").unwrap();
let svg_data: &str = &svg_asset;
println!("SVG data for 🦆: {:?}", svg_data);

#[cfg(feature = "png")]
{
    use twemoji_assets::png::PngTwemojiAsset;

    let png_asset: &PngTwemojiAsset = PngTwemojiAsset::from_emoji("🦆").unwrap();
    let png_data: &[u8] = &png_asset;
    println!("PNG data for 🦆: {:?}", png_data);
}

§Usage

This crate does not provide any direct methods for utilizing the Twemoji assets. The following additional crates may be necessary to take full advantage of these emoji graphics:

  • image for PNG image manipulation
  • resvg for SVG rendering
  • unicode-segmentation for splitting words into Unicode graphemes
  • emoji for working with emojis, which can later be converted to Twemoji assets

§Version Scheme

This crate follows the semantic versioning scheme as required by the Rust documentation. The version number is represented as x.y.z+a.b.c, where x.y.z is the version of the crate and a.b.c is the version of the integrated Twemoji assets. The + symbol is used to separate the two version numbers. The version of the crate may increase without a corresponding increase in the version of the integrated Twemoji assets, however, whenever the Twemoji assets are updated and new assets are added, the crate version will at least increase in the minor value (y).

§Licensing

The codebase and names provided by Emojibase for this crate are licensed under the MIT License and the included graphics are licensed by Twitter (Copyright 2020 Twitter, Inc and other contributors) under the Creative Commons Attribution 4.0 International (CC-BY 4.0) license. Proper attribution must be given to Twitter and other contributors if these graphics are used or modified.

§Comparison to twemoji-rs

Another crate with similar goals to this crate is twemoji-rs. It also provides the assets from Twemoji and makes them easily available, but instead of directly including them, it finds the paths for the particular graphic.

Pros:

  • Assets may be lazy loaded.
  • Simpler API than this crate.

Cons:

  • Deployment is not possible on a device the application is not built on, as the paths are absolute from the directory the app was built in.
  • Assets are not part of the built binary, making deployment even more challenging.
  • twemoji-rs only supports PNG.
  • twemoji-rs has no overview of all available Twemojis.

Modules§

  • png
    PNG Twemoji assets.
  • svg
    SVG Twemoji assets.

Macros§

Structs§