namba 0.1.0

A fast, lightweight library for parsing, validating, and formatting phone numbers
Documentation
use core::fmt;
use std::borrow::Cow;

use crate::{
    PhoneNumber, Region,
    plans::{self, FormatRule, Plan},
};

/// A phone number output format.
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
pub enum Format {
    /// Compact global form, such as `+442079460018`.
    #[default]
    E164,
    /// Human-readable international form.
    International,
    /// Region-specific national form.
    National,
    /// Global telephone URI form from RFC 3966.
    Rfc3966,
}

/// A lazily formatted phone number.
#[derive(Clone, Copy, Debug)]
pub struct Formatted<'a> {
    number: &'a PhoneNumber,
    format: Format,
}

impl<'a> Formatted<'a> {
    pub(crate) const fn new(number: &'a PhoneNumber, format: Format) -> Self {
        Self { number, format }
    }
}

impl fmt::Display for Formatted<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write_number(f, self.number, self.format)
    }
}

/// Policy used to produce a dial string.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct DialOptions<'a> {
    /// Region from which the call originates.
    origin: Region,
    /// Optional domestic carrier code with ASCII decimal digits.
    carrier_code: Option<&'a str>,
}

impl DialOptions<'_> {
    /// Creates a dialing policy for `origin`.
    pub const fn new(origin: Region) -> Self {
        Self {
            origin,
            carrier_code: None,
        }
    }
}

impl<'a> DialOptions<'a> {
    /// Sets the domestic carrier code.
    pub const fn with_carrier_code(self, carrier_code: &'a str) -> Self {
        Self {
            carrier_code: Some(carrier_code),
            ..self
        }
    }
}

impl PhoneNumber {
    /// Produces a dial string for an origin.
    ///
    /// Domestic calls use national formatting. Other calls use international
    /// formatting. Namba applies a carrier code only when the plan defines a
    /// carrier rule. Namba ignores empty or non-decimal carrier codes.
    pub fn dial(&self, options: DialOptions<'_>) -> String {
        let same_calling_code =
            plans::calling_code(options.origin.as_str()) == Some(self.calling_code().value());
        if same_calling_code
            && let Some(carrier) = options
                .carrier_code
                .filter(|code| !code.is_empty() && code.chars().all(|c| c.is_ascii_digit()))
        {
            return national_with_carrier(self, carrier);
        }
        if same_calling_code {
            return self.format(Format::National).to_string();
        }
        let international = self.format(Format::International).to_string();
        let Some(origin) = plans::by_region(options.origin.as_str()) else {
            return international;
        };
        let prefix = if !origin.preferred_international_prefix.is_empty() {
            &origin.preferred_international_prefix
        } else {
            &origin.international_prefix_pattern
        };
        if prefix.chars().all(|character| character.is_ascii_digit()) {
            format!("{prefix} {}", international.trim_start_matches('+'))
        } else {
            international
        }
    }
}

fn write_number(
    output: &mut fmt::Formatter<'_>,
    number: &PhoneNumber,
    format: Format,
) -> fmt::Result {
    if format == Format::E164 {
        return write!(output, "+{}{}", number.calling_code, number.national);
    }
    let plan = crate::assessment::resolve(number);
    let formatted = plan.map_or_else(
        || number.national.to_string(),
        |plan| format_national_digits(plan, &number.national, format, None),
    );
    match format {
        Format::E164 => unreachable!("handled above"),
        Format::National => output.write_str(&formatted)?,
        Format::International => write!(output, "+{} {formatted}", number.calling_code)?,
        Format::Rfc3966 => {
            write!(output, "tel:+{}", number.calling_code)?;
            for group in formatted
                .split(|character: char| !character.is_ascii_alphanumeric())
                .filter(|group| !group.is_empty())
            {
                write!(output, "-{group}")?;
            }
        }
    }
    write_extension(output, number, format, plan)
}

fn write_extension(
    output: &mut fmt::Formatter<'_>,
    number: &PhoneNumber,
    format: Format,
    plan: Option<&'static Plan>,
) -> fmt::Result {
    if let Some(extension) = &number.extension {
        if format == Format::Rfc3966 {
            output.write_str(";ext=")?;
        } else {
            output.write_str(
                plan.map(|plan| plan.preferred_extension_prefix.as_str())
                    .filter(|prefix| !prefix.is_empty())
                    .unwrap_or(" ext. "),
            )?;
        }
        output.write_str(extension.as_str())?;
    }
    Ok(())
}

fn national_with_carrier(number: &PhoneNumber, carrier: &str) -> String {
    let Some(plan) = crate::assessment::resolve(number) else {
        return number.national.to_string();
    };
    format_national_digits(plan, &number.national, Format::National, Some(carrier))
}

fn format_national_digits(
    plan: &'static Plan,
    national: &str,
    format: Format,
    carrier: Option<&str>,
) -> String {
    let formats = if format == Format::National || plan.international_formats.is_empty() {
        &plan.formats
    } else {
        &plan.international_formats
    };
    let Some(rule) = choose_rule(formats, national) else {
        return national.to_owned();
    };
    let Some(expression) = crate::pattern::full_expression(&rule.pattern) else {
        return national.to_owned();
    };
    let template = if format == Format::National {
        let prefix = if carrier.is_some() && !rule.carrier_code_template.is_empty() {
            &rule.carrier_code_template
        } else {
            &rule.national_prefix_template
        };
        if !prefix.is_empty() {
            let prefix = prefix
                .replace("$NP", &plan.national_prefix)
                .replace("$FG", "$1")
                .replace("$CC", carrier.unwrap_or_default());
            Cow::Owned(rule.template.replacen("$1", &prefix, 1))
        } else {
            Cow::Borrowed(rule.template.as_str())
        }
    } else {
        Cow::Borrowed(rule.template.as_str())
    };
    expression.replace(national, template.as_ref()).into_owned()
}

fn choose_rule(rules: &'static [FormatRule], national: &str) -> Option<&'static FormatRule> {
    rules.iter().find(|rule| {
        rule.leading_digits
            .last()
            .is_none_or(|pattern| crate::pattern::prefix_match(pattern, national))
            && crate::pattern::full_match(&rule.pattern, national)
    })
}