Chinese Numerals
Both BInt and Decimal can write themselves in Chinese numerals with
to_chinese():
print(BInt(15).to_chinese()) # 十五
print(Decimal("1050.07").to_chinese()) # 一千零五十点零七
print(Decimal("-100000001").to_chinese()) # 负一亿零一
The conversion works on the decimal string of the number rather than on a particular numeric type, so it is not limited by any integer width. The string-level entry point is available directly if you need it:
from decimo.numerals import decimal_string_to_chinese
print(decimal_string_to_chinese("1050.07")) # 一千零五十点零七
Reading rules
The integer part is split into sections of eight digits, counted from the decimal point. Within a section the digits take the 十/百/千 units, and the upper four take 万. Sections are joined by 亿, which multiplies everything read before it rather than labelling one section:
print(BInt("1234567890123").to_chinese())
# 一万二千三百四十五亿六千七百八十九万零一百二十三 (12345亿 + 6789万 + 123)
Because 亿 is a multiplier, each further 亿 raises the magnitude by another 10^8 — 亿亿 is 10^16, 亿亿亿 is 10^24 — so arbitrarily large integers are readable without the rarely-agreed-upon 兆/京/垓 units:
print(BInt("10000000000000000").to_chinese()) # 一亿亿
print(BInt("10000000000000005").to_chinese()) # 一亿亿零五
Runs of zeros collapse into a single 零, and a leading 一十 is shortened to 十
(BInt(15) is 十五, not 一十五). The fractional part is read digit by digit
after 点, zeros included, so the written precision survives the conversion:
print(Decimal("1.50").to_chinese()) # 一点五零 (not 一点五)
print(Decimal("2.000").to_chinese()) # 二点零零零
Styles
The character tables are supplied by ChineseNumeralStyle, which ships with
four presets:
| Preset | Digits | Units | 10^4 / 10^8 | Point | Example for 1050 |
|---|---|---|---|---|---|
simplified() (default) | 一二三 | 十百千 | 万 / 亿 | 点 | 一千零五十 |
simplified_financial() | 壹贰叁 | 拾佰仟 | 万 / 亿 | 点 | 壹仟零伍拾 |
traditional() | 一二三 | 十百千 | 萬 / 億 | 點 | 一千零五十 |
traditional_financial() | 壹貳參 | 拾佰仟 | 萬 / 億 | 點 | 壹仟零伍拾 |
from decimo import ChineseNumeralStyle
print(Decimal("1050.07").to_chinese(ChineseNumeralStyle.simplified_financial()))
# 壹仟零伍拾点零柒
print(Decimal("1050.07").to_chinese(ChineseNumeralStyle.traditional()))
# 一千零五十點零七
The financial (大写) styles keep the leading 一十 rather than shortening it, since dropping a digit on a cheque would make the amount easier to tamper with. A custom style can be built from the same constructor if you need a table the presets do not cover.
Digit budget
A reading is always written out in full, so its cost is set by the written
length of the number, not by how compactly the value was given —
Decimal("1E+1000000000") is a few characters of input and a billion digits
of output. Conversions therefore take a max_digits budget, defaulting to
MAX_CHINESE_NUMERAL_DIGITS (10 000), and raise a ValueError past it. The
check happens before the digits are expanded, so an absurd magnitude costs
nothing:
_ = Decimal("1E+1000000000").to_chinese() # raises ValueError
_ = BInt("1" + String("0") * 20000).to_chinese() # raises ValueError
# Raise or lift the cap when a very long reading really is what you want:
print(Decimal("1E+20000").to_chinese(max_digits=0))