n2words 1.23.1 → 2.0.0

package/lib/languages/zh-Hant.js

@@ -0,0 +1,111 @@
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
+
+/**
+ * Traditional Chinese language converter.
+ *
+ * Supports:
+ * - Traditional Chinese characters (繁體中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
+ */
+export class TraditionalChinese extends GreedyScaleLanguage {
+  negativeWord = '負'
+  decimalSeparatorWord = '點'
+  zeroWord = '零'
+  wordSeparator = ''
+
+  constructor (options = {}) {
+    super()
+
+    this.setOptions({
+      formal: true
+    }, options)
+
+    if (this.options.formal) {
+      this.scaleWords = [
+        [1_000_000_000_000n, '萬'],
+        [100_000_000n, '億'],
+        [10_000n, '萬'],
+        [1000n, '仟'],
+        [100n, '佰'],
+        [10n, '拾'],
+        [9n, '玖'],
+        [8n, '捌'],
+        [7n, '柒'],
+        [6n, '陸'],
+        [5n, '伍'],
+        [4n, '肆'],
+        [3n, '參'],
+        [2n, '貳'],
+        [1n, '壹'],
+        [0n, '零']
+      ]
+    } else {
+      this.scaleWords = [
+        [1_000_000_000_000n, '萬'],
+        [100_000_000n, '億'],
+        [10_000n, '萬'],
+        [1000n, '千'],
+        [100n, '百'],
+        [10n, '十'],
+        [9n, '九'],
+        [8n, '八'],
+        [7n, '七'],
+        [6n, '六'],
+        [5n, '五'],
+        [4n, '四'],
+        [3n, '三'],
+        [2n, '二'],
+        [1n, '一'],
+        [0n, '零']
+      ]
+    }
+  }
+
+  /** Combines two word-sets with Traditional Chinese grammar rules and zero insertion. */
+  combineWordSets (preceding, following) {
+    const precedingWord = Object.keys(preceding)[0]
+    const precedingValue = Object.values(preceding)[0]
+    const followingWord = Object.keys(following)[0]
+    const followingValue = Object.values(following)[0]
+
+    // Implicit one: omit 1 before single digits (< 10)
+    if (precedingValue === 1n && followingValue < 10n) {
+      return following
+    }
+
+    // Multiply when following > preceding (scale words like 千, 萬, 億)
+    if (followingValue > precedingValue) {
+      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
+    }
+
+    // Insert "零" (zero) when position skip levels (e.g., 1003 = 千零三)
+    // zeroDigit() checks if gap exists between preceding and following magnitude
+    if (this.zeroDigit(precedingValue) > this.digit(followingValue)) {
+      return { [`${precedingWord}${this.zeroWord}${followingWord}`]: precedingValue + followingValue }
+    }
+
+    // Default: concatenate without zero insertion
+    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
+  }
+
+  /** Returns the number of digits in a number. */
+  digit (number_) {
+    return number_.toString().length
+  }
+
+  /** Counts the number of zero digits in a number. */
+  zeroDigit (number_) {
+    return [...number_.toString()].filter(c => c === '0').length
+  }
+
+  /** Converts decimal digits to words by reading each digit individually. */
+  decimalDigitsToWords (decimalString) {
+    const words = []
+    for (let i = 0; i < decimalString.length; i++) {
+      const digitValue = BigInt(decimalString[i])
+      words.push(this.integerToWords(digitValue))
+    }
+    return words
+  }
+}

package/lib/n2words.d.ts

@@ -1,9 +1,209 @@
-export default floatToCardinal;
 /**
- * Converts a number to written form.
- * @param {number|string|bigint} value The number to convert.
- * @param {object} [options] User options.
- * @returns {string} Value in written format.
- * TODO [2024-06] Migrate to object destructing for parameters
+ * Numeric value that can be converted to words.
+ * Accepts number, bigint, or numeric string representations.
  */
-declare function floatToCardinal(value: number | string | bigint, options?: object): string;
+export type NumericValue = number | bigint | string;
+export type ArabicOptions = {
+    /**
+     * Word for negative numbers
+     */
+    negativeWord?: string | undefined;
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type BiblicalHebrewOptions = {
+    /**
+     * Conjunction character (typically 'ו' for and)
+     */
+    andWord?: string | undefined;
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type CroatianOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type CzechOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type DanishOptions = {
+    /**
+     * Enable ordinal number conversion
+     */
+    ordFlag?: boolean | undefined;
+};
+export type DutchOptions = {
+    /**
+     * Include optional "en" separator
+     */
+    includeOptionalAnd?: boolean | undefined;
+    /**
+     * Disable hundred-pairing (e.g., "twelve hundred" becomes "one thousand two hundred")
+     */
+    noHundredPairing?: boolean | undefined;
+    /**
+     * Use accented "één" for one
+     */
+    accentOne?: boolean | undefined;
+};
+export type FrenchOptions = {
+    /**
+     * Use hyphens (true) instead of spaces (false) in compounds
+     */
+    withHyphenSeparator?: boolean | undefined;
+};
+export type FrenchBelgiumOptions = {
+    /**
+     * Use hyphens (true) instead of spaces (false) in compounds
+     */
+    withHyphenSeparator?: boolean | undefined;
+};
+export type HebrewOptions = {
+    /**
+     * Conjunction character (typically 'ו' for and)
+     */
+    andWord?: string | undefined;
+};
+export type LatvianOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type LithuanianOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type PolishOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type RomanianOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type RussianOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type SerbianCyrillicOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type SerbianLatinOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type SimplifiedChineseOptions = {
+    /**
+     * Use formal/financial numerals (壹贰叁) vs. common numerals (一二三)
+     */
+    formal?: boolean | undefined;
+};
+export type SpanishOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type TraditionalChineseOptions = {
+    /**
+     * Use formal/financial numerals (壹貳參) vs. common numerals (一二三)
+     */
+    formal?: boolean | undefined;
+};
+export type TurkishOptions = {
+    /**
+     * Remove spaces between words if true
+     */
+    dropSpaces?: boolean | undefined;
+};
+export type UkrainianOptions = {
+    /**
+     * Grammatical gender for number forms
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type ParsedNumericValue = {
+    /**
+     * - Whether the value is negative
+     */
+    isNegative: boolean;
+    /**
+     * - The absolute integer part
+     */
+    integerPart: bigint;
+    /**
+     * - The decimal digits (without the point)
+     */
+    decimalPart?: string | undefined;
+};
+export const ArabicConverter: (value: NumericValue, options?: ArabicOptions) => string;
+export const AzerbaijaniConverter: (value: NumericValue) => string;
+export const BanglaConverter: (value: NumericValue) => string;
+export const BiblicalHebrewConverter: (value: NumericValue, options?: BiblicalHebrewOptions) => string;
+export const CroatianConverter: (value: NumericValue, options?: CroatianOptions) => string;
+export const CzechConverter: (value: NumericValue, options?: CzechOptions) => string;
+export const DanishConverter: (value: NumericValue, options?: DanishOptions) => string;
+export const DutchConverter: (value: NumericValue, options?: DutchOptions) => string;
+export const EnglishConverter: (value: NumericValue) => string;
+export const FilipinoConverter: (value: NumericValue) => string;
+export const FrenchConverter: (value: NumericValue, options?: FrenchOptions) => string;
+export const FrenchBelgiumConverter: (value: NumericValue, options?: FrenchBelgiumOptions) => string;
+export const GermanConverter: (value: NumericValue) => string;
+export const GreekConverter: (value: NumericValue) => string;
+export const GujaratiConverter: (value: NumericValue) => string;
+export const HebrewConverter: (value: NumericValue, options?: HebrewOptions) => string;
+export const HindiConverter: (value: NumericValue) => string;
+export const HungarianConverter: (value: NumericValue) => string;
+export const IndonesianConverter: (value: NumericValue) => string;
+export const ItalianConverter: (value: NumericValue) => string;
+export const JapaneseConverter: (value: NumericValue) => string;
+export const KannadaConverter: (value: NumericValue) => string;
+export const KoreanConverter: (value: NumericValue) => string;
+export const LatvianConverter: (value: NumericValue, options?: LatvianOptions) => string;
+export const LithuanianConverter: (value: NumericValue, options?: LithuanianOptions) => string;
+export const MalayConverter: (value: NumericValue) => string;
+export const MarathiConverter: (value: NumericValue) => string;
+export const NorwegianBokmalConverter: (value: NumericValue) => string;
+export const PersianConverter: (value: NumericValue) => string;
+export const PolishConverter: (value: NumericValue, options?: PolishOptions) => string;
+export const PortugueseConverter: (value: NumericValue) => string;
+export const PunjabiConverter: (value: NumericValue) => string;
+export const RomanianConverter: (value: NumericValue, options?: RomanianOptions) => string;
+export const RussianConverter: (value: NumericValue, options?: RussianOptions) => string;
+export const SerbianCyrillicConverter: (value: NumericValue, options?: SerbianCyrillicOptions) => string;
+export const SerbianLatinConverter: (value: NumericValue, options?: SerbianLatinOptions) => string;
+export const SimplifiedChineseConverter: (value: NumericValue, options?: SimplifiedChineseOptions) => string;
+export const SpanishConverter: (value: NumericValue, options?: SpanishOptions) => string;
+export const SwahiliConverter: (value: NumericValue) => string;
+export const SwedishConverter: (value: NumericValue) => string;
+export const TamilConverter: (value: NumericValue) => string;
+export const TeluguConverter: (value: NumericValue) => string;
+export const ThaiConverter: (value: NumericValue) => string;
+export const TraditionalChineseConverter: (value: NumericValue, options?: TraditionalChineseOptions) => string;
+export const TurkishConverter: (value: NumericValue, options?: TurkishOptions) => string;
+export const UkrainianConverter: (value: NumericValue, options?: UkrainianOptions) => string;
+export const UrduConverter: (value: NumericValue) => string;
+export const VietnameseConverter: (value: NumericValue) => string;