Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

TypedArray: buffer, offset, dimensione in byte e numero di elementi

Distingui l’intero buffer dall’intervallo di byte e dal numero di elementi di una vista, e scopri che cosa restituiscono i getter dopo un ridimensionamento o un distacco.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

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

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

Un’istanza come Uint16Array è una vista su un buffer. TypedArray indica la famiglia di tipi: non esiste un costruttore globale con questo nome da invocare direttamente. Le quattro proprietà sono ereditate e hanno un getter ma non un setter. Invocare uno di questi getter su un oggetto che non è un array tipizzato genera TypeError. view.length non è Uint16Array.length, che indica il numero di parametri dichiarati del costruttore.

view.buffer restituisce lo stesso oggetto ArrayBuffer o SharedArrayBuffer sottostante, non una copia. view.byteOffset indica dove inizia la vista rispetto all’inizio del buffer e view.byteLength ne indica la dimensione, in byte in entrambi i casi. view.length conta gli elementi. Se entrambe le letture si riferiscono alla stessa dimensione della vista, vale view.byteLength === view.length * view.BYTES_PER_ELEMENT. I getter vengono chiamati separatamente: se un altro agente espande il SharedArrayBuffer sottostante tra le due letture, i getter di una vista a lunghezza adattiva possono rilevare dimensioni diverse e il confronto può restituire false. view.buffer.byteLength misura l’intero buffer, non solo la vista.

In new Uint16Array(buffer, byteOffset, length), il secondo argomento è in byte e il terzo in elementi. Un offset non allineato o un intervallo che oltrepassa il buffer genera RangeError. Le scritture sono visibili nelle viste sovrapposte sullo stesso buffer. Passare una vista non nasconde gli altri byte: per esporre solo un intervallo valido, copiane i byte in un buffer separato.

Su un buffer di dimensione fissa, omettere length copre il resto del buffer, che deve contenere un numero intero di elementi. Su un ArrayBuffer ridimensionabile o un SharedArrayBuffer espandibile, omettere length o passare undefined crea una vista a lunghezza adattiva: conta gli elementi interi che trovano spazio a partire dall’offset. Un numero di elementi esplicito fissa la lunghezza della vista.

Ridurre il buffer può portare la vista fuori dai limiti; ingrandirlo di nuovo può farla rientrare. Quando la vista è fuori dai limiti o il suo ArrayBuffer è stato distaccato (per esempio durante un trasferimento), tutti e tre i getter numerici restituiscono 0, ma buffer restituisce ancora lo stesso oggetto. Una vista vuota valida può avere un offset diverso da zero. Ridimensionamento ed espansione sono specificati in ECMAScript 2024; verifica che siano supportati nell’ambiente di esecuzione di destinazione.

Esempi

{
  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]));
}

Risultato

true 4 6 3 16
513

La vista parte dal byte 4 e copre tre elementi da due byte, cioè 6 dei 16 byte. La scrittura all’indice 0 è visibile all’indice 2 della vista sull’intero buffer.

Lezioni correlate

  • JavaScript · Lezione 2 · Avanzato · Versione: 4

Fonti