@@ -1192,7 +1192,133 @@ only if the Node.js binary was compiled with including support for the
11921192added: v11.0.0
11931193-->
11941194
1195- The WHATWG ` TextDecoder ` class. See the [ ` TextDecoder ` ] [ ] section.
1195+ An implementation of the [ WHATWG Encoding Standard] [ ] ` TextDecoder ` API.
1196+
1197+ ``` js
1198+ const decoder = new TextDecoder ();
1199+ const u8arr = new Uint8Array ([72 , 101 , 108 , 108 , 111 ]);
1200+ console .log (decoder .decode (u8arr)); // Hello
1201+ ```
1202+
1203+ ### WHATWG supported encodings
1204+
1205+ Per the [ WHATWG Encoding Standard] [ ] , the encodings supported by the
1206+ ` TextDecoder ` API are outlined in the tables below. For each encoding,
1207+ one or more aliases may be used.
1208+
1209+ Different Node.js build configurations support different sets of encodings.
1210+ (see [ Internationalization] [ ] )
1211+
1212+ #### Encodings supported by default (with full ICU data)
1213+
1214+ | Encoding | Aliases |
1215+ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1216+ | ` 'ibm866' ` | ` '866' ` , ` 'cp866' ` , ` 'csibm866' ` |
1217+ | ` 'iso-8859-2' ` | ` 'csisolatin2' ` , ` 'iso-ir-101' ` , ` 'iso8859-2' ` , ` 'iso88592' ` , ` 'iso_8859-2' ` , ` 'iso_8859-2:1987' ` , ` 'l2' ` , ` 'latin2' ` |
1218+ | ` 'iso-8859-3' ` | ` 'csisolatin3' ` , ` 'iso-ir-109' ` , ` 'iso8859-3' ` , ` 'iso88593' ` , ` 'iso_8859-3' ` , ` 'iso_8859-3:1988' ` , ` 'l3' ` , ` 'latin3' ` |
1219+ | ` 'iso-8859-4' ` | ` 'csisolatin4' ` , ` 'iso-ir-110' ` , ` 'iso8859-4' ` , ` 'iso88594' ` , ` 'iso_8859-4' ` , ` 'iso_8859-4:1988' ` , ` 'l4' ` , ` 'latin4' ` |
1220+ | ` 'iso-8859-5' ` | ` 'csisolatincyrillic' ` , ` 'cyrillic' ` , ` 'iso-ir-144' ` , ` 'iso8859-5' ` , ` 'iso88595' ` , ` 'iso_8859-5' ` , ` 'iso_8859-5:1988' ` |
1221+ | ` 'iso-8859-6' ` | ` 'arabic' ` , ` 'asmo-708' ` , ` 'csiso88596e' ` , ` 'csiso88596i' ` , ` 'csisolatinarabic' ` , ` 'ecma-114' ` , ` 'iso-8859-6-e' ` , ` 'iso-8859-6-i' ` , ` 'iso-ir-127' ` , ` 'iso8859-6' ` , ` 'iso88596' ` , ` 'iso_8859-6' ` , ` 'iso_8859-6:1987' ` |
1222+ | ` 'iso-8859-7' ` | ` 'csisolatingreek' ` , ` 'ecma-118' ` , ` 'elot_928' ` , ` 'greek' ` , ` 'greek8' ` , ` 'iso-ir-126' ` , ` 'iso8859-7' ` , ` 'iso88597' ` , ` 'iso_8859-7' ` , ` 'iso_8859-7:1987' ` , ` 'sun_eu_greek' ` |
1223+ | ` 'iso-8859-8' ` | ` 'csiso88598e' ` , ` 'csisolatinhebrew' ` , ` 'hebrew' ` , ` 'iso-8859-8-e' ` , ` 'iso-ir-138' ` , ` 'iso8859-8' ` , ` 'iso88598' ` , ` 'iso_8859-8' ` , ` 'iso_8859-8:1988' ` , ` 'visual' ` |
1224+ | ` 'iso-8859-8-i' ` | ` 'csiso88598i' ` , ` 'logical' ` |
1225+ | ` 'iso-8859-10' ` | ` 'csisolatin6' ` , ` 'iso-ir-157' ` , ` 'iso8859-10' ` , ` 'iso885910' ` , ` 'l6' ` , ` 'latin6' ` |
1226+ | ` 'iso-8859-13' ` | ` 'iso8859-13' ` , ` 'iso885913' ` |
1227+ | ` 'iso-8859-14' ` | ` 'iso8859-14' ` , ` 'iso885914' ` |
1228+ | ` 'iso-8859-15' ` | ` 'csisolatin9' ` , ` 'iso8859-15' ` , ` 'iso885915' ` , ` 'iso_8859-15' ` , ` 'l9' ` |
1229+ | ` 'koi8-r' ` | ` 'cskoi8r' ` , ` 'koi' ` , ` 'koi8' ` , ` 'koi8_r' ` |
1230+ | ` 'koi8-u' ` | ` 'koi8-ru' ` |
1231+ | ` 'macintosh' ` | ` 'csmacintosh' ` , ` 'mac' ` , ` 'x-mac-roman' ` |
1232+ | ` 'windows-874' ` | ` 'dos-874' ` , ` 'iso-8859-11' ` , ` 'iso8859-11' ` , ` 'iso885911' ` , ` 'tis-620' ` |
1233+ | ` 'windows-1250' ` | ` 'cp1250' ` , ` 'x-cp1250' ` |
1234+ | ` 'windows-1251' ` | ` 'cp1251' ` , ` 'x-cp1251' ` |
1235+ | ` 'windows-1252' ` | ` 'ansi_x3.4-1968' ` , ` 'ascii' ` , ` 'cp1252' ` , ` 'cp819' ` , ` 'csisolatin1' ` , ` 'ibm819' ` , ` 'iso-8859-1' ` , ` 'iso-ir-100' ` , ` 'iso8859-1' ` , ` 'iso88591' ` , ` 'iso_8859-1' ` , ` 'iso_8859-1:1987' ` , ` 'l1' ` , ` 'latin1' ` , ` 'us-ascii' ` , ` 'x-cp1252' ` |
1236+ | ` 'windows-1253' ` | ` 'cp1253' ` , ` 'x-cp1253' ` |
1237+ | ` 'windows-1254' ` | ` 'cp1254' ` , ` 'csisolatin5' ` , ` 'iso-8859-9' ` , ` 'iso-ir-148' ` , ` 'iso8859-9' ` , ` 'iso88599' ` , ` 'iso_8859-9' ` , ` 'iso_8859-9:1989' ` , ` 'l5' ` , ` 'latin5' ` , ` 'x-cp1254' ` |
1238+ | ` 'windows-1255' ` | ` 'cp1255' ` , ` 'x-cp1255' ` |
1239+ | ` 'windows-1256' ` | ` 'cp1256' ` , ` 'x-cp1256' ` |
1240+ | ` 'windows-1257' ` | ` 'cp1257' ` , ` 'x-cp1257' ` |
1241+ | ` 'windows-1258' ` | ` 'cp1258' ` , ` 'x-cp1258' ` |
1242+ | ` 'x-mac-cyrillic' ` | ` 'x-mac-ukrainian' ` |
1243+ | ` 'gbk' ` | ` 'chinese' ` , ` 'csgb2312' ` , ` 'csiso58gb231280' ` , ` 'gb2312' ` , ` 'gb_2312' ` , ` 'gb_2312-80' ` , ` 'iso-ir-58' ` , ` 'x-gbk' ` |
1244+ | ` 'gb18030' ` | |
1245+ | ` 'big5' ` | ` 'big5-hkscs' ` , ` 'cn-big5' ` , ` 'csbig5' ` , ` 'x-x-big5' ` |
1246+ | ` 'euc-jp' ` | ` 'cseucpkdfmtjapanese' ` , ` 'x-euc-jp' ` |
1247+ | ` 'iso-2022-jp' ` | ` 'csiso2022jp' ` |
1248+ | ` 'shift_jis' ` | ` 'csshiftjis' ` , ` 'ms932' ` , ` 'ms_kanji' ` , ` 'shift-jis' ` , ` 'sjis' ` , ` 'windows-31j' ` , ` 'x-sjis' ` |
1249+ | ` 'euc-kr' ` | ` 'cseuckr' ` , ` 'csksc56011987' ` , ` 'iso-ir-149' ` , ` 'korean' ` , ` 'ks_c_5601-1987' ` , ` 'ks_c_5601-1989' ` , ` 'ksc5601' ` , ` 'ksc_5601' ` , ` 'windows-949' ` |
1250+
1251+ #### Encodings supported when Node.js is built with the ` small-icu ` option
1252+
1253+ | Encoding | Aliases |
1254+ | ------------ | ------------------------------- |
1255+ | ` 'utf-8' ` | ` 'unicode-1-1-utf-8' ` , ` 'utf8' ` |
1256+ | ` 'utf-16le' ` | ` 'utf-16' ` |
1257+ | ` 'utf-16be' ` | |
1258+
1259+ #### Encodings supported when ICU is disabled
1260+
1261+ | Encoding | Aliases |
1262+ | ------------ | ------------------------------- |
1263+ | ` 'utf-8' ` | ` 'unicode-1-1-utf-8' ` , ` 'utf8' ` |
1264+ | ` 'utf-16le' ` | ` 'utf-16' ` |
1265+
1266+ The ` 'iso-8859-16' ` encoding listed in the [ WHATWG Encoding Standard] [ ]
1267+ is not supported.
1268+
1269+ ### ` new TextDecoder([encoding[, options]]) `
1270+
1271+ * ` encoding ` {string} Identifies the ` encoding ` that this ` TextDecoder ` instance
1272+ supports. ** Default:** ` 'utf-8' ` .
1273+ * ` options ` {Object}
1274+ * ` fatal ` {boolean} ` true ` if decoding failures are fatal.
1275+ This option is not supported when ICU is disabled
1276+ (see [ Internationalization] [ ] ). ** Default:** ` false ` .
1277+ * ` ignoreBOM ` {boolean} When ` true ` , the ` TextDecoder ` will include the byte
1278+ order mark in the decoded result. When ` false ` , the byte order mark will
1279+ be removed from the output. This option is only used when ` encoding ` is
1280+ ` 'utf-8' ` , ` 'utf-16be' ` , or ` 'utf-16le' ` . ** Default:** ` false ` .
1281+
1282+ Creates a new ` TextDecoder ` instance. The ` encoding ` may specify one of the
1283+ supported encodings or an alias.
1284+
1285+ The ` TextDecoder ` class is also available on the global object.
1286+
1287+ ### ` textDecoder.decode([input[, options]]) `
1288+
1289+ * ` input ` {ArrayBuffer|DataView|TypedArray} An ` ArrayBuffer ` , ` DataView ` , or
1290+ ` TypedArray ` instance containing the encoded data.
1291+ * ` options ` {Object}
1292+ * ` stream ` {boolean} ` true ` if additional chunks of data are expected.
1293+ ** Default:** ` false ` .
1294+ * Returns: {string}
1295+
1296+ Decodes the ` input ` and returns a string. If ` options.stream ` is ` true ` , any
1297+ incomplete byte sequences occurring at the end of the ` input ` are buffered
1298+ internally and emitted after the next call to ` textDecoder.decode() ` .
1299+
1300+ If ` textDecoder.fatal ` is ` true ` , decoding errors that occur will result in a
1301+ ` TypeError ` being thrown.
1302+
1303+ ### ` textDecoder.encoding `
1304+
1305+ * Type: {string}
1306+
1307+ The encoding supported by the ` TextDecoder ` instance.
1308+
1309+ ### ` textDecoder.fatal `
1310+
1311+ * Type: {boolean}
1312+
1313+ The value will be ` true ` if decoding errors result in a ` TypeError ` being
1314+ thrown.
1315+
1316+ ### ` textDecoder.ignoreBOM `
1317+
1318+ * Type: {boolean}
1319+
1320+ The value will be ` true ` if the decoding result will include the byte order
1321+ mark.
11961322
11971323## Class: ` TextDecoderStream `
11981324
@@ -1214,7 +1340,51 @@ A browser-compatible implementation of [`TextDecoderStream`][].
12141340added: v11.0.0
12151341-->
12161342
1217- The WHATWG ` TextEncoder ` class. See the [ ` TextEncoder ` ] [ ] section.
1343+ An implementation of the [ WHATWG Encoding Standard] [ ] ` TextEncoder ` API. All
1344+ instances of ` TextEncoder ` only support UTF-8 encoding.
1345+
1346+ ``` js
1347+ const encoder = new TextEncoder ();
1348+ const uint8array = encoder .encode (' this is some data' );
1349+ ```
1350+
1351+ The ` TextEncoder ` class is also available on the global object.
1352+
1353+ ### ` textEncoder.encode([input]) `
1354+
1355+ * ` input ` {string} The text to encode. ** Default:** an empty string.
1356+ * Returns: {Uint8Array}
1357+
1358+ UTF-8 encodes the ` input ` string and returns a ` Uint8Array ` containing the
1359+ encoded bytes.
1360+
1361+ ### ` textEncoder.encodeInto(src, dest) `
1362+
1363+ <!-- YAML
1364+ added: v12.11.0
1365+ -->
1366+
1367+ * ` src ` {string} The text to encode.
1368+ * ` dest ` {Uint8Array} The array to hold the encode result.
1369+ * Returns: {Object}
1370+ * ` read ` {number} The read Unicode code units of src.
1371+ * ` written ` {number} The written UTF-8 bytes of dest.
1372+
1373+ UTF-8 encodes the ` src ` string to the ` dest ` Uint8Array and returns an object
1374+ containing the read Unicode code units and written UTF-8 bytes.
1375+
1376+ ``` js
1377+ const encoder = new TextEncoder ();
1378+ const src = ' this is some data' ;
1379+ const dest = new Uint8Array (10 );
1380+ const { read , written } = encoder .encodeInto (src, dest);
1381+ ```
1382+
1383+ ### ` textEncoder.encoding `
1384+
1385+ * Type: {string}
1386+
1387+ The encoding supported by the ` TextEncoder ` instance. Always set to ` 'utf-8' ` .
12181388
12191389## Class: ` TextEncoderStream `
12201390
@@ -1480,9 +1650,11 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
14801650[ CommonJS modules ] : modules.md
14811651[ ECMAScript module ] : esm.md
14821652[ HTML Standard ] : https://html.spec.whatwg.org/multipage/workers.html
1653+ [ Internationalization ] : intl.md
14831654[ Navigator API ] : https://html.spec.whatwg.org/multipage/system-state.html#the-navigator-object
14841655[ RFC 5646 ] : https://www.rfc-editor.org/rfc/rfc5646.txt
14851656[ Refable protocol ] : process.md#processrefmayberefable
1657+ [ WHATWG Encoding Standard ] : https://encoding.spec.whatwg.org/
14861658[ Web Crypto API ] : webcrypto.md
14871659[ `--experimental-eventsource` ] : cli.md#--experimental-eventsource
14881660[ `--localstorage-file` ] : cli.md#--localstorage-filefile
@@ -1514,9 +1686,7 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
15141686[ `Request` ] : #class-request
15151687[ `Response` ] : #class-response
15161688[ `TextDecoderStream` ] : webstreams.md#class-textdecoderstream
1517- [ `TextDecoder` ] : util.md#class-utiltextdecoder
15181689[ `TextEncoderStream` ] : webstreams.md#class-textencoderstream
1519- [ `TextEncoder` ] : util.md#class-utiltextencoder
15201690[ `TransformStreamDefaultController` ] : webstreams.md#class-transformstreamdefaultcontroller
15211691[ `TransformStream` ] : webstreams.md#class-transformstream
15221692[ `URLPattern` ] : url.md#class-urlpattern
0 commit comments