Skip to content

README_EN.md

Latest commit

 

History

History
193 lines (145 loc) · 6.97 KB

README_EN.md

File metadata and controls

193 lines (145 loc) · 6.97 KB

go-propisyu · Russian Number-to-Words for Go

English version · Русская версия

CI Go Reference Go Report Card codecov License: MIT

Russian number-to-words: amounts with currency, decimals, ordinal numbers in all three grammatical genders, and noun declension for any word.

propisyu.Money(1234, 56, propisyu.CurrencyRUB)
// одна тысяча двести тридцать четыре рубля пятьдесят шесть копеек

propisyu.Ordinal(1, propisyu.GenderFeminine)
// первая

propisyu.DecimalToWordsPrecision("3.141", 3)
// три целых сто сорок одна тысячная

propisyu.Decline(5, "заказ", "заказа", "заказов")
// заказов

Features

  • Full Go int range — from math.MinInt to math.MaxInt (±9.2 × 10¹⁸ on 64-bit). Edge values (including MinInt) do not crash -n — the magnitude is safely computed via uint64.
  • Three grammatical genders — GenderMasculine, GenderFeminine, GenderNeuter — for cardinals (IntToWordsGender) and ordinals (Ordinal).
  • Ordinal numbers — Ordinal(n, gender): compound forms ("сорок второй"), round numbers ("тысячный", "миллионный"), all three genders.
  • Decimals with arbitrary precision — DecimalToWordsPrecision supports 1–9 fractional digits (tenths through billionths). DecimalValueToWords accepts shopspring/decimal.
  • Currencies — Money + presets CurrencyRUB, CurrencyUSD, CurrencyEUR; easy to create your own Currency.
  • Declension — Decline picks the correct noun form by number, with proper handling of 11–14 and negatives.
  • Zero deps in the core — shopspring/decimal is only needed for DecimalValueToWords.

Installation

go get github.com/rekurt/go-propisyu

shopspring/decimal is only needed for DecimalValueToWords:

go get github.com/shopspring/decimal

Usage

Integers

Function Description
IntToWords(n int) string Integer to words, masculine gender by default
IntToWordsGender(n int, gender Gender) string Same with an explicit gender 
propisyu.IntToWords(42)                                // сорок два
propisyu.IntToWords(1000)                              // одна тысяча
propisyu.IntToWords(-321)                              // минус триста двадцать один

propisyu.IntToWordsGender(1, propisyu.GenderMasculine) // один
propisyu.IntToWordsGender(1, propisyu.GenderFeminine)  // одна
propisyu.IntToWordsGender(1, propisyu.GenderNeuter)    // одно

Gender constants: GenderMasculine, GenderFeminine, GenderNeuter (type Gender).

Currency & Money

Function / type Description
Money(whole, cents int, c Currency) string Amount in words
MoneyFromString(amount string, c Currency) (string, error) Parses "1234.56" and returns the result
CurrencyRUB, CurrencyUSD, CurrencyEUR Built-in presets 
propisyu.Money(1234, 56, propisyu.CurrencyRUB)
// одна тысяча двести тридцать четыре рубля пятьдесят шесть копеек

propisyu.Money(1, 1, propisyu.CurrencyRUB)
// один рубль одна копейка

propisyu.Money(100, 99, propisyu.CurrencyEUR)
// сто евро девяносто девять центов

Custom Currency preset — for any unit (tokens, points, loyalty):

myTokens := propisyu.Currency{
    WholeOne: "токен", WholeTwo: "токена", WholeFive: "токенов",
    WholeGender: propisyu.GenderMasculine,
    FracOne: "юнит", FracTwo: "юнита", FracFive: "юнитов",
    FracGender: propisyu.GenderMasculine,
}
propisyu.Money(42, 5, myTokens)
// сорок два токена пять юнитов

Decimals

Function Description
DecimalToWords(s string) (string, error) String with fixed .xx precision
DecimalValueToWords(d decimal.Decimal) (string, error) shopspring/decimal directly
DecimalToWordsPrecision(s string, precision int) (string, error) Arbitrary 1–9 digit precision 
propisyu.DecimalToWords("123.45")
// сто двадцать три целых сорок пять сотых

propisyu.DecimalToWordsPrecision("3.14159", 5)
// три целых четырнадцать тысяч сто пятьдесят девять стотысячных

propisyu.DecimalToWords("-0.50")
// минус ноль целых пятьдесят сотых

The fractional part is truncated, not rounded. The whole part is always rendered in the feminine gender ("одна целая", "две целых"). The minus sign is preserved for -0.xx.

Ordinals

Function Description
Ordinal(n int, gender Gender) string Ordinal number in the chosen gender 
propisyu.Ordinal(1, propisyu.GenderMasculine)     // первый
propisyu.Ordinal(1, propisyu.GenderFeminine)      // первая
propisyu.Ordinal(42, propisyu.GenderMasculine)    // сорок второй
propisyu.Ordinal(1000, propisyu.GenderFeminine)   // тысячная
propisyu.Ordinal(1_000_000, propisyu.GenderMasculine) // миллионный

Declension

Function Description
Decline(n int, one, two, five string) string Picks a noun form based on the number 
propisyu.Decline(1,  "рубль", "рубля", "рублей") // рубль
propisyu.Decline(5,  "день",  "дня",   "дней")   // дней
propisyu.Decline(21, "день",  "дня",   "дней")   // день
propisyu.Decline(11, "рубль", "рубля", "рублей") // рублей
Last digit of n n % 100 ∈ 11…19 Form
1 no one
2, 3, 4 no two
0, 5–9 — five
any yes five

Negative numbers are handled by magnitude.

Errors

ErrNumberTooLarge is returned from DecimalValueToWords when the whole part of a decimal.Decimal does not fit in Go int.

Limitations

  • Integers are bounded by Go int — on 64-bit platforms this is ±9.2 × 10¹⁸.
  • DecimalToWords and DecimalValueToWords work with two fractional digits (anything beyond is truncated). For higher precision use DecimalToWordsPrecision (1–9 digits).

Contributing

Contributions are welcome! See CONTRIBUTING.md.

License

MIT. See LICENSE.