Beschreibung

Der TypedArray-Konstruktor (oft als %TypedArray% bezeichnet, um seine "Intrinsizität" zu verdeutlichen, da er keinem globalen JavaScript-Programm entspricht) dient als die gemeinsame Superklasse aller TypedArray-Unterklassen. Betrachten Sie %TypedArray% als eine "abstrakte Klasse", die eine gemeinsame Schnittstelle von Dienstprogrammmethoden für alle TypedArray-Unterklassen bereitstellt. Dieser Konstruktor ist nicht direkt sichtbar: Es gibt keine globale TypedArray-Eigenschaft. Er ist nur über Object.getPrototypeOf(Int8Array) und ähnlich zugänglich.

Bei der Erstellung einer Instanz einer TypedArray-Unterklasse (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 werden Werte basierend auf dieser Array-Pufferadresse setzen und abrufen.

TypedArray-Objekte

Wert-Codierung und Normalisierung

Alle TypedArrays arbeiten auf ArrayBuffers, in denen Sie die genaue Byte-Darstellung jedes Elements beobachten können. Daher ist es bedeutend, wie die Zahlen im binären Format kodiert werden.

• Unsigned Integer Arrays (Uint8Array, Uint16Array, Uint32Array und BigUint64Array) speichern die Zahl direkt im Binärsystem.
• Signed Integer Arrays (Int8Array, Int16Array, Int32Array und BigInt64Array) speichern die Zahl unter Verwendung des Zweierkomplements.
• Gleitkomma-Arrays (Float16Array, Float32Array und Float64Array) speichern die Zahl unter Verwendung des IEEE 754 Gleitkommaformats. Die Number-Referenz enthält mehr Informationen über das genaue Format. JavaScript-Zahlen verwenden standardmäßig das Double-Precision-Gleitkommaformat, das dasselbe ist wie Float64Array. 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 dieselbe Bit-Codierung verwenden, aber das genaue Bitmuster ist implementierungsabhängig.
• Uint8ClampedArray ist ein besonderer Fall. Es speichert die Zahl im Binärsystem wie Uint8Array, aber wenn Sie eine Zahl außerhalb des Bereichs speichern, wird die Zahl auf den Bereich 0 bis 255 durch mathematischen Wert geklammert, anstatt die höchstwertigen Bits zu kürzen.

Alle TypedArrays außer Int8Array, Uint8Array und Uint8ClampedArray speichern jedes Element mit mehreren Bytes. Diese Bytes können entweder von den signifikantesten zu den am wenigsten signifikanten (big-endian) oder von den am wenigsten signifikanten zu den signifikantesten (little-endian) angeordnet sein. Siehe Endianness für eine ausführlichere Erklärung. TypedArrays 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 TypedArrays werden Werte, die außerhalb des darstellbaren Bereichs liegen, normalisiert.

• Alle Integer-Arrays (außer Uint8ClampedArray) verwenden Festbreiten-Zahlenumwandlung, die zuerst den Dezimalteil der Zahl abschneiden und dann die niedrigsten Bits nehmen.
• Uint8ClampedArray klammert die Zahl zuerst auf den Bereich 0 bis 255 (Werte größer als 255 werden zu 255 und Werte kleiner als 0 werden zu 0). Dann wird der Wert auf den nächsten ganzzahligen Wert gerundet (anstatt abgerundet), mit Rundung zur nächsten geraden Zahl; das heißt, wenn die Zahl genau zwischen zwei ganzzahligen Werten liegt, wird sie auf die nächste gerade Zahl gerundet. 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-Gleitkommazahlen in 32-Bit- und 16-Bit-Zahlen zu konvertieren. Dies ist derselbe Algorithmus, der von Math.fround() und Math.f16round() bereitgestellt wird.

Verhalten beim Anzeigen eines veränderbaren Puffers

Wenn ein TypedArray als Ansicht eines veränderbaren Puffers erstellt wird, hat das Ändern der Größe des zugrunde liegenden Puffers unterschiedliche Auswirkungen auf die Größe des TypedArray, je nachdem, ob das TypedArray als length-tracking erstellt wurde.

Wenn ein TypedArray ohne spezifische Größe erstellt wird, indem der dritte Parameter weggelassen oder undefined übergeben wird, wird das TypedArray length-tracking und wird automatisch auf die Größe des zugrunde liegenden buffers angepasst, 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 TypedArray mit einer spezifischen Größe unter Verwendung des dritten length-Parameters erstellt wird, wird es nicht wachsen, um den buffer einzuschließen, wenn letzterer vergrößert wird:

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 Typed Array außerhalb der Grenzen liegen, in diesem Fall sinkt die beobachtete Größe des TypedArrays auf 0. Dies ist der einzige Fall, in dem sich die Länge eines nicht length-tracking TypedArrays ä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 TypedArray wieder innerhalb der Grenzen zu bringen, wird die Größe des TypedArrays auf den Originalwert 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 für length-tracking TypedArrays 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

Konstruktor

Dieses Objekt kann nicht direkt instanziiert werden — der Versuch, es mit new zu konstruieren, führt zu einem TypeError.

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

Stattdessen erstellen Sie eine Instanz eines TypedArrays eines bestimmten Typs, wie zum Beispiel 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.

Parameter

typedArray

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

object

Wenn mit einem Objekt aufgerufen wird, das keine TypedArray-Instanz ist, wird ein neues TypedArray in derselben Weise erstellt wie die Methode TypedArray.from().

length Optional

Wenn mit einem Nicht-Objekt aufgerufen wird, wird der Parameter als Zahl behandelt, die die Länge des TypedArrays angibt. Ein interner Array-Puffer wird im Speicher erstellt, mit einer Größe von length, multipliziert mit BYTES_PER_ELEMENT Bytes, gefüllt mit Nullen. Das Weglassen aller Parameter ist gleichbedeutend mit der Verwendung von 0 als length.

buffer, byteOffset Optional, length Optional

Wenn mit einer Instanz von ArrayBuffer oder SharedArrayBuffer aufgerufen wird, und optional einem byteOffset und einem length-Argument, wird eine neue TypedArray-Ansicht erstellt, die den angegebenen Puffer anzeigt. Die Parameter byteOffset (in Bytes) und length (in Anzahl der Elemente, wobei jedes BYTES_PER_ELEMENT Bytes belegt) geben den Speicherrange an, der durch die TypedArray-Ansicht angezeigt wird. Wenn beide weggelassen werden, wird der gesamte buffer betrachtet; wenn nur length weggelassen wird, wird der Rest des buffers, ausgehend von byteOffset, betrachtet. Wenn length weggelassen wird, wird das TypedArray length-tracking.

Ausnahmen

Alle Konstruktoren von TypedArray-Unterklassen funktionieren auf die gleiche Weise. Alle werfen die folgenden Ausnahmen:

TypeError

Ausgelöst in einem der folgenden Fälle:

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

RangeError

Ausgelöst in einem der folgenden Fälle:

• Die neue Länge des TypedArrays ist zu groß.
• Die Länge des buffers (falls der length-Parameter nicht angegeben ist) oder byteOffset ist kein ganzzahliges Vielfaches der Elementgröße des neuen TypedArrays.
• byteOffset ist kein gültiger Arrayindex (eine ganze Zahl zwischen 0 und 2⁵³ - 1).
• Beim Erstellen einer Ansicht eines Puffers liegen die Grenzen außerhalb des Puffers. Mit anderen Worten, byteOffset + length * TypedArray.BYTES_PER_ELEMENT > buffer.byteLength.

Statische Eigenschaften

Diese Eigenschaften sind auf dem TypedArray-Konstruktorobjekt definiert und werden somit von allen TypedArray-Unterklass-Konstruktoren geteilt.

TypedArray[Symbol.species]

Die Konstruktionsfunktion, die zur Erstellung 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.

Statische Methoden

Diese Methoden sind auf dem TypedArray-Konstruktorobjekt definiert und werden somit von allen TypedArray-Unterklass-Konstruktoren geteilt.

TypedArray.from()

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

TypedArray.of()

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

Instanz-Eigenschaften

Diese Eigenschaften sind auf TypedArray.prototype definiert und werden von allen TypedArray-Unterklasse-Instanzen geteilt.

TypedArray.prototype.buffer

Gibt den durch das TypedArray referenzierten ArrayBuffer zurück.

TypedArray.prototype.byteLength

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

TypedArray.prototype.byteOffset

Gibt den Offset (in Bytes) des TypedArrays vom Beginn seines ArrayBuffer zurück.

TypedArray.prototype.constructor

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

TypedArray.prototype.length

Gibt die Anzahl der im TypedArray enthaltenen Elemente zurück.

TypedArray.prototype[Symbol.toStringTag]

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

Alle TypedArray-Unterklassen haben auch die folgenden Instanz-Eigenschaften:

TypedArray.prototype.BYTES_PER_ELEMENT

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

Instanz-Methoden

Diese Methoden sind auf dem TypedArray-Prototypobjekt definiert und werden somit von allen TypedArray-Unterklasse-Instanzen geteilt.

TypedArray.prototype.at()

Nimmt einen ganzzahligen Wert und gibt das Element an diesem Index zurück. Diese Methode erlaubt negative Ganzzahlen, die ausgehend vom letzten Element zurückzä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()

Gibt false zurück, wenn es ein Element im Array findet, das die bereitgestellte Testfunktion nicht erfüllt. Andernfalls gibt es true zurück. 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 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 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 TypedArray 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()

Gibt einen neuen String zurück, der die Verkettung aller Elemente in diesem TypedArray darstellt, getrennt durch Kommata oder einen angegebenen Trennstring. 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 der Aufrufe 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 es auf einen Einzelwert 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 es auf einen Einzelwert 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 TypedArray 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 es ein Element im Array findet, das die bereitgestellte Testfunktion erfüllt. Andernfalls gibt es false zurück. Siehe auch Array.prototype.some().

TypedArray.prototype.sort()

Sortiert die Elemente eines Arrays in-place und gibt das Array zurück. Siehe auch Array.prototype.sort().

TypedArray.prototype.subarray()

Gibt ein neues TypedArray von dem angegebenen Start- und Ende-Elementindex zurück.

TypedArray.prototype.toLocaleString()

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

TypedArray.prototype.toReversed()

Gibt ein neues Array zurück, dessen Elemente in umgekehrter Reihenfolge sind, ohne das Originalarray zu verändern.

TypedArray.prototype.toSorted()

Gibt ein neues Array zurück, dessen Elemente in aufsteigender Reihenfolge sortiert sind, ohne das Originalarray zu verändern.

TypedArray.prototype.toString()

Gibt eine Zeichenfolge zurück, die 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 mit dem Element am angegebenen Index zurück, das durch den angegebenen Wert ersetzt wird, 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.

Beispiele

Zugriff auf Eigenschaften

Sie können Elemente im Array unter Verwendung der Standard-Array-Indexsyntax ansprechen (d.h. unter Verwendung der Klammernotation). Beim Abrufen oder Setzen indizierter Eigenschaften auf TypedArrays wird jedoch nicht in der Prototypkette nach dieser Eigenschaft gesucht, auch wenn die Indizes außerhalb der Grenzen liegen. Indizierte Eigenschaften verwenden den ArrayBuffer und berücksichtigen niemals Objekteigenschaften. Sie können jedoch 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"

Kann nicht eingefroren werden

Nicht leere TypedArrays können nicht eingefroren werden, da ihr zugrunde liegender ArrayBuffer durch eine andere TypedArray-Ansicht des Puffers modifiziert 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

ByteOffset muss ausgerichtet sein

Beim Konstruieren 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);

ByteLength muss ausgerichtet sein

Wie der byteOffset-Parameter muss die byteLength-Eigenschaft eines ArrayBuffer, das einem TypedArray-Konstruktor ü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));

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill von TypedArrays in core-js
• Leitfaden zu JavaScript Typed Arrays
• ArrayBuffer
• DataView
• TextDecoder