Blame: 4-binary/02-text-decoder/article.md - javascript-tutorial/en.javascript.info

javascript-tutorial / en.javascript.info UNCLAIMED

Modern JavaScript Tutorial

0 0 0 HTML

drafts 2019-03-18 11:36:08 +03:00			`# TextDecoder and TextEncoder`
binary draft 2019-03-17 20:05:02 +03:00
up 2019-03-20 15:09:06 +03:00			`What if the binary data is actually a string? For instance, we received a file with textual data.`
binary draft 2019-03-17 20:05:02 +03:00
Remove extra article 2019-07-04 15:24:03 +03:00			`The build-in [TextDecoder](https://encoding.spec.whatwg.org/#interface-textdecoder) object allows to read the value into an actual JavaScript string, given the buffer and the encoding.`
binary draft 2019-03-17 20:05:02 +03:00
			`We first need to create it:`
			```js
			`let decoder = new TextDecoder([label], [options]);`
			```

up 2019-03-20 15:09:06 +03:00			- `label` -- the encoding, `utf-8` by default, but `big5`, `windows-1251` and many other are also supported.
binary draft 2019-03-17 20:05:02 +03:00			- `options` -- optional object:
up 2019-03-20 15:09:06 +03:00			- `fatal` -- boolean, if `true` then throw an exception for invalid (non-decodable) characters, otherwise (default) replace them with character `\uFFFD`.
Replace unicode with Unicode all over the book 2020-12-07 18:05:47 +02:00			- `ignoreBOM` -- boolean, if `true` then ignore BOM (an optional byte-order Unicode mark), rarely needed.
binary draft 2019-03-17 20:05:02 +03:00
			`...And then decode:`

			```js
			`let str = decoder.decode([input], [options]);`
			```

			- `input` -- `BufferSource` to decode.
			- `options` -- optional object:
			- `stream` -- true for decoding streams, when `decoder` is called repeatedly with incoming chunks of data. In that case a multi-byte character may occasionally split between chunks. This options tells `TextDecoder` to memorize "unfinished" characters and decode them when the next chunk comes.

			`For instance:`

			```js run
			`let uint8Array = new Uint8Array([72, 101, 108, 108, 111]);`

			`alert( new TextDecoder().decode(uint8Array) ); // Hello`
			```


			```js run
			`let uint8Array = new Uint8Array([228, 189, 160, 229, 165, 189]);`

			`alert( new TextDecoder().decode(uint8Array) ); // 你好`
			```

up 2019-03-20 15:09:06 +03:00			`We can decode a part of the buffer by creating a subarray view for it:`
binary draft 2019-03-17 20:05:02 +03:00

			```js run
			`let uint8Array = new Uint8Array([0, 72, 101, 108, 108, 111, 0]);`

			`// the string is in the middle`
			`// create a new view over it, without copying anything`
			`let binaryString = uint8Array.subarray(1, -1);`

			`alert( new TextDecoder().decode(binaryString) ); // Hello`
			```

			`## TextEncoder`

up 2019-03-20 15:09:06 +03:00			`[TextEncoder](https://encoding.spec.whatwg.org/#interface-textencoder) does the reverse thing -- converts a string into bytes.`
binary draft 2019-03-17 20:05:02 +03:00
			`The syntax is:`

minor fixes 2020-01-27 15:24:23 +09:00			```js
binary draft 2019-03-17 20:05:02 +03:00			`let encoder = new TextEncoder();`
			```

			`The only encoding it supports is "utf-8".`

			`It has two methods:`
			- `encode(str)` -- returns `Uint8Array` from a string.
			- `encodeInto(str, destination)` -- encodes `str` into `destination` that must be `Uint8Array`.

			```js run
			`let encoder = new TextEncoder();`

			`let uint8Array = encoder.encode("Hello");`
			`alert(uint8Array); // 72,101,108,108,111`
			```