Encoding

As interfaces TextEncoder e TextDecoder do Azion Runtime convertem strings em bytes e bytes em strings. Um TextEncoder transforma uma string em bytes UTF-8, e um TextDecoder transforma bytes de volta em uma string de code points. Para mais informações, consulte TextEncoder e TextDecoder na MDN Web Docs.

nota — Com azion dev, as duas mensagens de erro diferem das mensagens de uma function após o deploy listadas em Erros: um rótulo não suportado lança RangeError: The "nope" encoding is not supported, e um decoder fatal lança TypeError: The encoded data was not valid for encoding utf-8.

Construtores

O construtor TextEncoder() retorna um encoder que produz bytes UTF-8. Ele não recebe parâmetros:

let encoder = new TextEncoder();

O construtor TextDecoder() retorna um decoder para o encoding que utfLabel indica:

let decoder = new TextDecoder(utfLabel, options);

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`utfLabel`	String	Não	`utf-8`	Rótulo do encoding a decodificar, como `utf-8` ou `iso-8859-1`.
`options`	Object	Não	—	Opções do decoder: `fatal` e `ignoreBOM`.

O objeto options aceita estas propriedades:

Opção	Tipo	Descrição
`fatal`	Boolean	Quando é `true`, `decode()` lança um `TypeError` ao receber bytes que não são válidos no encoding.
`ignoreBOM`	Boolean	Opção de byte order mark (BOM) do decoder. É `false` quando a opção não é definida.

O decoder aceita estes rótulos. A propriedade encoding do decoder informa o nome do encoding em que cada rótulo resulta:

Rótulo	`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`

Por exemplo, um decoder criado com iso-8859-1 decodifica os bytes [0x6f, 0x6c, 0xe1] como olá.

Propriedades

Propriedade	Interface	Tipo	Descrição
`encoding`	`TextEncoder`	String	Encoding do encoder: `utf-8`.
`encoding`	`TextDecoder`	String	Encoding em que o rótulo resultou, como `windows-1252` para `latin1`.
`fatal`	`TextDecoder`	Boolean	Valor da opção `fatal`.
`ignoreBOM`	`TextDecoder`	Boolean	Valor da opção `ignoreBOM`.

Métodos

Método	Descrição
`encoder.encode(string)`	Codifica `string`, uma USVString que contém o texto, e retorna os bytes UTF-8 dela como um `Uint8Array`. `encode('Azion')` retorna `[65, 122, 105, 111, 110]`.
`encoder.encodeInto(string, uint8Array)`	Grava os bytes UTF-8 de `string` em `uint8Array` e retorna um objeto com `read` e `written`.
`decoder.decode(buffer, options)`	Decodifica `buffer` com o encoding do decoder e retorna o texto como uma string.

O método encodeInto() não grava um caractere cujos bytes não cabem no array. Codificar olá em um Uint8Array de 3 bytes retorna read 2 e written 2 e deixa o array como [111, 108, 0], porque á ocupa dois bytes.

O método decode() recebe os dois parâmetros em qualquer uma destas três formas:

JavaScript

01decoder.decode(buffer, options);

02decoder.decode(buffer);

03decoder.decode();

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`buffer`	`ArrayBuffer` ou `ArrayBufferView`	Não	—	Bytes do texto a decodificar. Chamado sem ele, `decode()` retorna uma string vazia.
`options`	Object	Não	—	Opções de decodificação, com uma propriedade: `stream`.

A opção stream é um Boolean cujo padrão é false. Defina-a como true quando você decodifica dados em partes e mais dados chegam em chamadas posteriores de decode(). Defina-a como false, ou omita-a, para a parte final e para dados que não estão divididos. Um decoder que recebe os dois primeiros bytes de um caractere de quatro bytes com stream: true retorna o caractere completo quando a chamada seguinte passa os dois bytes restantes.

Erros

Erro	Causa	O que fazer
`RangeError: The encoding label provided ('nope') is invalid.`	`new TextDecoder()` recebeu um rótulo que não suporta, neste caso `nope`.	Passe um rótulo suportado, como um dos rótulos da tabela de rótulos.
`TypeError: The encoded data is not valid`	Um decoder criado com `fatal: true` recebeu bytes que não são válidos no encoding dele.	Verifique se os bytes correspondem ao encoding que o rótulo indica.