n2words 1.24.0 → 3.0.0

package/lib/languages/pt.js

@@ -1,147 +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)
+// ============================================================================
 
 /**
- * (European) Portuguese language converter.
+ * 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
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Portuguese words.
  *
- * Features:
- * - Gender-aware hundreds (hundredos, duzentos, etc.)
- * - Million/Billion pluralization
- * - "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'
-  scaleWordPairs = [
-    [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']
-  ]
-
-  hundreds = {
-    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
   }
 
-  /**
-   * Merges two adjacent word-number pairs according to Portuguese grammar rules.
-   *
-   * Portuguese-specific rules:
-   * - Implicit "um": `mergeScales({ 'um': 1n }, { 'mil': 1000n })` → `{ 'mil': 1000n }`
-   * - "e" (and) between most combinations: `mergeScales({ 'vinte': 20n }, { 'três': 3n })` → `{ 'vinte e três': 23n }`
-   * - Special handling: "cem" (100) becomes "cento" when followed by non-thousands
-   * - Gender-aware hundreds: "duzentos", "trezentos", etc.
-   * - Million pluralization: "milhões" instead of "milhão" when coefficient > 1
-   * - Post-processing with postClean() to normalize word flow
-   *
-   * @param {Object} current The left operand as `{ word: BigInt }`.
-   * @param {Object} next The right operand as `{ word: BigInt }`.
-   * @returns {Object} Merged pair with combined word and resulting numeric value.
-   *
-   * @example
-   * mergeScales({ 'um': 1n }, { 'mil': 1000n }); // { 'mil': 1000n }
-   * mergeScales({ 'vinte': 20n }, { 'dois': 2n }); // { 'vinte e dois': 22n }
-   */
-  mergeScales (current, next) {
-    // Extract words and numeric values
-    let cText = Object.keys(current)[0]
-    let nText = Object.keys(next)[0]
-    const cNumber = Object.values(current)[0] // BigInt
-    const nNumber = Object.values(next)[0] // BigInt
-
-    // Implicit "um": omit before millions ("um milhão" → "milhão")
-    if (cNumber === 1n) {
-      if (nNumber < 1_000_000n) return { [nText]: nNumber }
-      cText = 'um'
-    } else if (cNumber === 100n && nNumber % 1000n !== 0n) {
-      // Special handling: "cem" (100) becomes "cento" when followed by non-thousands
-      cText = '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
+
+    const segmentWord = SEGMENTS[segment]
+    const isLastSegment = (i === firstNonZeroIdx)
 
-    if (nNumber < cNumber) {
-      return { [`${cText} e ${nText}`]: cNumber + nNumber }
+    // 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 (nText === 'milião') nText = 'milhão'
+    if (result) result += ' '
 
-    // Pluralization logic for large numbers
-    if (cNumber > 1n) {
-      if (nNumber % 1_000_000_000n === 0n) {
-        nText = nText.replace('bilião', 'biliões')
-      } else if (nNumber % 1_000_000n === 0n) {
-        nText = nText.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 (nNumber === 100n) {
-      cText = this.hundreds[cNumber]
-      return { [`${cText}`]: cNumber * nNumber }
-    }
+  return result
+}
 
-    return { [`${cText} ${nText}`]: cNumber * nNumber }
+/**
+ * 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 = ''
+
+  // 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 Portuguese cardinal (written) form.
+ * Converts a numeric value to Portuguese words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see Portuguese class options).
- * @returns {string} The number expressed in Portuguese words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
+ * 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
- * convertToWords(42); // 'quarenta e dois'
- * convertToWords('100.5'); // 'cem vírgula cinco'
+ * toWords(21)           // 'vinte e um'
+ * toWords(100)          // 'cem'
+ * toWords(1000000)      // 'um milhão'
  */
-export default function convertToWords (value, options = {}) {
-  return new Portuguese(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/ro.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts a numeric value to Romanian words.
+ *
+ * @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 function toWords(value: number | string | bigint, options?: {
+    gender?: string | undefined;
+}): string;