n2words 1.24.0 → 3.0.0

package/lib/languages/de.js

@@ -1,135 +1,332 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+/**
+ * German 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.
+ *
+ * German-specific rules (handled in precomputation):
+ * - Inverted tens-ones order: "einundzwanzig" (one-and-twenty) for 21-99
+ * - Compound words without spaces below million level
+ * - Three forms of 1: "eins" (standalone), "ein" (before hundert/tausend), "eine" (before Million+)
+ * - Scale pluralization: Million → Millionen, Milliarde → Milliarden
+ * - Spaces only around million+ scale words
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+// Ones words (1-9), index 0 unused
+const ONES = ['', 'eins', 'zwei', 'drei', 'vier', 'fünf', 'sechs', 'sieben', 'acht', 'neun']
+
+// "ein" form for use before hundert/und
+const EIN = 'ein'
+
+// Teens (10-19)
+const TEENS = ['zehn', 'elf', 'zwölf', 'dreizehn', 'vierzehn', 'fünfzehn', 'sechzehn', 'siebzehn', 'achtzehn', 'neunzehn']
+
+// Tens (20-90)
+const TENS = ['', '', 'zwanzig', 'dreißig', 'vierzig', 'fünfzig', 'sechzig', 'siebzig', 'achtzig', 'neunzig']
+
+// Scale words (index 0 = thousand, 1 = million, etc.)
+const SCALES = ['tausend', 'Million', 'Milliarde', 'Billion', 'Billiarde', 'Trillion', 'Trilliarde', 'Quadrillion', 'Quadrilliarde']
+
+// Pluralized scale words (million+)
+const SCALES_PLURAL = ['tausend', 'Millionen', 'Milliarden', 'Billionen', 'Billiarden', 'Trillionen', 'Trilliarden', 'Quadrillionen', 'Quadrilliarden']
+
+const HUNDRED = 'hundert'
+const ZERO = 'null'
+const NEGATIVE = 'minus'
+const DECIMAL_SEP = 'komma'
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
 
 /**
- * German language converter.
+ * Builds segment word for 0-999 (standalone form, uses "eins").
+ * German inverts ones and tens: "einundzwanzig" = one-and-twenty
+ * 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)
+
+  let result = ''
+
+  // Hundreds: "ein" before hundert, not "eins"
+  if (hundreds > 0) {
+    result += (hundreds === 1 ? EIN : ONES[hundreds]) + HUNDRED
+  }
+
+  // Tens and ones
+  if (tens === 1) {
+    // Teens
+    result += TEENS[ones]
+  } else if (tens >= 2 && ones > 0) {
+    // Inverted: "einundzwanzig" (one-and-twenty)
+    // Use "ein" before "und", not "eins"
+    result += (ones === 1 ? EIN : ONES[ones]) + 'und' + TENS[tens]
+  } else if (tens >= 2) {
+    // Just tens
+    result += TENS[tens]
+  } else if (ones > 0) {
+    // Just ones (no tens, possibly after hundreds)
+    // Use "eins" for standalone/after hundreds
+    result += ONES[ones]
+  }
+
+  return result
+}
+
+/**
+ * Builds segment word for use before "tausend".
+ * Uses "ein" instead of "eins" for 1.
+ */
+function buildSegmentForThousand (n) {
+  if (n === 0) return ''
+  if (n === 1) return EIN // "eintausend"
+
+  const ones = n % 10
+  const tens = Math.floor(n / 10) % 10
+  const hundreds = Math.floor(n / 100)
+
+  let result = ''
+
+  if (hundreds > 0) {
+    result += (hundreds === 1 ? EIN : ONES[hundreds]) + HUNDRED
+  }
+
+  if (tens === 1) {
+    result += TEENS[ones]
+  } else if (tens >= 2 && ones > 0) {
+    result += (ones === 1 ? EIN : ONES[ones]) + 'und' + TENS[tens]
+  } else if (tens >= 2) {
+    result += TENS[tens]
+  } else if (ones > 0 && hundreds > 0) {
+    // After hundreds, ones 1 stays "eins" when not followed by scale
+    // But we're going to tausend, so this path won't hit for n=1
+    result += ONES[ones]
+  } else if (ones > 0) {
+    result += ONES[ones]
+  }
+
+  return result
+}
+
+// Precompute all 1000 segment words (0-999) - standalone form
+const SEGMENTS = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS[i] = buildSegment(i)
+}
+
+// Precompute all 1000 segment words for thousand context
+const SEGMENTS_THOUSAND = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS_THOUSAND[i] = buildSegmentForThousand(i)
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to German words.
  *
- * Handles German grammatical features:
- * - "eins" vs "ein" and "eine" forms for 1
- * - Compound words without separators (e.g., "einundzwanzig" = 21)
- * - Million/Billion pluralization
- * - Special characters (e.g., "ü", "ö", "ß")
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} German words
  */
-export class German extends GreedyScaleLanguage {
-  negativeWord = 'minus'
-  decimalSeparatorWord = 'komma'
-  zeroWord = 'null'
-  scaleWordPairs = [
-    [1_000_000_000_000_000_000_000_000_000n, 'Quadrilliarde'],
-    [1_000_000_000_000_000_000_000_000n, 'Quadrillion'],
-    [1_000_000_000_000_000_000_000n, 'Trilliarde'],
-    [1_000_000_000_000_000_000n, 'Trillion'],
-    [1_000_000_000_000_000n, 'Billiarde'],
-    [1_000_000_000_000n, 'Billion'],
-    [1_000_000_000n, 'Milliarde'],
-    [1_000_000n, 'Million'],
-    [1000n, 'tausend'],
-    [100n, 'hundert'],
-    [90n, 'neunzig'],
-    [80n, 'achtzig'],
-    [70n, 'siebzig'],
-    [60n, 'sechzig'],
-    [50n, 'fünfzig'],
-    [40n, 'vierzig'],
-    [30n, 'dreißig'],
-    [20n, 'zwanzig'],
-    [19n, 'neunzehn'],
-    [18n, 'achtzehn'],
-    [17n, 'siebzehn'],
-    [16n, 'sechzehn'],
-    [15n, 'fünfzehn'],
-    [14n, 'vierzehn'],
-    [13n, 'dreizehn'],
-    [12n, 'zwölf'],
-    [11n, 'elf'],
-    [10n, 'zehn'],
-    [9n, 'neun'],
-    [8n, 'acht'],
-    [7n, 'sieben'],
-    [6n, 'sechs'],
-    [5n, 'fünf'],
-    [4n, 'vier'],
-    [3n, 'drei'],
-    [2n, 'zwei'],
-    [1n, 'eins'],
-    [0n, 'null']
-  ]
-
-  /**
-   * Merges two adjacent word-number pairs according to German grammar rules.
-   *
-   * German-specific rules:
-   * - Implicit "eins": `mergeScales({ 'eins': 1n }, { 'hundert': 100n })` → `{ 'einhundert': 100n }`
-   * - Compound words without separators (e.g., "einundzwanzig" = 21)
-   * - Special handling for forms of 1 (eins/ein/eine) depending on context
-   * - Pluralization of millions and higher: "Millionen", "Milliarden"
-   * - Reordering of tens and units: `mergeScales({ 'zwanzig': 20n }, { 'eins': 1n })` → `{ 'einundzwanzig': 21n }`
-   *
-   * @param {Object} currentPair The left operand as `{ word: BigInt }`.
-   * @param {Object} nextPair The right operand as `{ word: BigInt }`.
-   * @returns {Object} Merged pair with combined word and resulting numeric value.
-   *
-   * @example
-   * mergeScales({ 'eins': 1n }, { 'hundert': 100n }); // { 'einhundert': 100n }
-   * mergeScales({ 'zwanzig': 20n }, { 'drei': 3n }); // { 'dreiundzwanzig': 23n }
-   */
-  mergeScales (currentPair, nextPair) {
-    let currentWord = Object.keys(currentPair)[0]
-    let nextWord = Object.keys(nextPair)[0]
-    const currentNumber = Object.values(currentPair)[0]
-    const nextNumber = Object.values(nextPair)[0]
-
-    // Handle form of 1: "eins" → "ein(e)" in certain contexts
-    if (currentNumber === 1n) {
-      if (nextNumber === 100n || nextNumber === 1000n) {
-        return { [`ein${nextWord}`]: nextNumber }
-      }
-      if (nextNumber < 1_000_000n) {
-        return nextPair
-      }
-      currentWord = 'eine'
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return SEGMENTS[Number(n)]
+  }
+
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    // Compound: "eintausendzweihundert" (no spaces)
+    let result = SEGMENTS_THOUSAND[thousands] + SCALES[0]
+
+    if (remainder > 0) {
+      result += SEGMENTS[remainder]
     }
 
-    if (nextNumber > currentNumber) {
-      // Multiply: apply pluralization rules for millions
-      if (nextNumber >= 1_000_000n) {
-        if (currentNumber > 1n) {
-          nextWord += nextWord.at(-1) === 'e' ? 'n' : 'en'
+    return result
+  }
+
+  // For numbers >= 1,000,000, use scale decomposition
+  return buildLargeNumberWords(n)
+}
+
+/**
+ * Builds words for numbers >= 1,000,000.
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @returns {string} German words
+ */
+function buildLargeNumberWords (n) {
+  const numStr = n.toString()
+  const len = numStr.length
+
+  // Build segments of 3 digits from right to left
+  const segments = []
+  const segmentSize = 3
+
+  const remainderLen = len % segmentSize
+  let pos = 0
+  if (remainderLen > 0) {
+    segments.push(Number(numStr.slice(0, remainderLen)))
+    pos = remainderLen
+  }
+  while (pos < len) {
+    segments.push(Number(numStr.slice(pos, pos + segmentSize)))
+    pos += segmentSize
+  }
+
+  // Convert segments to words
+  const parts = []
+  let scaleIndex = segments.length - 1
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+
+    if (segment !== 0) {
+      if (scaleIndex === 0) {
+        // Units segment (no scale word)
+        parts.push({ words: SEGMENTS[segment], isScale: false, scaleLevel: 0 })
+      } else if (scaleIndex === 1) {
+        // Thousands: compound without space
+        const segWords = SEGMENTS_THOUSAND[segment]
+        parts.push({ words: segWords + SCALES[0], isScale: false, scaleLevel: 1 })
+      } else {
+        // Million+ : space around scale word
+        let segWords
+        if (segment === 1) {
+          segWords = 'eine' // "eine Million"
+        } else {
+          segWords = SEGMENTS[segment]
         }
-        currentWord += ' '
+        const scaleWord = segment === 1 ? SCALES[scaleIndex - 1] : SCALES_PLURAL[scaleIndex - 1]
+        parts.push({ words: segWords, isScale: false, scaleLevel: scaleIndex })
+        parts.push({ words: scaleWord, isScale: true, scaleLevel: scaleIndex })
       }
-      return { [`${currentWord}${nextWord}`]: currentNumber * nextNumber }
     }
 
-    // Add: handle special case of tens + units
-    if (nextNumber < 10n && currentNumber > 10n && currentNumber < 100n) {
-      // German reverses tens and units (einundzwanzig = one and twenty)
-      if (nextNumber === 1n) {
-        nextWord = 'ein'
+    scaleIndex--
+  }
+
+  // Join with German spacing rules: space around million+ scale words
+  return joinGermanParts(parts)
+}
+
+/**
+ * Joins parts with German spacing rules.
+ * Spaces only around million+ scale words.
+ *
+ * @param {Array} parts - Parts with metadata
+ * @returns {string} Joined string
+ */
+function joinGermanParts (parts) {
+  if (parts.length === 0) return ZERO
+
+  let result = ''
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]
+    const prevPart = i > 0 ? parts[i - 1] : null
+
+    // Add space before if:
+    // - Current is a million+ scale word
+    // - Previous was a million+ scale word
+    if (i > 0) {
+      const needsSpace = part.isScale || (prevPart && prevPart.isScale)
+      if (needsSpace) {
+        result += ' '
       }
-      const temp = nextWord
-      nextWord = currentWord
-      currentWord = `${temp}und`
-    } else if (currentNumber >= 1_000_000n) {
-      currentWord += ' '
     }
 
-    return { [`${currentWord}${nextWord}`]: currentNumber + nextNumber }
+    result += part.words
   }
+
+  return result
 }
 
 /**
- * Converts a number to German cardinal (written) form.
+ * Converts decimal digits to German words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see German class options).
- * @returns {string} The number expressed in German 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} German words for decimal part
+ */
+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 German 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 German words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
  *
  * @example
- * convertToWords(42); // 'zweiundvierzig'
- * convertToWords('1.5'); // 'eins komma fünf'
+ * toWords(21)           // 'einundzwanzig'
+ * toWords(1000)         // 'eintausend'
+ * toWords(1000000)      // 'eine Million'
  */
-export default function convertToWords (value, options = {}) {
-  return new German(options).convertToWords(value)
+function toWords (value) {
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

package/lib/languages/el.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Converts a numeric value to Greek words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Greek words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)       // 'είκοσι ένα'
+ * toWords(1000)     // 'χίλια'
+ * toWords('3.14')   // 'τρία κόμμα ένα τέσσερα'
+ */
+export function toWords(value: number | string | bigint): string;