n2words 1.23.0 → 1.24.0

package/lib/languages/ro.js

@@ -0,0 +1,380 @@
+import AbstractLanguage from '../classes/abstract-language.js'
+
+/**
+ * @typedef {Object} RomanianOptions
+ * @property {boolean} [feminine=false] Use feminine forms for numbers.
+ */
+
+/**
+ * Romanian language converter.
+ *
+ * Converts numbers to Romanian words with full grammatical support:
+ * - Gender agreement (masculine/feminine forms)
+ * - Complex pluralization (singular/plural forms)
+ * - "De" preposition insertion for groups >= 20
+ * - Special feminine handling for thousands
+ * - Proper case and agreement patterns
+ *
+ * Key Features:
+ * - Gender-aware number forms (unu/una, doi/două, doisprezece/douăsprezece)
+ * - Group-based algorithm:
+ *   1. Split number into groups of 3 digits
+ *   2. Convert each group using gender rules and special forms
+ *   3. Insert "de" preposition for groups >= 20 (e.g., "douăzeci de mii")
+ *   4. Append magnitude word with proper singular/plural form (mie/mii, milion/milioane)
+ *   5. Join with spaces
+ * - Special feminine units for thousands group
+ * - Automatic "de" insertion rules (nouăsprezece mii vs douăzeci de mii)
+ * - Proper singular/plural forms (mie/mii, milion/milioane)
+ * - Support for very large numbers (up to decillions)
+ *
+ * Features:
+ * - Feminine units for thousands group
+ * - Support for very large numbers (up to decillions)
+ */
+export class Romanian extends AbstractLanguage {
+  negativeWord = 'minus'
+  decimalSeparatorWord = 'virgulă'
+  zeroWord = 'zero'
+
+  ones = {
+    1: 'unu',
+    2: 'doi',
+    3: 'trei',
+    4: 'patru',
+    5: 'cinci',
+    6: 'șase',
+    7: 'șapte',
+    8: 'opt',
+    9: 'nouă'
+  }
+
+  onesFeminine = {
+    1: 'una',
+    2: 'două',
+    3: 'trei',
+    4: 'patru',
+    5: 'cinci',
+    6: 'șase',
+    7: 'șapte',
+    8: 'opt',
+    9: 'nouă'
+  }
+
+  tens = {
+    0: 'zece',
+    1: 'unsprezece',
+    2: 'douăsprezece',
+    3: 'treisprezece',
+    4: 'paisprezece',
+    5: 'cincisprezece',
+    6: 'șaisprezece',
+    7: 'șaptesprezece',
+    8: 'optsprezece',
+    9: 'nouăsprezece'
+  }
+
+  tensMasculine = {
+    0: 'zece',
+    1: 'unsprezece',
+    2: 'doisprezece',
+    3: 'treisprezece',
+    4: 'paisprezece',
+    5: 'cincisprezece',
+    6: 'șaisprezece',
+    7: 'șaptesprezece',
+    8: 'optsprezece',
+    9: 'nouăsprezece'
+  }
+
+  twenties = {
+    2: 'douăzeci',
+    3: 'treizeci',
+    4: 'patruzeci',
+    5: 'cincizeci',
+    6: 'șaizeci',
+    7: 'șaptezeci',
+    8: 'optzeci',
+    9: 'nouăzeci'
+  }
+
+  hundreds = {
+    1: 'o sută',
+    2: 'două sute',
+    3: 'trei sute',
+    4: 'patru sute',
+    5: 'cinci sute',
+    6: 'șase sute',
+    7: 'șapte sute',
+    8: 'opt sute',
+    9: 'nouă sute'
+  }
+
+  /**
+   * Romanian big units.
+   * For each power group we keep: singular, plural, feminineUnits?, needsDe?
+   * - 10^3: mie/mii (feminine units in chunk; "de" for chunk >= 20)
+   * - 10^6: milion/milioane ("de" for chunk >= 20)
+   * - 10^9: miliard/miliarde ("de" for chunk >= 20)
+   */
+  thousands = {
+    1: { singular: 'mie', plural: 'mii', feminine: true, needsDe: true }, // 10^3
+    2: { singular: 'milion', plural: 'milioane', feminine: false, needsDe: true }, // 10^6
+    3: { singular: 'miliard', plural: 'miliarde', feminine: false, needsDe: true }, // 10^9
+    4: { singular: 'trilion', plural: 'trilioane', feminine: false, needsDe: true }, // 10^12
+    5: { singular: 'cvadrilion', plural: 'cvadrilioane', feminine: false, needsDe: true }, // 10^15
+    6: { singular: 'cvintilion', plural: 'cvintilioane', feminine: false, needsDe: true }, // 10^18
+    7: { singular: 'sextilion', plural: 'sextilioane', feminine: false, needsDe: true }, // 10^21
+    8: { singular: 'septilion', plural: 'septilioane', feminine: false, needsDe: true }, // 10^24
+    9: { singular: 'octilion', plural: 'octilioane', feminine: false, needsDe: true }, // 10^27
+    10: { singular: 'decilion', plural: 'decilioane', feminine: false, needsDe: true } // 10^33
+  }
+
+  /**
+   * Initializes the Romanian converter with language-specific options.
+   *
+   * @param {RomanianOptions} [options={}] Configuration options.
+   */
+  constructor ({ feminine = false } = {}) {
+    super()
+
+    this.feminine = feminine
+  }
+
+  /**
+   * Split numeric string into BigInt groups of size x from left to right.
+   * @param {string} n - The numeric string to split
+   * @param {number} x - The size of each group
+   * @returns {bigint[]} Array of BigInt groups
+   */
+  splitByX (n, x) {
+    const results = []
+    const l = n.length
+    let result
+
+    if (l > x) {
+      const start = l % x
+      if (start > 0) {
+        result = n.slice(0, start)
+        results.push(BigInt(result))
+      }
+      for (let index = start; index < l; index += x) {
+        result = n.slice(index, index + x)
+        results.push(BigInt(result))
+      }
+    } else {
+      results.push(BigInt(n))
+    }
+    return results
+  }
+
+  getDigits (value) {
+    const stringValue = value.toString().padStart(3, '0').slice(-3)
+    const a = [...stringValue].toReversed()
+    return a.map(BigInt)
+  }
+
+  /**
+   * Romanian pluralization & "de" rule for big units.
+   * - 1 → singular with article ("o mie", "un milion", "un miliard", …)
+   * - otherwise → spell chunk + (optional "de") + plural
+   * "de" is inserted when chunk >= 20 (e.g., "douăzeci de mii/milioane/miliarde").
+   * @param {bigint} chunk - The chunk value
+   * @param {object} form - The form object with singular, plural, feminine, needsDe properties
+   * @returns {string} The pluralized form
+   */
+  romanianPluralize (chunk, form) {
+    const n = Number(chunk)
+
+    if (n === 1) {
+      // article differs for feminine "mie" (o mie) vs the rest (un milion/miliard…)
+      const article = form.feminine ? 'o' : 'un'
+      return `${article} ${form.singular}`
+    }
+
+    // For 21 with big units, use feminine "una" with plural nouns
+    if (n === 21 && form.needsDe) {
+      return `douăzeci și una de ${form.plural}`
+    }
+
+    // spell the chunk itself (use feminine units for big numbers)
+    const words = this.spellUnder1000(n, true)
+
+    // "de" after >= 20 (covers 20, 21, 100, 101, 999, etc.)
+    const needsDe = form.needsDe && n >= 20
+    const de = needsDe ? ' de ' : ' '
+
+    return `${words}${de}${form.plural}`
+  }
+
+  spellUnder100 (n, feminineUnits = false) {
+    if (n < 10) {
+      return (feminineUnits ? this.onesFeminine : this.ones)[n]
+    }
+    if (n < 20) {
+      return this.tens[n - 10]
+    }
+    const t = Math.floor(n / 10)
+    const u = n % 10
+    return u
+      ? `${this.twenties[t]} și ${(feminineUnits ? this.onesFeminine : this.ones)[u]}`
+      : this.twenties[t]
+  }
+
+  spellUnder1000 (n, feminineUnits = false) {
+    if (n < 100) return this.spellUnder100(n, feminineUnits)
+    const h = Math.floor(n / 100)
+    const r = n % 100
+    const hundredWords = this.hundreds[h]
+    if (!r) return hundredWords
+    // Standard readable form: "o sută unu" (for units) or "o sută cincizeci" (for tens)
+    const separator = ' '
+    return `${hundredWords}${separator}${this.spellUnder100(r, feminineUnits)}`
+  }
+
+  /**
+   * Override decimalDigitsToWords to use masculine forms for decimal places
+   * @param {string} decimal Decimal string to convert
+   * @returns {string} Value in written format
+   */
+  decimalDigitsToWords (decimal) {
+    const words = []
+
+    const chars = [...decimal]
+
+    // Loop through characters adding leading zeros to words array
+    let index = 0
+    while (index < chars.length && chars[index] === '0') {
+      words.push(this.zeroWord)
+      index++
+    }
+
+    // Prevent further processing if entire string was zeros
+    if (index === chars.length) {
+      return words
+    }
+
+    // Convert and add remaining using masculine forms for decimal places
+    const decimalNumber = BigInt(decimal)
+    const masculineWords = this.toCardinalWithMasculine(decimalNumber)
+    return [...words, masculineWords]
+  }
+
+  /**
+   * Convert number to cardinal form using masculine units
+   * @param {bigint} number Number to convert
+   * @returns {string} Value in written format
+   */
+  toCardinalWithMasculine (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+
+    const words = []
+    const chunks = this.splitByX(number.toString(), 3)
+    let index = chunks.length
+
+    for (const x of chunks) {
+      let onesMap = []
+      index = index - 1
+
+      if (x === 0n) continue
+
+      const [n1, n2, n3] = this.getDigits(x) // units, tens, hundreds (as BigInt)
+
+      // hundreds
+      if (n3 > 0n) {
+        words.push(this.hundreds[Number(n3)])
+      }
+
+      // tens & teens
+      if (n2 > 1n) {
+        words.push(this.twenties[Number(n2)])
+      }
+
+      if (n2 === 1n) {
+        words.push(this.tensMasculine[Number(n1)])
+      } else if (n1 > 0n) {
+        // Always use masculine units for decimal places
+        onesMap = this.ones
+
+        // if there is a twenty/treizeci/etc AND ones > 0 → add "și"
+        if (n2 > 1n) words.push('și')
+        words.push(onesMap[Number(n1)])
+      }
+
+      // big unit name (mie/mii, milion/milioane, …)
+      if (index > 0) {
+        const form = this.thousands[index]
+        if (form) {
+          words.push(this.romanianPluralize(x, form))
+        } else {
+          // For very large numbers beyond our defined units, just spell out the number
+          words.push(this.spellUnder1000(Number(x), false))
+        }
+      }
+    }
+
+    return words.join(' ').replaceAll(/\s+/g, ' ').trim()
+  }
+
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+    const words = []
+    const chunks = this.splitByX(number.toString(), 3)
+    let index = chunks.length
+    for (const x of chunks) {
+      let onesMap = []
+      index = index - 1
+      if (x === 0n) continue
+      const [n1, n2, n3] = this.getDigits(x) // units, tens, hundreds (as BigInt)
+      // hundreds (only for the last group, not for thousands)
+      if (n3 > 0n && index === 0) {
+        words.push(this.hundreds[Number(n3)])
+      }
+      // tens & teens (only for the last group, not for thousands)
+      if (index === 0) {
+        if (n2 > 1n) {
+          words.push(this.twenties[Number(n2)])
+        }
+        if (n2 === 1n) {
+          words.push(this.tens[Number(n1)])
+        } else if (n1 > 0n) {
+          // pick masculine/feminine units (only for the last group, not for thousands)
+          const feminineUnits = this.feminine && index === 0
+          onesMap = feminineUnits ? this.onesFeminine : this.ones
+          // if there is a twenty/treizeci/etc AND ones > 0 → add "și"
+          if (n2 > 1n) words.push('și')
+          words.push(onesMap[Number(n1)])
+        }
+      }
+      // big unit name (mie/mii, milion/milioane, …)
+      if (index > 0) {
+        const form = this.thousands[index]
+        if (form) {
+          words.push(this.romanianPluralize(x, form))
+        } else {
+          // For very large numbers beyond our defined units, just spell out the number
+          words.push(this.spellUnder1000(Number(x), true))
+        }
+      }
+    }
+    return words.join(' ').replaceAll(/\s+/g, ' ').trim()
+  }
+}
+
+/**
+ * Converts a number to Romanian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @param {boolean} [options.feminine=false] Use feminine forms for numbers.
+ * @returns {string} The number expressed in Romanian words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords (value, options = {}) {
+  return new Romanian(options).convertToWords(value)
+}

package/lib/languages/ru.js

@@ -0,0 +1,116 @@
+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
+ *
+ * Features:
+ * - Gender-aware forms (один/одна, два/две)
+ * - Three-form pluralization (тысяча/тысячи/тысяч)
+ * - Support for very large numbers (up to nonillions)
+ * - Proper spacing and conjunction rules
+ *
+ * This class extends SlavicLanguage, which provides the conversion algorithm
+ * shared by Czech, Polish, Ukrainian, Serbian, Croatian, Hebrew, Lithuanian, Latvian.
+ */
+export class Russian extends SlavicLanguage {
+  negativeWord = 'минус'
+  decimalSeparatorWord = 'запятая'
+  zeroWord = 'ноль'
+
+  ones = {
+    1: 'один',
+    2: 'два',
+    3: 'три',
+    4: 'четыре',
+    5: 'пять',
+    6: 'шесть',
+    7: 'семь',
+    8: 'восемь',
+    9: 'девять'
+  }
+
+  onesFeminine = {
+    1: 'одна',
+    2: 'две',
+    3: 'три',
+    4: 'четыре',
+    5: 'пять',
+    6: 'шесть',
+    7: 'семь',
+    8: 'восемь',
+    9: 'девять'
+  }
+
+  tens = {
+    0: 'десять',
+    1: 'одиннадцать',
+    2: 'двенадцать',
+    3: 'тринадцать',
+    4: 'четырнадцать',
+    5: 'пятнадцать',
+    6: 'шестнадцать',
+    7: 'семнадцать',
+    8: 'восемнадцать',
+    9: 'девятнадцать'
+  }
+
+  twenties = {
+    2: 'двадцать',
+    3: 'тридцать',
+    4: 'сорок',
+    5: 'пятьдесят',
+    6: 'шестьдесят',
+    7: 'семьдесят',
+    8: 'восемьдесят',
+    9: 'девяносто'
+  }
+
+  hundreds = {
+    1: 'сто',
+    2: 'двести',
+    3: 'триста',
+    4: 'четыреста',
+    5: 'пятьсот',
+    6: 'шестьсот',
+    7: 'семьсот',
+    8: 'восемьсот',
+    9: 'девятьсот'
+  }
+
+  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
+  }
+}
+
+/**
+ * Converts a number to Russian cardinal (written) form.
+ *
+ * @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.
+ */
+export default function convertToWords (value, options = {}) {
+  return new Russian(options).convertToWords(value)
+}

package/lib/languages/sr-Latn.js

@@ -0,0 +1,157 @@
+import SlavicLanguage from '../classes/slavic-language.js'
+
+/**
+ * @typedef {Object} SlavicOptions
+ * @property {boolean} [feminine=false] Use feminine forms for numbers.
+ */
+
+/**
+ * Serbian language converter.
+ *
+ * Implements Serbian number words using the Slavic language pattern:
+ * - Serbian number words (jedan/jedna, dva/dve, tri, četiri...)
+ * - Gender-aware forms (masculine/feminine)
+ * - Slavic three-form pluralization (hiljada/hiljade/hiljada)
+ * - Latin script representation
+ *
+ * Key Features:
+ * - Three-form pluralization system shared across Slavic languages
+ *   * Form 1 (singular): 1 (e.g., "hiljada")
+ *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "hiljade")
+ *   * Form 3 (many): all other numbers (e.g., "hiljada")
+ * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
+ * - Large number handling via SCALE[] array with indexed [singular, few, many] forms
+ * - Gender-specific number forms for 1 and 2 (masculine/feminine dual forms)
+ *
+ * Features:
+ * - Dual gender forms for 1 and 2 (jedan/jedna, dva/dve)
+ * - Similar structure to Croatian with different orthography
+ * - Latin script (Serbian can use both Latin and Cyrillic)
+ *
+ * Inherits from SlavicLanguage for complex pluralization algorithms.
+ */
+export class Serbian extends SlavicLanguage {
+  negativeWord = 'minus'
+  decimalSeparatorWord = 'zapeta'
+  zeroWord = 'nula'
+  ones = {
+    1: ['jedan', 'jedna'],
+    2: ['dva', 'dve'],
+    3: ['tri', 'tri'],
+    4: ['četiri', 'četiri'],
+    5: ['pet', 'pet'],
+    6: ['šest', 'šest'],
+    7: ['sedam', 'sedam'],
+    8: ['osam', 'osam'],
+    9: ['devet', 'devet']
+  }
+
+  tens = {
+    0: 'deset',
+    1: 'jedanaest',
+    2: 'dvanaest',
+    3: 'trinaest',
+    4: 'četrnaest',
+    5: 'petnaest',
+    6: 'šesnaest',
+    7: 'sedamnaest',
+    8: 'osamnaest',
+    9: 'devetnaest'
+  }
+
+  twenties = {
+    2: 'dvadeset',
+    3: 'trideset',
+    4: 'četrdeset',
+    5: 'pedeset',
+    6: 'šezdeset',
+    7: 'sedamdeset',
+    8: 'osamdeset',
+    9: 'devedeset'
+  }
+
+  hundreds = {
+    1: 'sto',
+    2: 'dvesta',
+    3: 'trista',
+    4: 'četiristo',
+    5: 'petsto',
+    6: 'šesto',
+    7: 'sedamsto',
+    8: 'osamsto',
+    9: 'devetsto'
+  }
+
+  SCALE = [
+    ['', '', '', false],
+    ['hiljada', 'hiljade', 'hiljada', true], // 10 ^ 3
+    ['milion', 'miliona', 'miliona', false], // 10 ^ 6
+    ['milijarda', 'milijarde', 'milijarda', false], // 10 ^ 9
+    ['bilion', 'biliona', 'biliona', false], // 10 ^ 12
+    ['bilijarda', 'bilijarde', 'bilijarda', false], // 10 ^ 15
+    ['trilion', 'triliona', 'triliona', false], // 10 ^ 18
+    ['trilijarda', 'trilijarde', 'trilijarda', false], // 10 ^ 21
+    ['kvadrilion', 'kvadriliona', 'kvadriliona', false], // 10 ^ 24
+    ['kvadrilijarda', 'kvadrilijarde', 'kvadrilijarda', false], // 10 ^ 27
+    ['kvintilion', 'kvintiliona', 'kvintiliona', false] // 10 ^ 30
+  ]
+
+  pluralize (n, forms) {
+    const lastDigit = n % 10n
+    const lastTwoDigits = n % 100n
+
+    if ((lastTwoDigits < 10n || lastTwoDigits > 20n) && lastDigit === 1n) {
+      return forms[0]
+    }
+
+    if ((lastTwoDigits < 10n || lastTwoDigits > 20n) && lastDigit > 1n && lastDigit < 5n) {
+      return forms[1]
+    }
+
+    return forms[2]
+  }
+
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+    const words = []
+    const chunks = this.splitByX(number.toString(), 3)
+    let index = chunks.length
+    for (const x of chunks) {
+      index = index - 1
+      const [n1, n2, n3] = this.getDigits(x)
+      if (n3 > 0) {
+        words.push(this.hundreds[n3])
+      }
+      if (n2 > 1) {
+        words.push(this.twenties[n2])
+      }
+      if (n2 === 1n) {
+        words.push(this.tens[n1])
+      } else if (n1 > 0) {
+        const isFeminine = (this.feminine || this.SCALE[index][3])
+        const genderIndex = isFeminine ? 1 : 0
+        words.push(this.ones[n1][genderIndex])
+      }
+      if ((index > 0) && (x !== 0n)) {
+        words.push(this.pluralize(x, this.SCALE[index]))
+      }
+    }
+    return words.join(' ')
+  }
+}
+
+/**
+ * Converts a number to Serbian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @param {boolean} [options.feminine=false] Use feminine forms for numbers.
+ * @returns {string} The number expressed in Serbian words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords (value, options = {}) {
+  return new Serbian(options).convertToWords(value)
+}