namba 0.1.0

A fast, lightweight library for parsing, validating, and formatting phone numbers
Documentation
use crate::{
    DATA_VERSION, PhoneNumber, Region,
    plans::{self, Plan},
};

/// A phone number's length classification.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum Possibility {
    /// The number has a plausible length.
    Possible,
    /// The number is only plausible for local dialing.
    LocalOnly,
    /// The number is shorter than the bundled numbering plans allow.
    TooShort,
    /// The number is longer than the bundled numbering plans allow.
    TooLong,
    /// The length falls into a numbering plan gap.
    InvalidLength,
    /// The bundled numbering plans cannot classify the length.
    Unknown,
}

/// A phone number's service category.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum NumberKind {
    /// A geographic fixed-line number.
    FixedLine,
    /// A mobile number.
    Mobile,
    /// A number that can be a fixed line or a mobile line.
    FixedLineOrMobile,
    /// A toll-free service.
    TollFree,
    /// A premium-rate service.
    PremiumRate,
    /// A shared-cost service.
    SharedCost,
    /// A personal routing number.
    Personal,
    /// A voice-over-IP service.
    Voip,
    /// A paging service.
    Pager,
    /// A universal access number.
    UniversalAccess,
    /// A voicemail access number.
    Voicemail,
    /// No service category matched.
    Unknown,
}

/// An assessment of a parsed number against the bundled numbering plans.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Assessment {
    possibility: Possibility,
    kind: NumberKind,
    regions: &'static [Region],
    internationally_dialable: bool,
}

impl Assessment {
    pub(crate) fn new(number: &PhoneNumber) -> Self {
        let plan = resolve(number);
        let kind = plan.map_or(NumberKind::Unknown, |plan| classify(plan, &number.national));
        let possibility = plan.map_or(Possibility::Unknown, |plan| {
            possibility_for(plan, &number.national)
        });
        let internationally_dialable =
            plan.is_none_or(|plan| !plan.no_international_dialing.matches(&number.national));
        let regions = plans::regions(number.calling_code().value());
        Self {
            possibility,
            kind,
            regions,
            internationally_dialable,
        }
    }

    /// Returns the length-based possibility result.
    pub const fn possibility(&self) -> Possibility {
        self.possibility
    }

    /// Returns whether the number matches a valid numbering pattern.
    /// Validity does not prove assignment or reachability.
    pub const fn is_valid(&self) -> bool {
        !matches!(self.kind, NumberKind::Unknown)
    }

    /// Returns the inferred service category.
    pub const fn kind(&self) -> NumberKind {
        self.kind
    }

    /// Returns every region sharing the calling code, primary region first.
    pub fn regions(&self) -> &[Region] {
        self.regions
    }

    /// Returns whether the numbering plan permits international dialing.
    pub const fn is_internationally_dialable(&self) -> bool {
        self.internationally_dialable
    }

    /// Returns the bundled numbering-data version used for this assessment.
    pub const fn data_version(&self) -> &'static str {
        DATA_VERSION
    }
}

pub(crate) fn is_valid(number: &PhoneNumber) -> bool {
    resolve(number).is_some_and(|plan| classify(plan, &number.national) != NumberKind::Unknown)
}

pub(crate) fn is_valid_for(number: &PhoneNumber, region: Region) -> bool {
    plans::by_region(region.as_str()).is_some_and(|plan| {
        plan.calling_code == number.calling_code
            && classify(plan, &number.national) != NumberKind::Unknown
    })
}

pub(crate) fn possibility(number: &PhoneNumber) -> Possibility {
    resolve(number).map_or(Possibility::Unknown, |plan| {
        possibility_for(plan, &number.national)
    })
}

pub(crate) fn resolve(number: &PhoneNumber) -> Option<&'static Plan> {
    let mut candidates = plans::by_calling_code(number.calling_code);
    let mut remaining = candidates.clone();
    let first = remaining.next()?;
    if remaining.next().is_none() {
        return Some(first);
    }

    candidates
        .clone()
        .find(|plan| {
            !plan.leading_digits.is_empty()
                && crate::pattern::prefix_match(&plan.leading_digits, &number.national)
        })
        .or_else(|| candidates.find(|plan| classify(plan, &number.national) != NumberKind::Unknown))
        .or(Some(first))
}

pub(crate) fn possibility_for(plan: &Plan, national: &str) -> Possibility {
    let length = national.len();
    if plan.general.contains_length(length) {
        return Possibility::Possible;
    }
    if plan.general.contains_local_length(length) {
        return Possibility::LocalOnly;
    }
    let Some((&shortest, &longest)) = plan
        .general
        .possible_lengths
        .first()
        .zip(plan.general.possible_lengths.last())
    else {
        return Possibility::Unknown;
    };
    match length {
        length if length < usize::from(shortest) => Possibility::TooShort,
        length if length > usize::from(longest) => Possibility::TooLong,
        _ => Possibility::InvalidLength,
    }
}

pub(crate) fn classify(plan: &'static Plan, national: &str) -> NumberKind {
    if !plan.general.matches(national) {
        return NumberKind::Unknown;
    }
    for (rule, kind) in [
        (&plan.premium_rate, NumberKind::PremiumRate),
        (&plan.toll_free, NumberKind::TollFree),
        (&plan.shared_cost, NumberKind::SharedCost),
        (&plan.voip, NumberKind::Voip),
        (&plan.personal, NumberKind::Personal),
        (&plan.pager, NumberKind::Pager),
        (&plan.universal_access, NumberKind::UniversalAccess),
        (&plan.voicemail, NumberKind::Voicemail),
    ] {
        if rule.matches(national) {
            return kind;
        }
    }

    match (
        plan.fixed_line.matches(national),
        plan.mobile.matches(national),
    ) {
        (true, true) => NumberKind::FixedLineOrMobile,
        (true, false) => NumberKind::FixedLine,
        (false, true) => NumberKind::Mobile,
        (false, false) => NumberKind::Unknown,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Format;

    #[test]
    fn every_plan_example_validates_and_round_trips() {
        let mut examples = 0;
        for plan in plans::all() {
            for rule in [
                &plan.fixed_line,
                &plan.mobile,
                &plan.toll_free,
                &plan.premium_rate,
                &plan.shared_cost,
                &plan.personal,
                &plan.voip,
                &plan.pager,
                &plan.universal_access,
                &plan.voicemail,
            ] {
                if rule.example.is_empty() {
                    continue;
                }
                examples += 1;
                assert!(
                    rule.matches(&rule.example),
                    "{} example {} does not match its rule",
                    plan.region,
                    rule.example
                );
                let number = PhoneNumber {
                    calling_code: plan.calling_code,
                    national: rule.example.clone().into_boxed_str(),
                    extension: None,
                };
                assert!(
                    matches!(
                        possibility(&number),
                        Possibility::Possible | Possibility::LocalOnly
                    ),
                    "{} example {} has an impossible length",
                    plan.region,
                    rule.example
                );
                if plan.region != "001" {
                    let region = Region::try_from(plan.region.as_str()).expect("plan region");
                    assert!(
                        is_valid_for(&number, region),
                        "{} example {} is invalid",
                        plan.region,
                        rule.example
                    );
                }
                let e164 = number.format(Format::E164).to_string();
                assert_eq!(
                    crate::parse_strict(&e164).expect("E.164 round trip"),
                    number
                );
                for format in [Format::International, Format::Rfc3966] {
                    let formatted = number.format(format).to_string();
                    assert_eq!(
                        crate::parse(&formatted).expect("global format round trip"),
                        number,
                        "{} example {} did not round trip from {format:?} {formatted}",
                        plan.region,
                        rule.example
                    );
                }
                if plan.region != "001" {
                    let region = Region::try_from(plan.region.as_str()).expect("plan region");
                    let national = number.format(Format::National).to_string();
                    let reparsed =
                        crate::parse_in(region, &national).expect("national format round trip");
                    assert_eq!(
                        reparsed.national_number(),
                        number.national_number(),
                        "{} example {} became {} from national format {national}",
                        plan.region,
                        rule.example,
                        reparsed.national_number()
                    );
                    assert_eq!(reparsed.calling_code(), number.calling_code());
                }
            }
        }
        assert!(examples >= 900, "unexpectedly few examples: {examples}");
    }

    #[test]
    fn every_short_plan_example_matches_its_rule() {
        let mut examples = 0;
        for plan in plans::all_short() {
            for rule in [
                &plan.short_code,
                &plan.emergency,
                &plan.carrier_specific,
                &plan.sms_services,
            ] {
                if !rule.example.is_empty() {
                    examples += 1;
                    assert!(
                        rule.matches(&rule.example),
                        "{} short example {} does not match",
                        plan.region,
                        rule.example
                    );
                }
            }
            let region = Region::try_from(plan.region.as_str()).expect("plan region");
            if !plan.short_code.example.is_empty() {
                let number = crate::ShortNumber::parse(region, &plan.short_code.example)
                    .expect("short number example");
                assert!(number.is_possible(), "{} short example", plan.region);
                assert!(number.is_valid(), "{} short example", plan.region);
            }
            if !plan.emergency.example.is_empty() {
                let number = crate::ShortNumber::parse(region, &plan.emergency.example)
                    .expect("emergency example");
                assert_eq!(
                    number.emergency_match(),
                    crate::EmergencyMatch::Exact,
                    "{} emergency example",
                    plan.region
                );
            }
        }
        assert!(
            examples >= 400,
            "unexpectedly few short examples: {examples}"
        );
    }
}