n2words/src/sr-Latn-RS.js

Convert numbers to words in 70+ languages with zero dependencies. Supports BigInt, decimals, and browser/Node.js environments.

/**
 * Serbian (Serbia, Latin script) language converter
 *
 * CLDR: sr-Latn-RS | Serbian as used in Serbia (Latin script)
 *
 * Key features:
 * - Three-form pluralization (one/few/many)
 * - Gender by scale word: the -arda forms (hiljada, milijarda, bilijarda, ...)
 *   are feminine; the -ion forms (milion, bilion, ...) are masculine
 * - Irregular hundreds (dvesta, trista, etc.)
 * - Long scale naming with -ard forms
 * - Latin script
 */

import { parseCardinalValue } from './utils/parse-cardinal.js'
import { parseCurrencyValue } from './utils/parse-currency.js'
import { parseOrdinalValue } from './utils/parse-ordinal.js'
import { checkMax } from './utils/check-max.js'
import { western } from './utils/scale.js'
import { resolveOptions } from './utils/resolve-options.js'

// ============================================================================
// Vocabulary
// ============================================================================

const ONES_MASC = ['', 'jedan', 'dva', 'tri', 'četiri', 'pet', 'šest', 'sedam', 'osam', 'devet']
const ONES_FEM = ['', 'jedna', 'dve', 'tri', 'četiri', 'pet', 'šest', 'sedam', 'osam', 'devet']
const TEENS = ['deset', 'jedanaest', 'dvanaest', 'trinaest', 'četrnaest', 'petnaest', 'šesnaest', 'sedamnaest', 'osamnaest', 'devetnaest']
const TENS = ['', '', 'dvadeset', 'trideset', 'četrdeset', 'pedeset', 'šezdeset', 'sedamdeset', 'osamdeset', 'devedeset']
const HUNDREDS = ['', 'sto', 'dvesta', 'trista', 'četiristo', 'petsto', 'šesto', 'sedamsto', 'osamsto', 'devetsto']

const ZERO = 'nula'
const NEGATIVE = 'minus'
const DECIMAL_SEP = 'zapeta'

// ============================================================================
// Ordinal Vocabulary (masculine nominative)
// ============================================================================

// Ordinal ones: prvi, drugi, treći...
const ORDINAL_ONES = ['', 'prvi', 'drugi', 'treći', 'četvrti', 'peti', 'šesti', 'sedmi', 'osmi', 'deveti']

// Ordinal teens: deseti, jedanaesti...
const ORDINAL_TEENS = ['deseti', 'jedanaesti', 'dvanaesti', 'trinaesti', 'četrnaesti', 'petnaesti', 'šesnaesti', 'sedamnaesti', 'osamnaesti', 'devetnaesti']

// Ordinal tens: dvadeseti, trideseti...
const ORDINAL_TENS = ['', '', 'dvadeseti', 'trideseti', 'četrdeseti', 'pedeseti', 'šezdeseti', 'sedamdeseti', 'osamdeseti', 'devedeseti']

// Ordinal hundreds: stoti, dvestoti...
const ORDINAL_HUNDREDS = ['', 'stoti', 'dvestoti', 'tristoti', 'četiristoti', 'petstoti', 'šestoti', 'sedamstoti', 'osamstoti', 'devetstoti']

// Ordinal scale words (hiljaditi, milioniti, etc.)
const ORDINAL_SCALES = [
  'hiljaditi',
  'milioniti',
  'milijarditi',
  'bilioniti',
  'bilijarditi',
  'trilioniti',
  'trilijarditi',
  'kvadrilioniti',
  'kvadrilijarditi',
]

// ============================================================================
// Currency Vocabulary (Serbian Dinar)
// ============================================================================

// Dinar: masculine, [singular, few, many]
const DINAR_FORMS = ['dinar', 'dinara', 'dinara']

// Para: feminine, [singular, few, many]
const PARA_FORMS = ['para', 'pare', 'para']

// Scale words: [singular, few, many]
const SCALE_FORMS = [
  ['hiljada', 'hiljade', 'hiljada'],
  ['milion', 'miliona', 'miliona'],
  ['milijarda', 'milijarde', 'milijarda'],
  ['bilion', 'biliona', 'biliona'],
  ['bilijarda', 'bilijarde', 'bilijarda'],
  ['trilion', 'triliona', 'triliona'],
  ['trilijarda', 'trilijarde', 'trilijarda'],
  ['kvadrilion', 'kvadriliona', 'kvadriliona'],
  ['kvadrilijarda', 'kvadrilijarde', 'kvadrilijarda'],
]

// Supported magnitude ceilings (checked at the public entry points). Both the
// cardinal SCALE_FORMS and the ORDINAL_SCALES tables cover units + N scale
// groups, so values must stay below 10^((length + 1) * 3) = 10^30.
export const cardinalMax = western(SCALE_FORMS.length)
export const ordinalMax = western(ORDINAL_SCALES.length)
export const currencyMax = western(SCALE_FORMS.length)

// ============================================================================
// Segment Building
// ============================================================================

/**
 * Selects the correct plural form based on Serbian grammar rules.
 * @param {number | bigint} n - The count
 * @param {string[]} forms - Plural forms [one, few, many]
 * @returns {string} The selected plural form
 */
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]
}

/**
 * Builds the masculine word form for a 0-999 segment.
 * @param {number} n - Segment value 0-999
 * @returns {string} The segment words
 */
function buildSegmentMasc(n) {
  if (n === 0) return ''

  const onesDigit = n % 10
  const tensDigit = Math.trunc(n / 10) % 10
  const hundredsDigit = Math.trunc(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_MASC[onesDigit])
  }

  return parts.join(' ')
}

/**
 * Builds the feminine word form for a 0-999 segment.
 * @param {number} n - Segment value 0-999
 * @returns {string} The segment words
 */
function buildSegmentFem(n) {
  if (n === 0) return ''

  const onesDigit = n % 10
  const tensDigit = Math.trunc(n / 10) % 10
  const hundredsDigit = Math.trunc(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_FEM[onesDigit])
  }

  return parts.join(' ')
}

// ============================================================================
// Conversion Functions
// ============================================================================

/**
 * Converts a non-negative integer to Serbian words.
 * @param {bigint} n - The integer to convert
 * @param {('masculine'|'feminine')} gender - Grammatical gender
 * @returns {string} The integer in Serbian words
 */
function integerToWords(n, gender) {
  if (n === 0n) return ZERO

  if (n < 1000n) {
    return gender === 'feminine' ? buildSegmentFem(Number(n)) : buildSegmentMasc(Number(n))
  }

  return buildLargeNumberWords(n, gender)
}

/**
 * Builds words for numbers >= 1000 using scale decomposition.
 * @param {bigint} n - The integer to convert (>= 1000)
 * @param {('masculine'|'feminine')} gender - Grammatical gender
 * @returns {string} The number in Serbian words
 */
function buildLargeNumberWords(n, gender) {
  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) {
        parts.push(gender === 'feminine' ? buildSegmentFem(segment) : buildSegmentMasc(segment))
      }
      else {
        const scaleForms = SCALE_FORMS[scaleIndex - 1]
        const scaleWord = pluralize(segment, scaleForms)
        // -arda scale words (hiljada, milijarda, ...) are feminine; -ion words masculine
        const isFeminine = scaleIndex % 2 === 1
        const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
        parts.push(segmentWord + ' ' + scaleWord)
      }
    }

    scaleIndex--
  }

  return parts.join(' ')
}

/**
 * Converts the decimal-part digit string to Serbian words.
 * @param {string} decimalPart - The fractional digits as a string
 * @param {('masculine'|'feminine')} gender - Grammatical gender
 * @returns {string} The decimal part in Serbian words
 */
function decimalPartToWords(decimalPart, gender) {
  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), gender)
  }

  return result
}

/**
 * @typedef {object} CardinalOptions
 * @property {('masculine'|'feminine')} [gender] - Grammatical gender
 */

/** @type {Required<CardinalOptions>} */
export const cardinalDefaults = { gender: 'masculine' }

/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
export const cardinalValues = { gender: ['masculine', 'feminine'] }

/**
 * Converts a numeric value to Serbian (Latin) words.
 * @param {number | string | bigint} value - The numeric value to convert
 * @param {CardinalOptions} [options] - Optional configuration
 * @returns {string} The number in Serbian Latin words
 */
function toCardinal(value, options) {
  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
  // Both the integer part and the decimal's significant digits are spelled via
  // the scale builder, so both must clear the ceiling.
  checkMax(integerPart, cardinalMax, decimalPart)

  // Apply option defaults
  const { gender } = resolveOptions(options, cardinalDefaults, cardinalValues)

  let result = ''

  if (isNegative) {
    result = NEGATIVE + ' '
  }

  result += integerToWords(integerPart, gender)

  if (decimalPart) {
    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, gender)
  }

  return result
}

// ============================================================================
// ORDINAL: toOrdinal(value)
// ============================================================================

/**
 * Builds ordinal for a 0-99 segment when it's the final (ordinal) part.
 * Returns ordinal form: "prvi", "dvadeset prvi", etc.
 * @param {number} n - Number 0-99
 * @returns {string} Ordinal words
 */
function buildOrdinalTensOnes(n) {
  if (n === 0) return ''

  const onesDigit = n % 10
  const tensDigit = Math.trunc(n / 10)

  if (tensDigit === 0) {
    // Single digit: prvi, drugi, etc.
    return ORDINAL_ONES[onesDigit]
  }

  if (tensDigit === 1) {
    // Teens: deseti, jedanaesti, etc.
    return ORDINAL_TEENS[onesDigit]
  }

  // Tens >= 20
  if (onesDigit === 0) {
    // Round tens: dvadeseti, trideseti, etc.
    return ORDINAL_TENS[tensDigit]
  }

  // Compound: dvadeset prvi, trideset drugi, etc.
  return TENS[tensDigit] + ' ' + ORDINAL_ONES[onesDigit]
}

/**
 * Converts a positive integer to Serbian ordinal words (masculine nominative).
 *
 * In Serbian ordinals, only the LAST component becomes ordinal.
 * E.g., 121 = "sto dvadeset prvi" (one hundred twenty first)
 * @param {bigint} n - Positive integer to convert
 * @returns {string} Ordinal Serbian words
 */
function integerToOrdinal(n) {
  // Fast path: numbers < 100
  if (n < 100n) {
    return buildOrdinalTensOnes(Number(n))
  }

  // Fast path: numbers < 1000
  if (n < 1000n) {
    const num = Number(n)
    const hundredsDigit = Math.trunc(num / 100)
    const remainder = num % 100

    if (remainder === 0) {
      // Exact hundreds: stoti, dvestoti, etc.
      return ORDINAL_HUNDREDS[hundredsDigit]
    }

    // Has remainder: cardinal hundreds + ordinal remainder
    return HUNDREDS[hundredsDigit] + ' ' + buildOrdinalTensOnes(remainder)
  }

  // Fast path: numbers < 1,000,000
  if (n < 1_000_000n) {
    const thousands = Number(n / 1000n)
    const remainder = Number(n % 1000n)

    if (remainder === 0) {
      // Exact thousands: hiljaditi, etc.
      if (thousands === 1) {
        return ORDINAL_SCALES[0]
      }
      // Use cardinal segment + ordinal scale
      return buildSegmentFem(thousands) + ' ' + ORDINAL_SCALES[0]
    }

    // Has remainder: cardinal thousands + ordinal remainder
    const thousandsWord = buildSegmentFem(thousands)
    const scaleWord = pluralize(thousands, SCALE_FORMS[0])
    return thousandsWord + ' ' + scaleWord + ' ' + integerToOrdinal(BigInt(remainder))
  }

  // For numbers >= 1,000,000, use scale decomposition
  return buildLargeOrdinal(n)
}

/**
 * Builds ordinal words for numbers >= 1,000,000.
 * All segments except the final one are cardinal; final segment is ordinal.
 * @param {bigint} n - Number >= 1,000,000
 * @returns {string} Ordinal Serbian words
 */
function buildLargeOrdinal(n) {
  const numStr = n.toString()
  const len = numStr.length

  // Extract segments (most-significant first)
  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
  }

  // Find the last non-zero segment
  let lastNonZeroIdx = segments.length - 1
  while (lastNonZeroIdx >= 0 && segments[lastNonZeroIdx] === 0) {
    lastNonZeroIdx--
  }

  const parts = []
  let scaleIndex = segments.length - 1

  for (let i = 0; i < segments.length; i++) {
    const segment = segments[i]

    if (segment !== 0) {
      const isLastNonZero = (i === lastNonZeroIdx)

      if (scaleIndex === 0) {
        // Units position (no scale)
        if (isLastNonZero) {
          parts.push(integerToOrdinal(BigInt(segment)))
        }
        else {
          parts.push(buildSegmentMasc(segment))
        }
      }
      else {
        // Has scale word
        if (isLastNonZero) {
          // This scale position is the final ordinal
          if (segment === 1) {
            parts.push(ORDINAL_SCALES[scaleIndex - 1])
          }
          else {
            // Use cardinal segment + ordinal scale
            const isFeminine = scaleIndex % 2 === 1 // feminine at -arda scales (hiljada, milijarda, ...)
            const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
            parts.push(segmentWord + ' ' + ORDINAL_SCALES[scaleIndex - 1])
          }
        }
        else {
          // Not the final segment: use cardinal
          const scaleForms = SCALE_FORMS[scaleIndex - 1]
          const scaleWord = pluralize(segment, scaleForms)
          const isFeminine = scaleIndex % 2 === 1
          const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
          parts.push(segmentWord + ' ' + scaleWord)
        }
      }
    }

    scaleIndex--
  }

  return parts.join(' ')
}

/**
 * Converts a numeric value to Serbian 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., "prvi", "četrdeset 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)    // 'prvi'
 * toOrdinal(2)    // 'drugi'
 * toOrdinal(3)    // 'treći'
 * toOrdinal(21)   // 'dvadeset prvi'
 * toOrdinal(42)   // 'četrdeset drugi'
 * toOrdinal(100)  // 'stoti'
 * toOrdinal(1000) // 'hiljaditi'
 */
function toOrdinal(value) {
  const integerPart = parseOrdinalValue(value)
  checkMax(integerPart, ordinalMax)
  return integerToOrdinal(integerPart)
}

// ============================================================================
// CURRENCY: toCurrency(value, options?)
// ============================================================================

/**
 * @typedef {object} CurrencyOptions
 * @property {boolean} [and] - Use "i" between dinars and para
 */

/** @type {Required<CurrencyOptions>} */
export const currencyDefaults = { and: true }

/**
 * Converts a numeric value to Serbian currency words (Serbian Dinar).
 * @param {number | string | bigint} value - The currency amount to convert
 * @param {CurrencyOptions} [options] - Optional configuration
 * @returns {string} The amount in Serbian 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)                    // 'četrdeset dva dinara i pedeset para'
 * toCurrency(1)                        // 'jedan dinar'
 * toCurrency(0.99)                     // 'devedeset devet para'
 * toCurrency(0.01)                     // 'jedna para'
 * toCurrency(42.50, { and: false })    // 'četrdeset dva dinara pedeset para'
 */
function toCurrency(value, options) {
  const { isNegative, dollars: dinars, cents: para } = parseCurrencyValue(value)
  checkMax(dinars, currencyMax)
  const { and: useAnd } = resolveOptions(options, currencyDefaults)

  // Build result
  let result = ''
  if (isNegative) result = NEGATIVE + ' '

  // Dinars part (masculine) - show if non-zero, or if no para
  if (dinars > 0n || para === 0n) {
    result += integerToWords(dinars, 'masculine')
    result += ' ' + pluralize(dinars, DINAR_FORMS)
  }

  // Para part (feminine)
  if (para > 0n) {
    if (dinars > 0n) {
      result += useAnd ? ' i ' : ' '
    }
    result += integerToWords(para, 'feminine')
    result += ' ' + pluralize(para, PARA_FORMS)
  }

  return result
}

// ============================================================================
// Exports
// ============================================================================

export { toCardinal, toOrdinal, toCurrency }