namba 0.1.0

A fast, lightweight library for parsing, validating, and formatting phone numbers
Documentation

Namba

A fast, lightweight library for parsing, validating, and formatting phone numbers.

Namba is inspired by the Japanese ナンバー (nanbā), a loanword for "number."

Namba uses numbering data generated from Google libphonenumber to interpret phone numbers worldwide. It also supports dialing rules, matching, extraction, interactive input, examples, and region-specific short numbers. It never performs network I/O at runtime.

use namba::{Format, Region, parse_in};

let india = Region::new("IN")?;
let number = parse_in(india, "098765 43210")?;

assert!(number.assess().is_valid());
assert_eq!(number.format(Format::E164).to_string(), "+919876543210");
# Ok::<(), namba::Error>(())

Parsing and validation are separate. A parsed number is structurally meaningful. Assessment::is_valid means only that the number matches the bundled numbering plan. It does not prove that the number is assigned, reachable, or owned by anyone.

Operations

  • parse accepts international numbers and global RFC 3966 telephone URIs.
  • PhoneNumber implements FromStr for international input.
  • parse_in interprets national input using an explicit fallback region.
  • parse_strict accepts only canonical E.164 or global RFC 3966 syntax.
  • PhoneNumber::assess reports length, validity, service category, regions, dialing policy, and numbering-data version.
  • PhoneNumber::format supports E.164, national, international, and RFC 3966.
  • PhoneNumber::dial produces a domestic or international dial string for an origin region.
  • FoundNumbers provides a lazy, bounded iterator over candidates in text.
  • AsYouType and FormattedEdit support bounded append-only and cursor-aware input.
  • ShortNumber keeps emergency and service codes separate from global numbers.
  • example_number and example_number_for_kind return bundled examples.

Namba does not implement contact lookup, number assignment, reachability, verification messages, or implicit locale detection.

Features

Core operations are synchronous and perform no network I/O. Optional features are serde, geocoding, carrier, and timezone. Each enrichment feature links only its data artifact. The default build does not link these artifacts. Lookups return borrowed values without decoding a complete table. Namba requires std. CI checks Linux and wasm32-wasip1.

Privacy

Phone numbers are sensitive. Debug output and errors never contain complete input. ParsedNumber owns source text only when you request it. FoundNumber borrows each match from the text that you provide.

Compatibility

Namba applies the bundled Google numbering rules through its own Rust API. Namba's documented operations and tests define compatibility. Namba does not provide Java API parity. Version 0.1.0 supports global and regional parsing, assessment, formatting, matching, extraction, short numbers, English geocoding and carrier data, and time zone data.

RFC 3966 parsing accepts global tel:+... URIs. Local phone-context URIs and parameters other than ext are not supported. Use FoundNumbers to search prose. Direct parsing only interprets one number. Flexible parsing accepts Unicode decimal digits, ASCII vanity letters, spaces, tabs, line breaks, hyphens, periods, parentheses, and slashes. It rejects other characters. Extensions can use ;ext=, ext, ext., x, or #. Regional parsing also recognizes the numbering plan's international dialing prefix.

With the serde feature, PhoneNumber serializes as a canonical RFC 3966 string. Deserialization accepts canonical E.164 and global RFC 3966 strings. Region serializes as its two-letter uppercase identifier.

The repository generator downloads the pinned libphonenumber v9.0.36 tag and verifies its SHA-256 before updating the committed artifacts. Normal builds use those artifacts without network access. DATA_VERSION identifies the snapshot. A data update can change an assessment as numbering plans evolve.

License

Namba's implementation is licensed under MIT. The bundled data is derived from Google libphonenumber and remains licensed under Apache License 2.0. See the third-party notice for attribution.