Roman

A production-ready encoder/decoder for roman numerals, with detailed validation.

Installation

The package can be installed by adding roman to your list of dependencies in mix.exs:

def deps do
  [{:roman, "~> 0.2"}]
end

The docs can be found online at https://hexdocs.pm/roman.

Basic Usage

iex>Roman.numeral?("III")
true

iex> Roman.decode("MMMDCCCXCVIII")
{:ok, 3898}
iex> Roman.decode("ix", ignore_case: true)
{:ok, 9}
iex> Roman.decode!("XVI")
16
iex> Roman.decode("CMC", explain: true)
{:error, {:value_greater_than_subtraction, "once a value has been subtracted
  from another, no further numeral or pair may match or exceed the subtracted
  value, but encountered C (100) after having previously subtracted
  100 (in CM)"}}

iex> Roman.encode(16)
{:ok, "XVI"}
iex> Roman.encode!(16)
"XVI"

Alternative Forms

Roman can handle alternative forms and differentiate them. For example, by default decoding VXL will return an error (since 45 should be encoded as XLV). However, the :strict option can be set to false to accept decoding alternative forms:

iex> Roman.decode("VXL")
{:error, {:invalid_numeral, "numeral is invalid"}}

iex> Roman.decode("VXL", strict: false)
{:ok, 45}

Other libraries typically won’t differentiate between VXL and XLV, considering both equally valid. Composition rules are documented here.

Author

David Sulc

License

Roman is released under the MIT License. See the LICENSE file for further details.