n2words 1.24.0 → 3.0.0

package/lib/languages/cs.js

@@ -1,212 +1,339 @@
-import SlavicLanguage from '../classes/slavic-language.js'
+/**
+ * Czech 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.
+ *
+ * Czech-specific rules (handled in precomputation):
+ * - Three-form pluralization: 1 = singular, 2-4 = few, 5+ = many
+ * - Irregular hundreds: sto, dvě stě, tři sta, čtyři sta, pět set...
+ * - Gender: dva (masc) vs dvě (fem) for 2
+ * - Omit "one" before scale words: "tisíc" not "jedna tisíc"
+ * - Dynamic decimal separator: celá/celé/celých based on integer
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+// Ones words (masculine form)
+const ONES = ['', 'jedna', 'dva', 'tři', 'čtyři', 'pět', 'šest', 'sedm', 'osm', 'devět']
+
+// Teens (10-19)
+const TEENS = ['deset', 'jedenáct', 'dvanáct', 'třináct', 'čtrnáct', 'patnáct', 'šestnáct', 'sedmnáct', 'osmnáct', 'devatenáct']
+
+// Tens (20-90)
+const TENS = ['', '', 'dvacet', 'třicet', 'čtyřicet', 'padesát', 'šedesát', 'sedmdesát', 'osmdesát', 'devadesát']
+
+// Irregular hundreds
+const HUNDREDS = ['', 'sto', 'dvě stě', 'tři sta', 'čtyři sta', 'pět set', 'šest set', 'sedm set', 'osm set', 'devět set']
+
+// Scale plural forms [singular, few (2-4), many (5+)]
+const PLURAL_FORMS = {
+  1: ['tisíc', 'tisíce', 'tisíc'], // 10^3
+  2: ['milion', 'miliony', 'milionů'], // 10^6
+  3: ['miliarda', 'miliardy', 'miliard'], // 10^9
+  4: ['bilion', 'biliony', 'bilionů'], // 10^12
+  5: ['biliarda', 'biliardy', 'biliard'], // 10^15
+  6: ['trilion', 'triliony', 'trilionů'], // 10^18
+  7: ['triliarda', 'triliardy', 'triliard'], // 10^21
+  8: ['kvadrilion', 'kvadriliony', 'kvadrilionů'], // 10^24
+  9: ['kvadriliarda', 'kvadriliardy', 'kvadriliard'] // 10^27
+}
+
+const ZERO = 'nula'
+const NEGATIVE = 'mínus'
+
+// ============================================================================
+// 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, default form).
+ * Only used during table construction.
  */
+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 (irregular)
+  if (hundreds > 0) {
+    parts.push(HUNDREDS[hundreds])
+  }
+
+  // Tens and ones
+  if (tens === 1) {
+    // Teens
+    parts.push(TEENS[ones])
+  } else if (tens >= 2) {
+    parts.push(TENS[tens])
+    if (ones > 0) {
+      parts.push(ONES[ones])
+    }
+  } else if (ones > 0) {
+    parts.push(ONES[ones])
+  }
+
+  return parts.join(' ')
+}
 
 /**
- * Czech language converter.
- *
- * Implements Czech number words using the Slavic language pattern:
- * - Czech number words (jedna, dva, tři, čtyři, pět...)
- * - Slavic three-form pluralization (tisíc/tisíce/tisíc)
- * - Gender agreement for numbers 1-2
- * - Czech-specific number word endings
- *
- * Key Features:
- * - Three-form pluralization system shared across Slavic languages
- *   * Form 1 (singular): 1 (e.g., "tisíc")
- *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "tisíce")
- *   * Form 3 (many): all other numbers (e.g., "tisíc")
- * - 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
- *
- * Inherits from SlavicLanguage:
- * - Complex pluralization rules (one/few/many forms)
- * - Group-based large number handling (chunk decomposition via splitByX())
- * - Proper declension patterns via pluralize() method
+ * Builds segment word for 0-999 with feminine hundreds.
+ * Hundreds use irregular forms (dvě stě, tři sta) but ones remain masculine.
  */
-export class Czech extends SlavicLanguage {
-  negativeWord = 'mínus'
-  zeroWord = 'nula'
-  ones = {
-    1: 'jedna',
-    2: 'dva',
-    3: 'tři',
-    4: 'čtyři',
-    5: 'pět',
-    6: 'šest',
-    7: 'sedm',
-    8: 'osm',
-    9: 'devět'
+function buildSegmentWithHundreds (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 use the irregular HUNDREDS array (already has "dvě stě" etc.)
+  if (hundreds > 0) {
+    parts.push(HUNDREDS[hundreds])
   }
 
-  tens = {
-    0: 'deset',
-    1: 'jedenáct',
-    2: 'dvanáct',
-    3: 'třináct',
-    4: 'čtrnáct',
-    5: 'patnáct',
-    6: 'šestnáct',
-    7: 'sedmnáct',
-    8: 'osmnáct',
-    9: 'devatenáct'
+  // Tens and ones use masculine form
+  if (tens === 1) {
+    parts.push(TEENS[ones])
+  } else if (tens >= 2) {
+    parts.push(TENS[tens])
+    if (ones > 0) {
+      parts.push(ONES[ones]) // masculine
+    }
+  } else if (ones > 0) {
+    parts.push(ONES[ones]) // masculine
   }
 
-  twenties = {
-    2: 'dvacet',
-    3: 'třicet',
-    4: 'čtyřicet',
-    5: 'padesát',
-    6: 'šedesát',
-    7: 'sedmdesát',
-    8: 'osmdesát',
-    9: 'devadesát'
+  return parts.join(' ')
+}
+
+// Precompute all 1000 segment words (0-999) - masculine form
+const SEGMENTS = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS[i] = buildSegment(i)
+}
+
+// Precompute all 1000 segment words with hundreds (irregular hundreds forms)
+const SEGMENTS_WITH_HUNDREDS = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS_WITH_HUNDREDS[i] = buildSegmentWithHundreds(i)
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Czech pluralization: 1 = singular, 2-4 = few, else = many.
+ * Teens (11-19) always use "many" form.
+ *
+ * @param {bigint} n - The number
+ * @param {string[]} forms - [singular, few, many]
+ * @returns {string} The appropriate form
+ */
+function pluralize (n, forms) {
+  if (n === 1n) return forms[0]
+
+  const lastDigit = n % 10n
+  const lastTwoDigits = n % 100n
+
+  // 2-4, but not 12-14 (teens use "many")
+  if (lastDigit >= 2n && lastDigit <= 4n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
+    return forms[1]
   }
 
-  hundreds = {
-    1: 'sto',
-    2: 'dvě stě',
-    3: 'tři sta',
-    4: 'čtyři sta',
-    5: 'pět set',
-    6: 'šest set',
-    7: 'sedm set',
-    8: 'osm set',
-    9: 'devět set'
+  return forms[2]
+}
+
+/**
+ * Gets the decimal separator word based on integer part.
+ * celá (0-1), celé (2-4), celých (5+)
+ */
+function getDecimalSeparator (integerPart) {
+  if (integerPart === 0n || integerPart === 1n) {
+    return 'celá'
+  } else if (integerPart >= 2n && integerPart <= 4n) {
+    return 'celé'
+  } else {
+    return 'celých'
   }
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Czech words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Czech words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
 
-  thousands = {
-    1: ['tisíc', 'tisíce', 'tisíc'], // 10^ 3
-    2: ['milion', 'miliony', 'milionů'], // 10^ 6
-    3: ['miliarda', 'miliardy', 'miliard'], // 10^ 9
-    4: ['bilion', 'biliony', 'bilionů'], // 10^ 12
-    5: ['biliarda', 'biliardy', 'biliard'], // 10^ 15
-    6: ['trilion', 'triliony', 'trilionů'], // 10^ 18
-    7: ['triliarda', 'triliardy', 'triliard'], // 10^ 21
-    8: ['kvadrilion', 'kvadriliony', 'kvadrilionů'], // 10^ 24
-    9: ['kvadriliarda', 'kvadriliardy', 'kvadriliard'], // 10^ 27
-    10: ['quintillion', 'quintilliony', 'quintillionů'] // 10^ 30
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return SEGMENTS[Number(n)]
   }
 
-  /**
-   * Returns the Czech word for the decimal separator based on the whole number.
-   *
-   * @returns {string} The Czech word for the decimal separator.
-   */
-  get decimalSeparatorWord () {
-    if (this.cachedWholeNumber === 0n || this.cachedWholeNumber === 1n) {
-      return 'celá'
-    } else if (this.cachedWholeNumber >= 2n && this.cachedWholeNumber <= 4n) {
-      return 'celé'
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = n / 1000n
+    const remainder = Number(n % 1000n)
+
+    const scaleWord = pluralize(thousands, PLURAL_FORMS[1])
+
+    let result
+    if (thousands === 1n) {
+      // Omit "one" before tisíc
+      result = scaleWord
     } else {
-      return 'celých'
+      result = SEGMENTS[Number(thousands)] + ' ' + scaleWord
     }
+
+    if (remainder > 0) {
+      // Use form with irregular hundreds (for "dvě stě" etc.)
+      result += ' ' + SEGMENTS_WITH_HUNDREDS[remainder]
+    }
+
+    return result
   }
 
-  /**
-   * Initializes the Czech converter with language-specific options.
-   *
-   * @param {SlavicOptions} [options={}] Configuration options (inherited from SlavicLanguage).
-   */
-  constructor (options = {}) {
-    super(options)
+  // For numbers >= 1,000,000, use scale decomposition
+  return buildLargeNumberWords(n)
+}
 
-    // Remove the inherited decimalSeparatorWord property so our getter works
-    delete this.decimalSeparatorWord
+/**
+ * Builds words for numbers >= 1,000,000.
+ * Uses BigInt division for faster segment extraction.
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @returns {string} Czech words
+ */
+function buildLargeNumberWords (n) {
+  // 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
   }
 
-  /**
-   * Implements Czech-specific three-form pluralization rules.
-   *
-   * Czech three-form system:
-   * - Form 1 (singular): exactly n=1 (e.g., "tisíc")
-   * - Form 2 (few): n ends in 2-4, excluding teens (22-24, 32-34...) (e.g., "tisíce")
-   * - Form 3 (many): all other numbers (e.g., "tisíc" for 0, 5+)
-   *
-   * @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]
-    }
+  // Build result string directly
+  let result = ''
 
-    // Check if n is in the "few" form range (2-4, 22-24, 32-34, etc., excluding teens)
-    const lastDigit = n % 10n
-    const lastTwoDigits = n % 100n
+  for (let i = segmentValues.length - 1; i >= 0; i--) {
+    const segment = segmentValues[i]
+    if (segment === 0n) continue
 
-    if (lastDigit > 1n && lastDigit < 5n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
-      return forms[1]
-    }
+    if (result) result += ' '
 
-    return forms[2]
-  }
+    if (i === 0) {
+      // Units segment (no scale word) - use form with irregular hundreds
+      result += SEGMENTS_WITH_HUNDREDS[Number(segment)]
+    } else {
+      // Scale word needed
+      const forms = PLURAL_FORMS[i]
+      if (forms) {
+        const scaleWord = pluralize(segment, forms)
 
-  /**
-   * Converts a whole number to Czech 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", "dvě stě")
-   *    c. Add tens/ones (handles teens 10-19 separately from compound tens)
-   *    d. Add pluralized magnitude word (e.g., "tisíce", "miliony")
-   * 3. Join all words with spaces
-   *
-   * Example: 1234 → chunks [1, 234] → "jeden tisíc dvěstěčtyřicet"
-   *   - Chunk 1 (index=1, thousands): "jeden" + "tisíc"
-   *   - Chunk 234 (index=0): "dvě stě" + "třicet" + "čtyři"
-   *
-   * Special case: When chunk=1 at thousands+ levels, omit the ones word to avoid
-   * redundancy with the pluralized magnitude (e.g., just "tisíc" not "jeden tisíc").
-   *
-   * @param {bigint} number The whole number to convert.
-   * @returns {string} The number expressed in Czech 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--
-      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]))
+        if (segment === 1n) {
+          // Omit "one" before scale words
+          result += scaleWord
+        } else {
+          // Use masculine form for multiplier before scale words
+          result += SEGMENTS[Number(segment)] + ' ' + scaleWord
+        }
+      } else {
+        // Fallback for very large scales without defined forms
+        result += SEGMENTS[Number(segment)]
       }
     }
-    return words.join(' ')
   }
+
+  return result
 }
 
 /**
- * Converts a number to Czech cardinal (written) form.
+ * Converts decimal digits to Czech words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {SlavicOptions} [options={}] Configuration options.
- * @returns {string} The number expressed in Czech 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)
+ * @returns {string} Czech words for decimal part
  */
-export default function convertToWords (value, options = {}) {
-  return new Czech(options).convertToWords(value)
+function decimalPartToWords (decimalPart) {
+  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))
+  }
+
+  return result
 }
+
+/**
+ * Converts a numeric value to Czech 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 Czech words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)           // 'dvacet jedna'
+ * toWords(1000)         // 'tisíc'
+ * toWords(2000)         // 'dva tisíce'
+ * toWords(5000)         // 'pět tisíc'
+ */
+function toWords (value) {
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    const separator = getDecimalSeparator(integerPart)
+    result += ' ' + separator + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

package/lib/languages/da.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Converts a numeric value to Danish words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Danish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)       // 'enogtyve'
+ * toWords(1000)     // 'ettusind'
+ * toWords(1000000)  // 'en millioner'
+ */
+export function toWords(value: number | string | bigint): string;