n2words 3.0.0 → 4.0.0

package/src/pa-IN.js

@@ -0,0 +1,268 @@
+/**
+ * Punjabi (India) language converter
+ *
+ * CLDR: pa-IN | Punjabi (Gurmukhi) as used in India
+ *
+ * Key features:
+ * - Indian numbering system (ਹਜ਼ਾਰ, ਲੱਖ, ਕਰੋੜ)
+ * - Gurmukhi script
+ * - 3-2-2 grouping pattern (last 3 digits, then groups of 2)
+ * - Complete word forms for 0-99
+ */
+
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ZERO = 'ਸਿਫ਼ਰ'
+const NEGATIVE = 'ਮਾਇਨਸ'
+const DECIMAL_SEP = 'ਦਸ਼ਮਲਵ'
+const HUNDRED = 'ਸੌ'
+
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal suffix (adds to cardinal for numbers >= 7)
+const ORDINAL_SUFFIX = 'ਵਾਂ'
+
+// Special ordinals for first few numbers (1-6 have irregular forms)
+const ORDINAL_SPECIAL = ['', 'ਪਹਿਲਾ', 'ਦੂਜਾ', 'ਤੀਜਾ', 'ਚੌਥਾ', 'ਪੰਜਵਾਂ', 'ਛੇਵਾਂ']
+
+// ============================================================================
+// Currency Vocabulary (Indian Rupee)
+// ============================================================================
+
+// Rupee: singular/plural
+const RUPEE = 'ਰੁਪਇਆ'
+const RUPEES = 'ਰੁਪਏ'
+
+// Paisa: singular/plural
+const PAISA = 'ਪੈਸਾ'
+const PAISE = 'ਪੈਸੇ'
+
+const BELOW_HUNDRED = [
+  'ਸਿਫ਼ਰ', 'ਇੱਕ', 'ਦੋ', 'ਤਿੰਨ', 'ਚਾਰ', 'ਪੰਜ', 'ਛੇ', 'ਸੱਤ', 'ਅੱਠ', 'ਨੌਂ',
+  'ਦੱਸ', 'ਗਿਆਰਾਂ', 'ਬਾਰਾਂ', 'ਤੇਰਾਂ', 'ਚੌਦਾਂ', 'ਪੰਦਰਾਂ', 'ਸੋਲਾਂ', 'ਸਤਾਰਾਂ', 'ਅਠਾਰਾਂ', 'ਉੱਨੀ',
+  'ਵੀਹ', 'ਇੱਕੀ', 'ਬਾਈ', 'ਤੇਈ', 'ਚੌਬੀ', 'ਪੱਚੀ', 'ਛੱਬੀ', 'ਸਤਾਈ', 'ਅਠਾਈ', 'ਉਨੱਤੀ',
+  'ਤੀਹ', 'ਇਕੱਤੀ', 'ਬੱਤੀ', 'ਤੇਤੀ', 'ਚੌਂਤੀ', 'ਪੈਂਤੀ', 'ਛੱਤੀ', 'ਸੈਂਤੀ', 'ਅਠੱਤੀ', 'ਉਨਤਾਲੀ',
+  'ਚਾਲੀ', 'ਇਕਤਾਲੀ', 'ਬਿਆਲੀ', 'ਤਿਰਤਾਲੀ', 'ਚੁਵਾਲੀ', 'ਪੰਤਾਲੀ', 'ਛਿਆਲੀ', 'ਸੈਂਤਾਲੀ', 'ਅਠਤਾਲੀ', 'ਉਨੰਜਾ',
+  'ਪੰਜਾਹ', 'ਇਕਵੰਜਾ', 'ਬਵੰਜਾ', 'ਤਰਵੰਜਾ', 'ਚੁਰਵੰਜਾ', 'ਪੰਜਵੰਜਾ', 'ਛਪੰਜਾ', 'ਸੱਤਵੰਜਾ', 'ਅਠਵੰਜਾ', 'ਉਨਾਹਠ',
+  'ਸੱਠ', 'ਇਕਾਹਠ', 'ਬਾਹਠ', 'ਤਰਸਠ', 'ਚੌਂਸਠ', 'ਪੈਂਸਠ', 'ਛਿਆਸਠ', 'ਸੜਸਠ', 'ਅੜਸਠ', 'ਉਣਹੱਤਰ',
+  'ਸਤੱਰ', 'ਇਕਹੱਤਰ', 'ਬਹੱਤਰ', 'ਤਹੱਤਰ', 'ਚੌਹੱਤਰ', 'ਪੰਝਹੱਤਰ', 'ਛਿਹੱਤਰ', 'ਸਤੱਤਰ', 'ਅਠੱਤਰ', 'ਉਨਾਸੀ',
+  'ਅੱਸੀ', 'ਇਕਿਆਸੀ', 'ਬਿਆਸੀ', 'ਤਰਿਆਸੀ', 'ਚੌਰਿਆਸੀ', 'ਪਚਾਸੀ', 'ਛਿਆਸੀ', 'ਸੱਤਾਸੀ', 'ਅਠਾਸੀ', 'ਨਵਾਸੀ',
+  'ਨੱਬੇ', 'ਇਕਾਨਵੇਂ', 'ਬਾਨਵੇਂ', 'ਤਰਾਨਵੇਂ', 'ਚੁਰਾਨਵੇਂ', 'ਪੰਚਾਨਵੇਂ', 'ਛਿਆਨਵੇਂ', 'ਸਤਾਨਵੇਂ', 'ਅਠਾਨਵੇਂ', 'ਨਿਨਾਨਵੇਂ'
+]
+
+// Scale words: index 0 = units (empty), 1 = thousand, 2 = lakh, 3 = crore, etc.
+const SCALE_WORDS = ['', 'ਹਜ਼ਾਰ', 'ਲੱਖ', 'ਕਰੋੜ', 'ਅਰਬ', 'ਖਰਬ', 'ਨੀਲ', 'ਪਦਮ', 'ਸ਼ੰਖ']
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds words for a 0-999 segment.
+ */
+function buildSegment (n) {
+  if (n === 0) return ''
+  if (n < 100) return BELOW_HUNDRED[n]
+
+  const hundreds = Math.trunc(n / 100)
+  const remainder = n % 100
+
+  if (remainder === 0) {
+    return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED
+  }
+  return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED + ' ' + BELOW_HUNDRED[remainder]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Punjabi words.
+ *
+ * Uses BigInt modulo for segment extraction (faster than string slicing).
+ * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Punjabi words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return buildSegment(Number(n))
+  }
+
+  // Extract segments using BigInt modulo
+  const segments = []
+  segments.push(Number(n % 1000n))
+  let temp = n / 1000n
+
+  while (temp > 0n) {
+    segments.push(Number(temp % 100n))
+    temp = temp / 100n
+  }
+
+  // Build result string (process from most-significant to least)
+  const words = []
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (i === 0) {
+      words.push(buildSegment(segment))
+    } else {
+      words.push(BELOW_HUNDRED[segment])
+    }
+
+    if (i > 0 && SCALE_WORDS[i]) {
+      words.push(SCALE_WORDS[i])
+    }
+  }
+
+  return words.join(' ')
+}
+
+function decimalPartToWords (decimalPart) {
+  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))
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Punjabi words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Punjabi words
+ */
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
+}
+
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Punjabi ordinal words.
+ *
+ * Punjabi ordinals: First 6 are irregular, then add -ਵਾਂ suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Punjabi ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special ordinals for 1-6
+  if (n >= 1n && n <= 6n) {
+    return ORDINAL_SPECIAL[Number(n)]
+  }
+
+  // For 7 and above, add suffix to cardinal
+  const cardinal = integerToWords(n)
+  return cardinal + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a numeric value to Punjabi ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'ਪਹਿਲਾ'
+ * toOrdinal(2)    // 'ਦੂਜਾ'
+ * toOrdinal(3)    // 'ਤੀਜਾ'
+ * toOrdinal(10)   // 'ਦੱਸਵਾਂ'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Punjabi currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Punjabi currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42.50)  // 'ਬਿਆਲੀ ਰੁਪਏ ਪੰਜਾਹ ਪੈਸੇ'
+ * toCurrency(1)      // 'ਇੱਕ ਰੁਪਇਆ'
+ * toCurrency(0.01)   // 'ਇੱਕ ਪੈਸਾ'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: rupees, cents: paise } = parseCurrencyValue(value)
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Rupees part - show if non-zero, or if no paise
+  if (rupees > 0n || paise === 0n) {
+    result += integerToWords(rupees)
+    // Singular for 1 rupee, plural otherwise
+    result += ' ' + (rupees === 1n ? RUPEE : RUPEES)
+  }
+
+  // Paise part
+  if (paise > 0n) {
+    if (rupees > 0n) {
+      result += ' '
+    }
+    result += integerToWords(paise)
+    // Singular for 1 paisa, plural otherwise
+    result += ' ' + (paise === 1n ? PAISA : PAISE)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toCardinal, toOrdinal, toCurrency }

package/src/pl-PL.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Converts a numeric value to Polish words.
+ *
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Conversion options
+ * @param {string} [options.gender='masculine'] - Gender for numbers < 1000
+ * @returns {string} The number in Polish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(1)                          // 'jeden'
+ * toCardinal(1, { gender: 'feminine' })  // 'jedna'
+ * toCardinal(1000)                       // 'tysiąc'
+ * toCardinal(2000)                       // 'dwa tysiące'
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    gender?: string | undefined;
+}): string;
+/**
+ * Converts a numeric value to Polish ordinal words (masculine nominative).
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (must be a positive integer)
+ * @returns {string} The number as ordinal words (e.g., "pierwszy", "czterdziesty drugi")
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'pierwszy'
+ * toOrdinal(2)    // 'drugi'
+ * toOrdinal(3)    // 'trzeci'
+ * toOrdinal(21)   // 'dwudziesty pierwszy'
+ * toOrdinal(42)   // 'czterdziesty drugi'
+ * toOrdinal(100)  // 'setny'
+ * toOrdinal(1000) // 'tysięczny'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Polish currency words (Polish Złoty).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Polish currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42)     // 'czterdzieści dwa złote'
+ * toCurrency(1)      // 'jeden złoty'
+ * toCurrency(1.50)   // 'jeden złoty pięćdziesiąt groszy'
+ * toCurrency(-5)     // 'minus pięć złotych'
+ */
+export function toCurrency(value: number | string | bigint): string;