@@ -27,9 +27,10 @@ Convert and detect character encoding in JavaScript.
27
27
* [ convert : Converts character encoding] ( #encodingconvert-data-to-from )
28
28
+ [ Specify conversion options to the argument ` to ` as an object] ( #specify-conversion-options-to-the-argument-to-as-an-object )
29
29
+ [ 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 )
30
31
+ [ Replacing characters with HTML entities when they cannot be represented] ( #replacing-characters-with-html-entities-when-they-cannot-be-represented )
31
32
+ [ 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 )
33
34
+ [ Specify BOM in UTF-16] ( #specify-bom-in-utf-16 )
34
35
* [ urlEncode : Encodes to percent-encoded string] ( #encodingurlencode-data )
35
36
* [ urlDecode : Decodes from percent-encoded string] ( #encodingurldecode-string )
@@ -365,15 +366,20 @@ The following `type` options are supported.
365
366
as performed by [ ` Encoding.codeToString ` ] ( #encodingcodetostring-code ) .
366
367
Note: Specifying ` type: 'string' ` may not handle conversions properly, except when converting to ` UNICODE ` .
367
368
368
- #### Replacing characters with HTML entities when they cannot be represented
369
+ #### Specify handling for unrepresentable characters
369
370
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.
372
378
373
- The ` fallback ` option supports the following values.
379
+ #### Replacing characters with HTML entities when they cannot be represented
374
380
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 ` 🍣 ` .
377
383
378
384
Example of specifying ` { fallback: 'html-entity' } ` option:
379
385
@@ -414,28 +420,30 @@ By specifying `ignore` as a `fallback` option, characters that cannot be represe
414
420
Example of specifying ` { fallback: 'ignore' } ` option:
415
421
416
422
``` javascript
417
- const unicodeArray = Encoding .stringToCode (" 寿司🍣ビール🍺" );
423
+ const unicodeArray = Encoding .stringToCode (' 寿司🍣ビール🍺' );
418
424
// No fallback specified
419
425
let sjisArray = Encoding .convert (unicodeArray, {
420
- to: " SJIS" ,
421
- from: " UNICODE" ,
426
+ to: ' SJIS' ,
427
+ from: ' UNICODE'
422
428
});
423
429
console .log (sjisArray); // Converted to a code array of '寿司?ビール?'
424
430
425
431
// Specify `fallback: ignore`
426
432
sjisArray = Encoding .convert (unicodeArray, {
427
- to: " SJIS" ,
428
- from: " UNICODE" ,
429
- fallback: " ignore" ,
433
+ to: ' SJIS' ,
434
+ from: ' UNICODE' ,
435
+ fallback: ' ignore'
430
436
});
431
437
console .log (sjisArray); // Converted to a code array of '寿司ビール'
432
438
```
433
439
434
- #### Raising an Error when they cannot be represented
440
+ #### Throwing an Error when they cannot be represented
435
441
436
442
If you need to throw an error when a character cannot be represented in the target character encoding,
437
443
specify ` error ` as a ` fallback ` option. This will cause an exception to be thrown.
438
444
445
+ Example of specifying ` { fallback: 'error' } ` option:
446
+
439
447
``` javascript
440
448
const unicodeArray = Encoding .stringToCode (' おにぎり🍙ラーメン🍜' );
441
449
try {
@@ -456,9 +464,9 @@ The default is no BOM.
456
464
457
465
``` javascript
458
466
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
462
470
});
463
471
```
464
472
@@ -467,9 +475,9 @@ If you want to convert as little-endian, specify the `{ bom: 'LE' }` option.
467
475
468
476
``` javascript
469
477
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
473
481
});
474
482
```
475
483
0 commit comments