# 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.
```rust
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][notice] for attribution.
[notice]: https://github.com/nouslabs-ai/nous/blob/main/crates/namba/NOTICE