n2words
Version:
Convert numbers to words in 70+ languages with zero dependencies. Supports BigInt, decimals, and browser/Node.js environments.
110 lines (109 loc) • 4.42 kB
TypeScript
/**
* Spanish (United States) language converter
*
* CLDR: es-US | Spanish as used in the United States
*
* Uses the short scale numbering system (like US English):
* - 10⁶ = millón
* - 10⁹ = billón (billion)
* - 10¹² = trillón (trillion)
*
* Spanish-specific rules:
* - Gender agreement: uno/una, veintiuno/veintiuna, hundreds
* - Special twenties: veinte, veintiuno, veintidós, ... veintinueve
* - "y" conjunction: treinta y uno (only 30-99 with ones)
* - "cien" for exact 100, "ciento/cienta" otherwise
* - Irregular hundreds: quinientos, setecientos, novecientos
* - "un" before millón (not "uno"), omit before mil
*/
export declare const cardinalMax: bigint;
export declare const ordinalMax: bigint;
export declare const currencyMax: bigint;
export type CardinalOptions = {
/**
* - Grammatical gender
*/
gender?: ('masculine' | 'feminine');
};
/**
* @typedef {object} CardinalOptions
* @property {('masculine'|'feminine')} [gender] - Grammatical gender
*/
/** @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 Spanish words (US short scale).
* @param {number | string | bigint} value - The numeric value to convert
* @param {CardinalOptions} [options] - Optional configuration
* @returns {string} The number in Spanish words
* @throws {TypeError} If value is not a valid numeric type
* @throws {Error} If value is not a valid number format
* @example
* toCardinal(21) // 'veintiuno'
* toCardinal(21, {gender: 'feminine'}) // 'veintiuna'
* toCardinal(1000000000) // 'un billón'
*/
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 Spanish ordinal words.
* @param {number | string | bigint} value - The positive integer to convert
* @param {OrdinalOptions} [options] - Optional configuration
* @returns {string} The number in Spanish ordinal words
* @throws {TypeError} If value is not a valid numeric type
* @throws {Error} If value is not a positive integer
* @example
* toOrdinal(1) // 'primero'
* toOrdinal(1, { gender: 'feminine' }) // 'primera'
* toOrdinal(21) // 'vigésimo primero'
*/
declare function toOrdinal(value: number | string | bigint, options?: OrdinalOptions): string;
export type CurrencyOptions = {
/**
* - Use "con" between dollars and cents
*/
and?: boolean;
};
/**
* @typedef {object} CurrencyOptions
* @property {boolean} [and] - Use "con" between dollars and cents
*/
/** @type {Required<CurrencyOptions>} */
export declare const currencyDefaults: Required<CurrencyOptions>;
/**
* Converts a numeric value to US Dollar currency words in Spanish.
*
* US Dollar uses masculine gender for dólares (el dólar)
* and masculine for centavos (el centavo).
* @param {number | string | bigint} value - The currency amount to convert
* @param {CurrencyOptions} [options] - Optional configuration
* @returns {string} The amount in Spanish US Dollar 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) // 'cuarenta y dos dólares con cincuenta centavos'
* toCurrency(1) // 'un dólar'
* toCurrency(0.99) // 'noventa y nueve centavos'
* toCurrency(42.50, { and: false }) // 'cuarenta y dos dólares cincuenta centavos'
*/
declare function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;
export { toCardinal, toOrdinal, toCurrency };