TypedArray

Der TypedArray Konstruktor (oft als %TypedArray% bezeichnet, um seine "Intrinsicness" anzuzeigen, da er keinem in einem JavaScript-Programm exponierten globalen Element entspricht) dient als die gemeinsame Superklasse aller TypedArray Subklassen. Denken Sie an %TypedArray% als eine "abstrakte Klasse", die eine gemeinsame Schnittstelle von Dienstmethoden für alle typisierten Arraysubklassen bereitstellt. Dieser Konstruktor ist nicht direkt exponiert: Es gibt keine globale TypedArray Eigenschaft. Er ist nur über Object.getPrototypeOf(Int8Array) und ähnliche zugänglich.

Beim Erstellen einer Instanz einer TypedArray Subklasse (z.B. Int8Array) wird intern im Speicher ein Array-Puffer erstellt oder, wenn ein ArrayBuffer Objekt als Konstruktionsargument 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 typisierten Arrays arbeiten auf ArrayBuffers, bei denen Sie die genaue Byte-Darstellung jedes Elements sehen können. Wie die Zahlen im Binärformat codiert sind, ist daher von Bedeutung.

• Vorzeichenlose ganze Arrays (Uint8Array, Uint16Array, Uint32Array und BigUint64Array) speichern die Zahl direkt im Binärformat.
• Vorzeichenbehaftete ganze Arrays (Int8Array, Int16Array, Int32Array und BigInt64Array) speichern die Zahl mit Zweierkomplement.
• Gleitkomma-Arrays (Float16Array, Float32Array und Float64Array) speichern die Zahl im IEEE 754 Gleitkommaformat. Die Number Referenz enthält mehr Informationen über das genaue Format. JavaScript-Zahlen verwenden standardmäßig das Double-Präzisions-Gleitkommaformat, das dem Float64Array entspricht. Float32Array verwendet 23 (statt 52) Bits für die Mantisse und 8 (statt 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 verlangt, dass alle NaN Werte die gleiche Bit-Codierung verwenden, aber das genaue Bit-Muster ist implementierungsabhängig.
• Uint8ClampedArray ist ein Sonderfall. Es speichert die Zahl im Binärformat wie Uint8Array, aber wenn man eine Zahl außerhalb des Bereichs speichert, klemmt es die Zahl auf den Bereich von 0 bis 255 durch mathematischen Wert, anstatt die höchstwertigen Bits abzuschneiden.

Alle typisierten Arrays außer Int8Array, Uint8Array und Uint8ClampedArray speichern jedes Element mit mehreren Bytes. Diese Bytes können entweder von den höchstwertigen zu den niederwertigen geordnet sein (big-endian) oder von den niederwertigen zu den höchstwertigen (little-endian). Weitere Erklärungen finden Sie unter Endianness. Typisierte Arrays verwenden immer die native Byte-Reihenfolge der Plattform. Wenn Sie die Byte-Reihenfolge beim Schreiben und Lesen aus Puffs angeben möchten, sollten Sie stattdessen ein DataView verwenden.

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

• Alle ganzen Arrays (außer Uint8ClampedArray) verwenden festbreite Zahllunmwandlung, die zuerst den Dezimalteil der Zahl abschneidet und dann die niedrigsten Bits berücksichtigt.
• Uint8ClampedArray klemmt zuerst die Zahl auf den Bereich von 0 bis 255 (Werte größer als 255 werden zu 255 und Werte kleiner als 0 werden zu 0). Danach wird das Ergebnis gerundet (anstatt abgerundet) auf die nächste ganze Zahl, mit halbem zu ganzem; das bedeutet, wenn die Zahl genau zwischen zwei ganzen Zahlen liegt, wird sie auf die nächste gerade Zahl gerundet. Zum Beispiel wird 0.5 zu 0, 1.5 wird zu 2, und 2.5 wird zu 2.
• Float16Array und Float32Array führen ein "Runden zu ganzem" durch, um 64-Bit-Gleitkommazahlen in 32-Bit- und 16-Bit-Zahlen umzuwandeln. Dies ist der gleiche Algorithmus, den Math.fround() und Math.f16round() bereitstellen.

Wenn ein TypedArray als Ansicht eines größenveränderbaren Puffers erstellt wird, hat das Verändern der Größe des unterliegenden Puffers unterschiedliche Auswirkungen auf die Größe des TypedArray, je nachdem, ob das TypedArray als längenverfolgend konstruiert wurde.

Wenn ein typisiertes Array ohne eine spezifische Größe durch Auslassen des dritten Parameters oder durch Übergeben von undefined erstellt wird, wird das typisierte Array längenverfolgend und passt sich automatisch an den unterliegenden buffer an, während 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 typisiertes Array mit einer spezifischen Größe unter Verwendung des dritten length Parameters erstellt wird, wird es sich nicht an den buffer anpassen, wenn dieser 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 betrachtete typisierte Array über die Grenzen hinausgehen, in diesem Fall wird die beobachtete Größe des typisierten Arrays auf 0 verkleinert. Dies ist der einzige Fall, in dem sich die Länge eines nicht längenverfolgenden typisierten 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 typisierte Array wieder in Grenzen zu bringen, wird die Größe des typisierten Arrays auf seinen ursprünglichen Wert zurückgesetzt.

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 bei längenverfolgenden typisierten Arrays passieren, wenn der Puffer ü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 – der Versuch, es mit new zu konstruieren, 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 z.B. 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)

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

typedArray

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

object

Wenn mit einem Objekt aufgerufen, das keine TypedArray-Instanz ist, wird ein neues typisiertes Array auf die gleiche Weise erstellt wie mit der TypedArray.from() Methode.

length Optional

Wenn mit einem Nicht-Objekt aufgerufen, wird der Parameter als Zahl angesehen, welche 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 ist und mit Nullen gefüllt wird. Das Weglassen aller Parameter ist äquivalent zur Verwendung von 0 als length.

buffer, byteOffset Optional, length Optional

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

Alle TypeArray Unterklasskonstruktoren funktionieren auf die gleiche Weise. Sie würden alle die folgenden Ausnahmen werfen:

TypeError

Wird in einem der folgenden Fälle geworfen:

• Ein typedArray wird übergeben, es ist jedoch ein bigint Typ, während der aktuelle Konstruktor kein solcher ist, 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 geworfen:

• Die Länge des neuen typisierten Arrays ist zu groß.
• Die Länge des Puffers (wenn der length Parameter nicht spezifiziert 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 liegen 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 daher von allen TypedArray Unterklasskonstruktoren geteilt.

TypedArray[Symbol.species]

Die Konstruktionsfunktion, die zum Erstellen abgeleiteter Objekte verwendet wird.

Alle TypedArray Unterklassen 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 daher von allen TypedArray Unterklasskonstruktoren geteilt.

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 Unterklasseninstanzen geteilt.

TypedArray.prototype.buffer

Gibt den ArrayBuffer zurück, auf den das typisierte Array verweist.

TypedArray.prototype.byteLength

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

TypedArray.prototype.byteOffset

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

TypedArray.prototype.constructor

Die Konstruktionsfunktion, die das Instanzobjekt erstellt hat. TypedArray.prototype.constructor ist die versteckte TypedArray Konstruktionsfunktion, aber jede typisierte Arrayunterklasse 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 anfängliche Wert der TypedArray.prototype[Symbol.toStringTag] Eigenschaft ist ein Getter, der denselben String wie der Name des typisierten Array-Konstruktors zurückgibt. Wenn der Wert von this keine der typisierten Arrayunterklassen ist, wird undefined zurückgegeben. Diese Eigenschaft wird in Object.prototype.toString() verwendet. Da TypedArray jedoch seine eigene toString() Methode besitzt, wird diese Eigenschaft nicht verwendet, es sei denn, Sie rufen Object.prototype.toString.call() mit einem Typisierten Array als thisArg auf.

Alle TypedArray Unterklassen 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 Prototypobjekt definiert und werden daher von allen TypedArray Unterklasseninstanzen geteilt.

TypedArray.prototype.at()

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

TypedArray.prototype.copyWithin()

Kopiert eine Folge 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()

Überprü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 Anfagsindex 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 wird. 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 wird. 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 wird. 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 wird. 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 enthält und gibt entsprechend true oder false zurück. Siehe auch Array.prototype.includes().

TypedArray.prototype.indexOf()

Gibt den ersten (kleinsten) Index eines Elements im Array zurück, das dem angegebenen Wert entspricht, oder -1, wenn keines gefunden wird. 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 letzen (größten) Index eines Elements im Array zurück, das dem angegebenen Wert entspricht, oder -1, wenn keines gefunden wird. Siehe auch Array.prototype.lastIndexOf().

TypedArray.prototype.map()

Erstellt ein neues Array mit den Ergebnissen des Aufrufens einer bereitgestellten Funktion auf jedes Element in diesem Array. Siehe auch Array.prototype.map().

TypedArray.prototype.reduce()

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

TypedArray.prototype.reduceRight()

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

TypedArray.prototype.reverse()

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

TypedArray.prototype.set()

Speichert mehrere Werte im typisierten Array und liest die Eingabewerte aus einem angegebenen Array.

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 vor Ort und gibt das Array zurück. Siehe auch Array.prototype.sort().

TypedArray.prototype.subarray()

Gibt ein neues TypedArray aus dem angegebenen Start- und Endelementindex zurück.

TypedArray.prototype.toLocaleString()

Gibt einen lokalisierten String zurück, der das Array und seine Elemente darstellt. Siehe auch Array.prototype.toLocaleString().

TypedArray.prototype.toReversed()

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

TypedArray.prototype.toSorted()

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

TypedArray.prototype.toString()

Gibt einen String zurück, der das Array und seine Elemente darstellt. 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 ursprüngliche Array zu verä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 auf Elemente im Array mit standardmäßiger Array-Index-Syntax (das heißt, unter Verwendung der Klammernnotation) zugreifen. Das Abrufen oder Setzen von indizierten Eigenschaften in typisierten Arrays führt jedoch keine Suche in der Prototypkette nach dieser Eigenschaft durch, selbst wenn die Indizes außerhalb der Grenzen liegen. Indizierte Eigenschaften konsultieren den ArrayBuffer und berücksichtigen nie Objekteigenschaften. Sie können dennoch benannte Eigenschaften verwenden, 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 ihre unterliegenden ArrayBuffer durch eine andere TypedArray Ansicht auf den Puffer geändert werden könnten. Dies 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 Erstellen eines TypedArray als Ansicht auf einem ArrayBuffer, muss das byteOffset Argument an seine Elementgröße ausgerichtet sein; mit anderen Worten, der Versatz 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);

Analog zum byteOffset-Parameter muss die byteLength-Eigenschaft eines ArrayBuffer, der an den Konstruktor eines TypedArray ü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