n2words 1.23.0 → 1.24.0

package/lib/classes/slavic-language.js

@@ -0,0 +1,251 @@
+import AbstractLanguage from './abstract-language.js'
+
+/**
+ * @typedef {string[]} SlavicPluralForms
+ * Array of three plural forms for Slavic languages:
+ * - [0]: Singular form (for numbers ending in 1, except 11)
+ * - [1]: Few form (for numbers ending in 2-4, except 12-14)
+ * - [2]: Many form (for all other numbers: 0, 5-20, and numbers ending in 0, 5-9, 11-19)
+ */
+
+/**
+ * @typedef {Object.<string, SlavicPluralForms>} SlavicThousandsMap
+ * Mapping from power indices to their plural forms.
+ * Example: { '0': ['тысяча', 'тысячи', 'тысяч'], '1': ['миллион', 'миллиона', 'миллионов'] }
+ */
+
+/**
+ * Base class for Slavic and related languages with complex pluralization.
+ *
+ * This class provides a reusable implementation for languages that share:
+ * - Three-form pluralization (singular/few/many)
+ * - Gender-aware number forms (masculine/feminine for 1, 2)
+ * - Hundreds, tens, ones decomposition
+ * - Chunk-based large number handling (thousands, millions, etc.)
+ * - Inherits decimal handling from AbstractLanguage (supports both grouped and
+ *   per-digit modes via the `convertDecimalsPerDigit` class property).
+ *
+ * Used by: Russian, Czech, Polish, Ukrainian, Serbian, Croatian,
+ * as well as Baltic (Lithuanian, Latvian) and Hebrew languages.
+ *
+ * Subclasses MUST define these properties with language-specific vocabulary:
+ * - `ones` - Object mapping 1-9 to masculine forms
+ * - `onesFeminine` - Object mapping 1-9 to feminine forms
+ * - `tens` - Object mapping 0-9 to teen numbers (10-19)
+ * - `twenties` - Object mapping 2-9 to tens (20-90)
+ * - `hundreds` - Object mapping 1-9 to hundreds (100-900)
+ * - `thousands` - Object mapping power indices to [singular, few, many] forms
+ * - `feminine` - Boolean indicating if feminine forms should be used (optional)
+ *
+ * @abstract
+ * @extends AbstractLanguage
+ */
+class SlavicLanguage extends AbstractLanguage {
+  /**
+   * Masculine forms for digits 1-9.
+   *
+   * @type {object}
+   */
+  ones = {}
+
+  /**
+   * Feminine forms for digits 1-9.
+   *
+   * @type {object}
+   */
+  onesFeminine = {}
+
+  /**
+   * Words for tens (10, 20, 30, etc.).
+   *
+   * @type {object}
+   */
+  tens = {}
+
+  /**
+   * Special forms for 21-29 in some languages.
+   *
+   * @type {object}
+   */
+  twenties = {}
+
+  /**
+   * Words for hundreds (100, 200, 300, etc.).
+   *
+   * @type {object}
+   */
+  hundreds = {}
+
+  /**
+   * Scale words for thousands, millions, etc.
+   *
+   * @type {object}
+   */
+  thousands = {}
+
+  /**
+   * Use feminine forms for numbers (affects 1-9).
+   *
+   * @type {boolean}
+   */
+  feminine
+
+  /**
+   * Initializes the Slavic language converter with language-specific options.
+   *
+   * @param {Object} [options={}] Configuration options.
+   * @param {boolean} [options.feminine=false] Use feminine forms for numbers (affects gender agreement).
+   */
+  constructor ({ feminine = false } = {}) {
+    super()
+
+    this.feminine = feminine
+  }
+
+  /**
+   * Converts a whole number to its word representation.
+   *
+   * This method implements the Slavic number construction algorithm:
+   * 1. Split number into 3-digit chunks (right to left)
+   * 2. For each chunk: convert hundreds, tens, ones
+   * 3. Apply gender rules for ones (feminine for thousands, or when feminine=true)
+   * 4. Add pluralized power word (thousand/million/billion/etc.)
+   * 5. Join all parts with spaces
+   *
+   * @param {bigint} number The whole number to convert (non-negative).
+   * @returns {string} The number in words.
+   */
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+
+    const words = []
+    const chunks = this.splitByX(number.toString(), 3)
+    let chunkIndex = chunks.length
+
+    for (const chunkValue of chunks) {
+      chunkIndex = chunkIndex - 1
+
+      if (chunkValue === 0n) {
+        continue
+      }
+
+      const [onesDigit, tensDigit, hundredsDigit] = this.getDigits(chunkValue)
+
+      if (hundredsDigit > 0n) {
+        words.push(this.hundreds[hundredsDigit])
+      }
+
+      if (tensDigit > 1n) {
+        words.push(this.twenties[tensDigit])
+      }
+
+      // Handle teens (10-19) or ones (1-9)
+      if (tensDigit === 1n) {
+        // Teens: use tens array directly
+        words.push(this.tens[onesDigit])
+      } else if (onesDigit > 0n) {
+        // Ones: use feminine form for thousands (chunkIndex 1) or when feminine=true (chunkIndex 0)
+        const onesArray =
+          chunkIndex === 1 || (this.feminine && chunkIndex === 0)
+            ? this.onesFeminine
+            : this.ones
+        words.push(onesArray[onesDigit])
+      }
+
+      // Add power word (thousand, million, etc.) with proper pluralization
+      if (chunkIndex > 0) {
+        words.push(this.pluralize(chunkValue, this.thousands[chunkIndex]))
+      }
+    }
+
+    return words.join(' ')
+  }
+
+  /**
+   * Splits a number string into chunks of X digits.
+   *
+   * Example: splitByX('1234567', 3) => [1n, 234n, 567n]
+   *
+   * @param {string} numberString The number as a string.
+   * @param {number} chunkSize Chunk size (typically 3 for thousands grouping).
+   * @returns {bigint[]} Array of BigInt chunks.
+   */
+  splitByX (numberString, chunkSize) {
+    const chunks = []
+    const stringLength = numberString.length
+
+    if (stringLength > chunkSize) {
+      const remainderLength = stringLength % chunkSize
+
+      if (remainderLength > 0) {
+        chunks.push(BigInt(numberString.slice(0, remainderLength)))
+      }
+
+      for (let i = remainderLength; i < stringLength; i += chunkSize) {
+        chunks.push(BigInt(numberString.slice(i, i + chunkSize)))
+      }
+    } else {
+      chunks.push(BigInt(numberString))
+    }
+
+    return chunks
+  }
+
+  /**
+   * Extracts individual digits from a number (units, tens, hundreds).
+   *
+   * Returns digits in reverse order: [ones, tens, hundreds]
+   * Example: 456 => [6n, 5n, 4n]
+   *
+   * @param {bigint} value The number to extract digits from (0-999).
+   * @returns {bigint[]} Array of [ones, tens, hundreds] as BigInts.
+   */
+  getDigits (value) {
+    // Direct BigInt arithmetic is faster than string manipulation
+    const onesPlace = value % 10n
+    const tensPlace = (value / 10n) % 10n
+    const hundredsPlace = value / 100n
+    return [onesPlace, tensPlace, hundredsPlace]
+  }
+
+  /**
+   * Selects the correct plural form based on Slavic pluralization rules.
+   *
+   * Slavic languages use three forms:
+   * - Form 0 (singular): numbers ending in 1 (but not 11)
+   * - Form 1 (few): numbers ending in 2-4 (but not 12-14)
+   * - Form 2 (many): all other numbers (0, 5-20, 25-30, etc.)
+   *
+   * Examples (Russian):
+   * - 1, 21, 31... => тысяча (form 0)
+   * - 2-4, 22-24, 32-34... => тысячи (form 1)
+   * - 0, 5-20, 25-30... => тысяч (form 2)
+   *
+   * @param {bigint} n The number to check.
+   * @param {string[]} forms Array of [singular, few, many] forms.
+   * @returns {string} The appropriate form for the number.
+   */
+  pluralize (number, pluralForms) {
+    const remainder100 = number % 100n
+    const remainder10 = number % 10n
+
+    // Check if in 11-19 range (special case)
+    if (remainder100 >= 10n && remainder100 <= 20n) {
+      return pluralForms[2] // Always use "many" form for 11-20
+    }
+
+    if (remainder10 === 1n) {
+      return pluralForms[0] // Singular
+    }
+
+    if (remainder10 >= 2n && remainder10 <= 4n) {
+      return pluralForms[1] // Few (2-4)
+    }
+
+    return pluralForms[2] // Many
+  }
+}
+
+export default SlavicLanguage

package/lib/classes/south-asian-language.js

@@ -0,0 +1,161 @@
+import AbstractLanguage from './abstract-language.js'
+
+/**
+ * @typedef {Array<string>} SouthAsianScaleWords
+ * Array of scale words for the Indian numbering system, in ascending order.
+ * - Index 0: Usually empty/unused (ones place)
+ * - Index 1: Thousands (hazaar/হাজার/हजार)
+ * - Index 2: Lakhs (lakh/লাখ/लाख)
+ * - Index 3: Crores (crore/কোটি/करोड़)
+ * - Index 4: Arabs (arab/আরব/अरब)
+ * Each index i represents the scale word for groups at position i in the Indian system.
+ */
+
+/**
+ * @typedef {Array<string>} SouthAsianBelowHundred
+ * Array of words for numbers 0-99, indexed directly.
+ * belowHundred[0] = word for 0, belowHundred[42] = word for 42, etc.
+ */
+
+/**
+ * Base class for South Asian languages with shared grouping patterns.
+ *
+ * This class provides a reusable implementation for South Asian languages that share:
+ * - Indian-style number grouping: last 3 digits, then 2-2 (1,23,45,67,89)
+ * - Lakh (100,000), Crore (10,000,000), Arab (1,000,000,000) scale words
+ * - Standard negative and decimal handling (inherits AbstractLanguage decimal logic,
+ *   including `convertDecimalsPerDigit` support when set by subclasses)
+ *
+ * Used by: Hindi (hi), Bengali (bn), Urdu (ur), Punjabi (pa), Marathi (mr), Gujarati (gu), Kannada (kn)
+ *
+ * Subclasses MUST define language-specific vocabulary via class properties:
+ * - `belowHundred` array with digit and teen words (0-99)
+ * - `hundredWord` string used inside `convertBelowThousand`
+ * - `scaleWords` array with grouping words (hazaar, lakh, crore, etc.) indexed by grouping level
+ * - `negativeWord`, `decimalSeparatorWord`, `zeroWord`, `wordSeparator`
+ *
+ * @abstract
+ * @extends AbstractLanguage
+ */
+class SouthAsianLanguage extends AbstractLanguage {
+  /**
+   * Array of words for numbers 0-99 (digits and teens).
+   * Index directly: belowHundred[0] through belowHundred[99].
+   * @type {Array<string>}
+   */
+  belowHundred
+
+  /**
+   * Word for "hundred" in the language (e.g., 'सौ' in Hindi, 'শত' in Bengali).
+   * Used to construct hundreds (e.g., "1 hundred", "2 hundred").
+   * @type {string}
+   */
+  hundredWord
+
+  /**
+   * Array of scale words for Indian-style grouping (hazaar, lakh, crore, arab, etc.).
+   * Index 0 is typically unused (ones place, no scale word).
+   * Index 1 is for thousands, Index 2 for lakhs, Index 3 for crores, etc.
+   * @type {Array<string>}
+   */
+  scaleWords
+
+  /**
+   * Split a number into Indian numbering system groups.
+   *
+   * The Indian system groups differently than Western (3-3-3) systems:
+   * - First group (rightmost): Up to 3 digits (ones, tens, hundreds)
+   * - Subsequent groups: Exactly 2 digits each (thousands, lakhs, crores, etc.)
+   *
+   * This creates the familiar Indian comma pattern: 1,23,45,67,890
+   *
+   * @protected
+   * @param {bigint} number The number to split into groups
+   * @returns {Array<number>} Array of groups from most significant to least significant
+   *
+   * @example
+   * // splitToGroups(1234567n) → [12, 34, 567]
+   * // Reads as: 12 lakhs, 34 thousands, 567 units
+   * // splitToGroups(98765432n) → [9, 87, 65, 432]
+   * // Reads as: 9 crores, 87 lakhs, 65 thousands, 432 units
+   */
+  splitToGroups (number) {
+    const numStr = number.toString()
+
+    if (numStr.length <= 3) {
+      return [Number(numStr)]
+    }
+
+    const groups = []
+    const last3 = numStr.slice(-3)
+    groups.unshift(Number(last3))
+
+    let remaining = numStr.slice(0, -3)
+    while (remaining.length > 0) {
+      const group = remaining.slice(-2)
+      groups.unshift(Number(group))
+      remaining = remaining.slice(0, -2)
+    }
+
+    return groups
+  }
+
+  /**
+   * Convert a number below 1000 to words (0-999).
+   *
+   * @protected
+   * @param {number} number Value between 0 and 999
+   * @returns {string} Language-specific word representation
+   */
+  convertBelowThousand (number) {
+    if (number === 0) return ''
+    if (number < 100) return this.belowHundred[number]
+
+    const hundreds = Math.trunc(number / 100)
+    const remainder = number % 100
+    const parts = []
+
+    if (hundreds === 1) {
+      parts.push(this.belowHundred[1] + ' ' + this.hundredWord)
+    } else {
+      parts.push(this.belowHundred[hundreds] + ' ' + this.hundredWord)
+    }
+
+    if (remainder > 0) {
+      parts.push(this.belowHundred[remainder])
+    }
+
+    return parts.join(' ')
+  }
+
+  /**
+   * Convert whole number to cardinal words using South Asian grouping.
+   *
+   * @param {bigint} number Number to convert
+   * @returns {string} Cardinal representation
+   */
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+
+    const groups = this.splitToGroups(number)
+    const groupCount = groups.length
+    const words = []
+
+    for (let i = 0; i < groupCount; i++) {
+      const groupValue = groups[i]
+      if (groupValue === 0) continue
+
+      const scaleIndex = groupCount - i - 1
+      words.push(this.convertBelowThousand(groupValue))
+      if (scaleIndex > 0 && this.scaleWords[scaleIndex]) {
+        words.push(this.scaleWords[scaleIndex])
+      }
+    }
+
+    return words.join(' ').trim()
+  }
+}
+
+export default SouthAsianLanguage

package/lib/classes/turkic-language.js

@@ -0,0 +1,63 @@
+import GreedyScaleLanguage from './greedy-scale-language.js'
+
+/**
+ * @typedef {Object} TurkicWordPair
+ * @property {string} word - The Turkic word or phrase
+ * @property {bigint} value - The numeric value represented by the word
+ */
+
+/**
+ * Base class for Turkic languages with shared grammar patterns.
+ *
+ * This class provides a reusable implementation for Turkic languages that share:
+ * - Space-separated number combinations
+ * - Implicit 'bir' (one) before hundreds and thousands
+ * - Simple multiplication/addition logic
+ * - Consistent magnitude handling
+ * - Inherits decimal handling from AbstractLanguage via GreedyScaleLanguage
+ *   (supports both grouped and per-digit modes via the `convertDecimalsPerDigit` class property).
+ *
+ * Used by: Turkish (TR), Azerbaijani (AZ)
+ *
+ * Subclasses MUST define (from GreedyScaleLanguage requirements):
+ * - `scaleWordPairs` array of [value, word] pairs as a class property (ordered descending by value).
+ * Optionally, language-specific class properties (e.g., `negativeWord`, `zeroWord`, `decimalSeparatorWord`, `wordSeparator`).
+ *
+ * TurkicLanguage provides a default `mergeScales()` implementation; subclasses may override
+ * if specialized merge logic is needed (unlikely for Turkic languages).
+ *
+ * @abstract
+ * @extends GreedyScaleLanguage
+ */
+class TurkicLanguage extends GreedyScaleLanguage {
+  /**
+   * Merges two adjacent word-number pairs according to Turkic grammar rules.
+   *
+   * Shared Turkic patterns:
+   * - Implicit 'bir' (one) before hundreds and thousands
+   * - Space separator (wordSeparator property) for all combinations
+   * - Multiplies when right > left (crossing magnitude boundary)
+   * - Adds otherwise (combining same-magnitude components)
+   *
+   * @param {Object} leftPair The left operand as `{ word: bigint }`.
+   * @param {Object} rightPair The right operand as `{ word: bigint }`.
+   * @returns {Object} Merged pair with combined word and resulting number (bigint).
+   */
+  mergeScales (leftPair, rightPair) {
+    const [[leftWord, leftNumber]] = Object.entries(leftPair)
+    const [[rightWord, rightNumber]] = Object.entries(rightPair)
+
+    // Implicit 'bir' (one) before certain magnitudes:
+    // Omit '1' before hundreds (100n) and thousands (1000n) to form natural combinations
+    if (leftNumber === 1n && (rightNumber <= 100n || rightNumber === 1000n)) {
+      return rightPair // Return just the magnitude word (e.g., "yüz", not "bir yüz")
+    }
+
+    // Combine numbers with space separator (wordSeparator from GreedyScaleLanguage):
+    // Multiply when crossing magnitude boundary, add otherwise
+    const mergedNumber = rightNumber > leftNumber ? leftNumber * rightNumber : leftNumber + rightNumber
+    return { [`${leftWord}${this.wordSeparator}${rightWord}`]: mergedNumber }
+  }
+}
+
+export default TurkicLanguage