# IVXL

[![License][1]][2] [![npm][3]][4] [![TypeScript][5]][6]

> convert integers to roman numerals and vice versa

[1]: https://img.shields.io/badge/License-0BSD-orange.svg
[2]: https://opensource.org/license/0bsd
[3]: https://img.shields.io/npm/v/ivxl.svg
[4]: https://www.npmjs.com/package/ivxl
[5]: https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg
[6]: https://www.typescriptlang.org/

## Usage

Integers from `1` to `4999` and their Roman Numeral ASCII string representation
are supported.

```typescript
import { roman } from "ivxl"

roman("IX") // -> 9
roman(420) // -> "CDXX"
roman("CDXX") // -> 420
roman(4999) // -> "MMMMCMXCIX"
roman("MMMMCMXCIX") // -> 4999

roman("4Twenty") // -> ""
roman(42.2) // -> ""
roman(0) // -> ""
roman(5000) // -> ""
roman("IVXL") // -> ""
```

## Install

```sh
pnpm add ivxl

# or with bun
bun add ivxl
```

## API

### roman

```txt
roman :: (number | string) -> (number | string)
```

Given a valid ASCII Roman Numeral string, returns an integer between `1` and
`4999`. Given a valid integer between `1` and `4999`, returns an ASCII Roman
Numeral string. Given an invalid input returns an empty string.

```typescript
import { roman } from "ivxl"

roman("XIV") // -> 14
roman(14) // -> "XIV"
roman(14).toLowerCase() // -> "xiv"
roman("42") // -> "XLII"
roman("666") // -> "DCLXVI"
roman(-99) // -> ""
```

### numberToRoman

```txt
numberToRoman :: number -> string
```

Given an integer between `1` and `4999`, returns an ASCII Roman Numeral string.
Everything else returns an empty string. The input type is more strict than the
`roman` funtion's types.

```typescript
import { numberToRoman } from "ivxl"

numberToRoman(42) // -> "XLII"
numberToRoman(-42) // -> ""
numberToRoman("42") // -> ""
numberToRoman(42.2) // -> ""
```

### romanToNumber

```txt
romanToNumber :: string -> number
```

Given a valid ASCII Roman Numeral string, returns an integer between `1` and
`4999`. Everything else returns `0`.

```typescript
import { romanToNumber } from "ivxl"

romanToNumber("XXVI") // -> 26
romanToNumber("xxvi") // -> 26
romanToNumber("IVXL") // -> 0
```

### romanToUnicode

```txt
romanToUnicode :: string -> string
```

Given an ASCII string, returns a string with the Roman Numeral characters
replaced by their Unicode counterparts. No validity checks are performed.

```txt
I -> Ⅰ
V -> Ⅴ
X -> Ⅹ
L -> Ⅼ
C -> Ⅽ
D -> Ⅾ
M -> Ⅿ
```

```typescript
import { romanToUnicode } from "ivxl"

romanToUnicode("XXVI") // -> "ⅩⅩⅤⅠ"
romanToUnicode("xxvi") // -> "ⅩⅩⅤⅠ"
romanToUnicode("IVXL") // -> "ⅠⅤⅩⅬ"
romanToUnicode("0U812 IVXL") // -> "0U812 ⅠⅤⅩⅬ"
```
