n2words 1.24.0 → 3.0.0

package/lib/languages/pl.js

@@ -1,189 +1,330 @@
-import SlavicLanguage from '../classes/slavic-language.js'
+/**
+ * Polish language converter - Functional Implementation
+ *
+ * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
+ *
+ * Key optimization: Precompute all segment values (0-999) at module load.
+ * This eliminates all per-call string manipulation for segment conversion.
+ *
+ * Polish-specific rules (handled in precomputation):
+ * - Three-form pluralization: 1 = singular, 2-4 = few, 5+ = many
+ * - Gender agreement (masculine/feminine for numbers < 1000)
+ * - Omit "jeden" before scale words (tysiąc, milion, etc.)
+ * - Irregular hundreds: dwieście, trzysta, czterysta, pięćset...
+ * - Long scale with -ard forms: miliard, biliard, tryliard
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES_MASC = ['', 'jeden', 'dwa', 'trzy', 'cztery', 'pięć', 'sześć', 'siedem', 'osiem', 'dziewięć']
+const ONES_FEM = ['', 'jedna', 'dwie', 'trzy', 'cztery', 'pięć', 'sześć', 'siedem', 'osiem', 'dziewięć']
+
+const TEENS = ['dziesięć', 'jedenaście', 'dwanaście', 'trzynaście', 'czternaście', 'piętnaście', 'szesnaście', 'siedemnaście', 'osiemnaście', 'dziewiętnaście']
+
+const TENS = ['', '', 'dwadzieścia', 'trzydzieści', 'czterdzieści', 'pięćdziesiąt', 'sześćdziesiąt', 'siedemdziesiąt', 'osiemdziesiąt', 'dziewięćdziesiąt']
+
+// Irregular hundreds
+const HUNDREDS = ['', 'sto', 'dwieście', 'trzysta', 'czterysta', 'pięćset', 'sześćset', 'siedemset', 'osiemset', 'dziewięćset']
+
+// Scale words: [singular, few (2-4), many (5+)]
+const PLURAL_FORMS = {
+  1: ['tysiąc', 'tysiące', 'tysięcy'],
+  2: ['milion', 'miliony', 'milionów'],
+  3: ['miliard', 'miliardy', 'miliardów'],
+  4: ['bilion', 'biliony', 'bilionów'],
+  5: ['biliard', 'biliardy', 'biliardów'],
+  6: ['trylion', 'tryliony', 'trylionów'],
+  7: ['tryliard', 'tryliardy', 'tryliardów'],
+  8: ['kwadrylion', 'kwadryliony', 'kwadrylionów'],
+  9: ['kwaryliard', 'kwadryliardy', 'kwadryliardów'],
+  10: ['kwintylion', 'kwintyliony', 'kwintylionów']
+}
+
+const ZERO = 'zero'
+const NEGATIVE = 'minus'
+const DECIMAL_SEP = 'przecinek'
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
 
 /**
- * @typedef {Object} SlavicOptions
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
+ * Builds segment word for 0-999 (masculine form).
+ * @param {number} n - Segment value
+ * @returns {string} Polish word
  */
+function buildSegment (n) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tens = Math.floor(n / 10) % 10
+  const hundreds = Math.floor(n / 100)
+
+  const parts = []
+
+  // Hundreds
+  if (hundreds > 0) {
+    parts.push(HUNDREDS[hundreds])
+  }
+
+  // Tens and ones
+  if (tens === 1) {
+    // Teens (10-19)
+    parts.push(TEENS[ones])
+  } else {
+    if (tens >= 2) {
+      parts.push(TENS[tens])
+    }
+    if (ones > 0) {
+      parts.push(ONES_MASC[ones])
+    }
+  }
+
+  return parts.join(' ')
+}
 
 /**
- * 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.
+ * Builds segment word for 0-999 (feminine form - only differs in ones).
+ * @param {number} n - Segment value
+ * @returns {string} Polish word
  */
-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ęć'
+function buildSegmentFeminine (n) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tens = Math.floor(n / 10) % 10
+  const hundreds = Math.floor(n / 100)
+
+  const parts = []
+
+  // Hundreds
+  if (hundreds > 0) {
+    parts.push(HUNDREDS[hundreds])
   }
 
-  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'
+  // Tens and ones - feminine for ones only
+  if (tens === 1) {
+    parts.push(TEENS[ones])
+  } else {
+    if (tens >= 2) {
+      parts.push(TENS[tens])
+    }
+    if (ones > 0) {
+      parts.push(ONES_FEM[ones])
+    }
   }
 
-  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'
+  return parts.join(' ')
+}
+
+// Precompute all 1000 segment words (0-999)
+const SEGMENTS_MASC = new Array(1000)
+const SEGMENTS_FEM = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS_MASC[i] = buildSegment(i)
+  SEGMENTS_FEM[i] = buildSegmentFeminine(i)
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Polish pluralization: 1 = singular, 2-4 = few, else = many.
+ * Special case: 11-19 always use many form.
+ *
+ * @param {bigint} n - Number to pluralize
+ * @param {string[]} forms - [singular, few, many]
+ * @returns {string} Correct plural form
+ */
+function pluralize (n, forms) {
+  if (n === 1n) {
+    return forms[0]
   }
 
-  hundreds = {
-    1: 'sto',
-    2: 'dwieście',
-    3: 'trzysta',
-    4: 'czterysta',
-    5: 'pięćset',
-    6: 'sześćset',
-    7: 'siedemset',
-    8: 'osiemset',
-    9: 'dziewięćset'
+  const lastDigit = n % 10n
+  const lastTwoDigits = n % 100n
+
+  // Teens (11-19) always use many form
+  // 2-4 use few form (but not 12-14)
+  if (lastDigit >= 2n && lastDigit <= 4n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
+    return forms[1]
   }
 
-  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
+  return forms[2]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Polish words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {Object} options - Conversion options
+ * @returns {string} Polish words
+ */
+function integerToWords (n, options = {}) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    const segments = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
+    return segments[Number(n)]
   }
 
-  /**
-   * 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]
-    }
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    const scaleWord = pluralize(BigInt(thousands), PLURAL_FORMS[1])
 
-    const lastDigit = n % 10n
-    const lastTwoDigits = n % 100n
+    let result
+    if (thousands === 1) {
+      // Omit "jeden" before tysiąc
+      result = scaleWord
+    } else {
+      result = SEGMENTS_MASC[thousands] + ' ' + scaleWord
+    }
 
-    if (lastDigit < 5n && lastDigit > 1n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
-      return forms[1]
+    if (remainder > 0) {
+      result += ' ' + SEGMENTS_MASC[remainder]
     }
 
-    return forms[2]
+    return result
   }
 
-  /**
-   * 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]))
+  // For numbers >= 1,000,000, use scale decomposition
+  return buildLargeNumberWords(n, options)
+}
+
+/**
+ * Builds words for numbers >= 1,000,000.
+ * Uses BigInt division for faster segment extraction.
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @param {Object} options - Conversion options
+ * @returns {string} Polish words
+ */
+function buildLargeNumberWords (n, options) {
+  // Extract segments using BigInt division (faster than string slicing)
+  // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
+  const segmentValues = []
+  let temp = n
+  while (temp > 0n) {
+    segmentValues.push(temp % 1000n)
+    temp = temp / 1000n
+  }
+
+  // Build result string directly
+  let result = ''
+
+  for (let i = segmentValues.length - 1; i >= 0; i--) {
+    const segment = segmentValues[i]
+    if (segment === 0n) continue
+
+    const segmentWord = SEGMENTS_MASC[Number(segment)]
+
+    if (result) result += ' '
+
+    if (i === 0) {
+      // Units segment
+      result += segmentWord
+    } else {
+      // Scale word needed
+      const forms = PLURAL_FORMS[i]
+      if (forms) {
+        const scaleWord = pluralize(segment, forms)
+
+        if (segment === 1n) {
+          // Omit "jeden" before scale words
+          result += scaleWord
+        } else {
+          result += segmentWord + ' ' + scaleWord
+        }
       }
     }
-    return words.join(' ')
   }
+
+  return result
 }
 
 /**
- * Converts a number to Polish cardinal (written) form.
+ * Converts decimal digits to Polish words.
  *
- * @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.
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @param {Object} options - Conversion options
+ * @returns {string} Polish words for decimal part
  */
-export default function convertToWords (value, options = {}) {
-  return new Polish(options).convertToWords(value)
+function decimalPartToWords (decimalPart, options) {
+  let result = ''
+
+  // Handle leading zeros
+  let i = 0
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  // Convert remainder as a single number
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder), options)
+  }
+
+  return result
 }
+
+/**
+ * Converts a numeric value to Polish words.
+ *
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Conversion options
+ * @param {string} [options.gender='masculine'] - Gender for numbers < 1000
+ * @returns {string} The number in Polish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(1)                          // 'jeden'
+ * toWords(1, { gender: 'feminine' })  // 'jedna'
+ * toWords(1000)                       // 'tysiąc'
+ * toWords(2000)                       // 'dwa tysiące'
+ */
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, options)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, options)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

package/lib/languages/pt.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a numeric value to Portuguese words.
+ *
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Portuguese words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)           // 'vinte e um'
+ * toWords(100)          // 'cem'
+ * toWords(1000000)      // 'um milhão'
+ */
+export function toWords(value: number | string | bigint): string;