TypedArray

Der TypedArray-Konstruktor (oft als %TypedArray% bezeichnet, um seine "intrinsische" Natur zu kennzeichnen, da er keiner globalen, in einem JavaScript-Programm sichtbaren Entität entspricht) dient als gemeinsame Superklasse aller TypedArray-Subklassen. Stellen Sie sich %TypedArray% als eine "abstrakte Klasse" vor, die eine gemeinsame Schnittstelle von Dienstprogrammmethoden für alle getypten Array-Subklassen bereitstellt. Dieser Konstruktor ist nicht direkt zugänglich: Es gibt keine globale TypedArray-Eigenschaft. Er ist nur über Object.getPrototypeOf(Int8Array) und ähnliches zugänglich.

Wenn eine Instanz einer TypedArray-Subklasse erstellt wird (z.B. Int8Array), wird intern im Speicher ein Array-Puffer erstellt oder, wenn ein ArrayBuffer-Objekt als Konstruktorargument angegeben wird, wird dieser ArrayBuffer stattdessen verwendet. Die Pufferadresse wird als interne Eigenschaft der Instanz gespeichert und alle Methoden von %TypedArray%.prototype setzen und holen Werte basierend auf dieser Array-Pufferadresse.

Alle getypten Arrays arbeiten mit ArrayBuffers, bei denen man die genaue Byte-Repräsentation jedes Elements beobachten kann, sodass es wichtig ist, wie die Zahlen im Binärformat kodiert sind.

• Ungesigned Integer Arrays (Uint8Array, Uint16Array, Uint32Array, und BigUint64Array) speichern die Nummer direkt im Binärformat.
• Signed Integer Arrays (Int8Array, Int16Array, Int32Array, und BigInt64Array) speichern die Nummer unter Verwendung von Zweierkomplement.
• Fließkomma Arrays (Float16Array, Float32Array, und Float64Array) speichern die Nummer unter Verwendung des IEEE 754 Fließkommaformats. Die Number Referenz enthält weitere Informationen über das exakte Format. JavaScript-Zahlen verwenden standardmäßig das Fließkommaformat mit doppelter Genauigkeit, was dem Float64Array entspricht. Float32Array verwendet 23 (anstatt 52) Bits für die Mantisse und 8 (anstatt 11) Bits für den Exponenten. Float16Array verwendet 10 Bits für die Mantisse und 5 Bits für den Exponenten. Beachten Sie, dass die Spezifikation vorschreibt, dass alle NaN-Werte die gleiche Bitkodierung verwenden müssen, das genaue Bitmuster jedoch implementierungsabhängig ist.
• Uint8ClampedArray ist ein Sonderfall. Es speichert die Nummer binär wie Uint8Array, aber wenn Sie eine Zahl außerhalb des Bereichs speichern, wird die Nummer auf den Bereich von 0 bis 255 durch mathematischen Wert geklammert, anstatt die bedeutendsten Bits abzutrennen.

Alle getypten Arrays außer Int8Array, Uint8Array und Uint8ClampedArray speichern jedes Element unter Verwendung mehrerer Bytes. Diese Bytes können entweder vom bedeutendsten zum wenigstbedeutendsten (big-endian) oder vom wenigstbedeutendsten zum bedeutendsten (little-endian) geordnet sein. Siehe Endianness für mehr Erklärung. Getypte Arrays verwenden immer die native Byte-Reihenfolge der Plattform. Wenn Sie die Byte-Reihenfolge beim Schreiben und Lesen von Puffern angeben möchten, sollten Sie stattdessen ein DataView verwenden.

Beim Schreiben in diese getypten Arrays werden Werte, die außerhalb des darstellbaren Bereichs liegen, normalisiert.

• Alle Integer-Arrays (außer Uint8ClampedArray) verwenden Fixed-Width Number Conversion, die zunächst den Dezimalteil der Nummer löscht und dann die niedrigsten Bits nimmt.
• Uint8ClampedArray klammert die Nummer zunächst auf den Bereich 0 bis 255 (Werte größer als 255 werden zu 255, und Werte kleiner als 0 werden zu 0). Anschließend wird das Ergebnis gerundet (anstatt es abzurunden) auf die nächste ganze Zahl, mit half-to-even; das bedeutet, wenn die Zahl genau zwischen zwei ganzen Zahlen liegt, rundet sie auf die nächste gerade ganze Zahl. Zum Beispiel wird 0.5 zu 0, 1.5 zu 2, und 2.5 zu 2.
• Float16Array und Float32Array führen ein "round to even" durch, um 64-Bit Fließkommazahlen in 32-Bit und 16-Bit zu konvertieren. Dies ist der gleiche Algorithmus, wie er von Math.fround() und Math.f16round() bereitgestellt wird.

Wenn ein TypedArray als Ansicht eines skalierbaren Puffers erstellt wird, hat das Verändern der Größe des zugrundeliegenden Puffers unterschiedliche Auswirkungen auf die Größe des TypedArray, abhängig davon, ob das TypedArray als längenverfolgend konstruiert wurde.

Wenn ein getyptes Array ohne spezifische Größe erstellt wird, indem der dritte Parameter weggelassen oder undefined übergeben wird, wird das getypte Array längenverfolgend und passt sich automatisch an den zugrunde liegenden buffer an, wenn dieser vergrößert wird:

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2

buffer.resize(12);

console.log(float32.byteLength); // 12
console.log(float32.length); // 3

Wenn ein getyptes Array mit einer bestimmten Größe unter Verwendung des dritten length-Parameters erstellt wird, wird es nicht vergrößert, um den buffer zu enthalten, wenn letzterer wächst:

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 0, 2);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0, the initial value

buffer.resize(12);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0, the initial value

Wenn ein buffer verkleinert wird, kann das anzeigende getypte Array außer Grenzen geraten, in welchem Fall die beobachtete Größe des typisierten Arrays auf 0 abnimmt. Dies ist der einzige Fall, in dem sich die Länge eines nicht längenverfolgenden getypten Arrays ändern kann.

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 0, 2);

buffer.resize(7);

console.log(float32.byteLength); // 0
console.log(float32.length); // 0
console.log(float32[0]); // undefined

Wenn Sie dann den buffer erneut vergrößern, um das getypte Array wieder in Reichweite zu bringen, wird die Größe des typisierten Arrays auf den ursprünglichen Wert wiederhergestellt.

buffer.resize(8);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0 - back in bounds again!

Das gleiche kann auch für längenverfolgende getypte Arrays passieren, wenn der Buffer über den byteOffset hinaus verkleinert wird.

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 4);
// float32 is length-tracking, but it only extends from the 4th byte
// to the end of the buffer, so if the buffer is resized to be shorter
// than 4 bytes, the typed array will become out of bounds
buffer.resize(3);
console.log(float32.byteLength); // 0

Dieses Objekt kann nicht direkt instanziiert werden — ein Konstrukt mit new auszuführen, wirft einen TypeError.

new (Object.getPrototypeOf(Int8Array))();
// TypeError: Abstract class TypedArray not directly constructable

Stattdessen erstellen Sie eine Instanz eines typisierten Arrays eines bestimmten Typs, wie ein Int8Array oder ein BigInt64Array. Diese Objekte haben alle eine gemeinsame Syntax für ihre Konstruktoren:

new TypedArray()
new TypedArray(length)
new TypedArray(typedArray)
new TypedArray(object)

new TypedArray(buffer)
new TypedArray(buffer, byteOffset)
new TypedArray(buffer, byteOffset, length)

Dabei ist TypedArray ein Konstruktor für einen der konkreten Typen.

typedArray

Wenn mit einer Instanz einer TypedArray-Unterklasse aufgerufen, wird das typedArray in ein neues typisiertes Array kopiert. Für einen nicht-bigint TypedArray-Konstruktor kann der typedArray-Parameter nur von einem der nicht-bigint Typen (wie Int32Array) sein. Ebenso kann für einen bigint TypedArray-Konstruktor (BigInt64Array oder BigUint64Array) der typedArray-Parameter nur von einem der bigint Typen sein. Jeder Wert in typedArray wird vor dem Kopieren in das neue Array in den entsprechenden Typ des Konstruktors konvertiert. Die Länge des neuen typisierten Arrays wird die gleiche sein wie die Länge des typedArray-Arguments.

object

Wenn mit einem Objekt aufgerufen, das keine Instanz von TypedArray ist, wird ein neues typisiertes Array genauso erstellt wie mit der Methode TypedArray.from().

length Optional

Wenn mit einem Nicht-Objekt aufgerufen, wird der Parameter als Zahl behandelt, die die Länge des typisierten Arrays angibt. Ein interner Array-Puffer wird im Speicher erstellt, dessen Größe length multipliziert mit BYTES_PER_ELEMENT Bytes beträgt und mit Nullen gefüllt wird. Wenn alle Parameter weggelassen werden, ist dies gleichbedeutend mit der Verwendung von 0 als length.

buffer, byteOffset Optional, length Optional

Wenn mit einer Instanz von ArrayBuffer oder SharedArrayBuffer und optional einem byteOffset und einem length Argument aufgerufen, wird eine neue typisierte Array-Ansicht erstellt, die den angegebenen Puffer betrachtet. Die byteOffset (in Bytes) und length (in Anzahl der Elemente, die jeweils BYTES_PER_ELEMENT Bytes belegen) Parameter spezifizieren den Speicherbereich, der durch die typisierte Array-Ansicht freigelegt wird. Wenn beide weggelassen werden, wird der gesamte buffer betrachtet; wenn nur length weggelassen wird, wird der Rest des buffer ab dem byteOffset betrachtet. Wenn length weggelassen wird, wird das typisierte Array längenverfolgend.

Alle TypedArray-Subklassenkonstruktoren arbeiten auf die gleiche Weise. Sie alle würden die folgenden Ausnahmen auslösen:

TypeError

Wird in einem der folgenden Fälle ausgelöst:

• Ein typedArray wird übergeben, aber es ist ein bigint Typ, während der aktuelle Konstruktor nicht, oder umgekehrt.
• Ein typedArray wird übergeben, aber der Puffer, den es betrachtet, ist getrennt, oder ein getrennter buffer wird direkt übergeben.

RangeError

Wird in einem der folgenden Fälle ausgelöst:

• Die Länge des neuen typisierten Arrays ist zu groß.
• Die Länge des buffer (wenn der length Parameter nicht angegeben ist) oder byteOffset ist kein ganzzahliges Vielfaches der Elementgröße des neuen typisierten Arrays.
• byteOffset ist kein gültiger Array-Index (eine Ganzzahl zwischen 0 und 2⁵³ - 1).
• Beim Erstellen einer Ansicht aus einem Puffer befinden sich die Grenzen außerhalb des Puffers. Mit anderen Worten, byteOffset + length * TypedArray.BYTES_PER_ELEMENT > buffer.byteLength.

Diese Eigenschaften sind auf dem TypedArray-Konstruktorobjekt definiert und werden somit von allen TypedArray-Subklassenkonstruktoren gemeinsam genutzt.

TypedArray[Symbol.species]

Die Konstruktorfunktion, die verwendet wird, um abgeleitete Objekte zu erstellen.

Alle TypedArray-Subklassen haben auch die folgenden statischen Eigenschaften:

TypedArray.BYTES_PER_ELEMENT

Gibt einen Zahlenwert der Elementgröße für die verschiedenen TypedArray-Objekte zurück.

Diese Methoden sind auf dem TypedArray-Konstruktorobjekt definiert und werden somit von allen TypedArray-Subklassenkonstruktoren gemeinsam genutzt.

TypedArray.from()

Erstellt ein neues TypedArray aus einem array-ähnlichen oder iterierbaren Objekt. Siehe auch Array.from().

TypedArray.of()

Erstellt ein neues TypedArray mit einer variablen Anzahl von Argumenten. Siehe auch Array.of().

Diese Eigenschaften sind auf TypedArray.prototype definiert und werden von allen TypedArray-Subklasseninstanzen gemeinsam genutzt.

TypedArray.prototype.buffer

Gibt den ArrayBuffer zurück, der durch das typisierte Array referenziert wird.

TypedArray.prototype.byteLength

Gibt die Länge (in Bytes) des typisierten Arrays zurück.

TypedArray.prototype.byteOffset

Gibt den Offset (in Bytes) des typisierten Arrays vom Anfang seines ArrayBuffer zurück.

TypedArray.prototype.constructor

Die Konstruktorfunktion, die das Instanzobjekt erstellt hat. TypedArray.prototype.constructor ist die versteckte TypedArray-Konstruktorfunktion, aber jede getypte Array-Subklasse definiert auch ihre eigene constructor-Eigenschaft.

TypedArray.prototype.length

Gibt die Anzahl der im typisierten Array gehaltenen Elemente zurück.

TypedArray.prototype[Symbol.toStringTag]

Der Anfangswert der TypedArray.prototype[Symbol.toStringTag] Eigenschaft ist ein Getter, der dieselbe Zeichenkette wie der Name des typisierten Array-Konstruktors zurückgibt. Er gibt undefined zurück, wenn der Wert von this nicht eine der typisierten Array-Unterklassen ist. Diese Eigenschaft wird in Object.prototype.toString() verwendet. Da TypedArray jedoch auch seine eigene toString() Methode hat, wird diese Eigenschaft nicht verwendet, es sei denn, Sie rufen Object.prototype.toString.call() mit einem typisierten Array als thisArg auf.

Alle TypedArray-Subklassen haben auch die folgenden Instanzeigenschaften:

TypedArray.prototype.BYTES_PER_ELEMENT

Gibt einen Zahlenwert der Elementgröße für die verschiedenen TypedArray-Objekte zurück.

Diese Methoden sind auf dem TypedArray Prototype-Objekt definiert und werden somit von allen TypedArray Subklasseninstanzen gemeinsam genutzt.

TypedArray.prototype.at()

Nimmt einen ganzzahligen Wert und gibt das Element an diesem Index zurück. Diese Methode erlaubt negative Ganzzahlen, die ab dem letzten Element zählen.

TypedArray.prototype.copyWithin()

Kopiert eine Sequenz von Array-Elementen innerhalb des Arrays. Siehe auch Array.prototype.copyWithin().

TypedArray.prototype.entries()

Gibt ein neues Array-Iterator-Objekt zurück, das die Schlüssel/Wert-Paare für jeden Index im Array enthält. Siehe auch Array.prototype.entries().

TypedArray.prototype.every()

Prüft, ob alle Elemente im Array den durch eine Funktion bereitgestellten Test bestehen. Siehe auch Array.prototype.every().

TypedArray.prototype.fill()

Füllt alle Elemente eines Arrays von einem Startindex bis zu einem Endindex mit einem statischen Wert. Siehe auch Array.prototype.fill().

TypedArray.prototype.filter()

Erstellt ein neues Array mit allen Elementen dieses Arrays, für die die bereitgestellte Filterfunktion true zurückgibt. Siehe auch Array.prototype.filter().

TypedArray.prototype.find()

Gibt das erste Element im Array zurück, das eine bereitgestellte Testfunktion erfüllt, oder undefined, wenn kein geeignetes Element gefunden wurde. Siehe auch Array.prototype.find().

TypedArray.prototype.findIndex()

Gibt den ersten Indexwert im Array zurück, der ein Element hat, das eine bereitgestellte Testfunktion erfüllt, oder -1, wenn kein geeignetes Element gefunden wurde. Siehe auch Array.prototype.findIndex().

TypedArray.prototype.findLast()

Gibt den Wert des letzten Elements im Array zurück, das eine bereitgestellte Testfunktion erfüllt, oder undefined, wenn kein geeignetes Element gefunden wurde. Siehe auch Array.prototype.findLast().

TypedArray.prototype.findLastIndex()

Gibt den Index des letzten Elements im Array zurück, das eine bereitgestellte Testfunktion erfüllt, oder -1, wenn kein geeignetes Element gefunden wurde. Siehe auch Array.prototype.findLastIndex().

TypedArray.prototype.forEach()

Ruft eine Funktion für jedes Element im Array auf. Siehe auch Array.prototype.forEach().

TypedArray.prototype.includes()

Bestimmt, ob ein typisiertes Array ein bestimmtes Element beinhaltet und gibt dementsprechend true oder false zurück. Siehe auch Array.prototype.includes().

TypedArray.prototype.indexOf()

Gibt den ersten (kleinsten) Index eines Elements innerhalb des Arrays zurück, der dem angegebenen Wert entspricht, oder -1, wenn keiner gefunden wurde. Siehe auch Array.prototype.indexOf().

TypedArray.prototype.join()

Verbindet alle Elemente eines Arrays zu einem String. Siehe auch Array.prototype.join().

TypedArray.prototype.keys()

Gibt einen neuen Array-Iterator zurück, der die Schlüssel für jeden Index im Array enthält. Siehe auch Array.prototype.keys().

TypedArray.prototype.lastIndexOf()

Gibt den letzten (größten) Index eines Elements innerhalb des Arrays zurück, das dem angegebenen Wert entspricht, oder -1, wenn keiner gefunden wurde. Siehe auch Array.prototype.lastIndexOf().

TypedArray.prototype.map()

Erstellt ein neues Array mit den Ergebnissen des Aufrufs einer bereitgestellten Funktion bei jedem Element in diesem Array. Siehe auch Array.prototype.map().

TypedArray.prototype.reduce()

Wendet eine Funktion gegen einen Akkumulator und jeden Wert des Arrays (von links nach rechts) an, um ihn auf einen einzigen Wert zu reduzieren. Siehe auch Array.prototype.reduce().

TypedArray.prototype.reduceRight()

Wendet eine Funktion gegen einen Akkumulator und jeden Wert des Arrays (von rechts nach links) an, um ihn auf einen einzigen Wert zu reduzieren. Siehe auch Array.prototype.reduceRight().

TypedArray.prototype.reverse()

Kehrt die Reihenfolge der Elemente eines Arrays um - das erste wird zum letzten, und das letzte wird zum ersten. Siehe auch Array.prototype.reverse().

TypedArray.prototype.set()

Speichert mehrere Werte im typisierten Array, indem Werte aus einem angegebenen Array gelesen werden.

TypedArray.prototype.slice()

Extrahiert einen Abschnitt eines Arrays und gibt ein neues Array zurück. Siehe auch Array.prototype.slice().

TypedArray.prototype.some()

Gibt true zurück, wenn mindestens ein Element in diesem Array die bereitgestellte Testfunktion erfüllt. Siehe auch Array.prototype.some().

TypedArray.prototype.sort()

Sortiert die Elemente eines Arrays an Ort und Stelle und gibt das Array zurück. Siehe auch Array.prototype.sort().

TypedArray.prototype.subarray()

Gibt ein neues TypedArray aus dem gegebenen Start- und Endindex der Elemente zurück.

TypedArray.prototype.toLocaleString()

Gibt eine lokalisierte Zeichenfolge zurück, die das Array und seine Elemente repräsentiert. Siehe auch Array.prototype.toLocaleString().

TypedArray.prototype.toReversed()

Gibt ein neues Array mit den Elementen in umgekehrter Reihenfolge zurück, ohne das Original-Array zu ändern.

TypedArray.prototype.toSorted()

Gibt ein neues Array mit den sortierten Elementen in aufsteigender Reihenfolge zurück, ohne das Original-Array zu ändern.

TypedArray.prototype.toString()

Gibt eine Zeichenkette zurück, die das Array und seine Elemente repräsentiert. Siehe auch Array.prototype.toString().

TypedArray.prototype.values()

Gibt ein neues Array-Iterator-Objekt zurück, das die Werte für jeden Index im Array enthält. Siehe auch Array.prototype.values().

TypedArray.prototype.with()

Gibt ein neues Array zurück, bei dem das Element am angegebenen Index durch den angegebenen Wert ersetzt wird, ohne das Original-Array zu ändern.

TypedArray.prototype[Symbol.iterator]()

Gibt ein neues Array-Iterator-Objekt zurück, das die Werte für jeden Index im Array enthält.

Sie können Elemente im Array mit der Standard-Syntax des Array-Indizes referenzieren (d.h. unter Verwendung der Klammernotation). Allerdings, das Abrufen oder Setzen von indizierten Eigenschaften auf typisierten Arrays wird nicht in der Prototypenkette nach dieser Eigenschaft suchen, selbst wenn die Indizes außer Reichweite sind. Indizierte Eigenschaften werden den ArrayBuffer konsultieren und niemals auf Objekteigenschaften schauen. Sie können nach wie vor benannte Eigenschaften verwenden, genau wie bei allen Objekten.

// Setting and getting using standard array syntax
const int16 = new Int16Array(2);
int16[0] = 42;
console.log(int16[0]); // 42

// Indexed properties on prototypes are not consulted (Fx 25)
Int8Array.prototype[20] = "foo";
new Int8Array(32)[20]; // 0
// even when out of bound
Int8Array.prototype[20] = "foo";
new Int8Array(8)[20]; // undefined
// or with negative integers
Int8Array.prototype[-1] = "foo";
new Int8Array(8)[-1]; // undefined

// Named properties are allowed, though (Fx 30)
Int8Array.prototype.foo = "bar";
new Int8Array(32).foo; // "bar"

TypedArrays, die nicht leer sind, können nicht eingefroren werden, da ihr zugrunde liegender ArrayBuffer durch eine andere TypedArray-Ansicht des Puffers verändert werden könnte. Das würde bedeuten, dass das Objekt niemals wirklich eingefroren wäre.

const i8 = Int8Array.of(1, 2, 3);
Object.freeze(i8);
// TypeError: Cannot freeze array buffer views with elements

Beim Konstruieren eines TypedArray als Ansicht auf einen ArrayBuffer muss das byteOffset-Argument an die Elementgröße angepasst sein; mit anderen Worten, der Offset muss ein Vielfaches von BYTES_PER_ELEMENT sein.

const i32 = new Int32Array(new ArrayBuffer(4), 1);
// RangeError: start offset of Int32Array should be a multiple of 4

const i32 = new Int32Array(new ArrayBuffer(4), 0);

Wie der byteOffset-Parameter muss die byteLength-Eigenschaft eines ArrayBuffer, das an einen TypedArray-Konstruktor übergeben wird, ein Vielfaches des BYTES_PER_ELEMENT des Konstruktors sein.

const i32 = new Int32Array(new ArrayBuffer(3));
// RangeError: byte length of Int32Array should be a multiple of 4

const i32 = new Int32Array(new ArrayBuffer(4));

• Polyfill von typisierten Arrays in core-js
• JavaScript typisierte Arrays Leitfaden
• ArrayBuffer
• DataView
• TextDecoder