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

CKTIS / JavaScript

TypedArray: buffer, deslocamento, tamanho em bytes e número de elementos

Distingue o buffer completo do intervalo de bytes e do número de elementos da vista. Descobre o que as propriedades devolvem após um redimensionamento ou um destacamento.

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

Sintaxe

view.buffer
view.byteOffset
view.byteLength
view.length

new Uint16Array(buffer)
new Uint16Array(buffer, byteOffset)
new Uint16Array(buffer, byteOffset, length)

Uma instância como Uint16Array é uma vista sobre um buffer. TypedArray designa a família de tipos; não existe um construtor global com esse nome que se possa invocar diretamente. As quatro propriedades são herdadas e têm getter, mas não setter. Invocar um destes getters sobre um objeto que não é um array tipado lança TypeError. view.length não é Uint16Array.length, que indica o número de parâmetros declarados do construtor.

view.buffer devolve o mesmo objeto ArrayBuffer ou SharedArrayBuffer subjacente, não uma cópia. view.byteOffset indica onde a vista começa em relação ao início do buffer e view.byteLength indica o seu tamanho, ambos em bytes. view.length conta elementos. Se ambas as leituras corresponderem ao mesmo tamanho da vista, verifica-se view.byteLength === view.length * view.BYTES_PER_ELEMENT. Os getters são invocados separadamente: se outro agente expandir o SharedArrayBuffer subjacente entre as leituras, os getters de uma vista de comprimento adaptável podem observar tamanhos diferentes e a comparação pode devolver false. view.buffer.byteLength mede o buffer completo, não apenas a vista.

Em new Uint16Array(buffer, byteOffset, length), o segundo argumento é dado em bytes e o terceiro em elementos. Um deslocamento desalinhado ou um intervalo que exceda o buffer lança RangeError. As escritas são visíveis nas vistas sobrepostas do mesmo buffer. Passar uma vista não oculta os restantes bytes: para expor apenas um intervalo válido, copia os seus bytes para um buffer separado.

Num buffer de tamanho fixo, omitir length abrange o restante espaço, que tem de conter um número inteiro de elementos. Num ArrayBuffer redimensionável ou num SharedArrayBuffer expansível, omitir length ou passar undefined cria uma vista de comprimento adaptável: conta os elementos inteiros que cabem a partir do seu deslocamento. Indicar explicitamente o número de elementos fixa o comprimento da vista.

Reduzir o buffer pode deixar a vista fora dos limites; voltar a aumentá-lo pode fazê-la caber de novo. Enquanto a vista estiver fora dos limites, ou após o destacamento do seu ArrayBuffer (por exemplo, numa transferência), os três getters numéricos devolvem 0, mas buffer continua a devolver o mesmo objeto. Uma vista vazia válida pode ter um deslocamento diferente de zero. O redimensionamento e a expansão estão especificados em ECMAScript 2024; confirma o suporte no ambiente de execução de destino.

Exemplos

{
  const buffer = new ArrayBuffer(16);
  const view = new Uint16Array(buffer, 4, 3);

  console.log([
    view.buffer === buffer,
    view.byteOffset,
    view.byteLength,
    view.length,
    view.buffer.byteLength,
  ].join(" "));

  view[0] = 513;
  console.log(String(new Uint16Array(buffer)[2]));
}

Resultado

true 4 6 3 16
513

A vista começa no byte 4 e abrange três elementos de dois bytes, ou seja, 6 dos 16 bytes. A escrita no índice 0 é visível no índice 2 da vista sobre o buffer completo.

Lições relacionadas

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

Fontes