#roman #numeral #xvii #seventeen


Library for parsing or printing Roman numerals

12 releases

0.4.1 Oct 12, 2020
0.3.4 Aug 16, 2018
0.3.3 May 11, 2018
0.2.3 Feb 12, 2018
0.1.1 Mar 15, 2017

#21 in Value formatting

Download history 2/week @ 2020-12-22 3/week @ 2020-12-29 48/week @ 2021-01-05 4/week @ 2021-01-12 20/week @ 2021-01-19 4/week @ 2021-01-26 3/week @ 2021-02-02 39/week @ 2021-02-09 45/week @ 2021-02-16 8/week @ 2021-02-23 5/week @ 2021-03-02 8/week @ 2021-03-09 3/week @ 2021-03-16 50/week @ 2021-03-23 41/week @ 2021-03-30 17/week @ 2021-04-06

66 downloads per month
Used in ruswords


367 lines


Crates.io documentation (docs.rs) Build Status

...Pronounced any way you like, including "seventeen."

This library provides parsing and formatting for Roman numerals. According to my (probably extremely suspect) benchmarks, this is the best-performing library of its kind available on crates.io (you know, as of St. Patrick's Day, 2017 when I did the tests), so you should definitely employ it in your high-availability NAAS (numerals-as-a-service) project.

(Seriously, though, read the license--no warranties implied!)

Also, if you have a high-availability NAAS project, you need to have your head examined. I don't know if that was clear when I originally wrote this readme, so I'm adding it now.



Parsing is provided through Rust's ordinary FromStr trait, meaning you can create Roman values same as you create any other number--albeit with slightly simpler error cases, since the only possible errors are "Hey, that letter can't go in there," or "Dude, they go from 1 to 4999 and that's it!"

let seventeen: Roman = "XVII".parse().unwrap();


There are several formatting options. Roman implements Display, which means that it'll work fine with println!("{}") et al., but for maximum efficiency (stop laughing!) I also provide two other functions: to_lowercase() and to_uppercase(). These skip the Display piping and just go straight into a new string.

Regarding formatting, there is one gotcha regarding the formatting of Roman values created via Roman::new_unchecked(): values that are larger than 4999 will simply look like MMMMMMMMMMMMMMMXIV or something like that.


  • v0.4.1 Upgrade to rust edition 2018, support for no-std usage (thanks to WaffleLapkin!), plenty of cleanup (also thanks to him, really).
  • v0.2.2 Upgrade parsing to use some kind of whacky state machine in order to permit numbers up to the commonly accepted ceiling of 4999, or MMMMCMXCIX, thereby avoiding a potential Y4K bug. Your thousand year reich is now safe with me.


Licensed under either of

at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

No runtime deps


  • std