@kensio/pinyinjs 0.1.0-beta.0 → 1.0.0

package/dist/numerals/cardinal.js

@@ -0,0 +1,111 @@
+import { DIGIT_CHARACTERS } from "./characters.js";
+/**
+ * The places inside one group of four digits, largest first.
+ */
+const PLACES = ["千", "百", "十", ""];
+/**
+ * The group separators, in the order the groups come off the number.
+ */
+const GROUPS = ["", "万", "亿", "万亿"];
+/**
+ * How many digits one group holds.
+ *
+ * Chinese numbers are grouped by 万 rather than by thousands, which is why a
+ * group is four digits wide and why 12,345 is *one* 万 and 2,345.
+ */
+const GROUP_DIGITS = 4;
+/**
+ * The largest number this can write, being four groups of four digits.
+ */
+export const LARGEST_CARDINAL = 10 ** 16 - 1;
+/**
+ * Whether a lone 2 opening this group takes 两.
+ */
+function isLiang(liang, isLeading) {
+    return liang === "always" || (liang === "leading" && isLeading);
+}
+/**
+ * The character a digit takes in a place: 两 before a 千, 二 otherwise.
+ */
+function digitAt(value, place, isFirst, options) {
+    return value === 2 &&
+        place === "千" &&
+        isLiang(options.liang, options.isLeading && isFirst)
+        ? "两"
+        : (DIGIT_CHARACTERS[value] ?? "");
+}
+/**
+ * Write one group of at most four digits: 2345 as 二千三百四十五.
+ *
+ * Empty for a group that is all zeros. A run of zeros inside the group becomes
+ * one 零, and only where a non-zero digit follows it: 1,005 is 一千零五 while
+ * 1,500 is 一千五百.
+ */
+function writeGroup(group, options) {
+    const digits = String(group).padStart(GROUP_DIGITS, "0").split("");
+    let written = "";
+    let isPending = false;
+    for (const [at, digit] of digits.entries()) {
+        const value = Number(digit);
+        if (value === 0) {
+            isPending = written !== "";
+            continue;
+        }
+        const place = PLACES[at] ?? "";
+        if (isPending) {
+            written += "零";
+            isPending = false;
+        }
+        // 十五 rather than 一十五: the 一 drops only from a bare leading 十, so
+        // 一百一十五 keeps it and so does the 一十五 inside 一万零一十五.
+        const isBareTen = value === 1 && place === "十" && written === "" && options.isLeading;
+        written += isBareTen
+            ? place
+            : digitAt(value, place, written === "", options) + place;
+    }
+    return written;
+}
+/**
+ * Write a non-negative integer as a cardinal: 12345 → 一万二千三百四十五.
+ *
+ * The awkward parts are 零 and the bare 十, and both are about saying the
+ * number aloud rather than about arithmetic. A 零 goes where a place is skipped
+ * inside* the spoken number (一千零五) and not where the number simply ends
+ * (一千五百), which is the same question one level up between groups: 25,000 is
+ * 两万五千 because the lower group fills its 千, and 20,050 is 两万零五十
+ * because it does not.
+ * @throws {RangeError} for a negative, a fraction, or anything above 10^16.
+ */
+export function cardinalHanzi(value, options = {}) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > LARGEST_CARDINAL) {
+        throw new RangeError(`not a writable whole number: ${String(value)}`);
+    }
+    if (value === 0) {
+        return "零";
+    }
+    const { liang = "always" } = options;
+    const groups = [];
+    for (let rest = value; rest > 0; rest = Math.floor(rest / 10_000)) {
+        groups.push(rest % 10_000);
+    }
+    let written = "";
+    for (const [at, group] of groups.entries()) {
+        if (group === 0) {
+            continue;
+        }
+        const unit = GROUPS[at] ?? "";
+        const body = writeGroup(group, {
+            isLeading: at === groups.length - 1,
+            liang,
+        });
+        // The group immediately below decides whether a 零 is spoken between them:
+        // it is needed unless that group fills its own 千 place.
+        const below = groups[at - 1] ?? 0;
+        const gap = written !== "" && below < 1000 ? "零" : "";
+        const isLeading = at === groups.length - 1;
+        const lone = body === "二" && unit !== "" && isLiang(liang, isLeading) ? "两" : body;
+        written = lone + unit + gap + written;
+    }
+    return written;
+}
+//# sourceMappingURL=cardinal.js.map

package/dist/numerals/cardinal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardinal.js","sourceRoot":"","sources":["../../src/numerals/cardinal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAyBnD;;GAEG;AACH,MAAM,MAAM,GAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,GAAsB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;AAW7C;;GAEG;AACH,SAAS,OAAO,CACd,KAA4C,EAC5C,SAAkB;IAElB,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,SAAS,CAAC,CAAC;AAClE,CAAC;AAED;;GAEG;AACH,SAAS,OAAO,CACd,KAAa,EACb,KAAa,EACb,OAAgB,EAChB,OAAqB;IAErB,OAAO,KAAK,KAAK,CAAC;QAChB,KAAK,KAAK,GAAG;QACb,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;QACpD,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,KAAa,EAAE,OAAqB;IACtD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnE,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,SAAS,GAAG,OAAO,KAAK,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,IAAI,GAAG,CAAC;YACf,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;QACD,iEAAiE;QACjE,oDAAoD;QACpD,MAAM,SAAS,GACb,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,GAAG,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;QACtE,OAAO,IAAI,SAAS;YAClB,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,KAAK,EAAE,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC;IAC7D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,OAAO,GAAoB,EAAE;IAE7B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,gBAAgB,EAAE,CAAC;QAC1E,MAAM,IAAI,UAAU,CAAC,gCAAgC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,EAAE,KAAK,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;IAErC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC;QAClE,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QAC3C,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,EAAE;YAC7B,SAAS,EAAE,EAAE,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC;YACnC,KAAK;SACN,CAAC,CAAC;QACH,0EAA0E;QAC1E,wDAAwD;QACxD,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,OAAO,KAAK,EAAE,IAAI,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,SAAS,GAAG,EAAE,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3C,MAAM,IAAI,GACR,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,EAAE,IAAI,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QACxE,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,OAAO,CAAC;IACxC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/numerals/characters.d.ts

@@ -0,0 +1,31 @@
+import { type Syllable } from "../syllable/syllable.js";
+/**
+ * The 汉字 a digit is written with, indexed by its value.
+ */
+export declare const DIGIT_CHARACTERS = "\u96F6\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D";
+/**
+ * The other 汉字 a written number is made of, and what each is worth.
+ *
+ * 十, 百 and 千 are the places inside a group of four; 万 and 亿 are the group
+ * separators, which is what makes Chinese numbers myriad-grouped rather than
+ * thousand-grouped: 12,345 is 一万二千三百四十五, one 万 and 2,345.
+ */
+export declare const UNIT_VALUES: ReadonlyMap<string, number>;
+/**
+ * Read one numeral character.
+ *
+ * Undefined for anything that is not one, which is how a caller tells a
+ * numeral apart from the text around it.
+ */
+export declare function numeralSyllable(character: string): Syllable | undefined;
+/**
+ * `yāo`, which is how 一 is said when digits are read out one at a time.
+ *
+ * 110 is `yāo yāo líng` and 120 is `yāo èr líng`, because `yī` and `qī` are
+ * hard to tell apart over a bad line. It is a reading of the digit rather than
+ * a different digit — 一 is still written — and it belongs to phone numbers,
+ * room numbers and the like rather than to counting, which is why it is a
+ * separate reading here and an option rather than a rule.
+ */
+export declare function yaoSyllable(): Syllable | undefined;
+//# sourceMappingURL=characters.d.ts.map

package/dist/numerals/characters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"characters.d.ts","sourceRoot":"","sources":["../../src/numerals/characters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,gBAAgB,iEAAe,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAMlD,CAAC;AAyCH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAGvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,QAAQ,GAAG,SAAS,CAElD"}

package/dist/numerals/characters.js

@@ -0,0 +1,80 @@
+import { readSyllable } from "../syllable/syllable.js";
+/**
+ * The 汉字 a digit is written with, indexed by its value.
+ */
+export const DIGIT_CHARACTERS = "零一二三四五六七八九";
+/**
+ * The other 汉字 a written number is made of, and what each is worth.
+ *
+ * 十, 百 and 千 are the places inside a group of four; 万 and 亿 are the group
+ * separators, which is what makes Chinese numbers myriad-grouped rather than
+ * thousand-grouped: 12,345 is 一万二千三百四十五, one 万 and 2,345.
+ */
+export const UNIT_VALUES = new Map([
+    ["十", 10],
+    ["百", 100],
+    ["千", 1000],
+    ["万", 10_000],
+    ["亿", 100_000_000],
+]);
+/**
+ * Every character a number can be written with, and how it is read.
+ *
+ * This is the whole of the numerals' data — twenty-odd readings, carried here
+ * rather than looked up, because reading a number needs no dictionary and a
+ * package that needed one for it would be the wrong shape. Readings are
+ * underlying*: 一 is `yī` and 不 would be `bù`, with the contextual tone left
+ * to the sandhi pass, exactly as the dictionary stores them.
+ */
+const READINGS = new Map([
+    ["零", "líng"],
+    ["〇", "líng"],
+    ["一", "yī"],
+    ["二", "èr"],
+    ["两", "liǎng"],
+    ["兩", "liǎng"],
+    ["三", "sān"],
+    ["四", "sì"],
+    ["五", "wǔ"],
+    ["六", "liù"],
+    ["七", "qī"],
+    ["八", "bā"],
+    ["九", "jiǔ"],
+    ["十", "shí"],
+    ["百", "bǎi"],
+    ["千", "qiān"],
+    ["万", "wàn"],
+    ["萬", "wàn"],
+    ["亿", "yì"],
+    ["億", "yì"],
+    ["点", "diǎn"],
+    ["點", "diǎn"],
+    ["负", "fù"],
+    ["負", "fù"],
+    ["分", "fēn"],
+    ["之", "zhī"],
+    ["百分之", "bǎi fēn zhī"],
+]);
+/**
+ * Read one numeral character.
+ *
+ * Undefined for anything that is not one, which is how a caller tells a
+ * numeral apart from the text around it.
+ */
+export function numeralSyllable(character) {
+    const spelling = READINGS.get(character);
+    return spelling === undefined ? undefined : readSyllable(spelling);
+}
+/**
+ * `yāo`, which is how 一 is said when digits are read out one at a time.
+ *
+ * 110 is `yāo yāo líng` and 120 is `yāo èr líng`, because `yī` and `qī` are
+ * hard to tell apart over a bad line. It is a reading of the digit rather than
+ * a different digit — 一 is still written — and it belongs to phone numbers,
+ * room numbers and the like rather than to counting, which is why it is a
+ * separate reading here and an option rather than a rule.
+ */
+export function yaoSyllable() {
+    return readSyllable("yāo");
+}
+//# sourceMappingURL=characters.js.map

package/dist/numerals/characters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"characters.js","sourceRoot":"","sources":["../../src/numerals/characters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAiB,MAAM,yBAAyB,CAAC;AAEtE;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAgC,IAAI,GAAG,CAAC;IAC9D,CAAC,GAAG,EAAE,EAAE,CAAC;IACT,CAAC,GAAG,EAAE,GAAG,CAAC;IACV,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,WAAW,CAAC;CACnB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,QAAQ,GAAgC,IAAI,GAAG,CAAC;IACpD,CAAC,GAAG,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,OAAO,CAAC;IACd,CAAC,GAAG,EAAE,OAAO,CAAC;IACd,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,IAAI,CAAC;IACX,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,GAAG,EAAE,KAAK,CAAC;IACZ,CAAC,KAAK,EAAE,aAAa,CAAC;CACvB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC"}

package/dist/numerals/numerals.d.ts

@@ -0,0 +1,76 @@
+import type { Syllable } from "../syllable/syllable.js";
+import { type CardinalOptions } from "./cardinal.js";
+/**
+ * How a number is said: as a quantity, or digit by digit.
+ *
+ * The distinction is the whole of this module's difficulty, because the *same*
+ * digits go both ways depending on what they are counting. 2026年 is
+ * `èr líng èr liù nián`, read out one digit at a time, and 2026个 is
+ * `liǎng qiān líng èr shí liù gè`, counted. Nothing about the number says
+ * which; only what follows it does, so the choice belongs to the caller and
+ * this module will do either.
+ */
+export type NumeralStyle = "cardinal" | "digits";
+/**
+ * How a number should be written and read.
+ */
+export interface NumeralOptions extends CardinalOptions {
+    /** Defaults to `cardinal`. */
+    readonly style?: NumeralStyle;
+    /**
+     * Whether 1 is read `yāo` when the digits are read out one at a time.
+     *
+     * Off by default and meaningless outside `digits`. 110 is `yāo yāo líng` and
+     * a room number is said the same way, because `yī` and `qī` are hard to tell
+     * apart down a bad line — but 2019 is `èr líng yī jiǔ` with an ordinary `yī`,
+     * so this is a property of what is being said rather than of the digits.
+     */
+    readonly yao?: boolean;
+    /**
+     * Which zero the digit style writes. Defaults to 〇, as dates and years do.
+     */
+    readonly zero?: "零" | "〇";
+}
+/**
+ * Write a number in 汉字: 12345 → 一万二千三百四十五, or 一二三四五.
+ *
+ * Undefined for anything that is not a number, and for a `cardinal` whose whole
+ * part is too large to write — a digit string is not limited that way, since
+ * reading digits out needs no arithmetic at all.
+ *
+ * The fractional part is always read digit by digit whatever the style, because
+ * that is how it is said: 3.14 is 三点一四 and never 三点十四.
+ */
+export declare function numeralHanzi(value: string | number, options?: NumeralOptions): string | undefined;
+/**
+ * Read written numeral 汉字 as syllables.
+ *
+ * Undefined where the text holds anything that is not a numeral character, so a
+ * caller can tell "not a number" from a number that reads oddly.
+ */
+export declare function readNumeralHanzi(hanzi: string, options?: NumeralOptions): readonly Syllable[] | undefined;
+/**
+ * Read a number as syllables: 2019 as `èr líng yī jiǔ`, or as a quantity.
+ *
+ * The readings are *underlying*, as the dictionary's are — 一 is `yī` however
+ * it will be said in context — so a caller assembling a longer utterance runs
+ * the sandhi pass over the result and gets `yìbǎi` and `yí gè` from it. That is
+ * the same contract `decodeRun` has, and it is what keeps a number from having
+ * to know what follows it.
+ */
+export declare function readNumeral(value: string | number, options?: NumeralOptions): readonly Syllable[] | undefined;
+/**
+ * Write a percentage the way it is said: 95% → 百分之九十五.
+ *
+ * The order reverses — "of a hundred parts, ninety-five" — which is why this
+ * cannot be left to whoever writes the number and the sign separately.
+ */
+export declare function percentHanzi(value: string | number, options?: NumeralOptions): string | undefined;
+/**
+ * Write a fraction the way it is said: 3/4 → 四分之三.
+ *
+ * Same reversal as a percentage, of which this is the general case: the
+ * denominator is named first and the numerator second.
+ */
+export declare function fractionHanzi(numerator: string | number, denominator: string | number, options?: NumeralOptions): string | undefined;
+//# sourceMappingURL=numerals.d.ts.map

package/dist/numerals/numerals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numerals.d.ts","sourceRoot":"","sources":["../../src/numerals/numerals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,eAAe,CAAC;AAOvB;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;CAC3B;AAiDD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE,cAAmB,GAC3B,MAAM,GAAG,SAAS,CAqBpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,GAC3B,SAAS,QAAQ,EAAE,GAAG,SAAS,CAajC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE,cAAmB,GAC3B,SAAS,QAAQ,EAAE,GAAG,SAAS,CAGjC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE,cAAmB,GAC3B,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,OAAO,GAAE,cAAmB,GAC3B,MAAM,GAAG,SAAS,CAMpB"}

package/dist/numerals/numerals.js

@@ -0,0 +1,119 @@
+import { toCharacters } from "../script/characters.js";
+import { cardinalHanzi, LARGEST_CARDINAL, } from "./cardinal.js";
+import { DIGIT_CHARACTERS, numeralSyllable, yaoSyllable, } from "./characters.js";
+/**
+ * Anything this module will read: digits, optionally signed and pointed.
+ */
+const NUMBER = /^(?<sign>-?)(?<whole>\d+)(?:\.(?<fraction>\d+))?$/u;
+/**
+ * Take a number apart, keeping the digits exactly as they were written.
+ *
+ * A string rather than a number is the input that carries the most: `007` and
+ * `7` are the same quantity and different digits, and a room number keeps its
+ * zeros. A `number` is stringified first, which is why a caller who cares about
+ * leading zeros should pass the string.
+ */
+function parse(value) {
+    const found = NUMBER.exec(String(value))?.groups;
+    if (found === undefined) {
+        return undefined;
+    }
+    return {
+        isNegative: found["sign"] === "-",
+        whole: found["whole"] ?? "",
+        fraction: found["fraction"] ?? "",
+    };
+}
+/**
+ * Write digits one at a time: 2019 → 二〇一九.
+ */
+function digitsHanzi(digits, zero) {
+    return toCharacters(digits)
+        .map((digit) => digit === "0" ? zero : (DIGIT_CHARACTERS[Number(digit)] ?? digit))
+        .join("");
+}
+/**
+ * Write a number in 汉字: 12345 → 一万二千三百四十五, or 一二三四五.
+ *
+ * Undefined for anything that is not a number, and for a `cardinal` whose whole
+ * part is too large to write — a digit string is not limited that way, since
+ * reading digits out needs no arithmetic at all.
+ *
+ * The fractional part is always read digit by digit whatever the style, because
+ * that is how it is said: 3.14 is 三点一四 and never 三点十四.
+ */
+export function numeralHanzi(value, options = {}) {
+    const parsed = parse(value);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    const { style = "cardinal", zero = "〇" } = options;
+    let whole;
+    if (style === "digits") {
+        whole = digitsHanzi(parsed.whole, zero);
+    }
+    else {
+        const quantity = Number(parsed.whole);
+        if (!Number.isSafeInteger(quantity) || quantity > LARGEST_CARDINAL) {
+            return undefined;
+        }
+        whole = cardinalHanzi(quantity, options);
+    }
+    const point = parsed.fraction === "" ? "" : `点${digitsHanzi(parsed.fraction, "零")}`;
+    return `${parsed.isNegative ? "负" : ""}${whole}${point}`;
+}
+/**
+ * Read written numeral 汉字 as syllables.
+ *
+ * Undefined where the text holds anything that is not a numeral character, so a
+ * caller can tell "not a number" from a number that reads oddly.
+ */
+export function readNumeralHanzi(hanzi, options = {}) {
+    const isYao = options.yao ?? false;
+    const syllables = [];
+    for (const character of toCharacters(hanzi)) {
+        const syllable = isYao && character === "一" ? yaoSyllable() : numeralSyllable(character);
+        if (syllable === undefined) {
+            return undefined;
+        }
+        syllables.push(syllable);
+    }
+    return syllables;
+}
+/**
+ * Read a number as syllables: 2019 as `èr líng yī jiǔ`, or as a quantity.
+ *
+ * The readings are *underlying*, as the dictionary's are — 一 is `yī` however
+ * it will be said in context — so a caller assembling a longer utterance runs
+ * the sandhi pass over the result and gets `yìbǎi` and `yí gè` from it. That is
+ * the same contract `decodeRun` has, and it is what keeps a number from having
+ * to know what follows it.
+ */
+export function readNumeral(value, options = {}) {
+    const hanzi = numeralHanzi(value, options);
+    return hanzi === undefined ? undefined : readNumeralHanzi(hanzi, options);
+}
+/**
+ * Write a percentage the way it is said: 95% → 百分之九十五.
+ *
+ * The order reverses — "of a hundred parts, ninety-five" — which is why this
+ * cannot be left to whoever writes the number and the sign separately.
+ */
+export function percentHanzi(value, options = {}) {
+    const written = numeralHanzi(value, options);
+    return written === undefined ? undefined : `百分之${written}`;
+}
+/**
+ * Write a fraction the way it is said: 3/4 → 四分之三.
+ *
+ * Same reversal as a percentage, of which this is the general case: the
+ * denominator is named first and the numerator second.
+ */
+export function fractionHanzi(numerator, denominator, options = {}) {
+    const top = numeralHanzi(numerator, options);
+    const bottom = numeralHanzi(denominator, options);
+    return top === undefined || bottom === undefined
+        ? undefined
+        : `${bottom}分之${top}`;
+}
+//# sourceMappingURL=numerals.js.map

package/dist/numerals/numerals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numerals.js","sourceRoot":"","sources":["../../src/numerals/numerals.ts"],"names":[],"mappings":"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"}

package/dist/numerals/text.d.ts

@@ -0,0 +1,52 @@
+import { type SandhiOptions } from "../decode/sandhi.js";
+import type { Syllable } from "../syllable/syllable.js";
+import { type NumeralOptions, type NumeralStyle } from "./numerals.js";
+/**
+ * One stretch of text that was never Han, read or left as it was.
+ */
+export interface NumeralSegment {
+    /** The characters this covers, exactly as they were written. */
+    readonly text: string;
+    /** How it is said, where it was read as a number. */
+    readonly reading: readonly Syllable[] | undefined;
+    /** The 汉字 the number would be written with, where it was read. */
+    readonly hanzi: string | undefined;
+    /** How it was read, which decides whether sandhi applies to it. */
+    readonly style: NumeralStyle | undefined;
+    /**
+     * Where the words break, as a syllable count each.
+     *
+     * A counted number is one word and needs none of this. A time is three or
+     * four — 6:30 is `liù diǎn sānshí fēn`, where the hour and the minutes are
+     * numbers and 点 and 分 are not — and nothing in the syllables themselves
+     * says where those breaks are.
+     */
+    readonly words?: readonly number[];
+}
+/**
+ * Split a stretch of non-Han text into what is read and what is not.
+ *
+ * `following` is the first character of the Han that comes after this stretch,
+ * which is the only context a number has: 年 makes 1997 a year and 个 makes 3 a
+ * count. Where there is nothing after it, or nothing that decides, the number
+ * is counted.
+ *
+ * Text that is not a number is returned unread rather than dropped, so the
+ * segments always concatenate back to the input.
+ */
+export declare function readNumbersIn(text: string, following: string, options?: NumeralOptions): readonly NumeralSegment[];
+/**
+ * A number as it is said, with the sandhi a counted quantity takes.
+ *
+ * Two things decide how much of it assimilates. A number read out digit by
+ * digit does not at all — 110 is `yāo yāo líng` and never `yì yì líng` —
+ * and in a counted one the sandhi stops at the 点, since everything after the
+ * decimal point is read digit by digit whatever the style: 3.14 is
+ * `sān diǎn yī sì`.
+ *
+ * `following` is the syllable after the number, which is what a 一 at the end
+ * of it assimilates to: the 一 of 一个 is `yí` because 个 is a fourth tone, and
+ * that tone is in the next run rather than in the number.
+ */
+export declare function saidNumeral(segment: NumeralSegment, following: Syllable | undefined, sandhi: SandhiOptions | undefined): readonly Syllable[];
+//# sourceMappingURL=text.d.ts.map

package/dist/numerals/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/numerals/text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,YAAY,EAGlB,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;IAClD,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAsMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,cAAmB,GAC3B,SAAS,cAAc,EAAE,CA2C3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,QAAQ,GAAG,SAAS,EAC/B,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,SAAS,QAAQ,EAAE,CAUrB"}