n2words 3.0.0 → 4.0.0

package/{lib/languages/fil.js → src/fil-PH.js}

@@ -1,7 +1,7 @@
 /**
- * Filipino language converter - Functional Implementation
+ * Filipino (Philippines) language converter
  *
- * Self-contained converter with precomputed lookup tables.
+ * CLDR: fil-PH | Filipino as used in the Philippines
  *
  * Key features:
  * - Linker "ng" after vowels: "isang daang" (100)
@@ -10,7 +10,9 @@
  * - Per-digit decimal reading
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
 
 // ============================================================================
 // Vocabulary
@@ -31,6 +33,25 @@ const DECIMAL_SEP = 'punto'
 // Short scale with linker
 const SCALE_WORDS = ['', THOUSAND, 'milyong', 'bilyong', 'trilyong']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Filipino ordinals use "ika-" prefix: ika-isa (1st), ikalawa (2nd), etc.
+// Special forms for 1st and 2nd
+const ORDINAL_PREFIX = 'ika'
+const ORDINAL_SPECIAL = {
+  1: 'una', // first
+  2: 'ikalawa' // second (contracted form)
+}
+
+// ============================================================================
+// Currency Vocabulary (Philippine Peso)
+// ============================================================================
+
+const PESO = 'piso'
+const SENTIMO = 'sentimo'
+
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -46,15 +67,15 @@ function addLinker (word) {
 }
 
 // ============================================================================
-// Precomputed Lookup Table
+// Segment Building
 // ============================================================================
 
 function buildSegment (n) {
   if (n === 0) return ''
 
   const ones = n % 10
-  const tensDigit = Math.floor(n / 10) % 10
-  const hundredsDigit = Math.floor(n / 100)
+  const tensDigit = Math.trunc(n / 10) % 10
+  const hundredsDigit = Math.trunc(n / 100)
 
   const parts = []
 
@@ -91,16 +112,11 @@ function buildSegment (n) {
   return parts.join(' ')
 }
 
-const SEGMENTS = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
 /**
  * Builds segment with linker added to last word (for use before scale words).
  */
 function buildSegmentWithLinker (n) {
-  const segmentWord = SEGMENTS[n]
+  const segmentWord = buildSegment(n)
   if (!segmentWord) return ''
 
   // Find the last space to get the last word
@@ -124,12 +140,6 @@ function buildSegmentWithLinker (n) {
   return prefix + addLinker(lastWord)
 }
 
-// Precompute segments with linker for scale word usage
-const SEGMENTS_WITH_LINKER = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_WITH_LINKER[i] = buildSegmentWithLinker(i)
-}
-
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -138,7 +148,7 @@ function integerToWords (n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   return buildLargeNumberWords(n)
@@ -170,10 +180,10 @@ function buildLargeNumberWords (n) {
     if (result) result += ' '
 
     if (i === 0) {
-      result += SEGMENTS[segment]
+      result += buildSegment(segment)
     } else {
       // Add linker to segment before scale word
-      const segmentWord = SEGMENTS_WITH_LINKER[segment]
+      const segmentWord = buildSegmentWithLinker(segment)
       result += segmentWord + ' ' + scaleWord
     }
   }
@@ -197,8 +207,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Filipino words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -215,8 +225,123 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Filipino ordinal words.
+ *
+ * Filipino ordinals: una (1st), ikalawa (2nd), then ika- + cardinal.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Filipino ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special forms for 1st and 2nd
+  if (n === 1n) return ORDINAL_SPECIAL[1]
+  if (n === 2n) return ORDINAL_SPECIAL[2]
+
+  // For 3+, use ika- prefix + cardinal
+  return ORDINAL_PREFIX + '-' + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Filipino 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)    // 'una'
+ * toOrdinal(2)    // 'ikalawa'
+ * toOrdinal(3)    // 'ika-tatlo'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Filipino currency words (Philippine Peso).
+ *
+ * Uses piso (peso) and sentimo (centavo).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Filipino 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)     // 'apatnapu dalawang piso'
+ * toCurrency(1.50)   // 'isang piso at limampung sentimo'
+ * toCurrency(-5)     // 'negatibo limang piso'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: pesos, cents: sentimos } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Pesos part
+  if (pesos > 0n || sentimos === 0n) {
+    // Add linker before "piso"
+    const pesoWords = integerToWords(pesos)
+    if (pesos === 0n) {
+      result += pesoWords + ' ' + PESO
+    } else {
+      // Need to add linker to the last word before "piso"
+      const lastSpaceIdx = pesoWords.lastIndexOf(' ')
+      if (lastSpaceIdx === -1) {
+        // Single word
+        result += addLinker(pesoWords) + ' ' + PESO
+      } else {
+        const prefix = pesoWords.slice(0, lastSpaceIdx + 1)
+        const lastWord = pesoWords.slice(lastSpaceIdx + 1)
+        if (lastWord.endsWith('ng')) {
+          result += pesoWords + ' ' + PESO
+        } else {
+          result += prefix + addLinker(lastWord) + ' ' + PESO
+        }
+      }
+    }
+  }
+
+  // Sentimos part
+  if (sentimos > 0n) {
+    if (pesos > 0n) {
+      result += ' at '
+    }
+    const sentimoWords = integerToWords(sentimos)
+    // Add linker before "sentimo"
+    const lastSpaceIdx = sentimoWords.lastIndexOf(' ')
+    if (lastSpaceIdx === -1) {
+      // Single word
+      result += addLinker(sentimoWords) + ' ' + SENTIMO
+    } else {
+      const prefix = sentimoWords.slice(0, lastSpaceIdx + 1)
+      const lastWord = sentimoWords.slice(lastSpaceIdx + 1)
+      if (lastWord.endsWith('ng')) {
+        result += sentimoWords + ' ' + SENTIMO
+      } else {
+        result += prefix + addLinker(lastWord) + ' ' + SENTIMO
+      }
+    }
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/fr-BE.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a numeric value to Belgian French words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.withHyphenSeparator=false] - Use hyphens between words
+ * @returns {string} The number in Belgian French words
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    withHyphenSeparator?: boolean | undefined;
+}): string;
+/**
+ * Converts a numeric value to Belgian French ordinal words.
+ *
+ * Belgian French ordinals: premier (1st), then cardinal + ième.
+ * Special rules: quatre→quatrième, cinq→cinquième, neuf→neuvième.
+ *
+ * @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)    // 'premier'
+ * toOrdinal(2)    // 'deuxième'
+ * toOrdinal(70)   // 'septantième'
+ * toOrdinal(90)   // 'nonantième'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Belgian French currency words (Euro).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "et" between euros and centimes
+ * @returns {string} The amount in Belgian French 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)                 // 'quarante-deux euros et cinquante centimes'
+ * toCurrency(1)                     // 'un euro'
+ * toCurrency(0.99)                  // 'nonante-neuf centimes'
+ * toCurrency(0.01)                  // 'un centime'
+ * toCurrency(42.50, { and: false }) // 'quarante-deux euros cinquante centimes'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;