n2words 1.24.0 → 3.0.0

package/lib/languages/ru.js

@@ -1,116 +1,240 @@
-import SlavicLanguage from '../classes/slavic-language.js'
-
 /**
- * @typedef {Object} SlavicOptions
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
- */
-
-/**
- * Russian language converter.
- *
- * Converts numbers to Russian words with full grammatical support:
- * - Gender agreement (masculine/feminine forms)
- * - Complex pluralization rules (one/few/many forms)
- * - Declension patterns for thousands, millions, billions, etc.
- * - Proper case endings for number words
+ * Russian language converter - Functional Implementation
  *
- * Features:
- * - Gender-aware forms (один/одна, два/две)
- * - Three-form pluralization (тысяча/тысячи/тысяч)
- * - Support for very large numbers (up to nonillions)
- * - Proper spacing and conjunction rules
+ * Self-contained converter using shared Slavic utilities.
  *
- * This class extends SlavicLanguage, which provides the conversion algorithm
- * shared by Czech, Polish, Ukrainian, Serbian, Croatian, Hebrew, Lithuanian, Latvian.
+ * Key features:
+ * - Three-form pluralization (one/few/many)
+ * - Gender: thousands are feminine, millions+ are masculine
+ * - Irregular hundreds (двести, триста, etc.)
+ * - Long scale naming
  */
-export class Russian extends SlavicLanguage {
-  negativeWord = 'минус'
-  decimalSeparatorWord = 'запятая'
-  zeroWord = 'ноль'
-
-  ones = {
-    1: 'один',
-    2: 'два',
-    3: 'три',
-    4: 'четыре',
-    5: 'пять',
-    6: 'шесть',
-    7: 'семь',
-    8: 'восемь',
-    9: 'девять'
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Slavic Utilities (inlined for performance)
+// ============================================================================
+
+function pluralize (n, forms) {
+  const num = typeof n === 'bigint' ? Number(n) : n
+  const lastDigit = num % 10
+  const lastTwoDigits = num % 100
+
+  if (lastTwoDigits >= 11 && lastTwoDigits <= 19) {
+    return forms[2]
   }
 
-  onesFeminine = {
-    1: 'одна',
-    2: 'две',
-    3: 'три',
-    4: 'четыре',
-    5: 'пять',
-    6: 'шесть',
-    7: 'семь',
-    8: 'восемь',
-    9: 'девять'
+  if (lastDigit === 1) return forms[0]
+  if (lastDigit >= 2 && lastDigit <= 4) return forms[1]
+  return forms[2]
+}
+
+function buildAllSegments (onesMasc, onesFem, teens, tens, hundreds) {
+  const masc = new Array(1000)
+  const fem = new Array(1000)
+
+  for (let i = 0; i < 1000; i++) {
+    masc[i] = buildSegment(i, onesMasc, teens, tens, hundreds)
+    fem[i] = buildSegment(i, onesFem, teens, tens, hundreds)
   }
 
-  tens = {
-    0: 'десять',
-    1: 'одиннадцать',
-    2: 'двенадцать',
-    3: 'тринадцать',
-    4: 'четырнадцать',
-    5: 'пятнадцать',
-    6: 'шестнадцать',
-    7: 'семнадцать',
-    8: 'восемнадцать',
-    9: 'девятнадцать'
+  return { masc, fem }
+}
+
+function buildSegment (n, ones, teens, tens, hundreds) {
+  if (n === 0) return ''
+
+  const onesDigit = n % 10
+  const tensDigit = Math.floor(n / 10) % 10
+  const hundredsDigit = Math.floor(n / 100)
+
+  const parts = []
+
+  if (hundredsDigit > 0) {
+    parts.push(hundreds[hundredsDigit])
   }
 
-  twenties = {
-    2: 'двадцать',
-    3: 'тридцать',
-    4: 'сорок',
-    5: 'пятьдесят',
-    6: 'шестьдесят',
-    7: 'семьдесят',
-    8: 'восемьдесят',
-    9: 'девяносто'
+  if (tensDigit > 1) {
+    parts.push(tens[tensDigit])
   }
 
-  hundreds = {
-    1: 'сто',
-    2: 'двести',
-    3: 'триста',
-    4: 'четыреста',
-    5: 'пятьсот',
-    6: 'шестьсот',
-    7: 'семьсот',
-    8: 'восемьсот',
-    9: 'девятьсот'
+  if (tensDigit === 1) {
+    parts.push(teens[onesDigit])
+  } else if (onesDigit > 0) {
+    parts.push(ones[onesDigit])
   }
 
-  thousands = {
-    1: ['тысяча', 'тысячи', 'тысяч'], // 10^ 3
-    2: ['миллион', 'миллиона', 'миллионов'], // 10^ 6
-    3: ['миллиард', 'миллиарда', 'миллиардов'], // 10^ 9
-    4: ['триллион', 'триллиона', 'триллионов'], // 10^ 12
-    5: ['квадриллион', 'квадриллиона', 'квадриллионов'], // 10^ 15
-    6: ['квинтиллион', 'квинтиллиона', 'квинтиллионов'], // 10^ 18
-    7: ['секстиллион', 'секстиллиона', 'секстиллионов'], // 10^ 21
-    8: ['септиллион', 'септиллиона', 'септиллионов'], // 10^ 24
-    9: ['октиллион', 'октиллиона', 'октиллионов'], // 10^ 27
-    10: ['нониллион', 'нониллиона', 'нониллионов'] // 10^ 30
+  return parts.join(' ')
+}
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ONES_MASC = ['', 'один', 'два', 'три', 'четыре', 'пять', 'шесть', 'семь', 'восемь', 'девять']
+const ONES_FEM = ['', 'одна', 'две', 'три', 'четыре', 'пять', 'шесть', 'семь', 'восемь', 'девять']
+
+const TEENS = ['десять', 'одиннадцать', 'двенадцать', 'тринадцать', 'четырнадцать', 'пятнадцать', 'шестнадцать', 'семнадцать', 'восемнадцать', 'девятнадцать']
+const TENS = ['', '', 'двадцать', 'тридцать', 'сорок', 'пятьдесят', 'шестьдесят', 'семьдесят', 'восемьдесят', 'девяносто']
+
+// Irregular hundreds
+const HUNDREDS = ['', 'сто', 'двести', 'триста', 'четыреста', 'пятьсот', 'шестьсот', 'семьсот', 'восемьсот', 'девятьсот']
+
+const ZERO = 'ноль'
+const NEGATIVE = 'минус'
+const DECIMAL_SEP = 'запятая'
+
+// Scale words: [singular, few, many]
+// Thousands (index 0) are feminine, rest are masculine
+const SCALE_FORMS = [
+  ['тысяча', 'тысячи', 'тысяч'],
+  ['миллион', 'миллиона', 'миллионов'],
+  ['миллиард', 'миллиарда', 'миллиардов'],
+  ['триллион', 'триллиона', 'триллионов'],
+  ['квадриллион', 'квадриллиона', 'квадриллионов'],
+  ['квинтиллион', 'квинтиллиона', 'квинтиллионов'],
+  ['секстиллион', 'секстиллиона', 'секстиллионов'],
+  ['септиллион', 'септиллиона', 'септиллионов'],
+  ['октиллион', 'октиллиона', 'октиллионов'],
+  ['нониллион', 'нониллиона', 'нониллионов']
+]
+
+// ============================================================================
+// Precomputed Lookup Tables
+// ============================================================================
+
+const { masc: SEGMENTS_MASC, fem: SEGMENTS_FEM } = buildAllSegments(ONES_MASC, ONES_FEM, TEENS, TENS, HUNDREDS)
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n, options = {}) {
+  if (n === 0n) return ZERO
+
+  const feminine = options.gender === 'feminine'
+
+  if (n < 1000n) {
+    const segments = feminine ? SEGMENTS_FEM : SEGMENTS_MASC
+    return segments[Number(n)]
   }
+
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    // Thousands are always feminine in Russian
+    const thousandsWord = SEGMENTS_FEM[thousands]
+    const scaleWord = pluralize(thousands, SCALE_FORMS[0])
+
+    let result = thousandsWord + ' ' + scaleWord
+
+    if (remainder > 0) {
+      const segments = feminine ? SEGMENTS_FEM : SEGMENTS_MASC
+      result += ' ' + segments[remainder]
+    }
+
+    return result
+  }
+
+  return buildLargeNumberWords(n, options)
+}
+
+function buildLargeNumberWords (n, options) {
+  const feminine = options.gender === 'feminine'
+  const numStr = n.toString()
+  const len = numStr.length
+
+  const segments = []
+  const segmentSize = 3
+
+  const remainderLen = len % segmentSize
+  let pos = 0
+  if (remainderLen > 0) {
+    segments.push(Number(numStr.slice(0, remainderLen)))
+    pos = remainderLen
+  }
+  while (pos < len) {
+    segments.push(Number(numStr.slice(pos, pos + segmentSize)))
+    pos += segmentSize
+  }
+
+  const parts = []
+  let scaleIndex = segments.length - 1
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+
+    if (segment !== 0) {
+      if (scaleIndex === 0) {
+        const segmentWords = feminine ? SEGMENTS_FEM : SEGMENTS_MASC
+        parts.push(segmentWords[segment])
+      } else {
+        const scaleForms = SCALE_FORMS[scaleIndex - 1]
+        const scaleWord = pluralize(segment, scaleForms)
+        // Thousands (scaleIndex=1) are feminine, others masculine
+        const isFeminine = scaleIndex === 1
+        const segmentWords = isFeminine ? SEGMENTS_FEM : SEGMENTS_MASC
+        parts.push(segmentWords[segment] + ' ' + scaleWord)
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+function decimalPartToWords (decimalPart, options) {
+  let result = ''
+  let i = 0
+
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder), options)
+  }
+
+  return result
 }
 
 /**
- * Converts a number to Russian cardinal (written) form.
+ * Converts a numeric value to Russian words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {SlavicOptions} [options={}] Configuration options.
- * @returns {string} The number expressed in Russian words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
+ * @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 Russian words
  */
-export default function convertToWords (value, options = {}) {
-  return new Russian(options).convertToWords(value)
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, options)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, options)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/sr-Cyrl.d.ts

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

package/lib/languages/sr-Cyrl.js

@@ -0,0 +1,215 @@
+/**
+ * Serbian Cyrillic language converter - Functional Implementation
+ *
+ * Self-contained converter using shared Slavic utilities.
+ *
+ * Key features:
+ * - Three-form pluralization (one/few/many)
+ * - Gender: thousands are feminine, millions+ are masculine
+ * - Irregular hundreds
+ * - Long scale naming with -ard forms
+ * - Cyrillic script
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Slavic Utilities (inlined for performance)
+// ============================================================================
+
+function pluralize (n, forms) {
+  const num = typeof n === 'bigint' ? Number(n) : n
+  const lastDigit = num % 10
+  const lastTwoDigits = num % 100
+
+  if (lastTwoDigits >= 11 && lastTwoDigits <= 19) {
+    return forms[2]
+  }
+
+  if (lastDigit === 1) return forms[0]
+  if (lastDigit >= 2 && lastDigit <= 4) return forms[1]
+  return forms[2]
+}
+
+function buildAllSegments (onesMasc, onesFem, teens, tens, hundreds) {
+  const masc = new Array(1000)
+  const fem = new Array(1000)
+
+  for (let i = 0; i < 1000; i++) {
+    masc[i] = buildSegment(i, onesMasc, teens, tens, hundreds)
+    fem[i] = buildSegment(i, onesFem, teens, tens, hundreds)
+  }
+
+  return { masc, fem }
+}
+
+function buildSegment (n, ones, teens, tens, hundreds) {
+  if (n === 0) return ''
+
+  const onesDigit = n % 10
+  const tensDigit = Math.floor(n / 10) % 10
+  const hundredsDigit = Math.floor(n / 100)
+
+  const parts = []
+
+  if (hundredsDigit > 0) {
+    parts.push(hundreds[hundredsDigit])
+  }
+
+  if (tensDigit > 1) {
+    parts.push(tens[tensDigit])
+  }
+
+  if (tensDigit === 1) {
+    parts.push(teens[onesDigit])
+  } else if (onesDigit > 0) {
+    parts.push(ones[onesDigit])
+  }
+
+  return parts.join(' ')
+}
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ONES_MASC = ['', 'један', 'два', 'три', 'четири', 'пет', 'шест', 'седам', 'осам', 'девет']
+const ONES_FEM = ['', 'једна', 'две', 'три', 'четири', 'пет', 'шест', 'седам', 'осам', 'девет']
+const TEENS = ['десет', 'једанаест', 'дванаест', 'тринаест', 'четрнаест', 'петнаест', 'шеснаест', 'седамнаест', 'осамнаест', 'деветнаест']
+const TENS = ['', '', 'двадесет', 'тридесет', 'четрдесет', 'педесет', 'шездесет', 'седамдесет', 'осамдесет', 'деведесет']
+const HUNDREDS = ['', 'сто', 'двеста', 'триста', 'четиристо', 'петсто', 'шесто', 'седамсто', 'осамсто', 'девестo']
+
+const ZERO = 'нула'
+const NEGATIVE = 'минус'
+const DECIMAL_SEP = 'запета'
+
+// Scale words: [singular, few, many]
+const SCALE_FORMS = [
+  ['хиљада', 'хиљаде', 'хиљада'],
+  ['милион', 'милиона', 'милиона'],
+  ['милијарда', 'милијарде', 'милијарда'],
+  ['билион', 'билиона', 'билиона'],
+  ['билијарда', 'билијарде', 'билијарда'],
+  ['трилион', 'трилиона', 'трилиона'],
+  ['трилијарда', 'трилијарде', 'трилијарда'],
+  ['квадрилион', 'квадрилиона', 'квадрилиона'],
+  ['квадрилијарда', 'квадрилијарде', 'квадрилијарда']
+]
+
+// ============================================================================
+// Precomputed Lookup Tables
+// ============================================================================
+
+const { masc: SEGMENTS_MASC, fem: SEGMENTS_FEM } = buildAllSegments(ONES_MASC, ONES_FEM, TEENS, TENS, HUNDREDS)
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n, options = {}) {
+  if (n === 0n) return ZERO
+
+  if (n < 1000n) {
+    const segments = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
+    return segments[Number(n)]
+  }
+
+  return buildLargeNumberWords(n, options)
+}
+
+function buildLargeNumberWords (n, options) {
+  const numStr = n.toString()
+  const len = numStr.length
+
+  const segments = []
+  const segmentSize = 3
+
+  const remainderLen = len % segmentSize
+  let pos = 0
+  if (remainderLen > 0) {
+    segments.push(Number(numStr.slice(0, remainderLen)))
+    pos = remainderLen
+  }
+  while (pos < len) {
+    segments.push(Number(numStr.slice(pos, pos + segmentSize)))
+    pos += segmentSize
+  }
+
+  const parts = []
+  let scaleIndex = segments.length - 1
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+
+    if (segment !== 0) {
+      if (scaleIndex === 0) {
+        const segmentWords = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
+        parts.push(segmentWords[segment])
+      } else {
+        const scaleForms = SCALE_FORMS[scaleIndex - 1]
+        const scaleWord = pluralize(segment, scaleForms)
+        // Thousands (scaleIndex=1) are feminine, others masculine
+        const isFeminine = scaleIndex === 1
+        const segmentWords = isFeminine ? SEGMENTS_FEM : SEGMENTS_MASC
+        parts.push(segmentWords[segment] + ' ' + scaleWord)
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+function decimalPartToWords (decimalPart, options) {
+  let result = ''
+  let i = 0
+
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder), options)
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Serbian (Cyrillic) words.
+ *
+ * @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 Serbian Cyrillic words
+ */
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, options)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, options)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/sr-Latn.d.ts

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