From f6422f78aea4d4360d76af7fbde4fa7da22214da Mon Sep 17 00:00:00 2001
From: polygonplanet <polygon.planet.aqua@gmail.com>
Date: Sat, 8 Jun 2024 22:27:45 +0900
Subject: [PATCH] docs: add `fallback: 'error'` option

---
 README.md    | 19 +++++++++++++++++++
 README_ja.md | 18 ++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/README.md b/README.md
index 8f4d275..065571a 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ Convert and detect character encoding in JavaScript.
     + [Specify the return type by the `type` option](#specify-the-return-type-by-the-type-option)
     + [Replacing characters with HTML entities when they cannot be represented](#replacing-characters-with-html-entities-when-they-cannot-be-represented)
     + [Ignoring characters when they cannot be represented](#ignoring-characters-when-they-cannot-be-represented)
+    + [Raising an Error when they cannot be represented](#raising-an-error-when-they-cannot-be-represented)
     + [Specify BOM in UTF-16](#specify-bom-in-utf-16)
   * [urlEncode : Encodes to percent-encoded string](#encodingurlencode-data)
   * [urlDecode : Decodes from percent-encoded string](#encodingurldecode-string)
@@ -430,6 +431,24 @@ sjisArray = Encoding.convert(unicodeArray, {
 console.log(sjisArray); // Converted to a code array of '寿司ビール'
 ```
 
+#### Raising an Error when they cannot be represented
+
+If you need to throw an error when a character cannot be represented in the target character encoding,
+specify `error` as a `fallback` option. This will cause an exception to be thrown.
+
+```javascript
+const unicodeArray = Encoding.stringToCode('おにぎり🍙ラーメン🍜');
+try {
+  const sjisArray = Encoding.convert(unicodeArray, {
+    to: 'SJIS',
+    from: 'UNICODE',
+    fallback: 'error' // Specify 'error' to throw an exception
+  });
+} catch (e) {
+  console.error(e); // Error: Character cannot be represented: [240, 159, 141, 153]
+}
+```
+
 #### Specify BOM in UTF-16
 
 You can add a BOM (byte order mark) by specifying the `bom` option when converting to `UTF16`.
diff --git a/README_ja.md b/README_ja.md
index 7cae3f8..16c7e00 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -29,6 +29,7 @@ JavaScript で文字コードの変換や判定をします。
     + [`type` オプションで戻り値の型を指定する](#type-オプションで戻り値の型を指定する)
     + [変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える](#変換できない文字を-html-エンティティ-html-数値文字参照-に置き換える)
     + [変換できない文字を無視する](#変換できない文字を無視する)
+    + [変換できない文字が含まれている場合にエラーを発生させる](#変換できない文字が含まれている場合にエラーを発生させる)
     + [UTF-16 に BOM をつける](#utf-16-に-bom-をつける)
   * [urlEncode : 文字コードの配列をURLエンコードする](#encodingurlencode-data)
   * [urlDecode : 文字コードの配列にURLデコードする](#encodingurldecode-string)
@@ -420,6 +421,23 @@ sjisArray = Encoding.convert(unicodeArray, {
 console.log(sjisArray); // '寿司ビール' の数値配列に変換されます
 ```
 
+#### 変換できない文字が含まれている場合にエラーを発生させる
+
+`fallback` オプションに `error` を指定すると、変換先の文字コードで表現できない文字が含まれている場合にエラーが発生し、例外が投げられます。
+
+```javascript
+const unicodeArray = Encoding.stringToCode('おにぎり🍙ラーメン🍜');
+try {
+  const sjisArray = Encoding.convert(unicodeArray, {
+    to: 'SJIS',
+    from: 'UNICODE',
+    fallback: 'error' // 'error'を指定
+  });
+} catch (e) {
+  console.error(e); // Error: Character cannot be represented: [240, 159, 141, 153]
+}
+```
+
 #### UTF-16 に BOM をつける
 
 `UTF16` に変換する際に `bom` オプションを指定すると BOM (byte order mark) の付加を指定できます。