Encoding
The TextEncoder and TextDecoder interfaces of Azion Runtime: their constructors, properties, methods, accepted labels, and errors.
The TextEncoder and TextDecoder interfaces of Azion Runtime convert between strings and bytes. A TextEncoder turns a string into UTF-8 bytes, and a TextDecoder turns bytes back into a string of code points. For more information, refer to TextEncoder and TextDecoder on MDN Web Docs.
Constructors
The TextEncoder() constructor returns an encoder that produces UTF-8 bytes. It takes no parameters:
The TextDecoder() constructor returns a decoder for the encoding that utfLabel names:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
utfLabel | String | No | utf-8 | Label of the encoding to decode, such as utf-8 or iso-8859-1. |
options | Object | No | — | Options of the decoder: fatal and ignoreBOM. |
The options object takes these properties:
| Option | Type | Description |
|---|---|---|
fatal | Boolean | When true, decode() throws a TypeError on bytes that are not valid in the encoding. |
ignoreBOM | Boolean | Byte order mark (BOM) option of the decoder. It is false when the option is not set. |
The decoder accepts these labels. The encoding property of the decoder reports the encoding name each label resolves to:
| Label | encoding |
|---|---|
utf-8 | utf-8 |
utf-16le | utf-16le |
utf-16be | utf-16be |
latin1 | windows-1252 |
iso-8859-1 | windows-1252 |
windows-1252 | windows-1252 |
shift_jis | shift_jis |
gbk | gbk |
For example, a decoder created with iso-8859-1 decodes the bytes [0x6f, 0x6c, 0xe1] as olá.
Properties
| Property | Interface | Type | Description |
|---|---|---|---|
encoding | TextEncoder | String | Encoding of the encoder: utf-8. |
encoding | TextDecoder | String | Encoding the label resolved to, such as windows-1252 for latin1. |
fatal | TextDecoder | Boolean | Value of the fatal option. |
ignoreBOM | TextDecoder | Boolean | Value of the ignoreBOM option. |
Methods
| Method | Description |
|---|---|
encoder.encode(string) | Encodes string, a USVString that holds the text, and returns its UTF-8 bytes as a Uint8Array. encode('Azion') returns [65, 122, 105, 111, 110]. |
encoder.encodeInto(string, uint8Array) | Writes the UTF-8 bytes of string into uint8Array and returns an object with read and written. |
decoder.decode(buffer, options) | Decodes buffer with the encoding of the decoder and returns the text as a string. |
The encodeInto() method does not write a character whose bytes do not fit. Encoding olá into a 3-byte Uint8Array returns read 2 and written 2, and leaves the array as [111, 108, 0], because á takes two bytes.
The decode() method takes its two parameters in any of these three forms:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
buffer | ArrayBuffer or ArrayBufferView | No | — | Bytes of the text to decode. Called without it, decode() returns an empty string. |
options | Object | No | — | Decode options with one property, stream. |
The stream option is a Boolean that defaults to false. Set it to true when you decode data in chunks and more data follows in later calls to decode(). Set it to false, or leave it out, for the final chunk and for data that is not split. A decoder that receives the first two bytes of a four-byte character with stream: true returns the full character when the next call passes the remaining two bytes.
Errors
| Error | Cause | Fix |
|---|---|---|
RangeError: The encoding label provided ('nope') is invalid. | new TextDecoder() received a label it does not support, here nope. | Pass a supported label, such as one in the label table. |
TypeError: The encoded data is not valid | A decoder created with fatal: true received bytes that are not valid in its encoding. | Check that the bytes match the encoding the label names. |
Example
This listener decodes four UTF-8 bytes into one character, logs it, and returns it as the response body:
The function logs 𠮷 and returns this status, these headers, and this body: