toRoman — Interactive Playground

Quick Start

Import the library and start converting in seconds.

JavaScript

const roman = require("toRoman");

// Convert number → Roman
roman.toRoman(2025);   // "MMXXV"

// Convert Roman → number
roman.fromRoman("XLII"); // 42

// Validate a Roman numeral
roman.isRoman("XIV");  // true

// Arithmetic
roman.addRoman("X", "V"); // "XV"

toRoman()

Method

Converts an Arabic integer (1–3999) into its Roman numeral string representation.

toRoman(value: number): string

valuenumberInteger between 1 and 3999

▶ Try it

→

MMXXV

Example

roman.toRoman(765);  // "DCCLXV"
roman.toRoman(1994); // "MCMXCIV"
roman.toRoman(4);    // "IV"

fromRoman()

Method

Parses a Roman numeral string and returns its integer value.

fromRoman(value: string): number

valuestringA valid Roman numeral string

▶ Try it

→

2025

Example

roman.fromRoman("DCCLXV");  // 765
roman.fromRoman("MCMXCIV"); // 1994
roman.fromRoman("IV");      // 4

isRoman()

Method

Validates whether a given string is a correctly formed Roman numeral.

isRoman(value: string): boolean

▶ Try it

→

true

Example

roman.isRoman("XIV");    // true
roman.isRoman("IIII");  // false
roman.isRoman("hello"); // false

addRoman()

Method

Adds two Roman numeral strings and returns the result as a Roman numeral.

addRoman(a: string, b: string): string

▶ Try it

+

→

XV

Example

roman.addRoman("X", "V");    // "XV"
roman.addRoman("L", "XXX"); // "LXXX"

subtractRoman()

Method

Subtracts the second Roman numeral from the first.

subtractRoman(a: string, b: string): string

▶ Try it

−

→

XV

Example

roman.subtractRoman("XX", "V"); // "XV"
roman.subtractRoman("C", "L");  // "L"

multiplyRoman()

Method

Multiplies two Roman numerals and returns the Roman numeral result.

multiplyRoman(a: string, b: string): string

▶ Try it

×

→

XXX

Example

roman.multiplyRoman("X", "III"); // "XXX"
roman.multiplyRoman("V", "IV");  // "XX"

divideRoman()

Method

Divides the first Roman numeral by the second (integer division).

divideRoman(a: string, b: string): string

▶ Try it

÷

→

V

Example

roman.divideRoman("X", "II");  // "V"
roman.divideRoman("C", "IV");  // "XXV"

rangeRoman()

Method

Returns an array of Roman numerals within the given integer range.

rangeRoman(start: number, end: number): string[]

▶ Try it

to

I, II, III, IV, V, VI, VII, VIII, IX, X

Example

roman.rangeRoman(1, 5);
// ["I", "II", "III", "IV", "V"]

randomRoman()

Method

Generates a random Roman numeral between 1 and 3999.

randomRoman(): string

▶ Try it

→

—

Example

roman.randomRoman(); // e.g. "DCCCXLVII"

tableRoman()

Method

Generates a lookup table of Roman numerals up to a given limit.

tableRoman(limit: number): Record<number, string>

▶ Try it

limit:

Example

roman.tableRoman(5);
// { 1: "I", 2: "II", 3: "III", 4: "IV", 5: "V" }

Live Sandbox

Write any JavaScript using the roman object. Results appear instantly.

// Explore toRoman freely!
// The `roman` object is available globally.

const year = 2025;
const yearRoman = roman.toRoman(year);
console.log(`${year} in Roman numerals: ${yearRoman}`);

// Arithmetic
const sum = roman.addRoman("MCM", "LXXXV");
console.log("1900 + 85 =", sum);

// Range
const decade = roman.rangeRoman(1, 10);
console.log("First decade:", decade.join(", "));

// Validate
const tests = ["XIV", "IIII", "MCM", "VV"];
tests.forEach(t => {
  console.log(`isRoman("${t}") →`, roman.isRoman(t));
});

Press ▶ Run or Ctrl+Enter to execute

Coming in v2.1

What's Next

The library is actively evolving. Here's what's planned for the next major release.

⚡

Expression Parser

Evaluate Roman numeral expressions directly.

roman.evaluate("X + V * II")
// → "XX"

🏛

Immutable Roman Object

A chainable, immutable Roman numeral class.

const x = Roman("X");
x.add("V").toString(); // "XV"

⚛️

Framework Hooks

First-class React & Vue integration.

const { roman, error }
  = useRoman(input);
// React / Vue hook

💻

CLI Improvements

Powerful flags and piping support.

# Convert from Roman
toroman --from XLII
# Pipe input
echo 42 | toroman

🛡

Consistent Error Design

Custom error classes with uniform messages.

throw new RomanError(
  "Invalid numeral: IIII"
);

📊

Benchmarks

Performance comparisons with similar libraries.

// Benchmark suite
bench("toRoman", () => {
  roman.toRoman(3999);
});