Skip to content

Commit d11c577

Browse files
committed
doc: swap util.TextDecoder and util.TextEncoder with globals
Signed-off-by: LiviaMedeiros <livia@cirno.name>
1 parent 57eda16 commit d11c577

2 files changed

Lines changed: 178 additions & 178 deletions

File tree

‎doc/api/globals.md‎

Lines changed: 174 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1192,7 +1192,133 @@ only if the Node.js binary was compiled with including support for the
11921192
added: 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`][].
12141340
added: 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

Comments
 (0)