Documentation/Calc Functions/ROMAN

Function name:
ROMAN

Category:
Text

Summary:
Converts a decimal number to its equivalent Roman numeral.

Syntax:
ROMAN(Number[; Mode])

Returns:
Returns an uppercase text string which is a Roman numeral that is equivalent to the specified decimal number.

Arguments:
Number is an integer value in the range 0 ≤ n ≤ 3999, or a reference to a cell containing that value, which is the decimal number to be converted.

Mode is an integer value in the range 0 ≤ m ≤ 4, or a reference to a cell containing that value, which controls the level of simplification or conciseness used in the conversion. The operation of this parameter is described further in the section below. If omitted, the default value of 0 is assumed.


 * If either Number or Mode is non-numeric, then ROMAN reports a #VALUE! error.
 * If either Number or Mode is a non-integer value, then ROMAN truncates it to an integer.
 * If, after any truncation, either Number or Mode is outside its specified range, ROMAN reports an invalid argument error (Err:502).
 * If, after any truncation, Number is equal to 0, then ROMAN returns the empty string for any valid value of Mode.

Additional details:
The following table lists the characters that are used to form Roman numerals and their associated values.

Wikipedia’s Roman numerals page includes general information about Roman numerals. This article describes a “standard form” for Roman numerals that includes a "subtractive notation", in which a number can be subtracted by placing a letter of lower value before one of higher value (for example, 4 is normally represented as IV). However, within the standard form, the only valid options for subtractive notation are IV (4), IX (9), XL (40), XC (90), CD (400), and CM (900). The key restrictions for subtractive notation in the standard form are therefore summarised as follows:


 * 1) Only I, X and C are used as the lower valued letters in subtractive notation; L and V are excluded.
 * 2) The lower valued letter in subtractive notation may only be 1/5th or 1/10th of the value of the higher valued letter. For example, IV and IX are allowed, but IL, IC, ID, and IM are not valid.

The standard notation is termed “classic” in ODF 1.2 and corresponds to a value of 0 for ROMAN’s Mode argument. Increasing values of Mode correspond to greater relaxation of the two restrictions above until when Mode is equal to 4, ROMAN will produce the fewest Roman digits possible – this is referred to as “simplified” in ODF 1.2. The following examples show how the Roman numeral for the value 999 changes depending on the value selected for Mode.
 * Mode = 0, ROMAN returns CMXCIX (900 + 90 + 9).
 * Mode = 1, ROMAN returns LMVLIV (950 + 45 + 4). Note that L and V are used within the subtractive notation for this example.
 * Mode = 2, ROMAN returns XMIX (990 + 9). Note that the ratio between the lower and higher valued letters in the subtractive notation has been relaxed for this example.
 * Mode = 3, ROMAN returns VMIV (995 + 4).
 * Mode = 4, ROMAN returns IM (999). The fewest characters possible.

The value 999 is an extreme example because the output is different for each possible value of Mode; there are other values for which the output does not change as Mode varies.

Related LibreOffice functions:
ARABIC

ODF standard:
Section 6.19.17, part 2

Equivalent Excel functions:
ROMAN