Skip to main content

Crate namba

Crate namba 

Source
Expand description

§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");

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.

Structs§

AsYouType
Append-only phone number formatting for text fields.
Assessment
An assessment of a parsed number against the bundled numbering plans.
CallingCode
An E.164 country calling code.
CarrierName
The original carrier’s English name for a numbering range.
DialOptions
Policy used to produce a dial string.
Error
A phone number error that omits input values.
Extension
A phone extension, preserving leading zeroes.
FindOptions
Bounds and policy for extracting numbers from text.
Formatted
A lazily formatted phone number.
FormattedEdit
Result of formatting editable input with cursor preservation.
FoundNumber
A phone number and its byte range in source text.
FoundNumbers
Lazy, bounded phone number extraction from text.
Location
An approximate English location for a numbering range.
MatchOptions
Options for semantic comparison.
ParseOptions
Bounds and policy for parsing untrusted input.
ParsedNumber
A parsed number with explicitly retained source text.
PhoneNumber
A structurally parsed global phone number.
Region
A two-letter region supported by the bundled numbering plans.
ShortNumber
A region-scoped short number such as an emergency or service code.
TimeZones
IANA time zone identifiers for a numbering range.

Enums§

Confidence
Confidence in a phone number found in text.
EmergencyMatch
Relationship between short digits and an emergency service code.
ErrorKind
Stable category for a failed operation.
Format
A phone number output format.
Match
Semantic relationship between two phone numbers.
NumberKind
A phone number’s service category.
Possibility
A phone number’s length classification.

Constants§

DATA_VERSION
Version of the bundled numbering data.

Functions§

example_number
Returns a bundled valid example number for region.
example_number_for_kind
Returns a bundled valid example of kind for region.
parse
Parses an international number or RFC 3966 URI.
parse_in
Parses a number, using region only when the input is not international.
parse_in_with_options
Parses a regional number with explicit input bounds.
parse_strict
Parses only canonical E.164 or global RFC 3966 syntax.
parse_with_options
Parses an international number with explicit input bounds.

Type Aliases§

Result
A Namba operation result.