n2words
Version:
Convert numbers to words in 70+ languages with zero dependencies. Supports BigInt, decimals, and browser/Node.js environments.
92 lines (91 loc) • 3.71 kB
TypeScript
/**
* French (France) language converter
*
* CLDR: fr-FR | French as used in France
*
* French-specific rules:
* - Vigesimal patterns: 70 = soixante-dix, 80 = quatre-vingts, 90 = quatre-vingt-dix
* - "et" conjunction: vingt et un (21), soixante et onze (71), but NOT quatre-vingt-un
* - Pluralization: "cents" loses 's' when followed by more digits
* - Long scale with -ard forms: milliard, billiard, trilliard
* - Omit "un" before mille
*/
export declare const cardinalMax: bigint;
export declare const ordinalMax: bigint;
export declare const currencyMax: bigint;
export type CardinalOptions = {
/**
* - Use hyphens between all words
*/
withHyphenSeparator?: boolean;
};
/**
* @typedef {object} CardinalOptions
* @property {boolean} [withHyphenSeparator] - Use hyphens between all words
*/
/** @type {Required<CardinalOptions>} */
export declare const cardinalDefaults: Required<CardinalOptions>;
/**
* Converts a numeric value to French 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 {CardinalOptions} [options] - Optional configuration
* @returns {string} The number in French words
* @throws {TypeError} If value is not a valid numeric type
* @throws {Error} If value is not a valid number format
* @example
* toCardinal(21) // 'vingt et un'
* toCardinal(80) // 'quatre-vingts'
* toCardinal(1000000) // 'un million'
*/
declare function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
/**
* Converts a numeric value to French ordinal words.
*
* French ordinals: premier (1st), then cardinal + ième.
* Special rules: quatre→quatrième, cinq→cinquième, neuf→neuvième.
* @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) // 'premier'
* toOrdinal(2) // 'deuxième'
* toOrdinal(4) // 'quatrième'
* toOrdinal(5) // 'cinquième'
* toOrdinal(9) // 'neuvième'
* toOrdinal(21) // 'vingt et unième'
* toOrdinal(100) // 'centième'
* toOrdinal(1000) // 'millième'
*/
declare function toOrdinal(value: number | string | bigint): string;
export type CurrencyOptions = {
/**
* - Use "et" between euros and centimes
*/
and?: boolean;
};
/**
* @typedef {object} CurrencyOptions
* @property {boolean} [and] - Use "et" between euros and centimes
*/
/** @type {Required<CurrencyOptions>} */
export declare const currencyDefaults: Required<CurrencyOptions>;
/**
* Converts a numeric value to French currency words (Euro).
* @param {number | string | bigint} value - The currency amount to convert
* @param {CurrencyOptions} [options] - Optional configuration
* @returns {string} The amount in French 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) // 'quarante-deux euros et cinquante centimes'
* toCurrency(1) // 'un euro'
* toCurrency(0.99) // 'quatre-vingt-dix-neuf centimes'
* toCurrency(0.01) // 'un centime'
* toCurrency(42.50, { and: false }) // 'quarante-deux euros cinquante centimes'
*/
declare function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;
export { toCardinal, toOrdinal, toCurrency };