feat: add Roman numeral conversion

[AliAlimohammadi]

Description

This PR adds comprehensive Roman numeral conversion functionality to the conversions module, supporting bidirectional conversion between integers and Roman numerals.

LeetCode Problem No. 13: Roman to Integer - This implementation solves the classic conversion problem with additional enhancements.

Implementation Details

The implementation provides two main functions:

1. roman_to_int(roman: &str) -> Result<u32, String>

   • Converts Roman numeral strings to integers
   • Handles subtractive notation (IV, IX, XL, XC, CD, CM)
   • Case-insensitive input
   • Validates all characters
   • Range: 1-3999

2. int_to_roman(number: u32) -> Result<String, String>

   • Converts integers to Roman numeral strings
   • Uses standard subtractive notation
   • Produces shortest representation
   • Range: 1-3999

Algorithm Details

Roman to Integer:

• Iterate through characters from left to right
• If current value < next value: subtract current from next (subtractive notation)
• Otherwise: add current value to total
• Time complexity: $O(n)$ where n is the length of the Roman numeral
• Space complexity: $O(1)$

Integer to Roman:

• Use greedy algorithm with value pairs in descending order
• For each value, append the Roman numeral as many times as it fits
• Time complexity: $O(1)$ - fixed 13 iterations maximum
• Space complexity: $O(1)$ - output string size bounded by input range

Key Features

1. Type Safety: Uses Result for proper error handling
2. Validation: Checks for invalid characters and out-of-range values
3. Case Insensitive: Accepts both uppercase and lowercase input
4. Comprehensive: Handles all standard Roman numeral rules
5. Well-Tested: 50+ test cases including roundtrip conversion
6. Standard Notation: Uses proper subtractive notation (IV not IIII)

Roman Numeral Rules

• I = 1, V = 5, X = 10, L = 50, C = 100, D = 500, M = 1000
• Subtractive pairs: IV (4), IX (9), XL (40), XC (90), CD (400), CM (900)
• Valid range: 1-3999
• Additive notation: VII = 7, XXX = 30, III = 3

Changes Made

• ✅ Added src/conversions/roman_numerals.rs with complete implementation
• ✅ Will update src/conversions/mod.rs to include and export the module
• ✅ Implemented comprehensive unit tests (50+ tests) covering:
  • Basic single-character conversions
  • Additive notation (II, III, VI, etc.)
  • Subtractive notation (IV, IX, XL, XC, CD, CM)
  • Complex combinations (CLIV, MCMXC, MMMCMXCIX)
  • Case-insensitive input
  • Invalid character detection
  • Empty string handling
  • Out-of-range value detection
  • Complete roundtrip conversion test (1-3999)
  • All examples from Python implementation
  • Edge cases (minimum, maximum, powers of 10)
• ✅ Added detailed documentation with examples for all public functions
• ✅ Included doctests demonstrating usage

Type of Change

• New conversion implementation
• Documentation (docstrings and examples)
• Tests (50+ comprehensive tests)

Testing

All tests pass successfully:

cargo test roman_numerals
cargo test --test conversions
cargo test --doc
cargo fmt --check
cargo clippy -- -D warnings

Test Coverage

✅ 50+ Unit Tests Including:

• Basic conversions (I, V, X, L, C, D, M)
• Additive notation (II, III, VI, VII, VIII, etc.)
• Subtractive notation (IV, IX, XL, XC, CD, CM)
• Complex numbers (CLIV = 154, MCMXC = 1990, etc.)
• All examples from Python version
• Case insensitivity
• Invalid input detection
• Empty string error handling
• Out-of-range detection (0, 4000+)
• Roundtrip conversion for all values 1-3999
• Edge cases (minimum 1, maximum 3999)
• Doctests for public API

Examples

use the_algorithms_rust::conversions::{roman_to_int, int_to_roman};

// Roman to Integer
assert_eq!(roman_to_int("III").unwrap(), 3);
assert_eq!(roman_to_int("CLIV").unwrap(), 154);
assert_eq!(roman_to_int("MIX").unwrap(), 1009);
assert_eq!(roman_to_int("MMMCMXCIX").unwrap(), 3999);

// Case insensitive
assert_eq!(roman_to_int("cliv").unwrap(), 154);

// Integer to Roman
assert_eq!(int_to_roman(3).unwrap(), "III");
assert_eq!(int_to_roman(154).unwrap(), "CLIV");
assert_eq!(int_to_roman(1009).unwrap(), "MIX");
assert_eq!(int_to_roman(3999).unwrap(), "MMMCMXCIX");

// Error handling
assert!(roman_to_int("INVALID").is_err());
assert!(roman_to_int("").is_err());
assert!(int_to_roman(0).is_err());
assert!(int_to_roman(4000).is_err());

// Roundtrip conversion
let num = 1990;
let roman = int_to_roman(num).unwrap();
let back = roman_to_int(&roman).unwrap();
assert_eq!(num, back);

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my implementation is correct
• New and existing unit tests pass locally with my changes
• I have checked my code with cargo fmt
• I have checked my code with cargo clippy
• Module is properly exported in mod.rs

Additional Context

• ✅ Type Safety: Uses Result type for error handling instead of assuming valid input
• ✅ Validation: Checks for invalid characters and range violations
• ✅ Case Insensitive: Automatically handles lowercase input
• ✅ Better Error Messages: Clear, descriptive error messages
• ✅ Idiomatic Rust: Uses iterators, pattern matching, and Rust conventions
• ✅ More Comprehensive Tests: 50+ tests including complete roundtrip validation
• ✅ Const Array: Uses const array for better performance
• ✅ Documentation: Full rustdoc with examples
• ✅ Helper Functions: Separated concerns with char_to_value helper

Algorithm Efficiency:

• Roman to Integer: $O(n)$ time, $O(1)$ space
• Integer to Roman: $O(1)$ time (max 13 iterations), $O(1)$ space
• Both algorithms are optimal for the problem

Historical Context:

• Roman numerals were used throughout the Roman Empire
• Standard form used today developed over centuries
• Still used in modern contexts (clocks, book chapters, movie sequels, etc.)

References

• Roman Numerals - Wikipedia
• LeetCode #12 - Integer to Roman
• LeetCode #13 - Roman to Integer

[AliAlimohammadi]

@siriak, this is ready to be merged.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.75281% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.84%. Comparing base (38024b0) to head (3b5b0cb).

Files with missing lines	Patch %	Lines
src/conversions/roman_numerals.rs	97.75%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #987      +/-   ##
==========================================
+ Coverage   95.83%   95.84%   +0.01%     
==========================================
  Files         356      357       +1     
  Lines       23745    23923     +178     
==========================================
+ Hits        22755    22928     +173     
- Misses        990      995       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[siriak]

Looks good, thanks!