diff --git a/README.md b/README.md index 754872e..16a4a1d 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,20 @@ # toroman -[![wakatime](https://wakatime.com/badge/github/Zubs/toRoman.svg)](https://wakatime.com/badge/github/Zubs/toRoman) - A minimalist library for Roman numeral operations. ## ๐Ÿš€ Features -- Convert Arabic numerals to Roman numerals โ…ฆ -- Convert Roman numerals to Arabic numerals ๐Ÿ”ข +- Convert ๐Ÿ” Arabic numerals ๐Ÿ”ข to Roman numerals +- Convert ๐Ÿ” Roman numerals to Arabic numerals ๐Ÿ”ข - Validate Roman numerals โœ… - Add Roman numerals โž• - Subtract Roman numerals โž– +- Multiply Roman numerals โœ–๏ธ +- Divide Roman numerals โž— +- Get maximum Roman numeral โฌ†๏ธ +- Get minimum Roman numeral โฌ‡๏ธ +- Get a random Roman numeral ๐Ÿคน +- Generate a table of Roman numerals ๐Ÿ“‹ - Get Roman numerals within a range ๐Ÿ“ก ## ๐Ÿ“ฆ Installation @@ -27,17 +31,18 @@ npm i toroman const roman = require("toRoman"); ``` - +## ๐Ÿ”ฉ Methods -#### ๐Ÿ”„ Convert integer to Roman numerals: `toRoman` +### ๐Ÿ”„ Convert integer to Roman numerals: `toRoman` -```js +```ts /** - * toRoman - Convert an integer to Roman numerals + * Convert an integer to Roman numerals * @param { number } value Integer to be converted to Roman numerals * @returns { string } Roman numeral representation of the input value + * @throws { Error } When the input is not a valid integer or is out of range */ -function toRoman(value: number): string | Error {} +function toRoman(value: number): string {} ``` ๐Ÿ”ต Example @@ -48,15 +53,16 @@ console.log(roman.toRoman(765)); // Returns DCCLXV ``` -#### ๐Ÿ” Convert Roman numeral to integer: `fromRoman` +### ๐Ÿ” Convert Roman numeral to integer: `fromRoman` -```js +```ts /** - * fromRoman - Convert Roman numeral to integer + * Convert Roman numeral to integer * @param { string } value Roman numeral to be converted to integer * @returns { number } Integer representation of the input value + * @throws { Error } When the input is not a valid Roman numeral */ -export function fromRoman(value: string): number | Error {} +function fromRoman(value: string): number {} ``` ๐Ÿ”ต Example @@ -67,15 +73,16 @@ console.log(roman.fromRoman("DCCLXV")); // Returns 765 ``` -#### ๐Ÿ” Confirm if string is valid Roman numeral: `isRoman` +### ๐Ÿ” Confirm if string is valid Roman numeral: `isRoman` -```js +```ts /** - * isRoman - Confirm that string is a valid Roman numeral + * Confirm that string is a valid roman numeral * @param { string } value String to be tested * @returns { boolean } true or false + * @throws { Error } When the input is not a valid roman numeral */ -export function isRoman(value: string): true | Error {} +function isRoman(value: string): true {} ``` ๐Ÿ”ต Example @@ -86,17 +93,17 @@ console.log(roman.isRoman("MMMCCXXXIV")); // Returns true ``` -#### โž• Sum Roman numerals and get output as Roman numeral or numbers: `sum` +### โž• Sum Roman numerals and get output as a Roman numeral or numbers: `sum` -```js +```ts /** - * @param args Roman numerals to be added - * @returns { string } Final Roman numeral + * Sum roman numerals + * @param expected { string } Expected response type + * @param args { string[] } Roman numerals to be added + * @returns { string | number } Final roman numeral + * @throws { Error } When the result exceeds maximum value of 3999 or invalid numeral is provided */ -export function sum( - expected: "number" | "roman", - ...args: string[] -): string | number | Error {} +function sum(expected: "number" | "roman", ...args: string[]): general {} ``` ๐Ÿ”ต Example @@ -107,15 +114,20 @@ console.log(roman.sum("number", "X", "MXC")); // Returns 1100 ``` -#### โž– Get difference between two Roman numerals and get output as Roman numeral or numbers: `diff` +### โž– Get difference between two Roman numerals and get output as a Roman numeral or numbers: `diff` -```js +```ts /** + * Get difference between two roman numerals * @param expected { string } Expected response type * @param numerals { string[] } Roman numerals to subtract * @returns { string | number } + * @throws { Error } When more than two numerals are provided */ -export function diff(expected: "number" | "roman", numerals: string[]) {} +function diff( + expected: "number" | "roman", + numerals: [string, string] +): general {} ``` ๐Ÿ”ต Example @@ -126,54 +138,170 @@ console.log(roman.diff("number", ["X", "MXC"])); // Returns 1080 ``` -#### ๐Ÿ“ก Get a range of Roman numerals: `range` +### โœ–๏ธ Multiply Roman numerals and get output as a Roman numeral or numbers: `multiply` + +```ts +/** + * Multiply roman numerals + * @param expected { string } Expected response type + * @param args { string[] } Roman numerals to be added + * @returns { string | number } Final roman numeral + * @throws { Error } When the result exceeds maximum value of 3999 or invalid numeral is provided + */ +function multiply(expected: "number" | "roman", ...args: string[]): general {} +``` + +๐Ÿ”ต Example ```js +console.log(roman.multiply("roman", "X", "V")); + +// Returns L +``` + +### โž— Divide two Roman numerals and get output as a Roman numeral or numbers: `divide` + +```ts /** - * Get range of Roman numerals - * @param end { string | number } Value to stop at - * @param start { string | number } Value to start from - * @param intervals { string | number } Difference between values + * Divide two roman numerals + * @param expected { string } Expected response type + * @param numerals { string[] } Roman numerals to divide + * @returns { string | number } + * @throws { Error } When more than two numerals are provided */ -export function range( - end: string | number, - start: string | number = "I", - intervals: string | number = "I" -): string[] | Error {} +function divide( + expected: "number" | "roman", + numerals: [string, string] +): general {} ``` -๐Ÿ”ต Examples +๐Ÿ”ต Example ```js -console.log(roman.range(7)); +console.log(roman.divide("number", ["L", "X"])); -// Returns [ 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII' ] +// Returns 5 +``` + +### โฌ†๏ธ Get maximum Roman numeral from a list: `max` + +```ts +/** + * Get maximum roman numeral from a list + * @param args { string[] } Roman numerals to compare + * @returns { string } Maximum roman numeral + * @throws { Error } When an invalid numeral is provided + */ +function max(...args: string[]): string {} +``` + +๐Ÿ”ต Example + +```js +console.log(roman.max("X", "V", "III", "VIII")); + +// Returns X +``` + +### โฌ‡๏ธ Get minimum Roman numeral from a list: `min` + +```ts +/** + * Get minimum roman numeral from a list + * @param args { string[] } Roman numerals to compare + * @returns { string } Minimum roman numeral + * @throws { Error } When an invalid numeral is provided + */ +function min(...args: string[]): string {} ``` +๐Ÿ”ต Example + ```js -console.log(roman.range("IX")); +console.log(roman.min("X", "V", "III", "VIII")); -// Returns [ 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX' ] +// Returns III ``` +### ๐Ÿคน Get a random Roman numeral: `random` + +```ts +/** + * Generate a random Roman numeral within a specified range + * @param max Maximum value + * @param min Minimum value + * @returns { string } Random Roman numeral within the specified range + * @throws { Error } When the inputs are invalid or out of range + */ +function random(max: general = 3999, min: general = 1): string {} +``` + +๐Ÿ”ต Example + ```js -console.log(roman.range(12, 7)); +console.log(roman.random(10)); + +// Returns a random Roman numeral between I and X +``` -// Returns [ 'VII', 'VIII', 'IX', 'X', 'XI', 'XII' ] +### ๐Ÿ“‹ Generate a table of Roman numerals: `table` + +```ts +/** + * Generate a table of Roman numerals within a specified range + * @param start Starting point for table + * @param end Stopping point for table + * @returns { number: number; roman: string }[] Array of objects containing number and its Roman numeral representation + * @throws { Error } When the inputs are invalid or out of range + */ +function table( + start: general, + end: general +): { number: number; roman: string }[] {} ``` +๐Ÿ”ต Example + ```js -console.log(roman.range(12, "IX")); +console.log(roman.table("I", "V")); -// Returns [ 'IX', 'X', 'XI', 'XII' ] +/** + * Returns [ + * { number: 1, roman: 'I' }, + * { number: 2, roman: 'II' }, + * { number: 3, roman: 'III' }, + * { number: 4, roman: 'IV' }, + * { number: 5, roman: 'V' } + * ] + */ ``` +### ๐Ÿ“ก Get a range of Roman numerals: `range` + +```ts +/** + * Get range of roman numerals + * @param end { string | number } Value to stop at + * @param start { string | number } Value to start from + * @param intervals { string | number } Difference between values + * @returns { string[] } Array of roman numerals in the specified range + * @throws { Error } When any of the inputs are invalid or out of range + */ +function range( + end: general, + start: general = "I", + intervals: general = "I" +): string[] {} +``` + +๐Ÿ”ต Examples + ```js -console.log(roman.range(22, 3, 5)); +console.log(roman.range(7)); -// Returns [ 'III', 'VIII', 'XIII', 'XVIII' ] +// Returns [ 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII' ] ``` -### โœจ Found this project useful? +## โœจ Found this project useful? -If you found this project useful or you like what you see, then please consider giving it a :star: on Github and sharing it with your social media folks ๐Ÿ™‚. +If you found this project useful, or you like what you see, then please consider giving it a โญ๏ธ on GitHub and sharing it with your social media folks ๐Ÿ™‚. diff --git a/templates/contributing.md b/templates/contributing.md index 2b517c1..700d50c 100644 --- a/templates/contributing.md +++ b/templates/contributing.md @@ -1,4 +1,4 @@ -# Contributing to Transcriptase +# Contributing to toroman We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's: @@ -8,13 +8,13 @@ We love your input! We want to make contributing to this project as easy and tra - Proposing new features - Becoming a maintainer -## We Develop with Github +## We Develop with GitHub -We use github to host code, to track issues and feature requests, as well as accept pull requests. +We use GitHub to host code, to track issues and feature requests, as well as accept pull requests. -## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests +## We Use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests -Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests: +Pull requests are the best way to propose changes to the codebase (we use [GitHub Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests: 1. Fork the repo and create your branch from `master`. 2. If you've added code that should be tested, add tests. @@ -27,9 +27,9 @@ Pull requests are the best way to propose changes to the codebase (we use [Githu In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern. -## Report bugs using Github's [issues](https://github.com/Zubs/toRoman/issues) +## Report bugs using GitHub's [issues](https://github.com/Zubs/toRoman/issues) -We use GitHub issues to track public bugs. Report a bug by [opening a new issue](); it's that easy! +We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/Zubs/toRoman/issues); it's that easy! ## Write bug reports with detail, background, and sample code @@ -50,7 +50,7 @@ People _love_ thorough bug reports. I'm not even kidding. I'm again borrowing these from [Facebook's Guidelines](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md) - 2 spaces for indentation rather than tabs -- You can try running `npm run lint` for style unification +- You can try running `npm run format` for style unification ## License