n2words 1.24.0 → 3.0.0

package/lib/languages/sv.js

@@ -1,127 +1,304 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
-
 /**
- * Swedish language converter.
+ * Swedish language converter - Functional Implementation
  *
- * Converts numbers to Swedish words, supporting:
- * - Negative numbers (prepended with "minus")
- * - Decimal numbers (word "komma" between whole and fractional parts)
- * - Numbers up to quadrillions
+ * A performance-optimized number-to-words converter using precomputed lookup tables.
  *
- * Merge rules:
- * - Hyphenated for compound tens (e.g., "tjugo-tre")
- * - "och" (and) after hundreds (e.g., "hundra och ett")
- * - Space-separated for larger composites (e.g., "en miljon")
+ * Key features:
+ * - Hyphenation for tens-ones (tjugo-ett)
+ * - "och" after hundreds before small numbers
+ * - Omit "ett" before hundra and tusen
+ * - Use "en" (not "ett") before million+ scales
+ * - Long scale naming with -ard forms
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES = ['', 'ett', 'två', 'tre', 'fyra', 'fem', 'sex', 'sju', 'åtta', 'nio']
+
+const TEENS = ['tio', 'elva', 'tolv', 'tretton', 'fjorton', 'femton', 'sexton', 'sjutton', 'arton', 'nitton']
+const TENS = ['', '', 'tjugo', 'trettio', 'fyrtio', 'femtio', 'sextio', 'sjuttio', 'åttio', 'nittio']
+
+const HUNDRED = 'hundra'
+
+const ZERO = 'noll'
+const NEGATIVE = 'minus'
+const DECIMAL_SEP = 'komma'
+
+// Scale words (long scale with -ard forms)
+const SCALES = ['tusen', 'miljon', 'miljard', 'biljon', 'biljard', 'triljon', 'triljard', 'kvadriljon']
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
+
+/**
+ * Builds segment word for 0-999.
+ * Returns object with word and metadata for "och" logic.
  */
-export class Swedish extends GreedyScaleLanguage {
-  negativeWord = 'minus'
-  decimalSeparatorWord = 'komma'
-  zeroWord = 'noll'
-  wordSeparator = ' '
-  scaleWordPairs = [
-    [1_000_000_000_000_000_000_000_000_000n, 'kvadriljon'],
-    [1_000_000_000_000_000_000_000_000n, 'triljon'],
-    [1_000_000_000_000_000_000_000n, 'biljon'],
-    [1_000_000_000_000_000_000n, 'miljard'],
-    [1_000_000_000_000n, 'biljon'],
-    [1_000_000_000n, 'miljard'],
-    [1_000_000n, 'miljon'],
-    [1000n, 'tusen'],
-    [100n, 'hundra'],
-    [90n, 'nittio'],
-    [80n, 'åttio'],
-    [70n, 'sjuttio'],
-    [60n, 'sextio'],
-    [50n, 'femtio'],
-    [40n, 'fyrtio'],
-    [30n, 'trettio'],
-    [20n, 'tjugo'],
-    [19n, 'nitton'],
-    [18n, 'arton'],
-    [17n, 'sjutton'],
-    [16n, 'sexton'],
-    [15n, 'femton'],
-    [14n, 'fjorton'],
-    [13n, 'tretton'],
-    [12n, 'tolv'],
-    [11n, 'elva'],
-    [10n, 'tio'],
-    [9n, 'nio'],
-    [8n, 'åtta'],
-    [7n, 'sju'],
-    [6n, 'sex'],
-    [5n, 'fem'],
-    [4n, 'fyra'],
-    [3n, 'tre'],
-    [2n, 'två'],
-    [1n, 'ett'],
-    [0n, 'noll']
-  ]
-
-  /**
-   * Merges two adjacent word-number pairs according to Swedish grammar rules.
-   *
-   * Swedish-specific rules:
-   * - Implicit "ett": `mergeScales({ 'ett': 1n }, { 'hundra': 100n })` → `{ 'hundra': 100n }`
-   * - Hyphenated compounds: `mergeScales({ 'tjugo': 20n }, { 'tre': 3n })` → `{ 'tjugo-tre': 23n }`
-   * - "och" after hundreds: `mergeScales({ 'hundra': 100n }, { 'ett': 1n })` → `{ 'hundra och ett': 101n }`
-   * - "en" for millions: `mergeScales({ 'ett': 1n }, { 'miljon': 1000000n })` → `{ 'en miljon': 1000000n }`
-   *
-   * @param {Object} leftPair Left word-set as `{ word: BigInt }`.
-   * @param {Object} rightPair Right word-set as `{ word: BigInt }`.
-   * @returns {Object} Merged pair with combined word and resulting numeric value.
-   *
-   * @example
-   * mergeScales({ 'ett': 1n }, { 'hundra': 100n }); // { 'hundra': 100n }
-   * mergeScales({ 'tjugo': 20n }, { 'tre': 3n }); // { 'tjugo-tre': 23n }
-   */
-  mergeScales (leftPair, rightPair) {
-    const leftWord = Object.keys(leftPair)[0]
-    const rightWord = Object.keys(rightPair)[0]
-    const leftNumber = Object.values(leftPair)[0]
-    const rightNumber = Object.values(rightPair)[0]
-
-    if (leftNumber === 1n && rightNumber < 100n) {
-      return rightPair
+function buildSegment (n) {
+  if (n === 0) return { word: '', hasHundred: false, lessThan100: false }
+
+  const ones = n % 10
+  const tens = Math.floor(n / 10) % 10
+  const hundreds = Math.floor(n / 100)
+
+  const parts = []
+  let hasHundred = false
+
+  // Hundreds - omit "ett" before hundra
+  if (hundreds > 0) {
+    hasHundred = true
+    if (hundreds === 1) {
+      parts.push(HUNDRED)
+    } else {
+      parts.push(ONES[hundreds] + ' ' + HUNDRED)
     }
+  }
 
-    // Omit 'ett' before 'hundra' and 'tusen'
-    if (leftNumber === 1n && (rightNumber === 100n || rightNumber === 1000n)) {
-      return rightPair
+  // Tens and ones with hyphenation
+  let tensOnesWord = ''
+  if (tens === 1) {
+    tensOnesWord = TEENS[ones]
+  } else if (tens >= 2) {
+    if (ones > 0) {
+      tensOnesWord = TENS[tens] + '-' + ONES[ones]
+    } else {
+      tensOnesWord = TENS[tens]
     }
+  } else if (ones > 0) {
+    tensOnesWord = ONES[ones]
+  }
+
+  // Combine with "och" after hundreds if there's a remainder
+  if (hasHundred && tensOnesWord) {
+    return { word: parts[0] + ' och ' + tensOnesWord, hasHundred: true, lessThan100: false }
+  } else if (hasHundred) {
+    return { word: parts[0], hasHundred: true, lessThan100: false }
+  } else {
+    return { word: tensOnesWord, hasHundred: false, lessThan100: true }
+  }
+}
 
-    if (leftNumber < 100n && leftNumber > rightNumber) {
-      return { [`${leftWord}-${rightWord}`]: leftNumber + rightNumber }
+// Precompute all 1000 segment words (0-999)
+const SEGMENTS = new Array(1000)
+const SEGMENTS_HAS_HUNDRED = new Array(1000)
+const SEGMENTS_LESS_THAN_100 = new Array(1000)
+
+for (let i = 0; i < 1000; i++) {
+  const result = buildSegment(i)
+  SEGMENTS[i] = result.word
+  SEGMENTS_HAS_HUNDRED[i] = result.hasHundred
+  SEGMENTS_LESS_THAN_100[i] = result.lessThan100
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Swedish words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Swedish words
+ */
+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)
+
+    // Omit "ett" before tusen
+    let result = thousands === 1 ? SCALES[0] : SEGMENTS[thousands] + ' ' + SCALES[0]
+
+    if (remainder > 0) {
+      const remainderWord = SEGMENTS[remainder]
+      // Insert "och" if remainder < 100 (doesn't have hundred)
+      if (SEGMENTS_LESS_THAN_100[remainder]) {
+        result += ' och ' + remainderWord
+      } else {
+        result += ' ' + remainderWord
+      }
     }
 
-    if (leftNumber >= 100n && rightNumber < 100n) {
-      return { [`${leftWord} och ${rightWord}`]: leftNumber + rightNumber }
+    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} Swedish 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
+        parts.push({
+          word: SEGMENTS[segment],
+          hasHundred: SEGMENTS_HAS_HUNDRED[segment],
+          isScale: false
+        })
+      } else {
+        // Segment with scale word
+        const scaleWord = SCALES[scaleIndex - 1]
+
+        let segmentWord
+        if (segment === 1) {
+          // Omit "ett" before tusen, use "en" before million+
+          if (scaleIndex === 1) {
+            segmentWord = '' // Just "tusen"
+          } else {
+            segmentWord = 'en' // "en miljon"
+          }
+        } else {
+          segmentWord = SEGMENTS[segment]
+        }
+
+        if (segmentWord) {
+          parts.push({ word: segmentWord, hasHundred: false, isScale: false })
+        }
+        parts.push({ word: scaleWord, hasHundred: false, isScale: true })
+      }
     }
 
-    if (rightNumber > leftNumber) {
-      if (leftNumber === 1n && rightNumber >= 1_000_000n) {
-        return { [`en ${rightWord}`]: leftNumber * rightNumber }
+    scaleIndex--
+  }
+
+  // Join with Swedish "och" rules
+  return joinSwedishParts(parts)
+}
+
+/**
+ * Joins parts with Swedish "och" rules.
+ * Insert "och" before final segment if it follows a scale word and doesn't have "hundra".
+ *
+ * @param {Array} parts - Parts with metadata
+ * @returns {string} Joined string
+ */
+function joinSwedishParts (parts) {
+  if (parts.length === 0) return ZERO
+  if (parts.length === 1) return parts[0].word
+
+  const result = []
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]
+    const isLast = i === parts.length - 1
+
+    if (isLast && parts.length > 1) {
+      const prevPart = parts[i - 1]
+      // Insert "och" if previous was scale and this doesn't have hundred
+      if (prevPart.isScale && !part.hasHundred) {
+        result.push('och')
       }
-      return { [`${leftWord} ${rightWord}`]: leftNumber * rightNumber }
     }
 
-    return { [`${leftWord} ${rightWord}`]: leftNumber + rightNumber }
+    result.push(part.word)
   }
+
+  return result.join(' ')
+}
+
+/**
+ * Converts decimal digits to Swedish words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Swedish 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 number to Swedish cardinal (written) form.
+ * Converts a numeric value to Swedish words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see Swedish class options).
- * @returns {string} The number expressed in Swedish words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Swedish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
  *
  * @example
- * convertToWords(42); // 'fyrtio-två'
- * convertToWords('1.5'); // 'ett komma fem'
+ * toWords(42)       // 'fyrtio-två'
+ * toWords(101)      // 'hundra och ett'
+ * toWords(1000000)  // 'en miljon'
  */
-export default function convertToWords (value, options = {}) {
-  return new Swedish(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/sw.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts a numeric value to Swahili words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Swahili words
+ */
+export function toWords(value: number | string | bigint): string;

package/lib/languages/sw.js

@@ -1,121 +1,153 @@
-import AbstractLanguage from '../classes/abstract-language.js'
-
-class Swahili extends AbstractLanguage {
-  negativeWord = 'minus'
-  decimalSeparatorWord = 'nukta'
-  zeroWord = 'sifuri'
-  digits = {
-    0: 'sifuri',
-    1: 'moja',
-    2: 'mbili',
-    3: 'tatu',
-    4: 'nne',
-    5: 'tano',
-    6: 'sita',
-    7: 'saba',
-    8: 'nane',
-    9: 'tisa'
-  }
+/**
+ * Swahili language converter - Functional Implementation
+ *
+ * Self-contained converter with precomputed lookup tables.
+ *
+ * Key features:
+ * - "na" connector for compound numbers
+ * - Reversed hundreds: "mia moja" (one hundred)
+ * - Scale words: elfu, milioni, bilioni
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ONES = ['sifuri', 'moja', 'mbili', 'tatu', 'nne', 'tano', 'sita', 'saba', 'nane', 'tisa']
+const TENS = { 10: 'kumi', 20: 'ishirini', 30: 'thelathini', 40: 'arobaini', 50: 'hamsini', 60: 'sitini', 70: 'sabini', 80: 'themanini', 90: 'tisini' }
+
+const SCALE_WORDS = ['', 'elfu', 'milioni', 'bilioni', 'trilioni', 'kwadrilioni', 'kwintilioni']
 
-  tens = {
-    10: 'kumi',
-    20: 'ishirini',
-    30: 'thelathini',
-    40: 'arobaini',
-    50: 'hamsini',
-    60: 'sitini',
-    70: 'sabini',
-    80: 'themanini',
-    90: 'tisini'
+const ZERO = 'sifuri'
+const NEGATIVE = 'minus'
+const DECIMAL_SEP = 'nukta'
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function wordsUnder100 (n) {
+  if (n < 10) return ONES[n]
+  if (n === 10) return TENS[10]
+  if (n < 20) {
+    // 11-19: 'kumi na <digit>'
+    return TENS[10] + ' na ' + ONES[n - 10]
   }
+  const tens = Math.trunc(n / 10) * 10
+  const ones = n % 10
+  if (ones === 0) return TENS[tens]
+  return TENS[tens] + ' na ' + ONES[ones]
+}
+
+function wordsUnder1000 (n) {
+  if (n < 100) return wordsUnder100(n)
+  if (n === 100) return 'mia moja'
+  const hundreds = Math.trunc(n / 100)
+  const rest = n % 100
+  const parts = []
 
-  scales = [
-    '',
-    'elfu',
-    'milioni',
-    'bilioni',
-    'trilioni'
-  ]
-
-  wordsUnder100 (n) {
-    if (n < 10) return this.digits[n]
-    if (n === 10) return this.tens[10]
-    if (n < 20) {
-      // 11-19: 'kumi na <digit>'
-      return this.tens[10] + ' na ' + this.digits[n - 10]
+  // Hundreds: 'mia <digit>'
+  parts.push('mia ' + ONES[hundreds])
+  if (rest > 0) {
+    if (rest < 10) {
+      parts.push('na ' + ONES[rest])
+    } else {
+      parts.push(wordsUnder100(rest))
     }
-    const tens = Math.trunc(n / 10) * 10
-    const ones = n % 10
-    if (ones === 0) return this.tens[tens]
-    return this.tens[tens] + ' na ' + this.digits[ones]
   }
 
-  wordsUnder1000 (n) {
-    if (n < 100) return this.wordsUnder100(n)
-    if (n === 100) return 'mia moja'
-    const hundreds = Math.trunc(n / 100)
-    const rest = n % 100
-    const parts = []
-
-    // Hundreds: 'mia <digit>'
-    parts.push('mia ' + this.digits[hundreds])
-    if (rest > 0) {
-      if (rest < 10) {
-        parts.push('na ' + this.digits[rest])
-      } else {
-        parts.push(this.wordsUnder100(rest))
-      }
-    }
+  return parts.join(' ')
+}
 
-    return parts.join(' ')
+function extractSegments (n) {
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
   }
+  return segments
+}
 
-  splitBy3 (number) {
-    const s = number.toString()
-    if (s.length <= 3) return [Number(s)]
-    const groups = []
-    const last3 = s.slice(-3)
-    groups.unshift(Number(last3))
-    let remaining = s.slice(0, -3)
-    while (remaining.length > 0) {
-      const group = remaining.slice(-3)
-      groups.unshift(Number(group))
-      remaining = remaining.slice(0, -3)
-    }
-    return groups
-  }
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // segments stored least-significant first: [ones, thousands, millions, ...]
+  const segments = extractSegments(n)
+  const parts = []
 
-  convertWholePart (number) {
-    if (number === 0n) return this.zeroWord
-
-    const groups = this.splitBy3(number)
-    const parts = []
-
-    for (let i = 0; i < groups.length; i++) {
-      const val = groups[i]
-      if (val === 0) continue
-      const scaleIndex = groups.length - i - 1
-      // scale word
-      if (scaleIndex === 0) {
-        if (val < 10 && parts.length > 0) {
-          parts.push('na ' + this.digits[val])
-        } else if (val === 100 && parts.length > 0) {
-          // In compound numbers (e.g., 1100 -> 'elfu moja mia'), use 'mia' not 'mia moja'
-          parts.push('mia')
-        } else {
-          parts.push(this.wordsUnder1000(val))
-        }
+  // Iterate from highest scale to lowest
+  for (let scaleIndex = segments.length - 1; scaleIndex >= 0; scaleIndex--) {
+    const val = segments[scaleIndex]
+    if (val === 0) continue
+
+    if (scaleIndex === 0) {
+      // Units segment
+      if (val < 10 && parts.length > 0) {
+        parts.push('na ' + ONES[val])
+      } else if (val === 100 && parts.length > 0) {
+        // In compound numbers (e.g., 1100 -> 'elfu moja mia'), use 'mia' not 'mia moja'
+        parts.push('mia')
       } else {
-        // e.g., 'elfu moja', 'milioni mbili'
-        const unit = (val === 1) ? 'moja' : this.wordsUnder1000(val)
-        parts.push(this.scales[scaleIndex] + ' ' + unit)
+        parts.push(wordsUnder1000(val))
       }
+    } else {
+      // Scale segments: 'elfu moja', 'milioni mbili'
+      const unit = (val === 1) ? 'moja' : wordsUnder1000(val)
+      parts.push(SCALE_WORDS[scaleIndex] + ' ' + unit)
     }
+  }
+
+  return parts.join(' ').trim()
+}
+
+function decimalPartToWords (decimalPart) {
+  let result = ''
+  let i = 0
 
-    return parts.join(' ').trim()
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
   }
+
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder))
+  }
+
+  return result
 }
 
-export default function convertToWords (value, options = {}) {
-  return new Swahili(options).convertToWords(value)
+/**
+ * Converts a numeric value to Swahili words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Swahili words
+ */
+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
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/ta.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts a numeric value to Tamil words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Tamil words
+ */
+export function toWords(value: number | string | bigint): string;