Skip to content

Commit 2a522ea

Browse files
committed
docs(readme): update fallback option section
1 parent 9beeb9c commit 2a522ea

File tree

2 files changed

+44
-28
lines changed

2 files changed

+44
-28
lines changed

README.md

Lines changed: 28 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,10 @@ Convert and detect character encoding in JavaScript.
2727
* [convert : Converts character encoding](#encodingconvert-data-to-from)
2828
+ [Specify conversion options to the argument `to` as an object](#specify-conversion-options-to-the-argument-to-as-an-object)
2929
+ [Specify the return type by the `type` option](#specify-the-return-type-by-the-type-option)
30+
+ [Specify handling for unrepresentable characters](#specify-handling-for-unrepresentable-characters)
3031
+ [Replacing characters with HTML entities when they cannot be represented](#replacing-characters-with-html-entities-when-they-cannot-be-represented)
3132
+ [Ignoring characters when they cannot be represented](#ignoring-characters-when-they-cannot-be-represented)
32-
+ [Raising an Error when they cannot be represented](#raising-an-error-when-they-cannot-be-represented)
33+
+ [Throwing an Error when they cannot be represented](#throwing-an-error-when-they-cannot-be-represented)
3334
+ [Specify BOM in UTF-16](#specify-bom-in-utf-16)
3435
* [urlEncode : Encodes to percent-encoded string](#encodingurlencode-data)
3536
* [urlDecode : Decodes from percent-encoded string](#encodingurldecode-string)
@@ -365,15 +366,20 @@ The following `type` options are supported.
365366
as performed by [`Encoding.codeToString`](#encodingcodetostring-code).
366367
Note: Specifying `type: 'string'` may not handle conversions properly, except when converting to `UNICODE`.
367368

368-
#### Replacing characters with HTML entities when they cannot be represented
369+
#### Specify handling for unrepresentable characters
369370

370-
Characters that cannot be represented in the target character set are replaced with '?' (U+003F) by default,
371-
but by specifying the `fallback` option, you can replace them with HTML entities (Numeric character references), such as `🍣`.
371+
With the `fallback` option, you can specify how to handle characters that cannot be represented in the target encoding.
372+
The `fallback` option supports the following values:
373+
374+
* **html-entity**: Replace characters with HTML entities (decimal HTML numeric character references).
375+
* **html-entity-hex**: Replace characters with HTML entities (hexadecimal HTML numeric character references).
376+
* **ignore**: Ignore characters that cannot be represented.
377+
* **error**: Throw an error if any character cannot be represented.
372378

373-
The `fallback` option supports the following values.
379+
#### Replacing characters with HTML entities when they cannot be represented
374380

375-
* **html-entity** : Replace to HTML entity (decimal HTML numeric character reference).
376-
* **html-entity-hex** : Replace to HTML entity (hexadecimal HTML numeric character reference).
381+
Characters that cannot be represented in the target character set are replaced with '?' (U+003F) by default,
382+
but by specifying `html-entity` as the `fallback` option, you can replace them with HTML entities (Numeric character references), such as `🍣`.
377383

378384
Example of specifying `{ fallback: 'html-entity' }` option:
379385

@@ -414,28 +420,30 @@ By specifying `ignore` as a `fallback` option, characters that cannot be represe
414420
Example of specifying `{ fallback: 'ignore' }` option:
415421

416422
```javascript
417-
const unicodeArray = Encoding.stringToCode("寿司🍣ビール🍺");
423+
const unicodeArray = Encoding.stringToCode('寿司🍣ビール🍺');
418424
// No fallback specified
419425
let sjisArray = Encoding.convert(unicodeArray, {
420-
to: "SJIS",
421-
from: "UNICODE",
426+
to: 'SJIS',
427+
from: 'UNICODE'
422428
});
423429
console.log(sjisArray); // Converted to a code array of '寿司?ビール?'
424430

425431
// Specify `fallback: ignore`
426432
sjisArray = Encoding.convert(unicodeArray, {
427-
to: "SJIS",
428-
from: "UNICODE",
429-
fallback: "ignore",
433+
to: 'SJIS',
434+
from: 'UNICODE',
435+
fallback: 'ignore'
430436
});
431437
console.log(sjisArray); // Converted to a code array of '寿司ビール'
432438
```
433439

434-
#### Raising an Error when they cannot be represented
440+
#### Throwing an Error when they cannot be represented
435441

436442
If you need to throw an error when a character cannot be represented in the target character encoding,
437443
specify `error` as a `fallback` option. This will cause an exception to be thrown.
438444

445+
Example of specifying `{ fallback: 'error' }` option:
446+
439447
```javascript
440448
const unicodeArray = Encoding.stringToCode('おにぎり🍙ラーメン🍜');
441449
try {
@@ -456,9 +464,9 @@ The default is no BOM.
456464

457465
```javascript
458466
const utf16Array = Encoding.convert(utf8Array, {
459-
to: 'UTF16', // to_encoding
460-
from: 'UTF8', // from_encoding
461-
bom: true // Add BOM
467+
to: 'UTF16',
468+
from: 'UTF8',
469+
bom: true // Specify to add the BOM
462470
});
463471
```
464472

@@ -467,9 +475,9 @@ If you want to convert as little-endian, specify the `{ bom: 'LE' }` option.
467475

468476
```javascript
469477
const utf16leArray = Encoding.convert(utf8Array, {
470-
to: 'UTF16', // to_encoding
471-
from: 'UTF8', // from_encoding
472-
bom: 'LE' // With BOM (little-endian)
478+
to: 'UTF16',
479+
from: 'UTF8',
480+
bom: 'LE' // Specify to add the BOM as little-endian
473481
});
474482
```
475483

README_ja.md

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ JavaScript で文字コードの変換や判定をします。
2727
* [convert : 文字コードを変換する](#encodingconvert-data-to-from)
2828
+ [引数 `to` にオブジェクトで変換オプションを指定する](#引数-to-にオブジェクトで変換オプションを指定する)
2929
+ [`type` オプションで戻り値の型を指定する](#type-オプションで戻り値の型を指定する)
30+
+ [`fallback` オプションで変換できない文字の扱いを指定する](#fallback-オプションで変換できない文字の扱いを指定する)
3031
+ [変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える](#変換できない文字を-html-エンティティ-html-数値文字参照-に置き換える)
3132
+ [変換できない文字を無視する](#変換できない文字を無視する)
3233
+ [変換できない文字が含まれている場合にエラーを発生させる](#変換できない文字が含まれている場合にエラーを発生させる)
@@ -355,15 +356,20 @@ console.log(unicodeString); // 'おはよ'
355356
`type: 'string'` は、配列から文字列に変換する [`Encoding.codeToString`](#encodingcodetostring-code) のショートハンドとして使用することができます。
356357
`UNICODE` への変換以外は `type: 'string'` を指定しても正しく扱えない可能性がありますのでご注意ください
357358

358-
#### 変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える
359-
360-
変換先の文字コードで表現できない文字はデフォルトで「?」 (U+003F) に置き換えられますが、
361-
`fallback` オプションを指定すると `🍣` 等の HTML エンティティに置き換えることができます。
359+
#### `fallback` オプションで変換できない文字の扱いを指定する
362360

361+
`fallback` オプションで、変換先の文字コードで表現できない文字があった場合の扱いを指定できます。
363362
`fallback` オプションは以下の値が使用できます。
364363

365364
* **html-entity** : HTML エンティティ (10進数の HTML 数値文字参照) に置き換える
366365
* **html-entity-hex** : HTML エンティティ (16進数の HTML 数値文字参照) に置き換える
366+
* **ignore** : 変換できない文字を無視する
367+
* **error** : 変換できない文字が含まれている場合にエラーを発生させる
368+
369+
#### 変換できない文字を HTML エンティティ (HTML 数値文字参照) に置き換える
370+
371+
変換先の文字コードで表現できない文字はデフォルトで「?」 (U+003F) に置き換えられますが、
372+
`fallback` オプションに `html-entity` を指定すると `🍣` 等の HTML エンティティに置き換えることができます。
367373

368374
`{ fallback: 'html-entity' }` オプションを指定する例:
369375

@@ -425,6 +431,8 @@ console.log(sjisArray); // '寿司ビール' の数値配列に変換されま
425431

426432
`fallback` オプションに `error` を指定すると、変換先の文字コードで表現できない文字が含まれている場合にエラーが発生し、例外が投げられます。
427433

434+
`{ fallback: 'error' }` オプションを指定する例:
435+
428436
```javascript
429437
const unicodeArray = Encoding.stringToCode('おにぎり🍙ラーメン🍜');
430438
try {
@@ -445,8 +453,8 @@ try {
445453

446454
```javascript
447455
const utf16Array = Encoding.convert(utf8Array, {
448-
to: 'UTF16', // to_encoding
449-
from: 'UTF8', // from_encoding
456+
to: 'UTF16',
457+
from: 'UTF8',
450458
bom: true // BOMをつける
451459
});
452460
```
@@ -456,8 +464,8 @@ little-endian として変換したい場合は `bom` オプションに `LE`
456464

457465
```javascript
458466
const utf16leArray = Encoding.convert(utf8Array, {
459-
to: 'UTF16', // to_encoding
460-
from: 'UTF8', // from_encoding
467+
to: 'UTF16',
468+
from: 'UTF8',
461469
bom: 'LE' // BOM (little-endian) をつける
462470
});
463471
```

0 commit comments

Comments
 (0)