country-emoji

Crates.iocountry-emoji
lib.rscountry-emoji
version0.3.2
created_at2020-10-26 07:35:11.736708+00
updated_at2025-09-21 20:36:53.019695+00
descriptionConverts between country names, ISO 3166-1 codes and flag emojis.
homepage
repositoryhttps://github.com/leodutra/country-emoji
max_upload_size
id305514
size91,117
Leo Dutra (leodutra)

documentation

README

country-emoji

crate.io docs.rs

A lightweight, fast Rust library that converts between country names, ISO 3166-1 codes and flag emojis. Features intelligent fuzzy matching, normalization, and comprehensive country data.

Features

  • โšก Fast lookups - Optimized for performance with pre-compiled regex patterns
  • ๐Ÿง  Fuzzy matching - Handles alternative names, government titles, and formatting variations
  • ๐ŸŒ Comprehensive data - All ISO 3166-1 countries including recent additions
  • โœจ Normalization - Handles diacritics, case-insensitivity, whitespace, and abbreviations
  • ๐Ÿ”„ Bidirectional conversion - Convert between any combination of codes, names, and flag emojis
  • ๐Ÿš€ Zero-copy - Returns string slices where possible for optimal memory usage

Usage

Basic Operations

use country_emoji::{flag, code, name};

// Generate flag emoji from country code
assert_eq!(flag("US"), Some("๐Ÿ‡บ๐Ÿ‡ธ".to_string()));  // โ†’ ๐Ÿ‡บ๐Ÿ‡ธ

// Extract country code from flag emoji  
assert_eq!(code("๐Ÿ‡จ๐Ÿ‡ฆ"), Some("CA"));               // โ†’ "CA"

// Get country name from code
assert_eq!(name("DE"), Some("Germany"));           // โ†’ "Germany"

// Convert country name to code  
assert_eq!(code("Japan"), Some("JP"));             // โ†’ "JP"
```### Advanced Fuzzy Matching

The library handles many name variations and formats intelligently:

```rust
use country_emoji::code;

// Alternative names and abbreviations
assert_eq!(code("UK"), Some("GB"));           // โ†’ ๐Ÿ‡ฌ๐Ÿ‡ง
assert_eq!(code("UAE"), Some("AE"));          // โ†’ ๐Ÿ‡ฆ๐Ÿ‡ช  
assert_eq!(code("Russia"), Some("RU"));       // โ†’ ๐Ÿ‡ท๐Ÿ‡บ

// Government titles and formal names
assert_eq!(code("Republic of Moldova"), Some("MD"));                        // โ†’ ๐Ÿ‡ฒ๐Ÿ‡ฉ
assert_eq!(code("Democratic People's Republic of Korea"), Some("KP"));      // โ†’ ๐Ÿ‡ฐ๐Ÿ‡ต
assert_eq!(code("United States of America"), Some("US"));                   // โ†’ ๐Ÿ‡บ๐Ÿ‡ธ

// Comma-reversed formats
assert_eq!(code("Virgin Islands, British"), Some("VG"));    // โ†’ ๐Ÿ‡ป๐Ÿ‡ฌ
assert_eq!(code("Korea, Republic of"), Some("KR"));         // โ†’ ๐Ÿ‡ฐ๐Ÿ‡ท

// Saint/St. normalization  
assert_eq!(code("Saint Lucia"), Some("LC"));   // โ†’ ๐Ÿ‡ฑ๐Ÿ‡จ
assert_eq!(code("St. Lucia"), Some("LC"));     
assert_eq!(code("St Lucia"), Some("LC"));      

// And/ampersand equivalence
assert_eq!(code("Bosnia and Herzegovina"), Some("BA"));     // โ†’ ๐Ÿ‡ง๐Ÿ‡ฆ
assert_eq!(code("Bosnia & Herzegovina"), Some("BA"));       

// Diacritic handling
assert_eq!(code("Cote d'Ivoire"), Some("CI"));    // โ†’ ๐Ÿ‡จ๐Ÿ‡ฎ
assert_eq!(code("Cรดte d'Ivoire"), Some("CI"));    

// Partial matching for unique names
assert_eq!(code("Vatican"), Some("VA"));          // โ†’ ๐Ÿ‡ป๐Ÿ‡ฆ

Direct API Functions

For explicit conversions, use the direct API:

use country_emoji::{code_to_flag, flag_to_code, name_to_code, code_to_name, is_code, is_country_flag};

assert_eq!(code_to_flag("FR"), Some("๐Ÿ‡ซ๐Ÿ‡ท".to_string()));   // โ†’ ๐Ÿ‡ซ๐Ÿ‡ท
assert_eq!(flag_to_code("๐Ÿ‡ฎ๐Ÿ‡น"), Some("IT"));                // โ†’ "IT"
assert_eq!(name_to_code("Spain"), Some("ES"));              // โ†’ "ES"
assert_eq!(code_to_name("BR"), Some("Brazil"));             // โ†’ "Brazil"

assert!(is_code(Some("CA")));          // โœ… Valid
assert!(is_country_flag("๐Ÿ‡ฏ๐Ÿ‡ต"));       // โœ… Valid

Error Handling

The library returns None for invalid or ambiguous inputs:

use country_emoji::code;

// Invalid inputs
assert_eq!(code("ZZ"), None);           // โŒ Invalid
assert_eq!(code("Atlantis"), None);     // โŒ Non-existent

// Ambiguous inputs (prevents false matches)
assert_eq!(code("Korea"), None);        // โ“ Ambiguous (๐Ÿ‡ฐ๐Ÿ‡ต or ๐Ÿ‡ฐ๐Ÿ‡ท?)
assert_eq!(code("United"), None);       // โ“ Too vague

Performance

This library is optimized for high performance:

  • Pre-compiled regex patterns for fast text normalization
  • Cached normalized data to avoid repeated processing
  • Early exit strategies in matching algorithms
  • Benchmarked - Run cargo bench to see performance metrics

Typical performance (release build):

  • Exact matches: ~40ฮผs for 10 lookups
  • Fuzzy matches: ~800ฮผs for 10 complex queries
  • Flag operations: ~500ns per conversion

Country Data

The library includes comprehensive country data:

  • All 249 ISO 3166-1 assigned codes
  • Current country names (e.g., "North Macedonia", "Eswatini")
  • Alternative names and historical names
  • Common abbreviations (UK, UAE, USA, etc.)
  • Territories and dependencies (Puerto Rico, Guam, etc.)
  • Recent additions (South Sudan, Curaรงao, Sint Maarten)

Installation

Add this to your Cargo.toml:

[dependencies]
country-emoji = "0.3"

Related Libraries

Don't need Rust? Check out these alternatives:

Contributing & Feedback

Credits

This library builds upon excellent prior work:

License

MIT @ Leo Dutra

Commit count: 43

cargo fmt