Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

PresetDigitsUnits10^4 / 10^8PointExample 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))