Convert Roman and Arabic Numbers with Numeri Romani

The Numeri Romani TypeScript/JavaScript library offers a suite of modules for handling Roman & Arabic numerals.

It enables developers to convert Roman numbers to Arabic and vice versa, check if a given Roman or Arabic number is valid, and even perform basic mathematical operations, such as addition, subtraction, multiplication, and division.

How to use it:

1. Istall & download the  Numeri Romani using your preferred package manager:

# Yarn
$ yarn add @dunkelhaiser/numeri-romani
# NPM
$ npm install @dunkelhaiser/numeri-romani
# PNPM
$ pnpm install @dunkelhaiser/numeri-romani
# BUN
$ bun add @dunkelhaiser/numeri-romani

2. Import the necessary modules based on your project setup (ESM or CommonJS):

// ESM
import {
  RomanNumber,
  romanNumerals,
  romanize,
  romanizeSafe,
  arabicize,
  arabicizeSafe,
  isValidRoman,
  isValidRomanSafe,
  isValidArabic,
  isValidArabicSafe,
} from '@dunkelhaiser/numeri-romani';

// CommonJS
const {
  RomanNumber,
  romanNumerals,
  romanize,
  romanizeSafe,
  arabicize,
  arabicizeSafe,
  isValidRoman,
  isValidRomanSafe,
  isValidArabic,
  isValidArabicSafe,
} = require("@dunkelhaiser/numeri-romani");

3. Convert between Roman and Arabic numbers:

// => DLXVII
romanize(567);
// => 1234
arabicize('MCCXXXIV');

4. If you prefer not to handle errors, you can use the safe implementations:

// => DLXVII
romanizeSafe(567);
// => 1234
arabicizeSafe('MCCXXXIV');

5. Ensure the correctness of Roman numerals with isValidRoman (or its safe counterpart isValidRomanSafe) and Arabic numbers with isValidArabic (or isValidArabicSafe).

// => true
isValidRoman("DLXVII"); 
// => Error
isValidRoman("IIV"); 
// => true
isValidRomanSafe("DLXVII"); 
// => false
isValidRomanSafe("IIV");

// => true
isValidArabic("LIV"); 
// => Error
isValidArabic(1.5);
isValidArabic(0);
isValidArabic(-1); 
isValidArabic(-1234); 
// => true
isValidArabicSafe(11); 
// => false
isValidArabicSafe(1.5); 
// => false
isValidArabicSafe("11");

6. The RomanNumber class allows you to create objects that encapsulate both Roman numeral representations and their corresponding Arabic values. This class provides convenient methods to access these values, update them, and perform basic arithmetic operations like addition, subtraction, multiplication, and division. These operations can be chained together for a concise and readable coding style.

// => { roman: "MCCXXXIV", arabic: 1234 }
const romanNumber = new RomanNumber(7);
// => { roman: "MCCXXXIV", arabic: 1234 }
const romanNumber = new RomanNumber("MCCXXXIV");
// => "MCCXXXIV"
romanNumber.getValue();
// => 1234
romanNumber.getNumericValue();
// => { roman: "MCCXXXIV", arabic: 1234 }
romanNumber.getValues();
// Set value
romanNumber.setValue(1234);
romanNumber.setValue("MCCXXXIV");
// Addition
romanNumber.add(3).add("VI");
// Subtraction
romanNumber.substract(1).subtract("III");
// Multiplication
romanNumber.multiply(4).multiply("VI");
// Division
romanNumber.divide(6).divide("III");