n2words 1.23.0 → 1.24.0

package/lib/languages/fa.js

@@ -0,0 +1,127 @@
+import AbstractLanguage from '../classes/abstract-language.js'
+
+/**
+ * Persian (Farsi) language converter.
+ *
+ * Converts numbers to Persian words using Persian-Arabic numerals:
+ * - Right-to-left script orientation
+ * - Base-10 decimal system with Persian number words
+ * - Conjunction "و" (va/and) for compound numbers
+ * - Traditional Persian number naming conventions
+ *
+ * Key Features:
+ * - Named number lookup table (namedNumbers) for direct mapping 0-999
+ * - Group-based algorithm for numbers >= 1000:
+ *   1. Split into groups of 3 digits
+ *   2. Convert each group to words using named table or recursion
+ *   3. Append magnitude word (هزار/میلیون/میلیارد)
+ *   4. Join with "و" (and) conjunction
+ * - Special compound forms (دویست for 200, سیصد for 300)
+ * - Proper Persian grammatical structure
+ * - Support for large numbers (thousands, millions, billions, trillions)
+ *
+ * Features:
+ * - Native Persian digits and words
+ * - Special compound forms (e.g., دویست for 200, سیصد for 300)
+ * - Support for large numbers (thousands, millions)
+ * - Proper Persian grammatical structure
+ */
+export class Farsi extends AbstractLanguage {
+  negativeWord = 'منفى'
+  decimalSeparatorWord = 'ممیّز'
+  zeroWord = 'صفر'
+  namedNumbers = {
+    0: 'صفر',
+    1: 'یک',
+    2: 'دو',
+    3: 'سه',
+    4: 'چهار',
+    5: 'پنج',
+    6: 'شش',
+    7: 'هفت',
+    8: 'هشت',
+    9: 'نه',
+    10: 'ده',
+    11: 'یازده',
+    12: 'دوازده',
+    13: 'سیزده',
+    14: 'چهارده',
+    15: 'پانزده',
+    16: 'شانزده',
+    17: 'هفده',
+    18: 'هجده',
+    19: 'نوزده',
+    20: 'بیست',
+    30: 'سی',
+    40: 'چهل',
+    50: 'پنجاه',
+    60: 'شصت',
+    70: 'هفتاد',
+    80: 'هشتاد',
+    90: 'نود',
+    100: 'صد',
+    200: 'دویست',
+    300: 'سيصد',
+    400: 'چهار صد',
+    500: 'پانصد',
+    600: 'ششصد',
+    700: 'هفتصد',
+    800: 'هشتصد',
+    900: 'نهصد',
+    1000: 'هزار',
+    1_000_000: 'میلیون'
+  }
+
+  convertWholePart (number) {
+    if (this.namedNumbers[number] && number !== 1_000_000n) {
+      return this.namedNumbers[number]
+    }
+
+    if (number > 20n && number < 100n) {
+      const xone = number % 10n
+      const xten = number - xone
+      return `${this.namedNumbers[xten]} و ${this.namedNumbers[xone]}`
+    }
+
+    if (number > 100n && number < 1000n) {
+      const xhundred = 100n * (number / 100n)
+      const tail = this.convertWholePart(number - xhundred)
+      return `${this.namedNumbers[xhundred]} و ${tail}`
+    }
+
+    if (number > 1000n && number < 1_000_000n) {
+      const thousandMultiplier = number / 1000n
+      const namedThousandMultiplier =
+        (thousandMultiplier === 1n
+          ? ''
+          : this.convertWholePart(thousandMultiplier)) +
+        ' ' +
+        this.namedNumbers[1000]
+      const tailNumber = number - thousandMultiplier * 1000n
+      const tail = tailNumber === 0n ? '' : ' ' + this.convertWholePart(tailNumber)
+      return `${namedThousandMultiplier}${tail}`
+    }
+
+    if (number >= 1_000_000n) {
+      const millionMultiplier = number / 1_000_000n
+      const namedMillion =
+        this.convertWholePart(millionMultiplier) + ' ' + this.namedNumbers[1_000_000]
+      const tailNumber = number - millionMultiplier * 1_000_000n
+      const tail = tailNumber === 0n ? '' : ' و ' + this.convertWholePart(tailNumber)
+      return `${namedMillion}${tail}`
+    }
+  }
+}
+
+/**
+ * Converts a number to Persian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @returns {string} The number expressed in Persian 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 Farsi(options).convertToWords(value)
+}

package/lib/languages/fil.js

@@ -0,0 +1,162 @@
+/**
+ * Filipino (Tagalog) language implementation for n2words
+ *
+ * Uses scale-based system with irregular patterns for numbers 1-19.
+ * Filipino numbers follow patterns like: sampu (10), labinisa (11), dalawampu (20)
+ *
+ * @module lib/languages/tl
+ * @example
+ * import fil from './lib/languages/fil.js'
+ * tl(42) // 'apatnapu dalawa'
+ * tl(1000) // 'isang libo'
+ */
+
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * Filipino language implementation
+ * Extends GreedyScaleLanguage with scale-based number conversion
+ */
+class FilipinoLanguage extends GreedyScaleLanguage {
+  negativeWord = 'negatibo'
+  decimalSeparatorWord = 'punto'
+  zeroWord = 'zero'
+  convertDecimalsPerDigit = true // Read decimals digit-by-digit
+
+  scaleWordPairs = [
+    [1000000000000n, 'trilyong'],
+    [1000000000n, 'milyong'],
+    [1000000n, 'milyong'],
+    [1000n, 'libong'],
+    [100n, 'daang'],
+
+    // Tens
+    [90n, 'siyamnapu'],
+    [80n, 'walumpu'],
+    [70n, 'pitumpu'],
+    [60n, 'animnapu'],
+    [50n, 'limampu'],
+    [40n, 'apatnapu'],
+    [30n, 'tatlumpu'],
+    [20n, 'dalawampu'],
+
+    // Teens (must come before 10 to be matched first)
+    [19n, 'labinsiyam'],
+    [18n, 'labingwalo'],
+    [17n, 'labimpito'],
+    [16n, 'labinanum'],
+    [15n, 'labinlima'],
+    [14n, 'labinapat'],
+    [13n, 'labintatlo'],
+    [12n, 'labindalawa'],
+    [11n, 'labinisa'],
+    [10n, 'sampu'],
+
+    // Ones
+    [9n, 'siyam'],
+    [8n, 'walo'],
+    [7n, 'pito'],
+    [6n, 'anim'],
+    [5n, 'lima'],
+    [4n, 'apat'],
+    [3n, 'tatlo'],
+    [2n, 'dalawa'],
+    [1n, 'isa'],
+    [0n, 'zero']
+  ]
+
+  /**
+   * Convert a whole number to Filipino words.
+   * Overrides parent to handle zero explicitly.
+   *
+   * @param {bigint} wholeNumber The whole number to convert.
+   * @returns {string} The Filipino representation.
+   */
+  convertWholePart (wholeNumber) {
+    // Handle zero explicitly
+    if (wholeNumber === 0n) {
+      return this.zeroWord
+    }
+    return super.convertWholePart(wholeNumber)
+  }
+
+  /**
+   * Merge two word-sets according to Filipino grammar rules.
+   *
+   * Features Filipino-specific rules:
+   * - "ng" connector between words
+   * - Consonant-ending words use "na" instead of "ng"
+   * - Implicit "one" omission ("isang daan" → "daan")
+   *
+   * @param {Object} leftWordSet Left word-set as `{ word: BigInt }`.
+   * @param {Object} rightWordSet Right word-set as `{ word: BigInt }`.
+   * @returns {Object} Merged word-set with combined text and value.
+   */
+  mergeScales (leftWordSet, rightWordSet) {
+    const leftWord = Object.keys(leftWordSet)[0]
+    const rightWord = Object.keys(rightWordSet)[0]
+    const leftValue = Object.values(leftWordSet)[0]
+    const rightValue = Object.values(rightWordSet)[0]
+
+    // Don't merge zero with anything - just return the non-zero value
+    if (leftValue === 0n) {
+      return rightWordSet
+    }
+    if (rightValue === 0n) {
+      return leftWordSet
+    }
+
+    // Implicit "one" - omit when adding with values < 100
+    if (leftValue === 1n && rightValue < 100n) {
+      return rightWordSet
+    }
+
+    // Multiply when right is a scale word AND right > left
+    // Use "ng" connector for Filipino, but consonant-ending words use " na "
+    if (rightValue > leftValue && rightValue >= 100n) {
+      // Words ending in consonants (not vowels) use " na " instead of "ng"
+      const vowels = ['a', 'e', 'i', 'o', 'u']
+      const lastChar = leftWord[leftWord.length - 1]
+      if (!vowels.includes(lastChar)) {
+        return {
+          [`${leftWord} na ${rightWord}`]: leftValue * rightValue
+        }
+      }
+      // Vowel-ending words add "ng"
+      return {
+        [`${leftWord}ng ${rightWord}`]: leftValue * rightValue
+      }
+    }
+
+    // Special Filipino rule: certain tens words take "-ng" linker when followed by ones
+    // Only limampu (50) confirmed to use this pattern
+    if (leftValue >= 10n && leftValue < 100n && rightValue >= 1n && rightValue < 10n) {
+      const tensWithNg = ['limampu']
+      if (tensWithNg.includes(leftWord)) {
+        return {
+          [`${leftWord}ng ${rightWord}`]: leftValue + rightValue
+        }
+      }
+    }
+
+    // Default: space for addition
+    return {
+      [`${leftWord} ${rightWord}`]: leftValue + rightValue
+    }
+  }
+}
+
+/**
+ * Convert a number to Filipino words
+ *
+ * @param {number|string|bigint} value - The number to convert
+ * @param {Object} [options={}] - Conversion options
+ * @returns {string} The Filipino word representation
+ * @example
+ * convertToWords(42) // 'apatnapu dalawa'
+ * convertToWords(1000) // 'isang libo'
+ * convertToWords(123456) // 'isang daang dalawampung tatlong libong apat na daang limampung anim'
+ */
+export default function convertToWords (value, options = {}) {
+  return new FilipinoLanguage(options).convertToWords(value)
+}

package/lib/languages/fr-BE.js

@@ -0,0 +1,61 @@
+import { French } from './fr.js'
+
+/**
+ * @typedef {Object} BelgianFrenchOptions
+ * @property {boolean} [withHyphenSeparator=false] Use hyphens (true) instead of spaces (false) in compounds.
+ */
+
+/**
+ * Belgian French language converter.
+ *
+ * Extends the French converter with Belgian French regional variant:
+ * - Uses "septante" (70) instead of "soixante-dix"
+ * - Uses "nonante" (90) instead of "quatre-vingt-dix"
+ * - Maintains standard French "quatre-vingts" for 80
+ * - More regular and logical number system than standard French
+ *
+ * Features:
+ * - Regional number word variations (septante, nonante)
+ * - Simplified tens naming (no complex arithmetic)
+ * - Inherits all other French grammar rules from FR class
+ * - Same pluralization and hyphenation patterns as standard French
+ */
+export class BelgianFrench extends French {
+  /**
+   * Initializes the Belgian French converter.
+   *
+   * @param {BelgianFrenchOptions} [options={}] Configuration options.
+   */
+  constructor (options = {}) {
+    super(options)
+    // Fill the empty placeholder slots with Belgian variants
+    // First empty slot (index 10) is for 90n (between 100n and 80n)
+    // Second empty slot (index 12) is for 70n (between 80n and 60n)
+    this.scaleWordPairs = this.scaleWordPairs.map((pair, index) => {
+      if (Array.isArray(pair) && pair.length === 0) {
+        // Check next pair to determine which slot this is
+        const nextPair = this.scaleWordPairs[index + 1]
+        if (nextPair && nextPair[0] === 80n) {
+          return [90n, 'nonante']
+        } else if (nextPair && nextPair[0] === 60n) {
+          return [70n, 'septante']
+        }
+      }
+      return pair
+    })
+  }
+}
+
+/**
+ * Converts a number to Belgian French cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @param {boolean} [options.withHyphenSeparator=false] Use hyphens (true) instead of spaces (false) in compounds.
+ * @returns {string} The number expressed in Belgian French 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 BelgianFrench(options).convertToWords(value)
+}

package/lib/languages/fr.js

@@ -0,0 +1,145 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * @typedef {Object} FrenchOptions
+ * @property {boolean} [withHyphenSeparator=false] Use hyphens (true) instead of spaces (false) in compounds.
+ */
+
+/**
+ * French language converter.
+ *
+ * Special handling:
+ * - Pluralization of "cent" (hundred) and other words
+ * - "et" (and) before odd numbers in tens place
+ * - Hyphenation for compound numbers
+ * - Regional number word variations
+ */
+export class French extends GreedyScaleLanguage {
+  negativeWord = 'moins'
+  decimalSeparatorWord = 'virgule'
+  zeroWord = 'zéro'
+  scaleWordPairs = [
+    [1_000_000_000_000_000_000_000_000_000n, 'quadrilliard'],
+    [1_000_000_000_000_000_000_000_000n, 'quadrillion'],
+    [1_000_000_000_000_000_000_000n, 'trilliard'],
+    [1_000_000_000_000_000_000n, 'trillion'],
+    [1_000_000_000_000_000n, 'billiard'],
+    [1_000_000_000_000n, 'billion'],
+    [1_000_000_000n, 'milliard'],
+    [1_000_000n, 'million'],
+    [1000n, 'mille'],
+    [100n, 'cent'],
+    [],
+    [80n, 'quatre-vingts'],
+    [],
+    [60n, 'soixante'],
+    [50n, 'cinquante'],
+    [40n, 'quarante'],
+    [30n, 'trente'],
+    [20n, 'vingt'],
+    [19n, 'dix-neuf'],
+    [18n, 'dix-huit'],
+    [17n, 'dix-sept'],
+    [16n, 'seize'],
+    [15n, 'quinze'],
+    [14n, 'quatorze'],
+    [13n, 'treize'],
+    [12n, 'douze'],
+    [11n, 'onze'],
+    [10n, 'dix'],
+    [9n, 'neuf'],
+    [8n, 'huit'],
+    [7n, 'sept'],
+    [6n, 'six'],
+    [5n, 'cinq'],
+    [4n, 'quatre'],
+    [3n, 'trois'],
+    [2n, 'deux'],
+    [1n, 'un'],
+    [0n, 'zéro']
+  ]
+
+  /**
+   * Initializes the French converter with language-specific options.
+   *
+   * @param {FrenchOptions} [options={}] Configuration options.
+   */
+  constructor ({ withHyphenSeparator = false } = {}) {
+    super()
+
+    this.withHyphenSeparator = withHyphenSeparator
+
+    if (this.withHyphenSeparator) {
+      this.wordSeparator = '-'
+    }
+  }
+
+  /**
+   * Merges two adjacent word-number pairs according to French grammar rules.
+   *
+   * French-specific rules:
+   * - Removes trailing 's' from multiples of 80 or 100 when followed by smaller numbers
+   * - Adds 's' to hundreds when appropriate
+   * - Uses "et" (and) when joining odd numbers to tens (e.g., "vingt et un")
+   * - Hyphens for compound tens (e.g., "vingt-deux")
+   *
+   * @param {Object} currentPair The left operand as `{ word: number }`.
+   * @param {Object} nextPair The right operand as `{ word: number }`.
+   * @returns {Object} Merged pair with combined word and resulting number.
+   */
+  mergeScales (currentPair, nextPair) {
+    let currentWord = Object.keys(currentPair)[0]
+    let nextWord = Object.keys(nextPair)[0]
+    const currentNumber = Object.values(currentPair)[0]
+    const nextNumber = Object.values(nextPair)[0]
+
+    if (currentNumber === 1n) {
+      if (nextNumber < 1_000_000n) {
+        return nextPair
+      }
+    } else {
+      if (
+        ((currentNumber - 80n) % 100n === 0n || (currentNumber % 100n === 0n && currentNumber < 1000n)) &&
+        nextNumber < 1_000_000n &&
+        currentWord.at(-1) === 's'
+      ) {
+        currentWord = currentWord.slice(0, -1)
+      }
+
+      if (
+        currentNumber < 1000n && nextNumber !== 1000n &&
+        nextWord.at(-1) !== 's' &&
+        nextNumber % 100n === 0n
+      ) {
+        nextWord += 's'
+      }
+    }
+
+    if (nextNumber < currentNumber && currentNumber < 100n) {
+      if (nextNumber % 10n === 1n && currentNumber !== 80n) {
+        return { [`${currentWord}${this.wordSeparator}et${this.wordSeparator}${nextWord}`]: currentNumber + nextNumber }
+      }
+      return { [`${currentWord}-${nextWord}`]: currentNumber + nextNumber }
+    }
+
+    if (nextNumber > currentNumber) return { [`${currentWord}${this.wordSeparator}${nextWord}`]: currentNumber * nextNumber }
+    return { [`${currentWord}${this.wordSeparator}${nextWord}`]: currentNumber + nextNumber }
+  }
+}
+
+/**
+ * Converts a number to French cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see FR class).
+ * @returns {string} The number expressed in French words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42, { lang: 'fr' }); // 'quarante-deux'
+ * convertToWords(81, { lang: 'fr' }); // 'quatre-vingt-un'
+ */
+export default function convertToWords (value, options = {}) {
+  return new French(options).convertToWords(value)
+}

package/lib/languages/gu.js

@@ -0,0 +1,156 @@
+/**
+ * Gujarati language implementation for n2words
+ *
+ * Gujarati uses Indian-style number grouping (3 digits, then 2-2 from right).
+ * Numbers: શૂન્ય (0), એક (1), બે (2), ત્રણ (3), ચાર (4), પાંચ (5)...
+ *
+ * @module lib/languages/gu
+ * @example
+ * import gu from './lib/languages/gu.js'
+ * gu(42) // 'બેતાળીસ'
+ * gu(1000) // 'એક હજાર'
+ */
+
+import SouthAsianLanguage from '../classes/south-asian-language.js'
+
+/**
+ * Gujarati language implementation
+ * Extends SouthAsianLanguage for Indian-style grouping
+ */
+class GujaratiLanguage extends SouthAsianLanguage {
+  negativeWord = 'ઋણ'
+  decimalSeparatorWord = 'દશાંશ'
+  zeroWord = 'શૂન્ય'
+  hundredWord = 'સો'
+  convertDecimalsPerDigit = true
+
+  belowHundred = [
+    'શૂન્ય',
+    'એક',
+    'બે',
+    'ત્રણ',
+    'ચાર',
+    'પાંચ',
+    'છ',
+    'સાત',
+    'આઠ',
+    'નવ',
+    'દસ',
+    'અગિયાર',
+    'બાર',
+    'તેર',
+    'ચૌદ',
+    'પંદર',
+    'સોળ',
+    'સત્તર',
+    'અઢાર',
+    'ઓગણીસ',
+    'વીસ',
+    'એકવીસ',
+    'બાવીસ',
+    'ત્રેવીસ',
+    'ચોવીસ',
+    'પચીસ',
+    'છવ્વીસ',
+    'સત્તાવીસ',
+    'અઠ્ઠાવીસ',
+    'ઓગણત્રીસ',
+    'ત્રીસ',
+    'એકત્રીસ',
+    'બત્રીસ',
+    'તેત્રીસ',
+    'ચોત્રીસ',
+    'પાંત્રીસ',
+    'છત્રીસ',
+    'સાડત્રીસ',
+    'અડત્રીસ',
+    'ઓગણચાલીસ',
+    'ચાલીસ',
+    'એકતાલીસ',
+    'બેતાળીસ',
+    'ત્રેતાળીસ',
+    'ચુંમાલીસ',
+    'પિસ્તાલીસ',
+    'છેતાળીસ',
+    'સુડતાળીસ',
+    'અડતાળીસ',
+    'ઓગણપચાસ',
+    'પચાસ',
+    'એકાવન',
+    'બાવન',
+    'ત્રેપન',
+    'ચોપન',
+    'પંચાવન',
+    'છપ્પન',
+    'સત્તાવન',
+    'અઠ્ઠાવન',
+    'ઓગણસાઠ',
+    'સાઠ',
+    'એકસઠ',
+    'બાસઠ',
+    'ત્રેસઠ',
+    'ચોસઠ',
+    'પાંસઠ',
+    'છાસઠ',
+    'સડસઠ',
+    'અડસઠ',
+    'અગણોસિત્તેર',
+    'સિત્તેર',
+    'એકોતેર',
+    'બોતેર',
+    'તોતેર',
+    'ચુમોતેર',
+    'પંચોતેર',
+    'છોતેર',
+    'સિત્યોતેર',
+    'ઇઠ્યોતેર',
+    'ઓગણાએંસી',
+    'એંસી',
+    'એક્યાસી',
+    'બ્યાસી',
+    'ત્યાસી',
+    'ચોર્યાસી',
+    'પંચાસી',
+    'છ્યાસી',
+    'સિત્યાસી',
+    'અઠ્યાસી',
+    'નેવ્યાસી',
+    'નેવું',
+    'એકાણું',
+    'બાણું',
+    'ત્રાણું',
+    'ચોરાણું',
+    'પંચાણું',
+    'છન્નું',
+    'સત્તાણું',
+    'અઠ્ઠાણું',
+    'નવ્વાણું'
+  ]
+
+  scaleWords = [
+    '',
+    'હજાર',
+    'લાખ',
+    'કરોડ',
+    'અબજ',
+    'ખરબ',
+    'નીલ',
+    'પદ્મ',
+    'શંખ'
+  ]
+}
+
+/**
+ * Convert a number to Gujarati words
+ *
+ * @param {number|string|bigint} value - The number to convert
+ * @param {Object} [options={}] - Conversion options
+ * @returns {string} The Gujarati word representation
+ * @example
+ * convertToWords(42) // 'બેતાળીસ'
+ * convertToWords(1000) // 'એક હજાર'
+ * convertToWords(100000) // 'એક લાખ'
+ */
+export default function convertToWords (value, options = {}) {
+  return new GujaratiLanguage(options).convertToWords(value)
+}