n2words/src/ar-SA.d.ts

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

/**
 * Arabic (Saudi Arabia) language converter
 *
 * CLDR: ar-SA | Modern Standard Arabic as used in Saudi Arabia
 *
 * Self-contained converter with gender agreement and complex pluralization.
 *
 * Key features:
 * - Gender agreement (masculine/feminine forms)
 * - Complex pluralization (singular/dual/plural)
 * - Traditional Arabic number naming conventions
 * - "و" (and) conjunction between segments
 */
export declare const cardinalMax: bigint;
export declare const ordinalMax: bigint;
export declare const currencyMax: bigint;
export type CardinalOptions = {
    /**
     * - Grammatical gender
     */
    gender?: ('masculine' | 'feminine');
    /**
     * - Custom word for negative numbers
     */
    negativeWord?: string;
};
/**
 * @typedef {object} CardinalOptions
 * @property {('masculine'|'feminine')} [gender] - Grammatical gender
 * @property {string} [negativeWord] - Custom word for negative numbers
 */
/** @type {Required<CardinalOptions>} */
export declare const cardinalDefaults: Required<CardinalOptions>;
/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
export declare const cardinalValues: {
    gender: ReadonlyArray<Required<CardinalOptions>['gender']>;
};
/**
 * Converts a numeric value to Arabic words.
 * @param {number | string | bigint} value - The numeric value to convert
 * @param {CardinalOptions} [options] - Optional configuration
 * @returns {string} The number in Arabic words
 * @example
 * toCardinal(1)                        // 'واحد'
 * toCardinal(1, {gender: 'feminine'})  // 'واحدة'
 */
declare function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
export type OrdinalOptions = {
    /**
     * - Grammatical gender
     */
    gender?: ('masculine' | 'feminine');
};
/**
 * @typedef {object} OrdinalOptions
 * @property {('masculine'|'feminine')} [gender] - Grammatical gender
 */
/** @type {Required<OrdinalOptions>} */
export declare const ordinalDefaults: Required<OrdinalOptions>;
/** @type {{ gender: ReadonlyArray<Required<OrdinalOptions>['gender']> }} */
export declare const ordinalValues: {
    gender: ReadonlyArray<Required<OrdinalOptions>['gender']>;
};
/**
 * Converts a numeric value to Arabic ordinal words.
 * @param {number | string | bigint} value - The numeric value to convert (positive integer)
 * @param {OrdinalOptions} [options] - Optional configuration
 * @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(1, {gender: 'feminine'})  // 'الأولى'
 * toOrdinal(3)                        // 'الثالث'
 */
declare function toOrdinal(value: number | string | bigint, options?: OrdinalOptions): string;
/**
 * Converts a numeric value to Arabic currency words (Saudi Riyal).
 * @param {number | string | bigint} value - The currency amount to convert
 * @returns {string} The amount in Arabic 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)   // 'هللة واحدة'
 */
declare function toCurrency(value: number | string | bigint): string;
export { toCardinal, toOrdinal, toCurrency };