Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

TextEncoder.encode e TypedArray.byteLength: contar bytes UTF-8

Codifica texto em UTF-8 e mede os bytes obtidos. Distingue essa contagem do número de unidades de código UTF-16, do número de elementos de um array tipado e do tamanho total do buffer.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

const encoder = new TextEncoder();
const bytes = encoder.encode(text);
const byteCount = bytes.byteLength;
// With no argument, encoder.encode() returns an empty Uint8Array.
// For any typed-array instance: view.byteLength

new TextEncoder().encode(text) chama um método de instância que codifica uma cadeia de texto exclusivamente em UTF-8 e devolve um novo Uint8Array. Sem argumentos, devolve um Uint8Array vazio. Cada unidade de código substituta sem par é substituída por U+FFFD, em vez de provocar um erro.

view.byteLength é uma propriedade só de leitura, não um método. Conta os bytes da vista; view.length conta os elementos e view.buffer.byteLength conta os bytes do buffer inteiro. Se a vista estiver dentro dos limites do buffer, view.byteLength é igual a view.length * view.BYTES_PER_ELEMENT. Num Uint8Array, cada elemento ocupa um byte. text.length conta unidades de código UTF-16, não bytes UTF-8. Usa bytes.byteLength para verificar um limite expresso em bytes UTF-8.

O ECMAScript 2024 define a propriedade dos arrays tipados. TextEncoder é uma API da plataforma web e a sua disponibilidade depende do ambiente de execução. Num buffer redimensionável, uma vista que acompanha o tamanho do buffer pode mudar de tamanho. A leitura de byteLength devolve 0 se o buffer estiver desassociado ou a vista estiver fora dos seus limites. Invocar o getter num objeto que não seja um array tipado lança TypeError.

Exemplos

{
  const text = "Aé🙂";
  const bytes = new TextEncoder().encode(text);
  console.log(`text.length=${text.length}; bytes.length=${bytes.length}; bytes.byteLength=${bytes.byteLength}`);
  console.log(bytes.join(","));

  const view = new Uint16Array(new ArrayBuffer(12), 2, 3);
  console.log(`view.length=${view.length}; view.byteLength=${view.byteLength}; view.buffer.byteLength=${view.buffer.byteLength}`);
}

Resultado

text.length=4; bytes.length=7; bytes.byteLength=7
65,195,169,240,159,153,130
view.length=3; view.byteLength=6; view.buffer.byteLength=12

`Aé🙂` ocupa 4 unidades de código UTF-16 e 7 bytes UTF-8. A vista `Uint16Array` tem 3 elementos de 2 bytes cada, pelo que abrange 6 dos 12 bytes do buffer.

Lições relacionadas

  • JavaScript · Lição 17 · Avançado · Versão: 4

Fontes