Text.Numeral.Roman

Parsing and pretty printing of Roman numerals.

This module provides functions for parsing and pretty printing Roman numerals. Because the notation of Roman numerals has varied through the centuries this package allows for some customisation using a configuration that is passed to the conversion functions. Exceptions are dealt with by wrapping the results of conversions in the error monad.

Example:

  > toRoman 1729 ∷ Either String String
  Right "MDCCXXIX"

  > fromRoman "MDCCXXIX" ∷ Either String Integer
  Right 1729

  > convertTo simpleRoman 1729 ∷ Either String String
  Right "MDCCXXVIIII"

  > fromRoman "Bla" ∷ Either String Integer
  Left "Roman.convertFrom: can't parse"

Types

data NumeralConfig s n

A configuration with which the convertTo and convertFrom functions can be parameterized.

Constructors

NC

Fields

ncMax :: n

The largest value that can be represented using this configuration.

ncZero :: Maybe s

Symbol to represent the value 0. The Romans did not have a symbol for zero. If set to Nothing a convertFrom 0 will throw an error.

ncTable :: [(s, n)]

A table of symbols and their numerical values. The table must be ordered in descending order of the value of the symbols. If any symbol is the empty string then convertFrom will be ⊥. If any symbol in this table is associated with the value 0 both the convertTo and convertFrom function will be ⊥.

Standard configurations

modernRoman :: (IsString s, Ord n, Num n) => NumeralConfig s n

Configuration for Roman numerals as they are commonly used today. The value 0 is represented by the empty string. It can be interpreted as not writing down a number. This configuration is limited to the range [1..3999]. Larger numbers can be represented using Roman numerals but you will need notations that are hard or impossible to express using strings.

simpleRoman :: (IsString s, Ord n, Num n) => NumeralConfig s n

Configuration for Roman numerals that do not use the rule that a lower rank symbol can be placed before a higher rank symbol to denote the difference between them. Thus a numeral like "IV" will not be accepted or generated by this configuration.

Pretty printing

convertTo :: (Monoid s, Ord n, Num n, MonadError String m) => NumeralConfig s n -> n -> m s

Converts a number to a Roman numeral according to the given configuration. Numbers which are out of bounds will cause exceptions to be thrown. An exception will also be raised if no representation is possible with the given configuration. If the value of any symbol in the configuration is equal to 0 or a symbol is the empty string this function is undefined.

unsafeConvertTo :: (Monoid s, Ord n, Num n) => NumeralConfig s n -> n -> s

Like convertTo, but exceptions are promoted to errors.

toRoman :: (IsString s, Monoid s, Ord n, Num n, MonadError String m) => n -> m s

Converts a number to a modern Roman numeral. See convertTo for possible exceptions.

unsafeToRoman :: (IsString s, Monoid s, Ord n, Num n) => n -> s

Like toRoman, but exceptions are promoted to errors.

Parsing

class StripPrefix s where

Class used to overload the input of the parsing functions.

Methods

null :: s -> Bool

stripPrefix :: s -> s -> Maybe s

Instances

StripPrefix ByteString

Eq α => StripPrefix [α]

convertFrom :: (Monoid s, StripPrefix s, Eq s, Ord n, Num n, MonadError String m) => NumeralConfig s n -> s -> m n

Parses a string as a Roman numeral according to the given configuration. An exception will be raised if the input is not a valid numeral.

fromRoman :: (IsString s, Monoid s, StripPrefix s, Eq s, Ord n, Num n, MonadError String m) => s -> m n

Parses a string as a modern Roman numeral. See convertFrom for possible exceptions.

unsafeConvertFrom :: (Monoid s, StripPrefix s, Eq s, Ord n, Num n) => NumeralConfig s n -> s -> n

Like convertFrom, but exceptions are promoted to errors.

unsafeFromRoman :: (IsString s, Monoid s, StripPrefix s, Eq s, Ord n, Num n) => s -> n

Like fromRoman, but exceptions are promoted to errors.