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