Humanizer.RomanNumeralExtensions.md

RomanNumeralExtensions Class

Contains extension methods for changing a number to Roman representation (ToRoman) and from Roman representation back to the number (FromRoman)

public static class RomanNumeralExtensions

Inheritance System.Object → RomanNumeralExtensions

Methods

RomanNumeralExtensions.FromRoman(ReadOnlySpan<char>) Method

Converts a Roman numeral character span to its integer representation.

public static int FromRoman(System.ReadOnlySpan<char> input);

Parameters

input System.ReadOnlySpan<System.Char>

The Roman numeral character span to convert. Must not be empty.

Returns

System.Int32
The integer value represented by the Roman numeral.

Exceptions

System.ArgumentException
Thrown when input is empty (after trimming) or contains an invalid Roman numeral format.

Example

"XIV".AsSpan().FromRoman() => 14
"MCMXC".AsSpan().FromRoman() => 1990

Remarks

This is a memory-efficient overload that works with character spans to avoid string allocations. Valid Roman numerals use the characters M, D, C, L, X, V, and I (case-insensitive). Supports subtractive notation (e.g., IV = 4, IX = 9).

RomanNumeralExtensions.FromRoman(this string) Method

Converts a Roman numeral string to its integer representation.

public static int FromRoman(this string input);

Parameters

input System.String

The Roman numeral string to convert (e.g., "XIV", "MCMXC"). Must not be null.

Returns

System.Int32
The integer value represented by the Roman numeral.

Exceptions

System.ArgumentNullException
Thrown when input is null.

System.ArgumentException
Thrown when input is empty or contains an invalid Roman numeral format.

Example

"XIV".FromRoman() => 14
"MCMXC".FromRoman() => 1990
"IV".FromRoman() => 4
"MMXXIII".FromRoman() => 2023

Remarks

Valid Roman numerals use the characters M, D, C, L, X, V, and I (case-insensitive). Supports subtractive notation (e.g., IV = 4, IX = 9, XL = 40, XC = 90, CD = 400, CM = 900). Valid range is 1 to 3999.

RomanNumeralExtensions.ToRoman(this int) Method

Converts an integer to its Roman numeral representation.

public static string ToRoman(this int input);

Parameters

input System.Int32

The integer value to convert. Must be between 1 and 3999 inclusive.

Returns

System.String
A string containing the Roman numeral representation of the input value.

Exceptions

System.ArgumentOutOfRangeException
Thrown when input is less than 1 or greater than 3999. Roman numerals are traditionally limited to this range.

Example

14.ToRoman() => "XIV"
1990.ToRoman() => "MCMXC"
4.ToRoman() => "IV"
2023.ToRoman() => "MMXXIII"
3999.ToRoman() => "MMMCMXCIX"

Remarks

Uses standard Roman numeral notation including subtractive notation for 4, 9, 40, 90, 400, and 900. The implementation is optimized for performance and avoids string allocations where possible.