Crate phonelib 

Phonelib

A dependency-free Rust library for validating, parsing, formatting and manipulating international phone numbers.

Features

• Validation - length- and (for the NANP) range-based validation
• Country detection - deterministic resolution of the calling code
• Normalization - canonical E.164 output
• Multiple formats - E.164, international, national, RFC 3966
• Type detection - mobile, landline, toll-free, premium, and more
• Text extraction - find phone numbers in free-form text
• Comparison - compare numbers regardless of formatting
• Batch processing - process many numbers in one call

Quick start

use phonelib::*;

assert!(is_valid_phone_number("+12025550173"));

assert_eq!(
    normalize_phone_number("+1 (202) 555-0173"),
    Some("+12025550173".to_string())
);

let text = "Call me at +12025550173 or +442079460958";
assert_eq!(extract_phone_numbers_from_text(text).len(), 2);

let a = PhoneNumber::parse("+1 202-555-0173").unwrap();
let b = PhoneNumber::parse("12025550173").unwrap();
assert_eq!(a, b);

Dependencies

The crate has none, and no feature flags. Everything it needs is core and alloc by way of std: the country and area-code tables are const data built at compile time, so there is no runtime initialization and no global state either.

Accuracy and scope

Validation is driven by the country table in this crate: the country calling code must be known and the national significant number must have a length that country accepts. For numbers in the North American Numbering Plan the area code and central office code are additionally checked against the assigned NANP ranges, which is what makes US / CA / Caribbean territory attribution exact.

A number must say which country it belongs to. Give it a leading +, an 00 international access code, or a country via PhoneNumber::parse_with_country. A bare national number is rejected with ParseError::MissingCallingCode rather than guessed at, because its leading digits usually match some country’s calling code — (202) 555-0173 is a Washington DC number, and also a well-formed Egyptian +20 2555 0173. The exception is calling code 1, where the area code is checked against the numbering plan, so 12025550173 resolves without a +.

Outside the NANP the crate does not carry per-operator prefix ranges, so a number with a plausible length is accepted even if its prefix is not in service. If you need full carrier-grade validation for every country, use a library backed by the complete libphonenumber metadata.

detect_phone_number_type is likewise metadata-driven. Countries without a published range table in this crate return PhoneNumberType::Unknown rather than a guess. Range tables are carried for the North American Numbering Plan and for GB, IE, DE, FR, IT, ES, NL, BE, CH, AT, SE, NO, PL, PT, RU, KZ, TR, IN, CN, JP, KR, AU, NZ, BR, ZA and NG.

Structs

Country

A country or territory in the international numbering plan.

ExtractedPhoneNumber

Result of extracting a phone number from text

PhoneNumber

A parsed and validated phone number.

PhoneNumberAnalysis

Detailed analysis result for a phone number.

PhoneNumberSet

A set of phone numbers, deduplicated by their E.164 form.

Enums

ParseError

Why a phone number could not be parsed.

PhoneFormat

Phone number format options.

PhoneNumberType

The service class of a phone number.

Functions

analyze_phone_numbers_batch

Comprehensive batch analysis of phone numbers.

are_phone_numbers_equal

Check if two phone numbers are equivalent, ignoring formatting.

count_phone_numbers_in_text

Count how many phone numbers are in the text.

countries

Every country and territory the crate knows about.

countries_by_calling_code

Every country that uses a given E.164 calling code, in resolution order.

countries_by_code

Every table entry for an ISO 3166-1 alpha-2 code.

country_by_code

Look up a country by its ISO 3166-1 alpha-2 code.

detect_phone_number_type

Detect the service class of a phone number.

detect_phone_number_types_batch

Detect phone number types for multiple numbers at once.

extract_countries

Every country whose numbering plan could account for this number.

extract_countries_batch

Extract countries for multiple phone numbers at once.

extract_country

Extracts country information from a phone number.

extract_phone_numbers_from_text

Extract all phone numbers from free-form text.

extract_phone_numbers_with_country_hint

Extract phone numbers from text, assuming a default country.

extract_valid_phone_numbers_from_text

Extract only the valid phone numbers from text.

format_phone_number

Format a phone number according to the specified format.

generate_random_phone_number

Generate a random valid phone number for a specific country.

generate_random_phone_numbers

Generate several random valid phone numbers for a country.

group_equivalent_phone_numbers

Group phone numbers by equivalence, preserving input order.

guess_country_from_number

Get the most likely country for a phone number.

is_landline_number

Check if a phone number is a landline number.

is_mobile_number

Check if a phone number is a mobile number.

is_potentially_valid_phone_number

Check if a phone number could plausibly become valid with reformatting.

is_toll_free_number

Check if a phone number is a toll-free number.

is_valid_phone_number

Validates whether a phone number is valid.

normalize_phone_number

Normalizes a phone number to E.164 format.

normalize_phone_number_in_place

Normalizes a phone number in place to E.164 format.

normalize_phone_numbers_batch

Normalize multiple phone numbers at once.

redact_phone_numbers

Redact phone numbers in text for privacy.

replace_phone_numbers_in_text

Replace phone numbers in text with a transformed version.

suggest_phone_number_corrections

Suggest corrections for an invalid phone number.

try_normalize_phone_number

Like normalize_phone_number but reports why the number was rejected.

validate_phone_numbers_batch

Validate multiple phone numbers at once.