# 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 ⅠⅤⅩⅬ"
```