[−][src]Module numerals::roman

This is a library for converting between computer integers, Roman numerals, and ASCII strings.

Operations are done by converting your input into a Roman value, then calling functions on it. For example:

use numerals::roman::Roman;

let string = format!("{:X}", Roman::from(134));
assert_eq!(string, "CXXXIV");

Converting numbers to Roman

The From function in std::convert can turn either an i16, or a vector of Numeral values, into a Roman value.

use numerals::roman::{Roman, Numeral::{I, V, X}};

let input    = Roman::from(27);
let expected = Roman::from(vec![ X, X, V, I, I ]);
assert_eq!(expected, input);

Converting Roman to numbers

The value function translates a sequence of numerals into their computer value equivalent.

use numerals::roman::{Roman, Numeral::{I, V, X}};

let input = Roman::from(vec![ X, X, V, I, I ]).value();
assert_eq!(27, input);

Converting strings to Roman

You can translate an existing sequence of characters with the parse constructor, which scans an input string, returning None if it encounters a character with no Roman meaning.

It accepts both uppercase and lowercase ASCII characters.

use numerals::roman::{Roman, Numeral::{I, V, X}};

let input    = Roman::parse("XXVII").unwrap();
let expected = Roman::from(vec![ X, X, V, I, I ]);
assert_eq!(expected, input);

Converting Roman to strings

There are two ways to convert numerals into strings:

For uppercase, use the UpperHex trait with the {:X} format string.
For lowercase, use the LowerHex trait with the {:x} format string.

use numerals::roman::{Roman, Numeral::{I, V, X}};

let input = format!("{:X}", Roman::from(vec![ X, X, V, I, I ]));
assert_eq!("XXVII", input);

Limitations

The Roman::from(i16) function will panic when given zero or a negative number! The Romans had the concept of zero, but no numeral for it, so it’s not relevant here. Be sure to check your input values.
Similarly, there is no common way to handle numbers in the tens of thousands, which is why this library uses i16-sized integers. Numbers in the tens of thousands will work, but will be prefixed with many, many Ms.

Structs

Roman

A sequence of Roman numerals.

Enums

Numeral

An individual Roman numeral, without a position.