TypedArray.prototype.set() — Methode · JavaScript-Referenz

Signatur

TypedArray.prototype.set(source, targetOffset)

Beschreibung

Mit set() kopierst du viele Werte auf einmal in ein vorhandenes typisiertes Array wie Uint8Array, Float32Array usw. Die Quelle kann ein normales Array, ein anderes typisiertes Array oder ein beliebiges array-ähnliches Objekt sein, also alles mit einer length-Eigenschaft und numerischen Indizes. Die Werte landen ab dem Index targetOffset im Ziel. Das Ziel wird dabei nie größer: Die Länge eines typisierten Arrays ist fest.

Die Methode ist das Mittel der Wahl, um Binärdaten zusammenzusetzen. Typische Fälle sind das Aneinanderhängen mehrerer Datenblöcke, etwa Netzwerk-Pakete oder Audio-Samples, das Befüllen von WebGL- bzw. WebGPU-Puffern und das Kopieren von Teilbereichen. Weil die Kopie intern in einem Stück passiert, ist sie deutlich schneller als eine Schleife, die Element für Element zuweist.

Unterscheiden sich Quell- und Zieltyp, wird jeder Wert in den Zieltyp umgewandelt. Beispiel: 300 wird in einem Uint8Array zu 44 (Rest bei Division durch 256), in einem Uint8ClampedArray zu 255. Teilen sich Quelle und Ziel denselben ArrayBuffer, liest die Methode zuerst alle Quelldaten und schreibt erst danach. Überlappende Kopien innerhalb eines Puffers funktionieren deshalb korrekt.

Parameter

Name	Typ	Default	Beschreibung
$source Pflicht	Array \| TypedArray \| ArrayLike<number \| bigint>		Die Quelle der Werte. Jeder Wert wird in den Elementtyp des Ziels umgewandelt. Bei `BigInt64Array` und `BigUint64Array` müssen die Werte vom Typ `bigint` sein.
$targetOffset	number	0	Index im Ziel, ab dem geschrieben wird. Gebrochene Werte werden abgeschnitten. Negative Werte lösen einen `RangeError` aus.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das Ziel wird direkt verändert.

Beispiele

Werte aus einem normalen Array übernehmen

const bytes = new Uint8Array(8);

// Ab Index 3 schreiben
bytes.set([1, 2, 3], 3);

console.log(bytes);

Uint8Array(8) [0, 0, 0, 1, 2, 3, 0, 0]

Mehrere Binär-Blöcke aneinanderhängen

const concatBytes = (...chunks) => {
  const total = chunks.reduce((sum, c) => sum + c.length, 0);
  const result = new Uint8Array(total);
  let offset = 0;
  for (const chunk of chunks) {
    result.set(chunk, offset);
    offset += chunk.length;
  }
  return result;
};

const header = new Uint8Array([0xca, 0xfe]);
const body = new TextEncoder().encode('Hi');
console.log(concatBytes(header, body));

Uint8Array(4) [202, 254, 72, 105]

Typumwandlung und Überlappung im selben Puffer

// Umwandlung: Float -> Uint8 (abschneiden + modulo 256)
const u8 = new Uint8Array(3);
u8.set(new Float32Array([1.9, 256, -1]));
console.log(u8); // [1, 0, 255]

// Überlappend verschieben: Elemente eine Position nach rechts
const data = new Int16Array([10, 20, 30, 40, 0]);
data.set(data.subarray(0, 4), 1);
console.log(data);

Uint8Array(3) [1, 0, 255] Int16Array(5) [10, 10, 20, 30, 40]

Fehler bei zu wenig Platz abfangen

const target = new Float64Array(4);

try {
  target.set([1, 2, 3], 2); // bräuchte Indizes 2–4
} catch (err) {
  console.log(err.name);
}

RangeError

// Wichtig · Fallstricke

RangeError: Die Methode wirft einen Fehler, wenn targetOffset + source.length größer ist als die Länge des Ziels. Sie kürzt die Quelle nicht automatisch. Wenn nötig, schneidest du die Quelle vorher mit subarray() oder slice() zu.
Keine Rückgabe: set() gibt undefined zurück. Aufrufe lassen sich deshalb nicht verketten.
BigInt-Arrays: Mischst du BigInt64Array bzw. BigUint64Array mit normalen Zahlen, gibt es einen TypeError. Das gilt in beide Richtungen.
Stilles Überlaufen: Werte außerhalb des Wertebereichs werden ohne Warnung umgebrochen, etwa bei Uint8Array. Nur Uint8ClampedArray begrenzt sie auf 0 bis 255.
Zeichenketten als Quelle: Eine Zeichenkette ist array-ähnlich. Jedes Zeichen wird also in eine Zahl umgewandelt, meist zu NaN und damit zu 0. Für Text nimmst du stattdessen TextEncoder.
Abgekoppelte Puffer: Wurde der ArrayBuffer übertragen (detached), zum Beispiel per postMessage mit Transfer-Liste, löst set() einen TypeError aus.
Kompatibilität: Die Methode ist seit ES2015 in allen modernen Browsern und in Node.js verfügbar.

Siehe auch

TypedArray.prototype.subarray() TypedArray.prototype.slice() TypedArray.prototype.copyWithin() TypedArray.prototype.fill() TypedArray.from() ArrayBuffer Uint8Array