docs(readme): update fallback option section

polygonplanet · Jun 8, 2024 · 2a522ea · 2a522ea
1 parent 9beeb9c
commit 2a522ea
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -27,9 +27,10 @@ Convert and detect character encoding in JavaScript.
   * [convert : Converts character encoding](#encodingconvert-data-to-from)
     + [Specify conversion options to the argument `to` as an object](#specify-conversion-options-to-the-argument-to-as-an-object)
     + [Specify the return type by the `type` option](#specify-the-return-type-by-the-type-option)
+    + [Specify handling for unrepresentable characters](#specify-handling-for-unrepresentable-characters)
     + [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)
+    + [Throwing an Error when they cannot be represented](#throwing-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)
@@ -365,15 +366,20 @@ The following `type` options are supported.
 as performed by [`Encoding.codeToString`](#encodingcodetostring-code).  
 Note: Specifying `type: 'string'` may not handle conversions properly, except when converting to `UNICODE`.
 
-#### Replacing characters with HTML entities when they cannot be represented
+#### Specify handling for unrepresentable characters
 
-Characters that cannot be represented in the target character set are replaced with '?' (U+003F) by default,
-but by specifying the `fallback` option, you can replace them with HTML entities (Numeric character references), such as `&#127843;`.
+With the `fallback` option, you can specify how to handle characters that cannot be represented in the target encoding.
+The `fallback` option supports the following values:
+
+* **html-entity**: Replace characters with HTML entities (decimal HTML numeric character references).
+* **html-entity-hex**: Replace characters with HTML entities (hexadecimal HTML numeric character references).
+* **ignore**: Ignore characters that cannot be represented.
+* **error**: Throw an error if any character cannot be represented.
 
-The `fallback` option supports the following values.
+#### Replacing characters with HTML entities when they cannot be represented
 
-* **html-entity** : Replace to HTML entity (decimal HTML numeric character reference).
-* **html-entity-hex** : Replace to HTML entity (hexadecimal HTML numeric character reference).
+Characters that cannot be represented in the target character set are replaced with '?' (U+003F) by default,
+but by specifying `html-entity` as the `fallback` option, you can replace them with HTML entities (Numeric character references), such as `&#127843;`.
 
 Example of specifying `{ fallback: 'html-entity' }` option:
 
@@ -414,28 +420,30 @@ By specifying `ignore` as a `fallback` option, characters that cannot be represe
 Example of specifying `{ fallback: 'ignore' }` option:
 
 ```javascript
-const unicodeArray = Encoding.stringToCode("寿司🍣ビール🍺");
+const unicodeArray = Encoding.stringToCode('寿司🍣ビール🍺');
 // No fallback specified
 let sjisArray = Encoding.convert(unicodeArray, {
-  to: "SJIS",
-  from: "UNICODE",
+  to: 'SJIS',
+  from: 'UNICODE'
 });
 console.log(sjisArray); // Converted to a code array of '寿司?ビール?'
 
 // Specify `fallback: ignore`
 sjisArray = Encoding.convert(unicodeArray, {
-  to: "SJIS",
-  from: "UNICODE",
-  fallback: "ignore",
+  to: 'SJIS',
+  from: 'UNICODE',
+  fallback: 'ignore'
 });
 console.log(sjisArray); // Converted to a code array of '寿司ビール'
 ```
 
-#### Raising an Error when they cannot be represented
+#### Throwing 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.
 
+Example of specifying `{ fallback: 'error' }` option:
+
 ```javascript
 const unicodeArray = Encoding.stringToCode('おにぎり🍙ラーメン🍜');
 try {
@@ -456,9 +464,9 @@ The default is no BOM.
 
 ```javascript
 const utf16Array = Encoding.convert(utf8Array, {
-  to: 'UTF16', // to_encoding
-  from: 'UTF8', // from_encoding
-  bom: true // Add BOM
+  to: 'UTF16',
+  from: 'UTF8',
+  bom: true // Specify to add the BOM
 });
 ```
 
@@ -467,9 +475,9 @@ If you want to convert as little-endian, specify the `{ bom: 'LE' }` option.
 
 ```javascript
 const utf16leArray = Encoding.convert(utf8Array, {
-  to: 'UTF16', // to_encoding
-  from: 'UTF8', // from_encoding
-  bom: 'LE' // With BOM (little-endian)
+  to: 'UTF16',
+  from: 'UTF8',
+  bom: 'LE' // Specify to add the BOM as little-endian
 });
 ```
 

diff --git a/README_ja.md b/README_ja.md
@@ -27,6 +27,7 @@ JavaScript で文字コードの変換や判定をします。
   * [convert : 文字コードを変換する](#encodingconvert-data-to-from)
     + [引数 `to` にオブジェクトで変換オプションを指定する](#引数-to-にオブジェクトで変換オプションを指定する)
     + [`type` オプションで戻り値の型を指定する](#type-オプションで戻り値の型を指定する)
+    + [`fallback` オプションで変換できない文字の扱いを指定する](#fallback-オプションで変換できない文字の扱いを指定する)
     + [変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える](#変換できない文字を-html-エンティティ-html-数値文字参照-に置き換える)
     + [変換できない文字を無視する](#変換できない文字を無視する)
     + [変換できない文字が含まれている場合にエラーを発生させる](#変換できない文字が含まれている場合にエラーを発生させる)
@@ -355,15 +356,20 @@ console.log(unicodeString); // 'おはよ'
 `type: 'string'` は、配列から文字列に変換する [`Encoding.codeToString`](#encodingcodetostring-code) のショートハンドとして使用することができます。  
 ※ `UNICODE` への変換以外は `type: 'string'` を指定しても正しく扱えない可能性がありますのでご注意ください
 
-#### 変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える
-
-変換先の文字コードで表現できない文字はデフォルトで「?」 (U+003F) に置き換えられますが、
-`fallback` オプションを指定すると `&#127843;` 等の HTML エンティティに置き換えることができます。
+#### `fallback` オプションで変換できない文字の扱いを指定する
 
+`fallback` オプションで、変換先の文字コードで表現できない文字があった場合の扱いを指定できます。
 `fallback` オプションは以下の値が使用できます。
 
 * **html-entity** : HTML エンティティ (10進数の HTML 数値文字参照) に置き換える
 * **html-entity-hex** : HTML エンティティ (16進数の HTML 数値文字参照) に置き換える
+* **ignore** : 変換できない文字を無視する
+* **error** : 変換できない文字が含まれている場合にエラーを発生させる
+
+#### 変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える
+
+変換先の文字コードで表現できない文字はデフォルトで「?」 (U+003F) に置き換えられますが、
+`fallback` オプションに `html-entity` を指定すると `&#127843;` 等の HTML エンティティに置き換えることができます。
 
 `{ fallback: 'html-entity' }` オプションを指定する例:
 
@@ -425,6 +431,8 @@ console.log(sjisArray); // '寿司ビール' の数値配列に変換されま
 
 `fallback` オプションに `error` を指定すると、変換先の文字コードで表現できない文字が含まれている場合にエラーが発生し、例外が投げられます。
 
+`{ fallback: 'error' }` オプションを指定する例:
+
 ```javascript
 const unicodeArray = Encoding.stringToCode('おにぎり🍙ラーメン🍜');
 try {
@@ -445,8 +453,8 @@ try {
 
 ```javascript
 const utf16Array = Encoding.convert(utf8Array, {
-  to: 'UTF16', // to_encoding
-  from: 'UTF8', // from_encoding
+  to: 'UTF16',
+  from: 'UTF8',
   bom: true // BOMをつける
 });
 ```
@@ -456,8 +464,8 @@ little-endian として変換したい場合は `bom` オプションに `LE`
 
 ```javascript
 const utf16leArray = Encoding.convert(utf8Array, {
-  to: 'UTF16', // to_encoding
-  from: 'UTF8', // from_encoding
+  to: 'UTF16',
+  from: 'UTF8',
   bom: 'LE' // BOM (little-endian) をつける
 });
 ```