n2words 3.0.0 → 3.1.0

package/lib/languages/vi.js

@@ -1,13 +1,9 @@
 /**
- * Vietnamese language converter - Functional Implementation v2
+ * Vietnamese 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.
- *
- * Vietnamese-specific rules (handled in precomputation):
+ * Vietnamese-specific rules:
  * - Special pronunciation: "lăm" for 5 in tens position, "mốt" for final 1
  * - "Lẻ" (odd/extra) marker when tens place is zero after hundreds/scales
  * - Short scale system with Vietnamese words (nghìn, triệu, tỷ)
@@ -42,12 +38,11 @@ const MOT_FINAL = 'mốt' // 1 in tens position (21, 31, etc.)
 const LAM = 'lăm' // 5 in tens position (25, 35, etc.)
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
  * Builds word for 0-99 with special forms (mốt, lăm).
- * Only used during table construction.
  */
 function buildBelowHundred (n) {
   if (n === 0) return ONES[0]
@@ -74,7 +69,6 @@ function buildBelowHundred (n) {
 
 /**
  * Builds segment word for 0-999.
- * Only used during table construction.
  */
 function buildSegment (n) {
   if (n === 0) return ''
@@ -101,37 +95,23 @@ function buildSegment (n) {
     } else {
       // 10-99 after hundreds
       if (result) result += ' '
-      result += BELOW_100[remainder]
+      result += buildBelowHundred(remainder)
     }
   }
 
   return result
 }
 
-// Precompute all 100 below-hundred words (0-99)
-// BELOW_100[n] gives the Vietnamese word for n
-const BELOW_100 = new Array(100)
-for (let i = 0; i < 100; i++) {
-  BELOW_100[i] = buildBelowHundred(i)
-}
-
-// Precompute all 1000 segment words (0-999)
-// SEGMENTS[n] gives the Vietnamese word for n within a segment
-const SEGMENTS = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
-// Precompute "lẻ" prefixed versions for small remainders after scale words
-// LE_SEGMENTS[n] gives "lẻ X" for n in range 1-99
-const LE_SEGMENTS = new Array(100)
-LE_SEGMENTS[0] = ''
-for (let i = 1; i < 10; i++) {
-  // Use "năm" not "lăm" after lẻ
-  LE_SEGMENTS[i] = LE + ' ' + (i === 5 ? 'năm' : ONES[i])
-}
-for (let i = 10; i < 100; i++) {
-  LE_SEGMENTS[i] = LE + ' ' + BELOW_100[i]
+/**
+ * Builds "lẻ" prefixed word for small remainders (1-99) after scale words.
+ */
+function buildLeSegment (n) {
+  if (n === 0) return ''
+  if (n < 10) {
+    // Use "năm" not "lăm" after lẻ
+    return LE + ' ' + (n === 5 ? 'năm' : ONES[n])
+  }
+  return LE + ' ' + buildBelowHundred(n)
 }
 
 // ============================================================================
@@ -147,14 +127,14 @@ for (let i = 10; i < 100; i++) {
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 100 (direct lookup)
+  // Fast path: numbers < 100
   if (n < 100n) {
-    return BELOW_100[Number(n)]
+    return buildBelowHundred(Number(n))
   }
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   // Fast path: numbers < 1,000,000 (thousands)
@@ -162,7 +142,7 @@ function integerToWords (n) {
     const thousands = Number(n / 1000n)
     const remainder = Number(n % 1000n)
 
-    const thousandsWords = SEGMENTS[thousands] + ' ' + SCALES[1]
+    const thousandsWords = buildSegment(thousands) + ' ' + SCALES[1]
 
     if (remainder === 0) {
       return thousandsWords
@@ -170,10 +150,10 @@ function integerToWords (n) {
 
     // Check if remainder needs "lẻ" marker (< 100)
     if (remainder < 100) {
-      return thousandsWords + ' ' + LE_SEGMENTS[remainder]
+      return thousandsWords + ' ' + buildLeSegment(remainder)
     }
 
-    return thousandsWords + ' ' + SEGMENTS[remainder]
+    return thousandsWords + ' ' + buildSegment(remainder)
   }
 
   // For numbers >= 1,000,000, use scale decomposition
@@ -212,7 +192,7 @@ function buildLargeNumberWords (n) {
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i]
     if (segment !== 0) {
-      const words = SEGMENTS[segment]
+      const words = buildSegment(segment)
       if (words) {
         if (scaleIndex > 0) {
           parts.push(words + ' ' + SCALES[scaleIndex])
@@ -237,7 +217,7 @@ function buildLargeNumberWords (n) {
     for (let i = 1; i < partsLen - 1; i++) {
       result += ' ' + parts[i]
     }
-    return result + ' ' + LE_SEGMENTS[lastSegment]
+    return result + ' ' + buildLeSegment(lastSegment)
   }
 
   // Join with spaces

package/lib/languages/yo.d.ts

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

package/lib/languages/yo.js

@@ -0,0 +1,303 @@
+/**
+ * Yoruba language converter - Functional Implementation
+ *
+ * A number-to-words converter for Yoruba (yo), a Niger-Congo language
+ * spoken by ~45 million people in Nigeria, Benin, and Togo.
+ *
+ * Yoruba uses a complex vigesimal (base-20) system with:
+ * - Additive patterns: 1-4 added to decade (lé = "plus")
+ * - Subtractive patterns: 5-9 subtracted from next decade (dín = "minus")
+ * - Odd decades (30,50,70,90) formed by subtracting 10 from next even decade
+ * - Even decades (20,40,60,80,100) are multiples of 20
+ *
+ * Examples:
+ * - 21 = ọ̀kan lé lógún (1 + 20)
+ * - 15 = àrùndínlógún (20 - 5)
+ * - 50 = àádọ́ta (60 - 10)
+ * - 45 = àrùndínláàádọ́ta (50 - 5)
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+// Basic numbers 1-10
+const ONES = [
+  '',
+  'ọ̀kan', // 1
+  'èjì', // 2
+  'ẹ̀ta', // 3
+  'ẹ̀rin', // 4
+  'àrùn', // 5
+  'ẹ̀fà', // 6
+  'èje', // 7
+  'ẹ̀jọ', // 8
+  'ẹ̀sán', // 9
+  'ẹ̀wá' // 10
+]
+
+// Numbers 11-14 (additive: X + 10, using "lá")
+const TEENS_ADD = [
+  '',
+  'ọ̀kànlá', // 11 = 1 + 10
+  'èjìlá', // 12 = 2 + 10
+  'ẹ̀talá', // 13 = 3 + 10
+  'ẹ̀rinlá' // 14 = 4 + 10
+]
+
+// Numbers 15-19 (subtractive: 20 - X, using "dín")
+const TEENS_SUB = [
+  'àrùndínlógún', // 15 = 20 - 5
+  'ẹ̀rìndínlógún', // 16 = 20 - 4
+  'ẹ̀tadínlógún', // 17 = 20 - 3
+  'èjìdínlógún', // 18 = 20 - 2
+  'ọ̀kàndínlógún' // 19 = 20 - 1
+]
+
+// Decades (base-20 structure)
+// Even decades are multiples of 20
+// Odd decades subtract 10 from next even decade
+const DECADES = {
+  20: 'ogún', // 20 = 20 × 1
+  30: 'ọgbọ̀n', // 30 = 20 + 10 (special word)
+  40: 'ogójì', // 40 = 20 × 2
+  50: 'àádọ́ta', // 50 = 60 - 10
+  60: 'ogóta', // 60 = 20 × 3
+  70: 'àádọ́rin', // 70 = 80 - 10
+  80: 'ogórin', // 80 = 20 × 4
+  90: 'àádọ́rùn', // 90 = 100 - 10
+  100: 'ọgọ́rùn' // 100 = 20 × 5
+}
+
+// Prefixes for adding to decades (lé lógún, lé lọgbọ̀n, etc.)
+const DECADE_ADD_SUFFIX = {
+  20: 'lógún',
+  30: 'lọgbọ̀n',
+  40: 'lógójì',
+  50: 'láàádọ́ta',
+  60: 'lógóta',
+  70: 'láàádọ́rin',
+  80: 'lógórin',
+  90: 'láàádọ́rùn',
+  100: 'lọ́gọ́rùn'
+}
+
+// Prefixes for subtracting from decades (dín lógójì, etc.)
+const DECADE_SUB_SUFFIX = {
+  20: 'dínlógún',
+  30: 'dínlọgbọ̀n',
+  40: 'dínlógójì',
+  50: 'dínláàádọ́ta',
+  60: 'dínlógóta',
+  70: 'dínláàádọ́rin',
+  80: 'dínlógórin',
+  90: 'dínláàádọ́rùn',
+  100: 'dínlọ́gọ́rùn'
+}
+
+// Scale words
+const HUNDRED = 'ọgọ́rùn'
+const TWO_HUNDRED = 'igba' // 200 (special word, historically 200 cowries)
+const FOUR_HUNDRED = 'irinwó' // 400 (20 × 20)
+const THOUSAND = 'ẹgbẹ̀rún' // 1000
+const TEN_THOUSAND = 'ẹgbàárùn' // 10,000 (special)
+const TWENTY_THOUSAND = 'ọ̀kẹ́' // 20,000 (bag of cowries)
+const MILLION = 'mílíọ̀nù' // million (loanword)
+
+const ZERO = 'òdo'
+const NEGATIVE = 'àìní'
+const DECIMAL_SEP = 'àmì'
+const AND = 'ó lé' // "and" / "plus" connector
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds word for numbers 0-99
+ */
+function buildUnder100 (n) {
+  if (n === 0) return ''
+  if (n <= 10) return ONES[n]
+
+  // 11-14: additive from 10
+  if (n <= 14) return TEENS_ADD[n - 10]
+
+  // 15-19: subtractive from 20
+  if (n <= 19) return TEENS_SUB[n - 15]
+
+  // Exact decades
+  if (n % 10 === 0) return DECADES[n]
+
+  const decade = Math.floor(n / 10) * 10
+  const unit = n % 10
+
+  // 1-4 are added to current decade (21 = 1 + 20, not 1 + 30)
+  if (unit <= 4) {
+    return ONES[unit] + ' lé ' + DECADE_ADD_SUFFIX[decade]
+  }
+
+  // 5-9 are subtracted from next decade
+  const nextDecade = decade + 10
+  const subtractAmount = 10 - unit
+  return ONES[subtractAmount] + DECADE_SUB_SUFFIX[nextDecade]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts hundreds (100-999)
+ */
+function convertHundreds (n) {
+  if (n < 100) return buildUnder100(n)
+
+  const hundreds = Math.floor(n / 100)
+  const remainder = n % 100
+
+  let result
+
+  // Special cases for 200 and 400
+  if (hundreds === 2 && remainder === 0) {
+    return TWO_HUNDRED
+  }
+  if (hundreds === 4 && remainder === 0) {
+    return FOUR_HUNDRED
+  }
+
+  // Build hundreds
+  if (hundreds === 1) {
+    result = HUNDRED
+  } else if (hundreds === 2) {
+    result = TWO_HUNDRED
+  } else if (hundreds === 4) {
+    result = FOUR_HUNDRED
+  } else {
+    // Other hundreds: X ọgọ́rùn
+    result = ONES[hundreds] + ' ' + HUNDRED
+  }
+
+  if (remainder > 0) {
+    result += ' ' + AND + ' ' + buildUnder100(remainder)
+  }
+
+  return result
+}
+
+/**
+ * Converts a non-negative integer to Yoruba words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Yoruba words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 100
+  if (n < 100n) {
+    return buildUnder100(Number(n))
+  }
+
+  // Numbers < 1000
+  if (n < 1000n) {
+    return convertHundreds(Number(n))
+  }
+
+  // Build from segments
+  const parts = []
+  let remaining = n
+
+  // Millions
+  if (remaining >= 1_000_000n) {
+    const millions = remaining / 1_000_000n
+    remaining = remaining % 1_000_000n
+    if (millions === 1n) {
+      parts.push(MILLION + ' kan')
+    } else {
+      parts.push(MILLION + ' ' + integerToWords(millions))
+    }
+  }
+
+  // Thousands
+  if (remaining >= 1000n) {
+    const thousands = remaining / 1000n
+    remaining = remaining % 1000n
+
+    if (thousands === 1n) {
+      parts.push(THOUSAND + ' kan')
+    } else if (thousands === 10n) {
+      parts.push(TEN_THOUSAND)
+    } else if (thousands === 20n) {
+      parts.push(TWENTY_THOUSAND)
+    } else if (thousands < 100n) {
+      parts.push(THOUSAND + ' ' + buildUnder100(Number(thousands)))
+    } else {
+      parts.push(THOUSAND + ' ' + convertHundreds(Number(thousands)))
+    }
+  }
+
+  // Hundreds and below
+  if (remaining > 0n) {
+    if (remaining < 100n) {
+      if (parts.length > 0) {
+        parts.push(AND + ' ' + buildUnder100(Number(remaining)))
+      } else {
+        parts.push(buildUnder100(Number(remaining)))
+      }
+    } else {
+      if (parts.length > 0) {
+        parts.push(AND + ' ' + convertHundreds(Number(remaining)))
+      } else {
+        parts.push(convertHundreds(Number(remaining)))
+      }
+    }
+  }
+
+  return parts.join(', ')
+}
+
+/**
+ * Converts decimal digits to Yoruba words.
+ *
+ * @param {string} decimalPart - Decimal digits
+ * @returns {string} Yoruba words for decimal
+ */
+function decimalPartToWords (decimalPart) {
+  const parts = []
+
+  for (const digit of decimalPart) {
+    const d = parseInt(digit, 10)
+    parts.push(d === 0 ? ZERO : ONES[d])
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * Converts a numeric value to Yoruba words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Yoruba 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
+}
+
+export { toWords }

package/lib/n2words.d.ts

@@ -24,6 +24,7 @@ import { toWords as hu } from './languages/hu.js';
 import { toWords as id } from './languages/id.js';
 import { toWords as it } from './languages/it.js';
 import { toWords as ja } from './languages/ja.js';
+import { toWords as ka } from './languages/ka.js';
 import { toWords as kn } from './languages/kn.js';
 import { toWords as ko } from './languages/ko.js';
 import { toWords as lt } from './languages/lt.js';
@@ -48,6 +49,7 @@ import { toWords as tr } from './languages/tr.js';
 import { toWords as uk } from './languages/uk.js';
 import { toWords as ur } from './languages/ur.js';
 import { toWords as vi } from './languages/vi.js';
+import { toWords as yo } from './languages/yo.js';
 import { toWords as zhHans } from './languages/zh-Hans.js';
 import { toWords as zhHant } from './languages/zh-Hant.js';
-export { am, amLatn, ar, az, bn, cs, da, de, el, en, es, fa, fi, fil, fr, frBE, gu, ha, hbo, he, hi, hr, hu, id, it, ja, kn, ko, lt, lv, mr, ms, nb, nl, pa, pl, pt, ro, ru, srCyrl, srLatn, sv, sw, ta, te, th, tr, uk, ur, vi, zhHans, zhHant };
+export { am, amLatn, ar, az, bn, cs, da, de, el, en, es, fa, fi, fil, fr, frBE, gu, ha, hbo, he, hi, hr, hu, id, it, ja, ka, kn, ko, lt, lv, mr, ms, nb, nl, pa, pl, pt, ro, ru, srCyrl, srLatn, sv, sw, ta, te, th, tr, uk, ur, vi, yo, zhHans, zhHant };

package/lib/n2words.js

@@ -39,6 +39,7 @@ import { toWords as hu } from './languages/hu.js'
 import { toWords as id } from './languages/id.js'
 import { toWords as it } from './languages/it.js'
 import { toWords as ja } from './languages/ja.js'
+import { toWords as ka } from './languages/ka.js'
 import { toWords as kn } from './languages/kn.js'
 import { toWords as ko } from './languages/ko.js'
 import { toWords as lt } from './languages/lt.js'
@@ -63,6 +64,7 @@ import { toWords as tr } from './languages/tr.js'
 import { toWords as uk } from './languages/uk.js'
 import { toWords as ur } from './languages/ur.js'
 import { toWords as vi } from './languages/vi.js'
+import { toWords as yo } from './languages/yo.js'
 import { toWords as zhHans } from './languages/zh-Hans.js'
 import { toWords as zhHant } from './languages/zh-Hant.js'
 
@@ -93,6 +95,7 @@ export {
   id,
   it,
   ja,
+  ka,
   kn,
   ko,
   lt,
@@ -117,6 +120,7 @@ export {
   uk,
   ur,
   vi,
+  yo,
   zhHans,
   zhHant
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n2words",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Convert numbers to words in 52 languages with zero dependencies. Supports BigInt, decimals, and browser/Node.js environments.",
   "keywords": [
     "number-to-words",