n2words 2.0.0 → 3.0.0

package/lib/languages/pt.js

@@ -1,112 +1,306 @@
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
+/**
+ * Portuguese 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.
+ *
+ * Portuguese-specific rules (handled in precomputation):
+ * - "e" conjunction everywhere: vinte e um, cento e um, mil e um
+ * - "cem" for exact 100, "cento" for 100+ remainder
+ * - Irregular hundreds: duzentos, trezentos, quatrocentos, etc.
+ * - Compound scale: milhão (10^6), mil milhões (10^9), bilião (10^12)
+ * - Omit "um" before "mil"
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES = ['', 'um', 'dois', 'três', 'quatro', 'cinco', 'seis', 'sete', 'oito', 'nove']
+const TEENS = ['dez', 'onze', 'doze', 'treze', 'catorze', 'quinze', 'dezasseis', 'dezassete', 'dezoito', 'dezanove']
+const TENS = ['', '', 'vinte', 'trinta', 'quarenta', 'cinquenta', 'sessenta', 'setenta', 'oitenta', 'noventa']
+
+// Irregular hundreds
+const HUNDREDS = ['', 'cento', 'duzentos', 'trezentos', 'quatrocentos', 'quinhentos', 'seiscentos', 'setecentos', 'oitocentos', 'novecentos']
+
+const THOUSAND = 'mil'
+const ZERO = 'zero'
+const NEGATIVE = 'menos'
+const DECIMAL_SEP = 'vírgula'
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
+
+/**
+ * Builds segment word for 0-999 with Portuguese "e" rules.
+ * Returns the word and whether it's an exact hundred (for "cem" handling).
+ */
+function buildSegment (n) {
+  if (n === 0) return { word: '', isExactHundred: false }
+
+  // Special case: exact 100 is "cem"
+  if (n === 100) return { word: 'cem', isExactHundred: true }
+
+  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) {
+    if (ones > 0) {
+      // Tens + ones with "e": "vinte e um"
+      parts.push(TENS[tens] + ' e ' + ONES[ones])
+    } else {
+      parts.push(TENS[tens])
+    }
+  } else if (ones > 0) {
+    parts.push(ONES[ones])
+  }
+
+  // Join hundreds with "e": "cento e um", "duzentos e trinta e um"
+  const word = parts.join(' e ')
+
+  return { word, isExactHundred: hundreds > 0 && tens === 0 && ones === 0 }
+}
+
+// Precompute all 1000 segment words (0-999)
+const SEGMENTS = new Array(1000)
+const SEGMENTS_STARTS_WITH_HUNDREDS = new Array(1000)
+
+for (let i = 0; i < 1000; i++) {
+  const result = buildSegment(i)
+  SEGMENTS[i] = result.word
+  // Precompute whether segment starts with hundreds (100-999)
+  SEGMENTS_STARTS_WITH_HUNDREDS[i] = i >= 100
+}
+
+// ============================================================================
+// Scale Word Lookup (precomputed for common scales)
+// ============================================================================
+
+// Precompute scale words for singular and plural forms
+// Index 1 = thousands, 2 = millions, 3 = billions (mil milhões), etc.
+const SCALE_WORDS_SINGULAR = [
+  '', // 0 unused
+  THOUSAND, // 1: mil
+  'milhão', // 2: 10^6
+  'mil milhões', // 3: 10^9 (compound)
+  'bilião', // 4: 10^12
+  'mil biliões', // 5: 10^15 (compound)
+  'trilião', // 6: 10^18
+  'mil triliões', // 7: 10^21 (compound)
+  'quatrilião' // 8: 10^24
+]
+
+const SCALE_WORDS_PLURAL = [
+  '', // 0 unused
+  THOUSAND, // 1: mil (same)
+  'milhões', // 2: 10^6
+  'mil milhões', // 3: 10^9 (compound, same)
+  'biliões', // 4: 10^12
+  'mil biliões', // 5: 10^15 (compound, same)
+  'triliões', // 6: 10^18
+  'mil triliões', // 7: 10^21 (compound, same)
+  'quatriliões' // 8: 10^24
+]
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
 
 /**
- * (European) Portuguese language converter.
+ * Converts a non-negative integer to Portuguese words.
  *
- * Supports:
- * - Gender-aware hundreds (duzentos, trezentos)
- * - "e" (and) conjunction for number combinations
- * - Post-processing to normalize word flow
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Portuguese words
  */
-export class Portuguese extends GreedyScaleLanguage {
-  negativeWord = 'menos'
-  decimalSeparatorWord = 'vírgula'
-  zeroWord = 'zero'
-
-  scaleWords = [
-    [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']
-  ]
-
-  hundredsWords = {
-    1: 'cento',
-    2: 'duzentos',
-    3: 'trezentos',
-    4: 'quatrocentos',
-    5: 'quinhentos',
-    6: 'seiscentos',
-    7: 'setecentos',
-    8: 'oitocentos',
-    9: 'novecentos'
+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)
+
+    let result
+    if (thousands === 1) {
+      // "mil" not "um mil"
+      result = THOUSAND
+    } else {
+      result = SEGMENTS[thousands] + ' ' + THOUSAND
+    }
+
+    if (remainder > 0) {
+      // Insert "e" before remainder if it doesn't start with hundreds (< 100)
+      if (!SEGMENTS_STARTS_WITH_HUNDREDS[remainder]) {
+        result += ' e ' + SEGMENTS[remainder]
+      } else {
+        result += ' ' + SEGMENTS[remainder]
+      }
+    }
+
+    return result
   }
 
-  // Pre-compiled regex patterns for postClean - avoid recompilation
-  static POSTCLEAN_REGEX = / e (.*entos?) (?=.*e)/g
+  // For numbers >= 1,000,000, use scale decomposition
+  return buildLargeNumberWords(n)
+}
 
-  finalizeWords (words) {
-    return words.replaceAll(Portuguese.POSTCLEAN_REGEX, ' $1 ')
+/**
+ * Builds words for numbers >= 1,000,000.
+ * Uses BigInt division for faster segment extraction.
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @returns {string} Portuguese words
+ */
+function buildLargeNumberWords (n) {
+  // Extract segments using BigInt division
+  // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
   }
 
-  /** Combines two word-sets according to Portuguese grammar rules. */
-  combineWordSets (preceding, following) {
-    // Extract words and numeric values
-    let precedingWord = Object.keys(preceding)[0]
-    let followingWord = Object.keys(following)[0]
-    const precedingValue = Object.values(preceding)[0] // BigInt
-    const followingValue = Object.values(following)[0] // BigInt
-
-    // Implicit "um": omit before millions ("um milhão" → "milhão")
-    if (precedingValue === 1n) {
-      if (followingValue < 1_000_000n) return { [followingWord]: followingValue }
-      precedingWord = 'um'
-    } else if (precedingValue === 100n && followingValue % 1000n !== 0n) {
-      // Special handling: "cem" (100) becomes "cento" when followed by non-thousands
-      precedingWord = 'cento'
+  // Find the first non-zero segment index (lowest scale with value)
+  let firstNonZeroIdx = 0
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i] !== 0) {
+      firstNonZeroIdx = i
+      break
     }
+  }
+
+  // Build result string directly
+  let result = ''
+  let prevWasScale = false
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
 
-    if (followingValue < precedingValue) {
-      return { [`${precedingWord} e ${followingWord}`]: precedingValue + followingValue }
+    const segmentWord = SEGMENTS[segment]
+    const isLastSegment = (i === firstNonZeroIdx)
+
+    // Add "e" before final segment if previous was scale and this doesn't start with hundreds
+    if (result && isLastSegment && prevWasScale && !SEGMENTS_STARTS_WITH_HUNDREDS[segment]) {
+      result += ' e'
     }
 
-    // Handle "milião" -> "milhão" conversion
-    if (followingWord === 'milião') followingWord = 'milhão'
+    if (result) result += ' '
 
-    // Pluralization logic for large numbers
-    if (precedingValue > 1n) {
-      if (followingValue % 1_000_000_000n === 0n) {
-        followingWord = followingWord.replace('bilião', 'biliões')
-      } else if (followingValue % 1_000_000n === 0n) {
-        followingWord = followingWord.replace('milhão', 'milhões')
+    if (i === 0) {
+      // Units segment
+      result += segmentWord
+      prevWasScale = false
+    } else if (i === 1) {
+      // Thousands
+      if (segment === 1) {
+        result += THOUSAND
+      } else {
+        result += segmentWord + ' ' + THOUSAND
+      }
+      prevWasScale = true
+    } else {
+      // Million and above - use precomputed scale arrays
+      const scaleWord = segment === 1 ? SCALE_WORDS_SINGULAR[i] : SCALE_WORDS_PLURAL[i]
+      if (segment === 1) {
+        result += 'um ' + scaleWord
+      } else {
+        result += segmentWord + ' ' + scaleWord
       }
+      prevWasScale = true
     }
+  }
 
-    if (followingValue === 100n) {
-      precedingWord = this.hundredsWords[precedingValue]
-      return { [`${precedingWord}`]: precedingValue * followingValue }
-    }
+  return result
+}
+
+/**
+ * Converts decimal digits to Portuguese words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Portuguese words for decimal part
+ */
+function decimalPartToWords (decimalPart) {
+  let result = ''
 
-    return { [`${precedingWord} ${followingWord}`]: precedingValue * followingValue }
+  // 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 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'
+ */
+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/ro.d.ts

@@ -1,158 +1,18 @@
 /**
- * Romanian language converter.
+ * Converts a numeric value to Romanian words.
  *
- * Supports:
- * - Gender agreement (unu/una, doi/două)
- * - Complex pluralization (singular/plural forms)
- * - "De" preposition insertion for groups >= 20
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Conversion options
+ * @param {string} [options.gender='masculine'] - Gender for numbers
+ * @returns {string} The number in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)                        // 'douăzeci și unu'
+ * toWords(1, { gender: 'feminine' }) // 'una'
+ * toWords(1000)                      // 'o mie'
  */
-export class Romanian extends AbstractLanguage {
-    constructor(options?: {});
-    onesWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    onesFeminineWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    teensWords: {
-        0: string;
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    teensMasculineWords: {
-        0: string;
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    twentiesWords: {
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    hundredsWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    /**
-     * Romanian big units.
-     * For each power group we keep: singular, plural, feminineUnits?, needsDe?
-     * - 10^3: mie/mii (feminine units in segment; "de" for segment >= 20)
-     * - 10^6: milion/milioane ("de" for segment >= 20)
-     * - 10^9: miliard/miliarde ("de" for segment >= 20)
-     */
-    scaleMetadata: {
-        1: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        2: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        3: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        4: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        5: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        6: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        7: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        8: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        9: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-        10: {
-            singular: string;
-            plural: string;
-            feminine: boolean;
-            needsDe: boolean;
-        };
-    };
-    /** Split numeric string into BigInt segments of specified size from left to right. */
-    splitToSegments(n: any, x: any): bigint[];
-    extractDigits(value: any): any;
-    /** Romanian pluralization & "de" rule for big units. */
-    romanianPluralize(segment: any, form: any): string;
-    spellUnder100(n: any, feminineUnits?: boolean, masculineTeens?: boolean): any;
-    spellUnder1000(n: any, feminineUnits?: boolean, masculineTeens?: boolean): any;
-    /** Decimals always use masculine forms regardless of gender option. */
-    decimalIntegerToWords(integerPart: any): any;
-    integerToWords(integerPart: any): string;
-}
-import { AbstractLanguage } from '../classes/abstract-language.js';
+export function toWords(value: number | string | bigint, options?: {
+    gender?: string | undefined;
+}): string;