TypedArray

Der TypedArray-Konstruktor (oft als %TypedArray% bezeichnet, um auf seine "Intrinsicness" hinzuweisen, da er keiner globalen Variablen entspricht, die einem JavaScript-Programm ausgesetzt ist) fungiert als gemeinsame Oberklasse aller TypedArray-Unterklassen. Betrachten Sie %TypedArray% als eine "abstrakte Klasse", die eine gemeinsame Schnittstelle von Nutzmethoden für alle Typarray-Unterklassen bereitstellt. Dieser Konstruktor ist nicht direkt exponiert: Es gibt keine globale TypedArray-Eigenschaft. Er ist nur über Object.getPrototypeOf(Int8Array) und Ähnliches zugänglich.

Beim Erstellen einer Instanz einer TypedArray-Unterklasse (z. B. Int8Array) wird ein Array-Puffer intern im Speicher erstellt, oder, wenn ein ArrayBuffer-Objekt als Konstruktor-Argument angegeben wird, wird dieser ArrayBuffer stattdessen verwendet. Die Pufferadresse wird als interne Eigenschaft der Instanz gespeichert und alle Methoden von %TypedArray%.prototype werden Werte basierend auf dieser Array-Pufferadresse setzen und abrufen.

Alle Typarrays operieren auf ArrayBuffers, bei denen Sie die genaue Byte-Darstellung jedes Elements beobachten können, weshalb die Kodierung der Zahlen im Binärformat von Bedeutung ist.

• Nicht-signierte Ganzzahl-Arrays (Uint8Array, Uint16Array, Uint32Array, und BigUint64Array) speichern die Zahl direkt im Binärformat.
• Signierte Ganzzahl-Arrays (Int8Array, Int16Array, Int32Array, und BigInt64Array) speichern die Zahl in Zweierkomplement.
• Gleitkomma-Arrays (Float16Array, Float32Array, und Float64Array) speichern die Zahl im IEEE 754-Gleitkommaformat. Weitere Informationen über das genaue Format finden Sie in der Referenz zu Number. JavaScript verwendet standardmäßig das Gleitkommaformat mit doppelter Genauigkeit, das dem von 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 erfordert, dass alle NaN-Werte die gleiche Bitkodierung verwenden, das genaue Bitmuster jedoch implementierungsabhängig ist.
• Uint8ClampedArray ist ein spezieller Fall. Es speichert die Zahl im Binärformat wie Uint8Array, aber wenn Sie eine Zahl außerhalb des Bereichs speichern, klammert es die Zahl auf den Bereich 0 bis 255 durch den mathematischen Wert, anstatt die bedeutendsten Bits abzuschneiden.

Alle Typarrays außer Int8Array, Uint8Array und Uint8ClampedArray speichern jedes Element mit mehreren Bytes. Diese Bytes können entweder in der Reihenfolge von den bedeutendsten zu den am wenigsten bedeutenden (Big-Endian) oder von den am wenigsten bedeutenden zu den bedeutendsten (Little-Endian) angeordnet werden. Siehe Endianness für mehr Erklärungen. Typarrays verwenden immer die native Byte-Reihenfolge der Plattform. Wenn Sie die Endianness beim Schreiben und Lesen von Puffern angeben möchten, sollten Sie stattdessen einen DataView verwenden.

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

• Alle Ganzzahl-Arrays (außer Uint8ClampedArray) verwenden die feste Breitenkonversion von Zahlen, die zuerst den Dezimalteil der Zahl abschneidet und dann die niedrigsten Bits nimmt.
• Uint8ClampedArray klammert die Zahl zuerst auf den Bereich 0 bis 255 (Werte größer als 255 werden 255 und Werte kleiner als 0 werden 0). Es rundet (statt abzurunden) dann das Ergebnis auf die nächste Ganzzahl, mit Half-to-Even; das heißt, wenn die Zahl genau zwischen zwei Ganzzahlen liegt, rundet sie auf die nächste gerade Ganzzahl. Zum Beispiel wird 0.5 zu 0, 1.5 zu 2 und 2.5 zu 2.
• Float16Array und Float32Array führen eine "Rundung zur geraden Zahl" durch, um 64-Bit-Gleitkommazahlen in 32-Bit und 16-Bit umzuwandeln. Dies ist derselbe Algorithmus wie er von Math.fround() und Math.f16round() bereitgestellt wird.

Wenn ein TypedArray als Ansicht eines vergrößerbaren Puffers erstellt wird, hat das Vergrößern des zugrunde liegenden Puffers unterschiedliche Auswirkungen auf die Größe des TypedArray, abhängig davon, ob das TypedArray als Längenverfolgungskonstruktion erstellt wird.

Wenn ein Typarray ohne eine spezifische Größe erstellt wird, indem der dritte Parameter weggelassen oder undefined übergeben wird, wird das Typarray zu einem Längenverfolgungsarray und wird automatisch an den zugrunde liegenden Buffer angepasst, sobald 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 Typarray mit einer spezifischen Größe unter Verwendung des dritten length-Parameters erstellt wird, vergrößert es sich nicht, um den Buffer zu enthalten, 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 Typarray außerhalb des Bereichs liegen, in diesem Fall wird die beobachtete Größe des Typarrays auf 0 reduziert. Dies ist der einzige Fall, in dem sich die Länge eines nicht-Längenverfolgungstyparrays ä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 wieder vergrößern, um das Typarray wieder in den Bereich zu bringen, wird die Größe des Typarrays 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!

Dasselbe kann auch bei Längenverfolgungstyparrays 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 — 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 Typarrays eines bestimmten Typs, wie z. B. Int8Array oder 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 der typedArray-Wert in ein neues Typarray kopiert. Für einen nicht-bigint TypedArray-Konstruktor kann der typedArray-Parameter nur eines der nicht-bigint Typen sein (wie Int32Array). Ebenso kann für einen bigint TypedArray-Konstruktor (BigInt64Array oder BigUint64Array) der typedArray-Parameter nur eines der bigint Typen sein. Jeder Wert in dem typedArray wird vor dem Kopieren in das neue Array in den entsprechenden Typ des Konstruktors umgewandelt. Die Länge des neuen Typarrays wird die gleiche sein wie die des typedArray-Arguments.

object

Wenn mit einem Objekt aufgerufen, das keine TypedArray-Instanz ist, wird ein neues Typarray auf die gleiche Weise 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 Typarrays 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 ist. Wenn alle Parameter ausgelassen werden, entspricht dies der Nutzung von 0 als length.

buffer, byteOffset Optional, length Optional

Wenn mit einer Instanz von ArrayBuffer oder SharedArrayBuffer aufgerufen, und optional einem byteOffset und einem length Argument, wird eine neue Typarray-Ansicht erstellt, die den angegebenen Puffer ansieht. Die byteOffset (in Bytes) und length (in Anzahl der Elemente, die jeweils BYTES_PER_ELEMENT Bytes belegen) Parameter geben den Speicherbereich an, der durch die Typarray-Ansicht exponiert wird. Wenn beides ausgelassen wird, wird der gesamte buffer betrachtet; wenn nur length ausgelassen wird, wird der Rest des buffer ab byteOffset angesehen. Wenn length ausgelassen wird, wird das Typarray längenverfolgend.

Alle TypeArray-Unterklassenkonstruktoren funktionieren auf die gleiche Weise. Sie werfen alle die folgenden Ausnahmen:

TypeError

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

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

RangeError

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

• Die neue Typarray-Länge ist zu groß.
• Die Länge von buffer (wenn der length-Parameter nicht angegeben ist) oder byteOffset ist kein integrales Vielfaches der neuen Typarray-Elementgröße.
• 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-Konstruktor-Objekt definiert und werden daher von allen TypedArray-Unterklassenkonstruktoren geteilt.

TypedArray[Symbol.species]

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

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-Konstruktor-Objekt definiert und werden daher von allen TypedArray-Unterklassenkonstruktoren 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, den das Typarray referenziert.

TypedArray.prototype.byteLength

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

TypedArray.prototype.byteOffset

Gibt den Offset (in Bytes) des Typarrays 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 Typarray-Unterklasse definiert auch ihre eigene constructor-Eigenschaft.

TypedArray.prototype.length

Gibt die Anzahl der im Typarray gehaltenen Elemente zurück.

TypedArray.prototype[Symbol.toStringTag]

Der anfängliche Wert der Eigenschaft TypedArray.prototype[Symbol.toStringTag] ist ein Getter, der dieselbe Zeichenfolge wie der Name des Typarray-Konstruktors zurückgibt. Es gibt undefined zurück, wenn der Wert von this nicht eine der Typarray-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 Typarray 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-Prototype-Objekt 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 von hinten aus 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()

Testet, 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 all den 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 enthält, 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 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 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 Typarray ein bestimmtes Element enthält und gibt true oder false entsprechend zurück. Siehe auch Array.prototype.includes().

TypedArray.prototype.indexOf()

Gibt den ersten (niedrigsten) Index eines Elements innerhalb des Arrays 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 letzten (größten) Index eines Elements innerhalb des Arrays 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 Aufrufs einer bereitgestellten Funktion für jedes 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 einzelnen 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 einzelnen Wert zu reduzieren. Siehe auch Array.prototype.reduceRight().

TypedArray.prototype.reverse()

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

TypedArray.prototype.set()

Speichert mehrere Werte im Typarray und liest 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 an Ort und Stelle und gibt das Array zurück. Siehe auch Array.prototype.sort().

TypedArray.prototype.subarray()

Gibt ein neues TypedArray vom angegebenen Start- und Endindex der Elemente 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 zurück, bei dem die Elemente in umgekehrter Reihenfolge vorliegen, ohne das Originalarray zu verändern.

TypedArray.prototype.toSorted()

Gibt ein neues Array zurück, bei dem die Elemente in aufsteigender Reihenfolge sortiert sind, ohne das Originalarray 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 an dem angegebenen Index durch den angegebenen Wert ersetzt ist, ohne das Originalarray 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 der Standard-Arrayindexsyntax zugreifen (das heißt, mit Klammernotation). Wenn Sie jedoch Eigenschaften eines Typarrays über Indizes abrufen oder setzen, wird die Prototypkette nicht nach dieser Eigenschaft durchsucht, auch nicht, wenn die Indizes außerhalb des Bereichs liegen. Aufruf von indizierten Eigenschaften konsultiert den ArrayBuffer und wird nie nach Objekteigenschaften suchen. Sie können dennoch 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. 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 einen ArrayBuffer, muss das byteOffset-Argument auf seine Elementgröße ausgerichtet 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 den Konstruktor eines TypedArray übergeben wird, ein Vielfaches von 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 Typarrays in core-js
• JavaScript Typarrays Leitfaden
• ArrayBuffer
• DataView
• TextDecoder