Expand description
Numbers to words in 50 languages (72 regional variants).
A Rust port of the n2words JavaScript library. Each language is a module named after its BCP 47 code in snake_case, exposing up to three forms:
| Form | Function | Example |
|---|---|---|
| Cardinal | en::to_cardinal | “forty-two” |
| Ordinal | en::to_ordinal | “forty-second” |
| Currency | en_us::to_currency | “forty-two dollars and fifty cents” |
use n2words::{en, en_us, es, fr, Currency};
assert_eq!(en::to_cardinal(42)?, "forty-two");
assert_eq!(en::to_ordinal(42)?, "forty-second");
assert_eq!(es::to_cardinal(42)?, "cuarenta y dos");
assert_eq!(fr::to_cardinal("1234.5")?, "mille deux cent trente-quatre virgule cinq");
// A region-qualified code carries a default currency ...
assert_eq!(en_us::to_currency(42.5)?, "forty-two dollars and fifty cents");
// ... while a bare language tag has no country to take one from, so it is explicit.
assert_eq!(en::to_currency(42.5, Currency::GBP)?, "forty-two pounds and fifty pence");§Input
Every function takes impl Into<Number>: any primitive integer, an
f64/f32, a numeric &str/String (arbitrary precision, scientific
notation accepted) or a num_bigint::BigInt/BigUint. Cardinal and
currency accept negatives and decimals; ordinal takes positive integers.
§Options
A form that has options comes in two flavours: to_cardinal(value) with
the language’s defaults, and to_cardinal_with(value, &options) taking a
per-language options struct whose Default is those defaults:
use n2words::en_us::{self, CardinalOptions};
assert_eq!(en_us::to_cardinal(1501)?, "one thousand five hundred one");
let informal = CardinalOptions { and: true, hundred_pairing: true, ..Default::default() };
assert_eq!(en_us::to_cardinal_with(1501, &informal)?, "fifteen hundred and one");§Range
Each form spells values up to the largest scale word it knows, declared as
a Max constant (en_us::CARDINAL_MAX is 10^66), and returns
Error::OutOfRange past it rather than inventing vocabulary.
§Picking a language at runtime
language() looks an entry point up by code and gives access to the same
conversions through string-keyed options, which is what the n2words
command-line tool is built on:
use n2words::{language, FormKind};
let de = language("de").expect("German is supported");
assert_eq!(de.convert(FormKind::Cardinal, 42, &[])?, "zweiundvierzig");
assert_eq!(de.convert(FormKind::Currency, "42.50", &[("currency", "EUR")])?, "zweiundvierzig Euro und fünfzig Cent");§Languages
Most languages are reachable through a bare primary subtag (de, en,
fr, …), a documented alias of one specific regional variant; the
region- or script-qualified module always exists too (en_gb, fr_be),
and is the only entry point for the few languages whose variants differ in
script or core numbering (zh_hans_cn/zh_hant_tw, pt_br/pt_pt,
sr_cyrl_rs/sr_latn_rs, am_et/am_latn_et). See LANGUAGES.md in
the repository for the full table, per-language options and ceilings.
Re-exports§
pub use currency::Currency;pub use language::ConvertFn;pub use language::Form;pub use language::FormKind;pub use language::Kind;pub use language::Language;pub use language::language;pub use language::languages;pub use options::Gender;pub use num_bigint;
Modules§
- am_et
- Amharic (Ethiopia) (
am-ET): Amharic as used in Ethiopia (Ge’ez script). - am_
latn_ et - Amharic (Latin, Ethiopia) (
am-Latn-ET): Amharic as used in Ethiopia, in Latin-script romanization. - ar
- Arabic (
ar): the bare-tag alias ofar_sa. - ar_sa
- Arabic (Saudi Arabia) (
ar-SA): Modern Standard Arabic as used in Saudi Arabia. - az
- Azerbaijani (
az): the bare-tag alias ofaz_az. - az_az
- Azerbaijani (Azerbaijan) (
az-AZ). - bn
- Bangla (
bn): the bare-tag alias ofbn_bd. - bn_bd
- Bangla (Bangladesh) (
bn-BD). - cs
- Czech (
cs): the bare-tag alias ofcs_cz. - cs_cz
- Czech (Czechia) (
cs-CZ). - currency
- Currencies and the per-language currency vocabulary.
- da
- Danish (
da): the bare-tag alias ofda_dk. - da_dk
- Danish (Denmark) (
da-DK). - de
- German (
de): the bare-tag alias ofde_de. - de_de
- German (Germany) (
de-DE). - el
- Greek (
el): the bare-tag alias ofel_gr. - el_gr
- Greek (Greece) (
el-GR). - en
- English (
en): the bare-tag alias ofen_us. - en_au
- Australian English (
en-AU): a locale profile ofen_gb. - en_bd
- English (Bangladesh) (
en-BD): a locale profile ofen_in. - en_ca
- Canadian English (
en-CA). - en_gb
- British English (
en-GB). - en_gh
- English (Ghana) (
en-GH): a locale profile ofen_gb. - en_ie
- English (Ireland) (
en-IE): a locale profile ofen_gb. - en_in
- English (India) (
en-IN). - en_ke
- English (Kenya) (
en-KE): a locale profile ofen_gb. - en_my
- English (Malaysia) (
en-MY): a locale profile ofen_gb. - en_ng
- English (Nigeria) (
en-NG): a locale profile ofen_gb. - en_nz
- English (New Zealand) (
en-NZ): a locale profile ofen_gb. - en_ph
- English (Philippines) (
en-PH): a locale profile ofen_gb. - en_pk
- English (Pakistan) (
en-PK): a locale profile ofen_in. - en_sg
- English (Singapore) (
en-SG): a locale profile ofen_gb. - en_us
- American English (
en-US). - en_za
- English (South Africa) (
en-ZA): a locale profile ofen_gb. - es
- Spanish (
es): the bare-tag alias ofes_es. - es_es
- European Spanish (
es-ES). - es_mx
- Mexican Spanish (
es-MX): a locale profile ofes_es. - es_us
- Spanish (United States) (
es-US). - fa
- Persian (
fa): the bare-tag alias offa_ir. - fa_ir
- Persian (Iran) (
fa-IR): Persian as used in Iran. - fi
- Finnish (
fi): the bare-tag alias offi_fi. - fi_fi
- Finnish (Finland) (
fi-FI). - fil
- Filipino (
fil): the bare-tag alias offil_ph. - fil_ph
- Filipino (Philippines) (
fil-PH). - fr
- French (
fr): the bare-tag alias offr_fr. - fr_be
- French (Belgium) (
fr-BE). - fr_fr
- French (France) (
fr-FR). - gu
- Gujarati (
gu): the bare-tag alias ofgu_in. - gu_in
- Gujarati (India) (
gu-IN). - ha
- Hausa (
ha): the bare-tag alias ofha_ng. - ha_ng
- Hausa (Nigeria) (
ha-NG): Hausa as used in Nigeria. - hbo
- Biblical Hebrew (
hbo): the bare-tag alias ofhbo_il. - hbo_il
- Biblical Hebrew (Israel) (
hbo-IL). - he
- Hebrew (
he): the bare-tag alias ofhe_il. - he_il
- Modern Hebrew (Israel) (
he-IL). - hi
- Hindi (
hi): the bare-tag alias ofhi_in. - hi_in
- Hindi (India) (
hi-IN). - hr
- Croatian (
hr): the bare-tag alias ofhr_hr. - hr_hr
- Croatian (Croatia) (
hr-HR). - hu
- Hungarian (
hu): the bare-tag alias ofhu_hu. - hu_hu
- Hungarian (Hungary) (
hu-HU). - id
- Indonesian (
id): the bare-tag alias ofid_id. - id_id
- Indonesian (Indonesia) (
id-ID). - it
- Italian (
it): the bare-tag alias ofit_it. - it_it
- Italian (Italy) (
it-IT). - ja
- Japanese (
ja): the bare-tag alias ofja_jp. - ja_jp
- Japanese (Japan) (
ja-JP). - ka
- Georgian (
ka): the bare-tag alias ofka_ge. - ka_ge
- Georgian (Georgia) (
ka-GE). - kn
- Kannada (
kn): the bare-tag alias ofkn_in. - kn_in
- Kannada (India) (
kn-IN). - ko
- Korean (
ko): the bare-tag alias ofko_kr. - ko_kr
- Korean (South Korea) (
ko-KR). - language
- The language registry: every entry point, its forms, their ceilings and options, reachable by BCP 47 code at runtime.
- lt
- Lithuanian (
lt): the bare-tag alias oflt_lt. - lt_lt
- Lithuanian (Lithuania) (
lt-LT). - lv
- Latvian (
lv): the bare-tag alias oflv_lv. - lv_lv
- Latvian (Latvia) (
lv-LV). - mr
- Marathi (
mr): the bare-tag alias ofmr_in. - mr_in
- Marathi (India) (
mr-IN). - ms
- Malay (
ms): the bare-tag alias ofms_my. - ms_my
- Malay (Malaysia) (
ms-MY). - nb
- Norwegian Bokmål (
nb): the bare-tag alias ofnb_no. - nb_no
- Norwegian Bokmål (Norway) (
nb-NO). - nl
- Dutch (
nl): the bare-tag alias ofnl_nl. - nl_nl
- Dutch (Netherlands) (
nl-NL). - options
- Per-form options: typed structs for the Rust API, plus the declarative metadata behind the dynamic API, the CLI and the generated docs.
- pa
- Punjabi (
pa): the bare-tag alias ofpa_in. - pa_in
- Punjabi (India) (
pa-IN). - pl
- Polish (
pl): the bare-tag alias ofpl_pl. - pl_pl
- Polish (Poland) (
pl-PL). - pt_br
- Brazilian Portuguese (
pt-BR). - pt_pt
- European Portuguese (
pt-PT). - ro
- Romanian (
ro): the bare-tag alias ofro_ro. - ro_ro
- Romanian (Romania) (
ro-RO). - ru
- Russian (
ru): the bare-tag alias ofru_ru. - ru_ru
- Russian (Russia) (
ru-RU). - sr_
cyrl_ rs - Serbian (Cyrillic, Serbia) (
sr-Cyrl-RS). - sr_
latn_ rs - Serbian (Latin, Serbia) (
sr-Latn-RS). - sv
- Swedish (
sv): the bare-tag alias ofsv_se. - sv_se
- Swedish (Sweden) (
sv-SE): Swedish as used in Sweden. - sw
- Swahili (
sw): the bare-tag alias ofsw_ke. - sw_ke
- Swahili (Kenya) (
sw-KE): Swahili as used in Kenya. - ta
- Tamil (
ta): the bare-tag alias ofta_in. - ta_in
- Tamil (India) (
ta-IN). - te
- Telugu (
te): the bare-tag alias ofte_in. - te_in
- Telugu (India) (
te-IN). - th
- Thai (
th): the bare-tag alias ofth_th. - th_th
- Thai (Thailand) (
th-TH). - tr
- Turkish (
tr): the bare-tag alias oftr_tr. - tr_tr
- Turkish (Türkiye) (
tr-TR). - uk
- Ukrainian (
uk): the bare-tag alias ofuk_ua. - uk_ua
- Ukrainian (Ukraine) (
uk-UA). - ur
- Urdu (
ur): the bare-tag alias ofur_pk. - ur_pk
- Urdu (Pakistan) (
ur-PK). - vi
- Vietnamese (
vi): the bare-tag alias ofvi_vn. - vi_vn
- Vietnamese (Vietnam) (
vi-VN). - yo
- Yoruba (
yo): the bare-tag alias ofyo_ng. - yo_ng
- Yoruba (Nigeria) (
yo-NG): Yoruba as used in Nigeria. - zh_
hans_ cn - Simplified Chinese (China) (
zh-Hans-CN). - zh_
hant_ tw - Traditional Chinese (Taiwan) (
zh-Hant-TW).
Enums§
- Error
- Why a conversion was refused.
- Max
- A form’s ceiling: the smallest value it refuses to convert.
- Number
- A numeric value accepted by every form.
Constants§
- VERSION
- The crate version, as published.
Statics§
- LANGUAGES
- Every entry point the crate ships, sorted by BCP 47 code.