ipflag 0.1.0

Human-friendly IP -> country flag display core (resolver-pluggable, no data bundled).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

use crate::CountryCode;
use core::fmt;

/// The display result for an IP address.
///
/// - `Country(code)`: resolver found a country
/// - `Private`: local/internal IP (never resolved)
/// - `Special`: loopback/multicast/documentation/etc. (never resolved)
/// - `Unknown`: public IP but resolver returned `None`
///
/// This is the primary type you render in UI/logs.
///
/// # Example
///
/// ```rust
/// use ipflag::{IpTag, CountryCode};
///
/// let tag = IpTag::Country(CountryCode::new("US").unwrap());
/// assert_eq!(tag.to_string(), "🇺🇸 US");
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum IpTag {
    /// Public IP successfully resolved to a country code.
    Country(CountryCode),

    /// Private/internal IP range (LAN).
    Private,

    /// Special non-public ranges.
    Special,

    /// Public IP with no country match.
    Unknown,
}

/// Formatting presets for UI output.
///
/// - `FlagAndCode`: `"🇰🇷 KR"`
/// - `FlagOnly`: `"🇰🇷"`
/// - `CodeOnly`: `"KR"`
/// - `DefaultText`: fallback to [`core::fmt::Display`] output
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TagFormat {
    FlagAndCode,
    FlagOnly,
    CodeOnly,
    DefaultText,
}

impl IpTag {
    /// Returns a single emoji representing this tag.
    ///
    /// - Country → the country flag emoji
    /// - Private → 🏠
    /// - Special → ⚙️
    /// - Unknown → 🌐
    ///
    /// This is useful when you want a compact UI label.
    pub fn emoji(&self) -> String {
        match self {
            IpTag::Country(code) => code.flag().unwrap_or_else(|| "🌐".to_string()),
            IpTag::Private => "🏠".to_string(),
            IpTag::Special => "⚙️".to_string(),
            IpTag::Unknown => "🌐".to_string(),
        }
    }

    /// Format this tag using a preset [`TagFormat`].
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ipflag::{IpTag, TagFormat, CountryCode};
    ///
    /// let tag = IpTag::Country(CountryCode::new("KR").unwrap());
    /// assert_eq!(tag.format(TagFormat::FlagAndCode), "🇰🇷 KR");
    /// assert_eq!(tag.format(TagFormat::FlagOnly), "🇰🇷");
    /// assert_eq!(tag.format(TagFormat::CodeOnly), "KR");
    /// ```
    pub fn format(&self, fmt: TagFormat) -> String {
        match (self, fmt) {
            (IpTag::Country(code), TagFormat::FlagAndCode) => {
                let flag = code.flag().unwrap_or_else(|| "🌐".to_string());
                format!("{} {}", flag, code.to_string())
            }
            (IpTag::Country(code), TagFormat::FlagOnly) => {
                code.flag().unwrap_or_else(|| "🌐".to_string())
            }
            (IpTag::Country(code), TagFormat::CodeOnly) => code.to_string(),
            _ => self.to_string(),
        }
    }
}

impl fmt::Display for IpTag {
    /// Default display output for logs/UI.
    ///
    /// - Country → `"🇰🇷 KR"`
    /// - Private → `"🏠 PRIVATE"`
    /// - Special → `"⚙️ SPECIAL"`
    /// - Unknown → `"🌐 UNKNOWN"`
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            IpTag::Country(code) => {
                let flag = code.flag().unwrap_or_else(|| "🌐".to_string());
                write!(f, "{} {}", flag, code.to_string())
            }
            IpTag::Private => write!(f, "🏠 PRIVATE"),
            IpTag::Special => write!(f, "⚙️ SPECIAL"),
            IpTag::Unknown => write!(f, "🌐 UNKNOWN"),
        }
    }
}