n2words
Version:
Convert numbers to words in 70+ languages with zero dependencies. Supports BigInt, decimals, and browser/Node.js environments.
353 lines (294 loc) • 10.2 kB
JavaScript
/**
* Hausa (Nigeria) language converter
*
* CLDR: ha-NG | Hausa as used in Nigeria
*
* Key features:
* - Authentic Boko orthography with ɗ (hooked d) and ' (glottal stop)
* - Teens with "sha" prefix (sha ɗaya = 11)
* - Compound numbers with "da" connector (ashirin da ɗaya = 21)
* - Arabic loanwords for tens (ashirin, talatin, arba'in, etc.)
* - Reversed multiplier order: "biyu ɗari" (200), "biyu dubu" (2000)
* - Implicit one before ɗari and dubu
* - Per-digit decimal reading
*/
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'
// ============================================================================
// Vocabulary
// ============================================================================
const ONES = ['', 'ɗaya', 'biyu', 'uku', 'huɗu', 'biyar', 'shida', 'bakwai', 'takwas', 'tara']
const TEENS = ['goma', 'sha ɗaya', 'sha biyu', 'sha uku', 'sha huɗu', 'sha biyar', 'sha shida', 'sha bakwai', 'sha takwas', 'sha tara']
// Arabic loanwords for tens
const TENS = ['', '', 'ashirin', 'talatin', 'arba\'in', 'hamsin', 'sittin', 'saba\'in', 'tamanin', 'tis\'in']
const HUNDRED = 'ɗari'
const THOUSAND = 'dubu'
const ZERO = 'sifiri'
const NEGATIVE = 'babu'
const DECIMAL_SEP = 'digo'
// Short scale
const SCALE_WORDS = ['', THOUSAND, 'miliyan', 'biliyan']
// Supported magnitude ceiling (checked at the public entry points), derived from the scale table.
export const cardinalMax = western(SCALE_WORDS.length - 1)
export const ordinalMax = western(SCALE_WORDS.length - 1)
export const currencyMax = western(SCALE_WORDS.length - 1)
// ============================================================================
// Ordinal Vocabulary
// ============================================================================
// Hausa ordinals: "na" + cardinal (na ɗaya = 1st, na biyu = 2nd)
// First has special form "na fari" or "farko"
const ORDINAL_PREFIX = 'na'
const ORDINAL_FIRST = 'na farko'
// ============================================================================
// Currency Vocabulary (Nigerian Naira)
// ============================================================================
const NAIRA = 'naira'
const KOBO = 'kobo'
// ============================================================================
// Precomputed Lookup Table
// ============================================================================
/**
* Build segment for 0-999 with Hausa patterns.
* Hausa uses reversed order for hundreds: "biyu ɗari" (200)
* And "da" connector for ones: "ashirin da ɗaya" (21)
* @param {number} n - Integer segment value (0-999)
* @returns {string} The segment in Hausa words
*/
function buildSegment(n) {
if (n === 0) return ''
const ones = n % 10
const tensDigit = Math.trunc(n / 10) % 10
const hundredsDigit = Math.trunc(n / 100)
const parts = []
// Hundreds: implicit one, or "biyu ɗari" (reversed order)
if (hundredsDigit > 0) {
if (hundredsDigit === 1) {
parts.push(HUNDRED)
}
else {
// Reversed: multiplier + hundredWord
parts.push(ONES[hundredsDigit] + ' ' + HUNDRED)
}
}
// Tens and ones
const tensOnes = n % 100
if (tensOnes === 0) {
// Just hundreds
}
else if (tensOnes < 10) {
// Single digit - with "da" connector if after hundreds
if (hundredsDigit > 0) {
parts.push('da ' + ONES[ones])
}
else {
parts.push(ONES[ones])
}
}
else if (tensOnes < 20) {
// Teens (10-19): "sha X"
parts.push(TEENS[ones])
}
else if (ones === 0) {
// Even tens (20, 30, 40, etc.)
parts.push(TENS[tensDigit])
}
else {
// Tens + ones with "da" connector
parts.push(TENS[tensDigit] + ' da ' + ONES[ones])
}
return parts.join(' ')
}
// ============================================================================
// Conversion Functions
// ============================================================================
/**
* @param {bigint} n - Non-negative integer value
* @returns {string} The integer in Hausa words
*/
function integerToWords(n) {
if (n === 0n) return ZERO
if (n < 1000n) {
return buildSegment(Number(n))
}
return buildLargeNumberWords(n)
}
/**
* Checks if a word is a single digit (1-9).
* @param {string} word - Word to test
* @returns {boolean} True if the word is a single digit (1-9)
*/
function isSingleDigit(word) {
return ONES.slice(1).includes(word)
}
/**
* @param {bigint} n - Integer value of 1000 or greater
* @returns {string} The number in Hausa words
*/
function buildLargeNumberWords(n) {
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
}
// Build raw parts (segment words and scale words)
const rawParts = []
let scaleIndex = segments.length - 1
for (let i = 0; i < segments.length; i++) {
const segment = segments[i]
if (segment !== 0) {
const scaleWord = SCALE_WORDS[scaleIndex] || ''
if (scaleIndex === 0) {
rawParts.push(buildSegment(segment))
}
else {
rawParts.push(buildSegment(segment))
rawParts.push(scaleWord)
}
}
scaleIndex--
}
// Filter out implicit "ɗaya" before ɗari or dubu
const filtered = []
for (let i = 0; i < rawParts.length; i++) {
const part = rawParts[i]
const nextPart = rawParts[i + 1]
// Skip "ɗaya" before ɗari or dubu (implicit one)
if (part === 'ɗaya' && nextPart && (nextPart === HUNDRED || nextPart === THOUSAND)) {
continue
}
filtered.push(part)
}
// Join with correct separators
const result = []
for (let i = 0; i < filtered.length; i++) {
const part = filtered[i]
const prevPart = i > 0 ? filtered[i - 1] : null
// Determine if we need "da" connector
// Use "da" when current is a single digit following a scale word
if (prevPart && isSingleDigit(part)
&& (prevPart === THOUSAND || prevPart === HUNDRED
|| SCALE_WORDS.includes(prevPart))) {
result.push(' da ')
}
else if (i > 0) {
result.push(' ')
}
result.push(part)
}
return result.join('')
}
/**
* @param {string} decimalPart - Digit string of the fractional part
* @returns {string} The fractional digits in Hausa words
*/
function decimalPartToWords(decimalPart) {
// Per-digit decimal reading
const digits = []
for (const char of decimalPart) {
const d = parseInt(char, 10)
digits.push(d === 0 ? ZERO : ONES[d])
}
return digits.join(' ')
}
/**
* Converts a numeric value to Hausa words.
* @param {number | string | bigint} value - The numeric value to convert
* @returns {string} The number in Hausa words
*/
function toCardinal(value) {
const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
checkMax(integerPart, cardinalMax)
let result = ''
if (isNegative) {
result = NEGATIVE + ' '
}
result += integerToWords(integerPart)
if (decimalPart) {
result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
}
return result
}
// ============================================================================
// ORDINAL: toOrdinal(value)
// ============================================================================
/**
* Converts a non-negative integer to Hausa ordinal words.
*
* Hausa ordinals: na farko (1st), na biyu (2nd), na uku (3rd), etc.
* @param {bigint} n - Positive integer to convert
* @returns {string} Hausa ordinal words
*/
function integerToOrdinal(n) {
// Special form for first
if (n === 1n) return ORDINAL_FIRST
// For 2+, use "na" prefix + cardinal
return ORDINAL_PREFIX + ' ' + integerToWords(n)
}
/**
* Converts a numeric value to Hausa 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) // 'na farko'
* toOrdinal(2) // 'na biyu'
* toOrdinal(10) // 'na goma'
*/
function toOrdinal(value) {
const integerPart = parseOrdinalValue(value)
checkMax(integerPart, ordinalMax)
return integerToOrdinal(integerPart)
}
// ============================================================================
// CURRENCY: toCurrency(value)
// ============================================================================
/**
* Converts a numeric value to Hausa currency words (Nigerian Naira).
*
* Uses naira and kobo (100 kobo = 1 naira).
* @param {number | string | bigint} value - The currency amount to convert
* @returns {string} The amount in Hausa 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) // 'arba'in da biyu naira'
* toCurrency(1.50) // 'ɗaya naira da hamsin kobo'
* toCurrency(-5) // 'babu biyar naira'
*/
function toCurrency(value) {
const { isNegative, dollars: naira, cents: kobo } = parseCurrencyValue(value)
checkMax(naira, currencyMax)
let result = ''
if (isNegative) {
result = NEGATIVE + ' '
}
// Naira part
if (naira > 0n || kobo === 0n) {
result += integerToWords(naira) + ' ' + NAIRA
}
// Kobo part
if (kobo > 0n) {
if (naira > 0n) {
result += ' da '
}
result += integerToWords(kobo) + ' ' + KOBO
}
return result
}
// ============================================================================
// Exports
// ============================================================================
export { toCardinal, toOrdinal, toCurrency }