namba 0.1.0

A fast, lightweight library for parsing, validating, and formatting phone numbers
Documentation
use crate::{Error, ErrorKind, PhoneNumber, Region, Result};

/// Bounds and policy for parsing untrusted input.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct ParseOptions {
    /// Maximum accepted UTF-8 input bytes.
    max_input_bytes: usize,
}

impl Default for ParseOptions {
    fn default() -> Self {
        Self::new()
    }
}

impl ParseOptions {
    /// Creates the default parsing policy.
    pub const fn new() -> Self {
        Self {
            max_input_bytes: 256,
        }
    }

    /// Sets the maximum accepted UTF-8 input bytes.
    pub const fn with_max_input_bytes(mut self, max_input_bytes: usize) -> Self {
        self.max_input_bytes = max_input_bytes;
        self
    }

    /// Returns the maximum accepted UTF-8 input bytes.
    pub const fn max_input_bytes(self) -> usize {
        self.max_input_bytes
    }
}

/// Parses an international number or RFC 3966 URI.
///
/// The default input limit is 256 UTF-8 bytes.
pub fn parse(input: &str) -> Result<PhoneNumber> {
    parse_with(None, input, ParseOptions::default())
}

/// Parses an international number with explicit input bounds.
pub fn parse_with_options(input: &str, options: ParseOptions) -> Result<PhoneNumber> {
    parse_with(None, input, options)
}

/// Parses a number, using `region` only when the input is not international.
///
/// The default input limit is 256 UTF-8 bytes.
pub fn parse_in(region: Region, input: &str) -> Result<PhoneNumber> {
    parse_with(Some(region), input, ParseOptions::default())
}

/// Parses a regional number with explicit input bounds.
pub fn parse_in_with_options(
    region: Region,
    input: &str,
    options: ParseOptions,
) -> Result<PhoneNumber> {
    parse_with(Some(region), input, options)
}

/// Parses only canonical E.164 or global RFC 3966 syntax.
pub fn parse_strict(input: &str) -> Result<PhoneNumber> {
    let number = parse(input)?;
    let e164 = number.format(crate::Format::E164).to_string();
    let rfc3966 = number.format(crate::Format::Rfc3966).to_string();
    if input == e164 || input == rfc3966 {
        Ok(number)
    } else {
        Err(Error::new(ErrorKind::NotCanonical))
    }
}

pub(crate) fn parse_with(
    region: Option<Region>,
    input: &str,
    options: ParseOptions,
) -> Result<PhoneNumber> {
    if input.len() > options.max_input_bytes {
        return Err(Error::new(ErrorKind::TooLong));
    }
    if input.trim().is_empty() {
        return Err(Error::new(ErrorKind::NotANumber));
    }
    let input = input.trim();
    let is_uri = input
        .get(..4)
        .is_some_and(|prefix| prefix.eq_ignore_ascii_case("tel:"));
    let (candidate, extension) = split_extension(input)?;
    let candidate = if is_uri {
        let candidate = &candidate[4..];
        if !candidate.starts_with('+') || candidate.contains(';') {
            return Err(Error::new(ErrorKind::NotANumber));
        }
        candidate
    } else {
        candidate
    };
    let digit_count = candidate
        .chars()
        .filter(|character| decimal_digit(*character).is_some())
        .count();
    if candidate.chars().any(|character| character.is_alphabetic()) && digit_count < 3 {
        return Err(Error::new(ErrorKind::NotANumber));
    }
    let normalized = normalize(candidate)?;
    if !normalized.bytes().any(|byte| byte.is_ascii_digit()) {
        return Err(Error::new(ErrorKind::NotANumber));
    }
    if region.is_none() && !normalized.starts_with('+') {
        return Err(Error::new(ErrorKind::MissingRegion));
    }
    let default_plan = region
        .map(|region| {
            crate::plans::by_region(region.as_str())
                .ok_or_else(|| Error::new(ErrorKind::UnsupportedRegion))
        })
        .transpose()?;
    let (calling_code, mut national) = identify(&normalized, default_plan)?;
    let plan = default_plan
        .filter(|plan| plan.calling_code == calling_code)
        .or_else(|| crate::plans::primary(calling_code));
    if let Some(plan) = plan {
        let candidate = without_national_prefix(plan, &national);
        if candidate != national && prefix_result_is_usable(plan, &candidate) {
            national = candidate;
        }
    }
    if national.len() < 2 {
        return Err(Error::new(ErrorKind::TooShort));
    }
    if calling_code_digits(calling_code) + national.len() > 15 {
        return Err(Error::new(ErrorKind::TooLong));
    }
    Ok(PhoneNumber {
        calling_code,
        national: national.into_boxed_str(),
        extension: extension.map(crate::Extension::new),
    })
}

fn split_extension(input: &str) -> Result<(&str, Option<String>)> {
    let lower = input.to_ascii_lowercase();
    for marker in [";ext=", " ext.", " ext", " x", "#"] {
        if let Some(index) = lower.rfind(marker) {
            let suffix = input[index + marker.len()..].trim();
            if suffix.chars().any(|character| {
                decimal_digit(character).is_none() && !matches!(character, ' ' | '-')
            }) {
                return Err(Error::new(ErrorKind::NotANumber));
            }
            let extension: String = suffix
                .chars()
                .filter_map(decimal_digit)
                .map(|digit| char::from(b'0' + digit))
                .collect();
            if extension.is_empty() {
                return Err(Error::new(ErrorKind::NotANumber));
            }
            if extension.len() > 20 {
                return Err(Error::new(ErrorKind::TooLong));
            }
            return Ok((&input[..index], Some(extension)));
        }
    }
    Ok((input, None))
}

fn normalize(input: &str) -> Result<String> {
    let mut output = String::with_capacity(input.len());
    for character in input.chars() {
        if is_plus_sign(character) && output.is_empty() {
            output.push('+');
        } else if let Some(digit) = decimal_digit(character) {
            output.push(char::from(b'0' + digit));
        } else if character.is_ascii_alphabetic() {
            output.push(keypad(character));
        } else if !matches!(
            character,
            ' ' | '\t' | '\n' | '\r' | '-' | '.' | '(' | ')' | '/'
        ) {
            return Err(Error::new(ErrorKind::NotANumber));
        }
    }
    Ok(output)
}

pub(crate) fn decimal_digit(character: char) -> Option<u8> {
    const ZEROES: &[u32] = &[
        0x0030, 0x0660, 0x06f0, 0x07c0, 0x0966, 0x09e6, 0x0a66, 0x0ae6, 0x0b66, 0x0be6, 0x0c66,
        0x0ce6, 0x0d66, 0x0de6, 0x0e50, 0x0ed0, 0x0f20, 0x1040, 0x1090, 0x17e0, 0x1810, 0x1946,
        0x19d0, 0x1a80, 0x1a90, 0x1b50, 0x1bb0, 0x1c40, 0x1c50, 0xa620, 0xa8d0, 0xa900, 0xa9d0,
        0xa9f0, 0xaa50, 0xabf0, 0xff10, 0x104a0, 0x10d30, 0x11066, 0x110f0, 0x11136, 0x111d0,
        0x112f0, 0x11450, 0x114d0, 0x11650, 0x116c0, 0x11730, 0x118e0, 0x11950, 0x11c50, 0x11d50,
        0x11da0, 0x11f50, 0x16a60, 0x16ac0, 0x16b50, 0x1d7ce, 0x1d7d8, 0x1d7e2, 0x1d7ec, 0x1d7f6,
        0x1e140, 0x1e2f0, 0x1e4f0, 0x1e950,
    ];
    let value = character as u32;
    let index = ZEROES
        .partition_point(|zero| *zero <= value)
        .checked_sub(1)?;
    let digit = u8::try_from(value - ZEROES[index]).ok()?;
    (digit < 10).then_some(digit)
}

pub(crate) const fn is_plus_sign(character: char) -> bool {
    matches!(character, '+' | '\u{ff0b}')
}

const fn calling_code_digits(code: u16) -> usize {
    if code >= 100 {
        3
    } else if code >= 10 {
        2
    } else {
        1
    }
}

fn keypad(character: char) -> char {
    match character.to_ascii_uppercase() {
        'A'..='C' => '2',
        'D'..='F' => '3',
        'G'..='I' => '4',
        'J'..='L' => '5',
        'M'..='O' => '6',
        'P'..='S' => '7',
        'T'..='V' => '8',
        'W'..='Z' => '9',
        _ => unreachable!("ASCII alphabetic character"),
    }
}

fn identify(
    normalized: &str,
    default_plan: Option<&'static crate::plans::Plan>,
) -> Result<(u16, String)> {
    if let Some(digits) = normalized.strip_prefix('+') {
        return identify_global(digits).or_else(|_| {
            let digits = default_plan
                .and_then(|plan| strip_idd(plan, digits))
                .ok_or_else(|| Error::new(ErrorKind::UnsupportedCallingCode))?;
            identify_global(digits)
        });
    }

    let plan = default_plan.ok_or_else(|| Error::new(ErrorKind::MissingRegion))?;
    if let Some(digits) = strip_idd(plan, normalized) {
        return identify_global(digits);
    }

    Ok(regional_identity(plan, normalized))
}

fn identify_global(digits: &str) -> Result<(u16, String)> {
    extract_calling_code(digits).ok_or_else(|| Error::new(ErrorKind::UnsupportedCallingCode))
}

fn regional_identity(plan: &'static crate::plans::Plan, normalized: &str) -> (u16, String) {
    let code_length = calling_code_digits(plan.calling_code);
    let Some(prefix) = normalized.get(..code_length) else {
        return (plan.calling_code, normalized.to_owned());
    };
    if prefix.parse::<u16>().ok() != Some(plan.calling_code) {
        return (plan.calling_code, normalized.to_owned());
    }
    let remainder = &normalized[code_length..];
    let candidate = without_national_prefix(plan, remainder);
    let original_matches = plan.general.matches(normalized);
    let candidate_matches = plan.general.matches(&candidate);
    let original_is_too_long =
        crate::assessment::possibility_for(plan, normalized) == crate::Possibility::TooLong;

    if (!original_matches && candidate_matches) || original_is_too_long {
        (plan.calling_code, candidate)
    } else {
        (plan.calling_code, normalized.to_owned())
    }
}

fn extract_calling_code(digits: &str) -> Option<(u16, String)> {
    if digits.starts_with('0') {
        return None;
    }
    (1..=3).find_map(|length| {
        let prefix = digits.get(..length)?;
        let code = prefix.parse().ok()?;
        crate::plans::primary(code)?;
        Some((code, digits[length..].to_owned()))
    })
}

fn strip_idd<'a>(plan: &'static crate::plans::Plan, digits: &'a str) -> Option<&'a str> {
    let preferred = plan.preferred_international_prefix.as_str();
    if !preferred.is_empty()
        && preferred.bytes().all(|byte| byte.is_ascii_digit())
        && let Some(national) = digits.strip_prefix(preferred)
    {
        return (!national.starts_with('0')).then_some(national);
    }

    let matched =
        crate::pattern::prefix_expression(&plan.international_prefix_pattern)?.find(digits)?;
    let remainder = &digits[matched.end()..];
    (matched.end() > 0 && !remainder.starts_with('0')).then_some(remainder)
}

fn without_national_prefix(plan: &'static crate::plans::Plan, national: &str) -> String {
    let pattern = if plan.national_prefix_pattern.is_empty() {
        plan.national_prefix.as_str()
    } else {
        plan.national_prefix_pattern.as_str()
    };
    if pattern.is_empty() {
        return national.to_owned();
    }
    let Some(expression) = crate::pattern::prefix_expression(pattern) else {
        return national.to_owned();
    };
    let Some(captures) = expression.captures(national) else {
        return national.to_owned();
    };
    let Some(found) = captures.get(0) else {
        return national.to_owned();
    };
    if found.end() == 0 || found.end() == national.len() {
        return national.to_owned();
    }
    let candidate = if plan.national_prefix_transform.is_empty()
        || !replacement_captures_match(&plan.national_prefix_transform, &captures)
    {
        national[found.end()..].to_owned()
    } else {
        expression
            .replace(national, plan.national_prefix_transform.as_str())
            .into_owned()
    };
    if plan.general.matches(national) && !plan.general.matches(&candidate) {
        national.to_owned()
    } else {
        candidate
    }
}

fn prefix_result_is_usable(plan: &'static crate::plans::Plan, candidate: &str) -> bool {
    !candidate.is_empty()
        && !matches!(
            crate::assessment::possibility_for(plan, candidate),
            crate::Possibility::TooShort
                | crate::Possibility::LocalOnly
                | crate::Possibility::InvalidLength
        )
}

fn replacement_captures_match(rule: &str, captures: &regex::Captures<'_>) -> bool {
    rule.as_bytes()
        .windows(2)
        .filter(|bytes| bytes[0] == b'$' && bytes[1].is_ascii_digit())
        .map(|bytes| usize::from(bytes[1] - b'0'))
        .all(|index| captures.get(index).is_some())
}