n2words 3.1.0 → 4.0.0

package/src/es-US.js

@@ -0,0 +1,446 @@
+/**
+ * Spanish (United States) language converter
+ *
+ * CLDR: es-US | Spanish as used in the United States
+ *
+ * Uses the short scale numbering system (like US English):
+ * - 10⁶ = millón
+ * - 10⁹ = billón (billion)
+ * - 10¹² = trillón (trillion)
+ *
+ * Spanish-specific rules:
+ * - Gender agreement: uno/una, veintiuno/veintiuna, hundreds
+ * - Special twenties: veinte, veintiuno, veintidós, ... veintinueve
+ * - "y" conjunction: treinta y uno (only 30-99 with ones)
+ * - "cien" for exact 100, "ciento/cienta" otherwise
+ * - Irregular hundreds: quinientos, setecientos, novecientos
+ * - "un" before millón (not "uno"), omit before mil
+ */
+
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { validateOptions } from './utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES_MASC = ['', 'uno', 'dos', 'tres', 'cuatro', 'cinco', 'seis', 'siete', 'ocho', 'nueve']
+const ONES_FEM = ['', 'una', 'dos', 'tres', 'cuatro', 'cinco', 'seis', 'siete', 'ocho', 'nueve']
+
+const TEENS = ['diez', 'once', 'doce', 'trece', 'catorce', 'quince', 'dieciseis', 'diecisiete', 'dieciocho', 'diecinueve']
+
+// 20-29 have special compound forms
+const TWENTIES_MASC = ['veinte', 'veintiuno', 'veintidós', 'veintitrés', 'veinticuatro', 'veinticinco', 'veintiséis', 'veintisiete', 'veintiocho', 'veintinueve']
+const TWENTIES_FEM = ['veinte', 'veintiuna', 'veintidós', 'veintitrés', 'veinticuatro', 'veinticinco', 'veintiséis', 'veintisiete', 'veintiocho', 'veintinueve']
+
+const TENS = ['', '', '', 'treinta', 'cuarenta', 'cincuenta', 'sesenta', 'setenta', 'ochenta', 'noventa']
+
+// Irregular hundreds
+const HUNDREDS_MASC = ['', 'ciento', 'doscientos', 'trescientos', 'cuatrocientos', 'quinientos', 'seiscientos', 'setecientos', 'ochocientos', 'novecientos']
+const HUNDREDS_FEM = ['', 'cienta', 'doscientas', 'trescientas', 'cuatrocientas', 'quinientas', 'seiscientas', 'setecientas', 'ochocientas', 'novecientas']
+
+// Scale words (short scale - each scale is 10^3 apart)
+const SCALES = ['mil', 'millón', 'billón', 'trillón', 'cuatrillón', 'quintillón']
+const SCALES_PLURAL = ['mil', 'millones', 'billones', 'trillones', 'cuatrillones', 'quintillones']
+
+const ZERO = 'cero'
+const NEGATIVE = 'menos'
+const DECIMAL_SEP = 'punto'
+
+// Ordinal vocabulary (identical across Spanish regions)
+const ORDINAL_ONES_MASC = ['', 'primero', 'segundo', 'tercero', 'cuarto', 'quinto', 'sexto', 'séptimo', 'octavo', 'noveno']
+const ORDINAL_ONES_FEM = ['', 'primera', 'segunda', 'tercera', 'cuarta', 'quinta', 'sexta', 'séptima', 'octava', 'novena']
+const ORDINAL_TENS_MASC = ['', 'décimo', 'vigésimo', 'trigésimo', 'cuadragésimo', 'quincuagésimo', 'sexagésimo', 'septuagésimo', 'octogésimo', 'nonagésimo']
+const ORDINAL_TENS_FEM = ['', 'décima', 'vigésima', 'trigésima', 'cuadragésima', 'quincuagésima', 'sexagésima', 'septuagésima', 'octogésima', 'nonagésima']
+const ORDINAL_HUNDRED_MASC = 'centésimo'
+const ORDINAL_HUNDRED_FEM = 'centésima'
+const ORDINAL_THOUSAND_MASC = 'milésimo'
+const ORDINAL_THOUSAND_FEM = 'milésima'
+const ORDINAL_MILLION_MASC = 'millonésimo'
+const ORDINAL_MILLION_FEM = 'millonésima'
+
+// Currency vocabulary (US Dollar - USD)
+const DOLAR = 'dólar'
+const DOLARES = 'dólares'
+const CENTAVO = 'centavo'
+const CENTAVOS = 'centavos'
+const CURRENCY_CONNECTOR = 'con'
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds segment word for 0-999.
+ * @param {number} n - Segment value
+ * @param {boolean} feminine - Use feminine forms
+ * @returns {string} Spanish word
+ */
+function buildSegment (n, feminine) {
+  if (n === 0) return ''
+
+  // Special case: exact 100 is "cien" (no gender)
+  if (n === 100) return 'cien'
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
+  const tensOnes = n % 100
+
+  const parts = []
+
+  // Hundreds
+  if (hundreds > 0) {
+    const hundredsArr = feminine ? HUNDREDS_FEM : HUNDREDS_MASC
+    parts.push(hundredsArr[hundreds])
+  }
+
+  // Tens and ones
+  if (tensOnes === 0) {
+    // Just hundreds
+  } else if (tensOnes < 10) {
+    // Single digit
+    const onesArr = feminine ? ONES_FEM : ONES_MASC
+    parts.push(onesArr[tensOnes])
+  } else if (tensOnes < 20) {
+    // 10-19: teens
+    parts.push(TEENS[ones])
+  } else if (tensOnes < 30) {
+    // 20-29: special twenties
+    const twentiesArr = feminine ? TWENTIES_FEM : TWENTIES_MASC
+    parts.push(twentiesArr[ones])
+  } else {
+    // 30-99: tens y ones
+    if (ones === 0) {
+      parts.push(TENS[tens])
+    } else {
+      const onesArr = feminine ? ONES_FEM : ONES_MASC
+      parts.push(TENS[tens] + ' y ' + onesArr[ones])
+    }
+  }
+
+  return parts.join(' ')
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Spanish words (short scale).
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {boolean} feminine - Use feminine forms
+ * @returns {string} Spanish words
+ */
+function integerToWords (n, feminine) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    return buildSegment(Number(n), feminine)
+  }
+
+  // Extract segments using BigInt division
+  // Each segment is 3 digits, short scale increments by 10^3
+  const segmentValues = []
+  let temp = n
+  while (temp > 0n) {
+    segmentValues.push(temp % 1000n)
+    temp = temp / 1000n
+  }
+
+  // Build result string
+  let result = ''
+
+  for (let i = segmentValues.length - 1; i >= 0; i--) {
+    const segment = segmentValues[i]
+    if (segment === 0n) continue
+
+    if (result) result += ' '
+
+    if (i === 0) {
+      // Units segment - use requested gender
+      result += buildSegment(Number(segment), feminine)
+    } else if (i === 1) {
+      // Thousands: "mil" not "uno mil"
+      if (segment === 1n) {
+        result += SCALES[0]
+      } else {
+        result += buildSegment(Number(segment), false) + ' ' + SCALES[0]
+      }
+    } else {
+      // Millions and above: "un millón", "dos millones", etc.
+      const scaleIndex = i - 1 // SCALES[1] = millón, SCALES[2] = billón, etc.
+      if (scaleIndex >= SCALES.length) {
+        // Beyond our scale vocabulary
+        result += buildSegment(Number(segment), false)
+      } else if (segment === 1n) {
+        // "un millón" not "uno millón"
+        result += 'un ' + SCALES[scaleIndex]
+      } else {
+        result += buildSegment(Number(segment), false) + ' ' + SCALES_PLURAL[scaleIndex]
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Converts decimal digits to Spanish words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @param {boolean} feminine - Use feminine forms
+ * @returns {string} Spanish words for decimal part
+ */
+function decimalPartToWords (decimalPart, feminine) {
+  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), feminine)
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Spanish words (US short scale).
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @returns {string} The number in Spanish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(21)                        // 'veintiuno'
+ * toCardinal(21, {gender: 'feminine'})  // 'veintiuna'
+ * toCardinal(1000000000)                // 'un billón'
+ */
+function toCardinal (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  // Apply option defaults
+  const { gender = 'masculine' } = options
+  const feminine = gender === 'feminine'
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, feminine)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, feminine)
+  }
+
+  return result
+}
+
+// ============================================================================
+// ORDINAL: toOrdinal(value, options?)
+// ============================================================================
+
+/**
+ * Builds ordinal word for a 0-999 segment.
+ *
+ * @param {number} n - Segment value 0-999
+ * @param {boolean} feminine - Use feminine forms
+ * @returns {string} Spanish ordinal word
+ */
+function buildOrdinalSegment (n, feminine) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
+
+  const onesArr = feminine ? ORDINAL_ONES_FEM : ORDINAL_ONES_MASC
+  const tensArr = feminine ? ORDINAL_TENS_FEM : ORDINAL_TENS_MASC
+  const hundredWord = feminine ? ORDINAL_HUNDRED_FEM : ORDINAL_HUNDRED_MASC
+
+  const parts = []
+
+  // Hundreds
+  if (hundreds > 0) {
+    if (hundreds === 1) {
+      parts.push(hundredWord)
+    } else {
+      const prefixes = ['', '', 'du', 'tri', 'cuadri', 'quin', 'sex', 'septi', 'octi', 'noni']
+      parts.push(prefixes[hundreds] + hundredWord)
+    }
+  }
+
+  // Tens
+  if (tens > 0) {
+    parts.push(tensArr[tens])
+  }
+
+  // Ones
+  if (ones > 0) {
+    parts.push(onesArr[ones])
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * Converts a positive integer to Spanish ordinal words.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @param {boolean} feminine - Use feminine forms
+ * @returns {string} Spanish ordinal words
+ */
+function integerToOrdinal (n, feminine) {
+  const thousandWord = feminine ? ORDINAL_THOUSAND_FEM : ORDINAL_THOUSAND_MASC
+  const millionWord = feminine ? ORDINAL_MILLION_FEM : ORDINAL_MILLION_MASC
+
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    return buildOrdinalSegment(Number(n), feminine)
+  }
+
+  // Numbers 1000-999999
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    let result = ''
+
+    if (thousands === 1) {
+      result = thousandWord
+    } else {
+      result = buildOrdinalSegment(thousands, feminine) + ' ' + thousandWord
+    }
+
+    if (remainder > 0) {
+      result += ' ' + buildOrdinalSegment(remainder, feminine)
+    }
+
+    return result
+  }
+
+  // Numbers >= 1,000,000
+  const millions = Number(n / 1_000_000n)
+  const remainder = n % 1_000_000n
+
+  let result = ''
+
+  if (millions === 1) {
+    result = millionWord
+  } else {
+    result = buildOrdinalSegment(millions, feminine) + ' ' + millionWord
+  }
+
+  if (remainder > 0n) {
+    result += ' ' + integerToOrdinal(remainder, feminine)
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Spanish ordinal words.
+ *
+ * @param {number | string | bigint} value - The positive integer to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @returns {string} The number in Spanish ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)                          // 'primero'
+ * toOrdinal(1, { gender: 'feminine' })  // 'primera'
+ * toOrdinal(21)                         // 'vigésimo primero'
+ */
+function toOrdinal (value, options) {
+  options = validateOptions(options)
+  const integerPart = parseOrdinalValue(value)
+
+  const { gender = 'masculine' } = options
+  const feminine = gender === 'feminine'
+
+  return integerToOrdinal(integerPart, feminine)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to US Dollar currency words in Spanish.
+ *
+ * US Dollar uses masculine gender for dólares (el dólar)
+ * and masculine for centavos (el centavo).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "con" between dollars and cents
+ * @returns {string} The amount in Spanish US Dollar currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42.50)                  // 'cuarenta y dos dólares con cincuenta centavos'
+ * toCurrency(1)                      // 'un dólar'
+ * toCurrency(0.99)                   // 'noventa y nueve centavos'
+ * toCurrency(42.50, { and: false })  // 'cuarenta y dos dólares cincuenta centavos'
+ */
+function toCurrency (value, options) {
+  options = validateOptions(options)
+  const { isNegative, dollars, cents: centavos } = parseCurrencyValue(value)
+  const { and: useAnd = true } = options
+
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Dollars part (show if non-zero, or if no centavos)
+  if (dollars > 0n || centavos === 0n) {
+    // Use masculine for dollars, but "un dólar" not "uno dólar"
+    if (dollars === 1n) {
+      result += 'un ' + DOLAR
+    } else {
+      result += integerToWords(dollars, false) + ' ' + DOLARES
+    }
+  }
+
+  // Centavos part
+  if (centavos > 0n) {
+    if (dollars > 0n) {
+      result += useAnd ? ' ' + CURRENCY_CONNECTOR + ' ' : ' '
+    }
+    // Use masculine for centavos, but "un centavo" not "uno centavo"
+    if (centavos === 1n) {
+      result += 'un ' + CENTAVO
+    } else {
+      result += integerToWords(centavos, false) + ' ' + CENTAVOS
+    }
+  }
+
+  return result
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toCardinal, toOrdinal, toCurrency }

package/src/fa-IR.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Converts a numeric value to Persian words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Persian words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Persian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'اول'
+ * toOrdinal(2)    // 'دوم'
+ * toOrdinal(10)   // 'دهم'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Persian currency words (Rial).
+ *
+ * Iranian Rial has no subunit in modern usage.
+ * (Historically dinar was 1/100 rial, but not used today)
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Persian currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42)     // 'چهل و دو ریال'
+ * toCurrency(1000)   // 'هزار ریال'
+ * toCurrency(-5)     // 'منفى پنج ریال'
+ */
+export function toCurrency(value: number | string | bigint): string;