big-roman

Roman numerals parsing/serialisation package which supports the overbar extension for numbers 4,000 (MV̅) and above. Supports arbitrarily large integer floats and BigInts.

Example

import { numberToRoman, romanToNumber } from 'big-roman'

console.log(numberToRoman(Number.MAX_SAFE_INTEGER))
// 'M̅̅̅̅X̅̅̅̅̅V̅̅̅̅M̅̅̅M̅̅̅C̅̅̅X̅̅̅C̅̅̅M̅̅X̅̅̅C̅̅C̅̅L̅̅M̅V̅̅D̅C̅C̅X̅L̅CMXCI'

console.log(romanToNumber('M̅̅̅̅X̅̅̅̅̅V̅̅̅̅M̅̅̅M̅̅̅C̅̅̅X̅̅̅C̅̅̅M̅̅X̅̅̅C̅̅C̅̅L̅̅M̅V̅̅D̅C̅C̅X̅L̅CMXCI'))
// 9007199254740991

Installation

npm install big-roman

API

Conversions to Roman numerals

numberToRoman(number)

Accepts a number e.g. 123456 and returns a string containing the appropriate Roman numeral, in this case 'C̅X̅X̅MMMCDLVI'. Numbers must be positive integers or an exception will be thrown. Other than that, numbers may be arbitrarily large, up to and including Number.MAX_VALUE, and correct Roman numerals will be returned. Note that the Roman numeral representation will not be truncated after around 15 "digits" of precision, you'll get the whole thing.

arabicToRoman(string)

Accepts a string containing a decimal Arabic numeral e.g. '123456' and returns a string containing the appropriate Roman numeral, in this case 'C̅X̅X̅MMMCDLVI'. Leading zeroes are okay. Decimal points, exponents and other non-digit characters will cause an exception to be thrown. Other than that, the input Arabic numeral may be arbitrarily large e.g. '1' + '0'.repeat(2000).

bigIntToRoman(bigInt)

Accepts a BigInt e.g. 123456n and returns a string containing the appropriate Roman numeral, in this case 'C̅X̅X̅MMMCDLVI'. BigInts must be positive or an exception will be thrown.

Conversions from Roman numerals

For all of these methods, if the input is not a syntactically correct Roman numeral, an exception will be thrown. Fun fact: Roman numerals using the overbar extension cannot be described using a context-free grammar.

romanToNumber(string)

Accepts a string containing a Roman numeral e.g. 'C̅X̅X̅MMMCDLVI' and returns the nearest available number, in this case 123456. If the input describes a number which is too large then the returned value will be Infinity.

romanToArabic(string)

Accepts a string containing a Roman numeral e.g. 'C̅X̅X̅MMMCDLVI' and returns a string containing the appropriate Arabic numeral, in this case '123456'. As long as the input is well-formed, you will get a meaningful output containing the full decimal expansion, even if you use arbitrary numbers of overbars e.g. 'C' + '\u0305'.repeat(666).

romanToBigInt(string)

Accepts a string containing a Roman numeral e.g. 'C̅X̅X̅MMMCDLVI' and return the appropriate BigInt, in this case 123456n.

Roman numerals beyond 3,999

Ordinarily, to express an Arabic digit 4 in a Roman numeral, we take the Roman "digit" for 1 and the Roman "digit" for 5 and put them next to one another, expressing a subtraction. The Roman digit varies by place.

• In the 1s place, 1 is I and 5 is V, so 4 is IV.
• In the 10s place, 1 is X and 5 is L, so 4 is XL.
• In the 100s place, 1 is C and 5 is D, so 4 is CD.
• In the 1,000s place, 1 is M... but there is normally no way to express 5 in the 1,000s place, or any higher number, so 4 cannot be expressed either.

This means it's impossible to express the number 4,000 or any higher number using a Roman numeral. The largest number expressible as a Roman numeral is 3,999 = MMMCMXCIX.

The overbar extension introduces the overbar or vinculum, U+0305 COMBINING OVERLINE (in HTML or Markdown, this can be written as ̅; as a JavaScript string, write '\u0305'). The overbar means "multiply by 1,000". And the pattern continues as follows:

• In the 1,000s place, 1 is M and 5 is V̅, so 4 is MV̅.
• In the 10,000s place, 1 is X̅ and 5 is L̅, so 4 is X̅L̅.
• In the 100,000s place, 1 is C̅ and 5 is D̅, so 4 is C̅D̅.
• In the 1,000,000s place, 1 is M̅ and 5 is V̅̅, so 4 is M̅V̅̅.
• And so on...

Two overbars mean "multiply by 1,000,000". Three overbars mean "multiply by 1,000,000,000", and so on. This allows us to express arbitrary positive integers using Roman numerals.

There is a slight inconsistency in that we use M to indicate 1,000 when we could have saved ourselves a letter and used I̅ instead, and similarly M̅ instead of I̅̅ and so on. However, this maintains backwards compatibility with the universal practice for smaller Roman numerals.

There are various other ways to extend Roman numerals to large numbers.