feat: 숫자로 된 금액을 국립국어원 규칙의 한글 읽기로 변환합니다. (#125)

* feat: 숫자로 된 금액을 국립국어원 규칙의 한글 읽기로 변환합니다.

* fix: amounts 를 amount 로 명칭 변경

* fix: 변환 가능 최대 수 가독성 개선

* fix: 변환 버그 수정

* fix: 버그 수정한 예제 추가

* Create big-radios-occur.md

---------

Co-authored-by: 박찬혁 <[email protected]>

.changeset/big-radios-occur.md

@@ -0,0 +1,5 @@
+---
+"es-hangul": patch
+---
+
+feat: 숫자로 된 금액을 국립국어원 규칙의 한글 읽기로 변환합니다.

docs/src/pages/docs/api/amountToHangul.en.md

@@ -0,0 +1,24 @@
+---
+title: amountToHangul
+---
+
+# amountToHangul
+
+Converts numeric amounts to the Korean reading of the [National Institute of Korean Language](https://ko.dict.naver.com/#/correct/korean/info?seq=602) rules.
+
+For detailed examples, see below.
+
+```typescript
+function amountToHangul(
+  // A string of numeric amounts
+  str: string
+): string;
+```
+
+## Examples
+
+```tsx
+amountToHangul('15,201,100'); // '일천오백이십만천백';
+amountToHangul('120,030원'); // '일십이만삼십' - Ignore non-numeric characters
+amountToHangul('392.24'); // '삼백구십이' - Ignore decimals
+```

docs/src/pages/docs/api/amountToHangul.ko.md

@@ -0,0 +1,24 @@
+---
+title: amountToHangul
+---
+
+# amountToHangul
+
+숫자로 된 금액을 [국립국어원](https://ko.dict.naver.com/#/correct/korean/info?seq=602) 규칙의 한글 읽기로 변환합니다.
+
+자세한 예시는 아래 Example을 참고하세요.
+
+```typescript
+function amountToHangul(
+  // 숫자로 된 금액 문자열
+  str: string
+): string;
+```
+
+## Examples
+
+```tsx
+amountToHangul('15,201,100'); // '일천오백이십만천백';
+amountToHangul('120,030원'); // '일십이만삼십' - 숫자 외 문자 무시
+amountToHangul('392.24'); // '삼백구십이' - 소수점 무시
+```

src/amountToHangul.spec.ts

@@ -0,0 +1,11 @@
+import { amountToHangul } from './amountToHangul';
+
+describe('amountToHangul', () => {
+  it('숫자로 된 금액을 한글로 표기', () => {
+    expect(amountToHangul('15,201,100')).toEqual('일천오백이십만천백');
+    expect(amountToHangul('120,030원')).toEqual('일십이만삼십'); // 숫자 외 문자 무시
+    expect(amountToHangul('392.24')).toEqual('삼백구십이'); // 소수점 무시
+    expect(amountToHangul('100000000')).toEqual('일억');
+    expect(amountToHangul('100000100')).toEqual('일억백');
+  });
+});

src/amountToHangul.ts

@@ -0,0 +1,35 @@
+export const HANGUL_DIGITS = ['', '만', '억', '조', '경', '해', '자', '양', '구', '간', '정', '재', '극', '항하사', '아승기', '나유타', '불가사의', '무량대수', '겁', '업'];
+export const HANGUL_DIGITS_MAX = HANGUL_DIGITS.length * 4;
+export const HANGUL_NUMBERS = ['', '일', '이', '삼', '사', '오', '육', '칠', '팔', '구'];
+export const HANGUL_CARDINAL = ['', '십', '백', '천'];
+
+// https://ko.dict.naver.com/#/correct/korean/info?seq=602
+// https://github.com/crucifyer/koreanCardinalOrdinal
+export function amountToHangul(str: string) {
+  str = str.replace(/\..*$/, '') // 소수점 지원 안함
+    .replace(/[^\d]+/g, ''); // , 표기 등 오류내지 않음
+  if(str.length > HANGUL_DIGITS_MAX) {
+    throw new Error('convert range exceeded : ' + str);
+  }
+  const result = [];
+  let pronunDigits = true;
+  for(let i = 0; i < str.length - 1; i ++) {
+    const d = str.length - i - 1;
+    if(str[i] > '1' || d % 4 === 0 || i === 0) {
+      const tnum = HANGUL_NUMBERS[parseInt(str[i])];
+      if(tnum) {
+        result.push(tnum);
+        pronunDigits = true;
+      }
+    }
+    if(pronunDigits && d % 4 === 0) {
+      result.push(HANGUL_DIGITS[d / 4]);
+      pronunDigits = false;
+    }
+    if(str[i] !== '0') {
+      result.push(HANGUL_CARDINAL[d % 4]);
+    }
+  }
+  result.push(HANGUL_NUMBERS[parseInt(str[str.length - 1])]);
+  return result.join('');
+}