TypedArray

Beschreibung

Der TypedArray-Konstruktor (oft als %TypedArray% bezeichnet, um seine "Intrinsizitt" 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 fr 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 zugnglich.

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 knnen. Daher ist es bedeutend, wie die Zahlen im binren Format kodiert werden.

• Unsigned Integer Arrays (Uint8Array, Uint16Array, Uint32Array und BigUint64Array) speichern die Zahl direkt im Binrsystem.
• 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 enthlt mehr Informationen ber das genaue Format. JavaScript-Zahlen verwenden standardmig das Double-Precision-Gleitkommaformat, das dasselbe ist wie Float64Array. Float32Array verwendet 23 (statt 52) Bits fr die Mantisse und 8 (statt 11) Bits fr den Exponenten. Float16Array verwendet 10 Bits fr die Mantisse und 5 Bits fr den Exponenten. Beachten Sie, dass die Spezifikation erfordert, dass alle NaN-Werte dieselbe Bit-Codierung verwenden, aber das genaue Bitmuster ist implementierungsabhngig.
• Uint8ClampedArray ist ein besonderer Fall. Es speichert die Zahl im Binrsystem wie Uint8Array, aber wenn Sie eine Zahl auerhalb des Bereichs speichern, wird die Zahl auf den Bereich 0 bis 255 durch mathematischen Wert geklammert, anstatt die hchstwertigen Bits zu krzen.

Alle TypedArrays auer Int8Array, Uint8Array und Uint8ClampedArray speichern jedes Element mit mehreren Bytes. Diese Bytes knnen 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 fr eine ausfhrlichere Erklrung. TypedArrays verwenden immer die native Byte-Reihenfolge der Plattform. Wenn Sie die Endianness beim Schreiben und Lesen von Puffern angeben mchten, sollten Sie stattdessen einen DataView verwenden.

Beim Schreiben in diese TypedArrays werden Werte, die auerhalb des darstellbaren Bereichs liegen, normalisiert.

• Alle Integer-Arrays (auer 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 grer als 255 werden zu 255 und Werte kleiner als 0 werden zu 0). Dann wird der Wert auf den nchsten ganzzahligen Wert gerundet (anstatt abgerundet), mit Rundung zur nchsten geraden Zahl; das heit, wenn die Zahl genau zwischen zwei ganzzahligen Werten liegt, wird sie auf die nchste gerade Zahl gerundet. Zum Beispiel wird 0.5 zu 0, 1.5 zu 2 und 2.5 zu 2.
• Float16Array und Float32Array fhren 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 vernderbaren Puffers

Wenn ein TypedArray als Ansicht eines vernderbaren Puffers erstellt wird, hat das ndern der Gre des zugrunde liegenden Puffers unterschiedliche Auswirkungen auf die Gre des TypedArray, je nachdem, ob das TypedArray als length-tracking erstellt wurde.

Wenn ein TypedArray ohne spezifische Gre erstellt wird, indem der dritte Parameter weggelassen oder undefined bergeben wird, wird das TypedArray length-tracking und wird automatisch auf die Gre des zugrunde liegenden buffers angepasst, wenn dieser vergrert 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 Gre unter Verwendung des dritten length-Parameters erstellt wird, wird es nicht wachsen, um den buffer einzuschlieen, wenn letzterer vergrert 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 auerhalb der Grenzen liegen, in diesem Fall sinkt die beobachtete Gre des TypedArrays auf 0. Dies ist der einzige Fall, in dem sich die Lnge 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 vergrern, um das TypedArray wieder innerhalb der Grenzen zu bringen, wird die Gre des TypedArrays auf den Originalwert zurckgesetzt.

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 fr 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, fhrt 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 fr 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 fr einen der konkreten Typen ist.

Parameter

typedArray

Wenn mit einer Instanz einer TypedArray-Unterklasse aufgerufen wird, wird das typedArray in ein neues TypedArray kopiert. Fr einen nicht-bigint TypedArray-Konstruktor kann der typedArray-Parameter nur einer der nicht-bigint Typen sein (wie Int32Array). hnlich kann fr 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 Lnge des neuen TypedArrays entspricht der Lnge 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 Lnge des TypedArrays angibt. Ein interner Array-Puffer wird im Speicher erstellt, mit einer Gre von length, multipliziert mit BYTES_PER_ELEMENT Bytes, gefllt 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

Ausgelst in einem der folgenden Flle:

• Ein typedArray wird bergeben, aber es ist ein bigint-Typ, whrend 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

Ausgelst in einem der folgenden Flle:

• Die neue Lnge des TypedArrays ist zu gro.
• Die Lnge des buffers (falls der length-Parameter nicht angegeben ist) oder byteOffset ist kein ganzzahliges Vielfaches der Elementgre des neuen TypedArrays.
• byteOffset ist kein gltiger Arrayindex (eine ganze Zahl zwischen 0 und 253 - 1).
• Beim Erstellen einer Ansicht eines Puffers liegen die Grenzen auerhalb 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 Elementgre fr die verschiedenen TypedArray-Objekte zurck.

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 zurck.

TypedArray.prototype.byteLength

Gibt die Lnge (in Bytes) des TypedArrays zurck.

TypedArray.prototype.byteOffset

Gibt den Offset (in Bytes) des TypedArrays vom Beginn seines ArrayBuffer zurck.

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 zurck.

TypedArray.prototype[Symbol.toStringTag]

Der anfngliche Wert der TypedArray.prototype[Symbol.toStringTag]-Eigenschaft ist ein Getter, der dieselbe Zeichenfolge wie der Name des TypedArray-Konstruktors zurckgibt. Er gibt undefined zurck, 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 Elementgre fr die verschiedenen TypedArray-Objekte zurck.

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 zurck. Diese Methode erlaubt negative Ganzzahlen, die ausgehend vom letzten Element zurckzhlen.

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 zurck, das die Schlssel/Wert-Paare fr jeden Index im Array enthlt. Siehe auch Array.prototype.entries().

TypedArray.prototype.every()

Gibt false zurck, wenn es ein Element im Array findet, das die bereitgestellte Testfunktion nicht erfllt. Andernfalls gibt es true zurck. Siehe auch Array.prototype.every().

TypedArray.prototype.fill()

Fllt 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, fr die die bereitgestellte Filterfunktion true zurckgibt. Siehe auch Array.prototype.filter().

TypedArray.prototype.find()

Gibt das erste Element im Array zurck, das eine bereitgestellte Testfunktion erfllt, oder undefined, wenn kein geeignetes Element gefunden wird. Siehe auch Array.prototype.find().

TypedArray.prototype.findIndex()

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

TypedArray.prototype.findLast()

Gibt den Wert des letzten Elements im Array zurck, das eine bereitgestellte Testfunktion erfllt, oder undefined, wenn kein geeignetes Element gefunden wird. Siehe auch Array.prototype.findLast().

TypedArray.prototype.findLastIndex()

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

TypedArray.prototype.forEach()

Ruft eine Funktion fr jedes Element im Array auf. Siehe auch Array.prototype.forEach().

TypedArray.prototype.includes()

Bestimmt, ob ein TypedArray ein bestimmtes Element enthlt und gibt true oder false entsprechend zurck. Siehe auch Array.prototype.includes().

TypedArray.prototype.indexOf()

Gibt den ersten (niedrigsten) Index eines Elements innerhalb des Arrays zurck, das dem angegebenen Wert entspricht, oder -1, wenn keines gefunden wird. Siehe auch Array.prototype.indexOf().

TypedArray.prototype.join()

Gibt einen neuen String zurck, 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 zurck, der die Schlssel fr jeden Index im Array enthlt. Siehe auch Array.prototype.keys().

TypedArray.prototype.lastIndexOf()

Gibt den letzten (grten) Index eines Elements innerhalb des Arrays zurck, 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 fr 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 zurck. Siehe auch Array.prototype.slice().

TypedArray.prototype.some()

Gibt true zurck, wenn es ein Element im Array findet, das die bereitgestellte Testfunktion erfllt. Andernfalls gibt es false zurck. Siehe auch Array.prototype.some().

TypedArray.prototype.sort()

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

TypedArray.prototype.subarray()

Gibt ein neues TypedArray von dem angegebenen Start- und Ende-Elementindex zurck.

TypedArray.prototype.toLocaleString()

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

TypedArray.prototype.toReversed()

Gibt ein neues Array zurck, dessen Elemente in umgekehrter Reihenfolge sind, ohne das Originalarray zu verndern.

TypedArray.prototype.toSorted()

Gibt ein neues Array zurck, dessen Elemente in aufsteigender Reihenfolge sortiert sind, ohne das Originalarray zu verndern.

TypedArray.prototype.toString()

Gibt eine Zeichenfolge zurck, die das Array und seine Elemente darstellt. Siehe auch Array.prototype.toString().

TypedArray.prototype.values()

Gibt ein neues Array-Iterator-Objekt zurck, das die Werte fr jeden Index im Array enthlt. Siehe auch Array.prototype.values().

TypedArray.prototype.with()

Gibt ein neues Array mit dem Element am angegebenen Index zurck, das durch den angegebenen Wert ersetzt wird, ohne das Originalarray zu verndern.

TypedArray.prototype[Symbol.iterator]()

Gibt ein neues Array-Iterator-Objekt zurck, das die Werte fr jeden Index im Array enthlt.

Beispiele

Zugriff auf Eigenschaften

Sie knnen 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 auerhalb der Grenzen liegen. Indizierte Eigenschaften verwenden den ArrayBuffer und bercksichtigen niemals Objekteigenschaften. Sie knnen 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 knnen nicht eingefroren werden, da ihr zugrunde liegender ArrayBuffer durch eine andere TypedArray-Ansicht des Puffers modifiziert werden knnte. Dies wrde bedeuten, dass das Objekt niemals wirklich eingefroren wre.

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 Elementgre 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-Kompatibilitt

Siehe auch

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