From 2a522ea07c651b2dceae5e97fdc4756bc22bfd3f Mon Sep 17 00:00:00 2001 From: polygonplanet Date: Sun, 9 Jun 2024 00:08:18 +0900 Subject: [PATCH] docs(readme): update fallback option section --- README.md | 48 ++++++++++++++++++++++++++++-------------------- README_ja.md | 24 ++++++++++++++++-------- 2 files changed, 44 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 065571a..f910222 100644 --- 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 `🍣`. +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 `🍣`. 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 index 16c7e00..e6d83f0 100644 --- 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` オプションを指定すると `🍣` 等の HTML エンティティに置き換えることができます。 +#### `fallback` オプションで変換できない文字の扱いを指定する +`fallback` オプションで、変換先の文字コードで表現できない文字があった場合の扱いを指定できます。 `fallback` オプションは以下の値が使用できます。 * **html-entity** : HTML エンティティ (10進数の HTML 数値文字参照) に置き換える * **html-entity-hex** : HTML エンティティ (16進数の HTML 数値文字参照) に置き換える +* **ignore** : 変換できない文字を無視する +* **error** : 変換できない文字が含まれている場合にエラーを発生させる + +#### 変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える + +変換先の文字コードで表現できない文字はデフォルトで「?」 (U+003F) に置き換えられますが、 +`fallback` オプションに `html-entity` を指定すると `🍣` 等の 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) をつける }); ```