n2words 1.23.0 → 1.24.0

package/lib/languages/pl.js

@@ -0,0 +1,189 @@
+import SlavicLanguage from '../classes/slavic-language.js'
+
+/**
+ * @typedef {Object} SlavicOptions
+ * @property {boolean} [feminine=false] Use feminine forms for numbers.
+ */
+
+/**
+ * Polish language converter.
+ *
+ * Implements Polish number words using the Slavic language pattern:
+ * - Polish number words (jeden, dwa, trzy, cztery, pięć...)
+ * - Complex Slavic three-form pluralization (tysiąc/tysiące/tysięcy)
+ * - Polish-specific declension patterns
+ * - Distinctive Polish phonology and orthography
+ *
+ * Key Features:
+ * - Three-form pluralization system shared across Slavic languages
+ *   * Form 1 (singular): 1 (e.g., "tysiąc")
+ *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "tysiące")
+ *   * Form 3 (many): all other numbers (e.g., "tysięcy")
+ * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
+ * - Large number handling via thousands[] array with indexed [singular, few, many] forms
+ *
+ * Features:
+ * - Polish diacritical marks (ą, ć, ę, ł, ń, ś, ź, ż)
+ * - Gender and case agreement
+ * - Polish-specific number word endings
+ *
+ * Inherits from SlavicLanguage for complex pluralization algorithms.
+ */
+export class Polish extends SlavicLanguage {
+  negativeWord = 'minus'
+  decimalSeparatorWord = 'przecinek'
+  zeroWord = 'zero'
+  ones = {
+    1: 'jeden',
+    2: 'dwa',
+    3: 'trzy',
+    4: 'cztery',
+    5: 'pięć',
+    6: 'sześć',
+    7: 'siedem',
+    8: 'osiem',
+    9: 'dziewięć'
+  }
+
+  tens = {
+    0: 'dziesięć',
+    1: 'jedenaście',
+    2: 'dwanaście',
+    3: 'trzynaście',
+    4: 'czternaście',
+    5: 'piętnaście',
+    6: 'szesnaście',
+    7: 'siedemnaście',
+    8: 'osiemnaście',
+    9: 'dziewiętnaście'
+  }
+
+  twenties = {
+    2: 'dwadzieścia',
+    3: 'trzydzieści',
+    4: 'czterdzieści',
+    5: 'pięćdziesiąt',
+    6: 'sześćdziesiąt',
+    7: 'siedemdziesiąt',
+    8: 'osiemdziesiąt',
+    9: 'dziewięćdziesiąt'
+  }
+
+  hundreds = {
+    1: 'sto',
+    2: 'dwieście',
+    3: 'trzysta',
+    4: 'czterysta',
+    5: 'pięćset',
+    6: 'sześćset',
+    7: 'siedemset',
+    8: 'osiemset',
+    9: 'dziewięćset'
+  }
+
+  thousands = {
+    1: ['tysiąc', 'tysiące', 'tysięcy'], // 10^ 3
+    2: ['milion', 'miliony', 'milionów'], // 10^ 6
+    3: ['miliard', 'miliardy', 'miliardów'], // 10^ 9
+    4: ['bilion', 'biliony', 'bilionów'], // 10^ 12
+    5: ['biliard', 'biliardy', 'biliardów'], // 10^ 15
+    6: ['trylion', 'tryliony', 'trylionów'], // 10^ 18
+    7: ['tryliard', 'tryliardy', 'tryliardów'], // 10^ 21
+    8: ['kwadrylion', 'kwadryliony', 'kwadrylionów'], // 10^ 24
+    9: ['kwaryliard', 'kwadryliardy', 'kwadryliardów'], // 10^ 27
+    10: ['kwintylion', 'kwintyliony', 'kwintylionów'] // 10^ 30
+  }
+
+  /**
+   * Implements Polish-specific three-form pluralization rules.
+   *
+   * Polish three-form system:
+   * - Form 1 (singular): exactly n=1 (e.g., "tysiąc")
+   * - Form 2 (few): n ends in 2-4, excluding teens (22-24, 32-34...) (e.g., "tysiące")
+   * - Form 3 (many): all other numbers (e.g., "tysięcy")
+   *
+   * @param {bigint} n The number to classify.
+   * @param {Array<string>} forms Array of [singular, few, many] word forms.
+   * @returns {string} The appropriate form for the number n.
+   */
+  pluralize (n, forms) {
+    if (n === 1n) {
+      return forms[0]
+    }
+
+    const lastDigit = n % 10n
+    const lastTwoDigits = n % 100n
+
+    if (lastDigit < 5n && lastDigit > 1n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
+      return forms[1]
+    }
+
+    return forms[2]
+  }
+
+  /**
+   * Converts a whole number to Polish cardinal form.
+   *
+   * Algorithm (chunk-based decomposition):
+   * 1. Split number into chunks of 3 digits (right-to-left): ones, thousands, millions, etc.
+   * 2. For each non-zero chunk:
+   *    a. Extract hundreds digit (n3), tens digit (n2), ones digit (n1)
+   *    b. Add hundreds word (e.g., "sto", "dwieście")
+   *    c. Add tens/ones (handles teens 10-19 separately from compound tens)
+   *    d. Add pluralized magnitude word (e.g., "tysiące", "miliony")
+   * 3. Join all words with spaces
+   *
+   * Example: 1234 → chunks [1, 234] → "jeden tysiąc dwieście trzydzieści cztery"
+   *   - Chunk 1 (index=1, thousands): "jeden" + "tysiąc"
+   *   - Chunk 234 (index=0): "dwieście" + "trzydzieści" + "cztery"
+   *
+   * Special case: When chunk=1 at thousands+ levels, omit the ones word to avoid
+   * redundancy with the pluralized magnitude (e.g., just "tysiąc" not "jeden tysiąc").
+   *
+   * @param {bigint} number The whole number to convert.
+   * @returns {string} The number expressed in Polish words.
+   */
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+    const words = []
+    const chunks = this.splitByX(number.toString(), 3)
+    let index = chunks.length
+    for (const x of chunks) {
+      index = index - 1
+      if (x === 0n) {
+        continue
+      }
+      const [n1, n2, n3] = this.getDigits(x)
+      if (n3 > 0n) {
+        words.push(this.hundreds[n3])
+      }
+      if (n2 > 1n) {
+        words.push(this.twenties[n2])
+      }
+      if (n2 === 1n) {
+        words.push(this.tens[n1])
+      } else if (n1 > 0n && !(index > 0 && x === 1n)) {
+        words.push(this.ones[n1])
+      }
+      if (index > 0) {
+        words.push(this.pluralize(x, this.thousands[index]))
+      }
+    }
+    return words.join(' ')
+  }
+}
+
+/**
+ * Converts a number to Polish cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {SlavicOptions} [options={}] Configuration options.
+ * @returns {string} The number expressed in Polish words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords (value, options = {}) {
+  return new Polish(options).convertToWords(value)
+}

package/lib/languages/pt.js

@@ -0,0 +1,147 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * (European) Portuguese language converter.
+ *
+ * Features:
+ * - Gender-aware hundreds (hundredos, duzentos, etc.)
+ * - Million/Billion pluralization
+ * - "e" (and) conjunction for number combinations
+ * - Post-processing to normalize word flow
+ */
+export class Portuguese extends GreedyScaleLanguage {
+  negativeWord = 'menos'
+  decimalSeparatorWord = 'vírgula'
+  zeroWord = 'zero'
+  scaleWordPairs = [
+    [1_000_000_000_000_000_000_000_000n, 'quatrilião'],
+    [1_000_000_000_000_000_000n, 'trilião'],
+    [1_000_000_000_000n, 'bilião'],
+    [1_000_000n, 'milião'],
+    [1000n, 'mil'],
+    [100n, 'cem'],
+    [90n, 'noventa'],
+    [80n, 'oitenta'],
+    [70n, 'setenta'],
+    [60n, 'sessenta'],
+    [50n, 'cinquenta'],
+    [40n, 'quarenta'],
+    [30n, 'trinta'],
+    [20n, 'vinte'],
+    [19n, 'dezanove'],
+    [18n, 'dezoito'],
+    [17n, 'dezassete'],
+    [16n, 'dezasseis'],
+    [15n, 'quinze'],
+    [14n, 'catorze'],
+    [13n, 'treze'],
+    [12n, 'doze'],
+    [11n, 'onze'],
+    [10n, 'dez'],
+    [9n, 'nove'],
+    [8n, 'oito'],
+    [7n, 'sete'],
+    [6n, 'seis'],
+    [5n, 'cinco'],
+    [4n, 'quatro'],
+    [3n, 'três'],
+    [2n, 'dois'],
+    [1n, 'um'],
+    [0n, 'zero']
+  ]
+
+  hundreds = {
+    1: 'cento',
+    2: 'duzentos',
+    3: 'trezentos',
+    4: 'quatrocentos',
+    5: 'quinhentos',
+    6: 'seiscentos',
+    7: 'setecentos',
+    8: 'oitocentos',
+    9: 'novecentos'
+  }
+
+  // Pre-compiled regex patterns for postClean - avoid recompilation
+  static POSTCLEAN_REGEX = / e (.*entos?) (?=.*e)/g
+
+  finalizeWords (words) {
+    return words.replaceAll(Portuguese.POSTCLEAN_REGEX, ' $1 ')
+  }
+
+  /**
+   * Merges two adjacent word-number pairs according to Portuguese grammar rules.
+   *
+   * Portuguese-specific rules:
+   * - Implicit "um": `mergeScales({ 'um': 1n }, { 'mil': 1000n })` → `{ 'mil': 1000n }`
+   * - "e" (and) between most combinations: `mergeScales({ 'vinte': 20n }, { 'três': 3n })` → `{ 'vinte e três': 23n }`
+   * - Special handling: "cem" (100) becomes "cento" when followed by non-thousands
+   * - Gender-aware hundreds: "duzentos", "trezentos", etc.
+   * - Million pluralization: "milhões" instead of "milhão" when coefficient > 1
+   * - Post-processing with postClean() to normalize word flow
+   *
+   * @param {Object} current The left operand as `{ word: BigInt }`.
+   * @param {Object} next The right operand as `{ word: BigInt }`.
+   * @returns {Object} Merged pair with combined word and resulting numeric value.
+   *
+   * @example
+   * mergeScales({ 'um': 1n }, { 'mil': 1000n }); // { 'mil': 1000n }
+   * mergeScales({ 'vinte': 20n }, { 'dois': 2n }); // { 'vinte e dois': 22n }
+   */
+  mergeScales (current, next) {
+    // Extract words and numeric values
+    let cText = Object.keys(current)[0]
+    let nText = Object.keys(next)[0]
+    const cNumber = Object.values(current)[0] // BigInt
+    const nNumber = Object.values(next)[0] // BigInt
+
+    // Implicit "um": omit before millions ("um milhão" → "milhão")
+    if (cNumber === 1n) {
+      if (nNumber < 1_000_000n) return { [nText]: nNumber }
+      cText = 'um'
+    } else if (cNumber === 100n && nNumber % 1000n !== 0n) {
+      // Special handling: "cem" (100) becomes "cento" when followed by non-thousands
+      cText = 'cento'
+    }
+
+    if (nNumber < cNumber) {
+      return { [`${cText} e ${nText}`]: cNumber + nNumber }
+    }
+
+    // Handle "milião" -> "milhão" conversion
+    if (nText === 'milião') nText = 'milhão'
+
+    // Pluralization logic for large numbers
+    if (cNumber > 1n) {
+      if (nNumber % 1_000_000_000n === 0n) {
+        nText = nText.replace('bilião', 'biliões')
+      } else if (nNumber % 1_000_000n === 0n) {
+        nText = nText.replace('milhão', 'milhões')
+      }
+    }
+
+    if (nNumber === 100n) {
+      cText = this.hundreds[cNumber]
+      return { [`${cText}`]: cNumber * nNumber }
+    }
+
+    return { [`${cText} ${nText}`]: cNumber * nNumber }
+  }
+}
+
+/**
+ * Converts a number to Portuguese cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see Portuguese class options).
+ * @returns {string} The number expressed in Portuguese words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42); // 'quarenta e dois'
+ * convertToWords('100.5'); // 'cem vírgula cinco'
+ */
+export default function convertToWords (value, options = {}) {
+  return new Portuguese(options).convertToWords(value)
+}