new Int16Array() — Methode · JavaScript-Referenz

Signatur

new Int16Array(lengthOrTypedArrayOrObjectOrBuffer, byteOffset, length)

Beschreibung

Mit new Int16Array() legst du ein typisiertes Array an, dessen Elemente jeweils 2 Byte belegen und ganze Zahlen im Bereich -32768 bis 32767 speichern. Alle Elemente werden mit 0 initialisiert, außer du übergibst Quelldaten. Typische Einsatzgebiete sind Audiodaten (16-Bit-PCM), Binärformate, WebGL-Vertex-Daten und der Datenaustausch mit WebAssembly.

Den Konstruktor gibt es in mehreren Formen:

new Int16Array() oder new Int16Array(length): ein neues, mit Nullen gefülltes Array der angegebenen Länge.
new Int16Array(typedArray): kopiert die Werte eines anderen typisierten Arrays und wandelt sie dabei in 16-Bit-Ganzzahlen um.
new Int16Array(object): übernimmt Werte aus einem iterierbaren oder array-ähnlichen Objekt, z. B. einem normalen Array oder einem Set.
new Int16Array(buffer, byteOffset, length): legt eine Sicht auf einen vorhandenen ArrayBuffer oder SharedArrayBuffer an. Dabei wird nichts kopiert, und Änderungen wirken sich auf alle Sichten aus, die denselben Speicher nutzen.

Werte außerhalb des Wertebereichs werden nach Modulo-2¹⁶-Regeln umgebrochen (z. B. wird 32768 zu -32768), Nachkommastellen werden abgeschnitten, und NaN wird zu 0. Der Konstruktor lässt sich nur mit new aufrufen.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente. Es wird ein neuer, mit Nullen gefüllter Puffer von `length * 2` Byte angelegt.
$typedArray	TypedArray		Ein anderes typisiertes Array, dessen Werte in ein neues `Int16Array` kopiert und dabei umgewandelt werden. Ein `BigInt64Array` ist hier nicht erlaubt (`TypeError`).
$object	Iterable\|ArrayLike		Ein iterierbares oder array-ähnliches Objekt, dessen Werte übernommen werden (wie bei `Int16Array.from()`).
$buffer	ArrayBuffer\|SharedArrayBuffer		Ein vorhandener Puffer, auf den das Array als Sicht zugreift. Es wird nichts kopiert.
$byteOffset	number	0	Startposition in Byte innerhalb von `buffer`. Muss ein Vielfaches von `2` sein, sonst gibt es einen `RangeError`.
$length	number	(buffer.byteLength - byteOffset) / 2	Anzahl der Elemente in der Sicht. Ohne Angabe reicht die Sicht bis zum Ende des Puffers, dann muss die restliche Bytelänge ein Vielfaches von 2 sein.

Beispiele

Länge angeben und aus einem Array erzeugen

const leer = new Int16Array(4);
console.log(leer);

const werte = new Int16Array([100, -200, 32767, 32768, 1.9]);
console.log(werte);
console.log(werte.BYTES_PER_ELEMENT, werte.byteLength);

Int16Array(4) [0, 0, 0, 0] Int16Array(5) [100, -200, 32767, -32768, 1] 2 10

Sicht auf einen ArrayBuffer (ohne Kopie)

const buffer = new ArrayBuffer(8);
const alle = new Int16Array(buffer);          // 4 Elemente
const teil = new Int16Array(buffer, 4, 2);    // ab Byte 4, 2 Elemente

teil[0] = -1;
console.log(alle);
console.log(new Uint8Array(buffer));

Int16Array(4) [0, 0, -1, 0] Uint8Array(8) [0, 0, 0, 0, 255, 255, 0, 0]

Float32-Audiodaten in 16-Bit-PCM umwandeln

const floatToPcm16 = (samples) => {
  const pcm = new Int16Array(samples.length);
  samples.forEach((s, i) => {
    const clamped = Math.max(-1, Math.min(1, s));
    pcm[i] = clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff;
  });
  return pcm;
};

const audio = new Float32Array([0, 0.5, -0.5, 1, -1, 1.2]);
console.log(floatToPcm16(audio));

Int16Array(6) [0, 16383, -16384, 32767, -32768, 32767]

Aus einem anderen typisierten Array oder Iterable kopieren

const bytes = new Uint8Array([10, 200, 255]);
const kopie = new Int16Array(bytes);  // Werte kopiert, nicht geteilt
kopie[0] = 999;
console.log(kopie, bytes[0]);

const ausSet = new Int16Array(new Set([1, 2, 2, 3]));
console.log(ausSet);

Int16Array(3) [999, 200, 255] 10 Int16Array(3) [1, 2, 3]

// Wichtig · Fallstricke

Nur mit new: Ein Aufruf wie Int16Array([1, 2]) ohne new löst einen TypeError aus.
Ausrichtung: byteOffset muss durch 2 teilbar sein. Wird keine Länge angegeben, muss auch buffer.byteLength - byteOffset durch 2 teilbar sein, sonst gibt es einen RangeError.
Byte-Reihenfolge: Die Werte werden in der Byte-Reihenfolge der Plattform gespeichert, auf praktisch allen Systemen also Little-Endian. Für Dateiformate oder Netzwerkprotokolle mit fester Byte-Reihenfolge nimmst du besser DataView mit getInt16(offset, littleEndian).
Stilles Umbrechen: Werte außerhalb des Wertebereichs lösen keinen Fehler aus, sondern werden umgebrochen (40000 wird zu -25536). Wenn du begrenzen willst, musst du selbst klemmen, ein Int16ClampedArray gibt es nicht.
Sicht oder Kopie: Wird ein ArrayBuffer übergeben, entsteht eine Sicht auf denselben Speicher. Bei einem typisierten Array oder einem normalen Array wird dagegen immer kopiert.
Wird der zugrunde liegende Puffer übertragen (z. B. per postMessage mit Transfer-Liste), hat das Array danach die Länge 0.
Kompatibilität: wird von allen modernen Browsern und von Node.js unterstützt. Die Übergabe von Iterables wird seit ES2015 unterstützt, in sehr alten Engines nur array-ähnliche Objekte.

Siehe auch

Int16Array Uint16Array Int32Array TypedArray ArrayBuffer DataView TypedArray.from()