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
parseaccepts international numbers and global RFC 3966 telephone URIs.PhoneNumberimplementsFromStrfor international input.parse_ininterprets national input using an explicit fallback region.parse_strictaccepts only canonical E.164 or global RFC 3966 syntax.PhoneNumber::assessreports length, validity, service category, regions, dialing policy, and numbering-data version.PhoneNumber::formatsupports E.164, national, international, and RFC 3966.PhoneNumber::dialproduces a domestic or international dial string for an origin region.FoundNumbersprovides a lazy, bounded iterator over candidates in text.AsYouTypeandFormattedEditsupport bounded append-only and cursor-aware input.ShortNumberkeeps emergency and service codes separate from global numbers.example_numberandexample_number_for_kindreturn 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§
- AsYou
Type - Append-only phone number formatting for text fields.
- Assessment
- An assessment of a parsed number against the bundled numbering plans.
- Calling
Code - An E.164 country calling code.
- Carrier
Name - The original carrier’s English name for a numbering range.
- Dial
Options - Policy used to produce a dial string.
- Error
- A phone number error that omits input values.
- Extension
- A phone extension, preserving leading zeroes.
- Find
Options - Bounds and policy for extracting numbers from text.
- Formatted
- A lazily formatted phone number.
- Formatted
Edit - Result of formatting editable input with cursor preservation.
- Found
Number - A phone number and its byte range in source text.
- Found
Numbers - Lazy, bounded phone number extraction from text.
- Location
- An approximate English location for a numbering range.
- Match
Options - Options for semantic comparison.
- Parse
Options - Bounds and policy for parsing untrusted input.
- Parsed
Number - A parsed number with explicitly retained source text.
- Phone
Number - A structurally parsed global phone number.
- Region
- A two-letter region supported by the bundled numbering plans.
- Short
Number - A region-scoped short number such as an emergency or service code.
- Time
Zones - IANA time zone identifiers for a numbering range.
Enums§
- Confidence
- Confidence in a phone number found in text.
- Emergency
Match - Relationship between short digits and an emergency service code.
- Error
Kind - Stable category for a failed operation.
- Format
- A phone number output format.
- Match
- Semantic relationship between two phone numbers.
- Number
Kind - 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
kindforregion. - parse
- Parses an international number or RFC 3966 URI.
- parse_
in - Parses a number, using
regiononly 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.