ArrayBuffer.prototype.transferToFixedLength() — Methode · JavaScript-Referenz

Signatur

ArrayBuffer.prototype.transferToFixedLength(newLength)

Beschreibung

transferToFixedLength() überträgt den Inhalt eines ArrayBuffer in einen neuen Puffer mit fester Länge. Danach ist der ursprüngliche Puffer abgetrennt (detached): Seine byteLength ist 0, detached ist true, und alle Views darauf sind nicht mehr nutzbar. Der Besitz der Daten geht also auf den neuen Puffer über, ganz ähnlich wie bei einem Transfer mit postMessage().

Die Methode ist das Gegenstück zu transfer(). Der Unterschied: transfer() übernimmt die Größenveränderbarkeit des Quellpuffers (ein mit maxByteLength erzeugter Puffer bleibt resizable). transferToFixedLength() liefert dagegen immer einen Puffer mit fester Länge. Das ist praktisch, wenn Sie Daten zuerst in einem wachsenden Puffer sammeln und am Ende einen kompakten, unveränderlichen Puffer weitergeben möchten.

Mit dem optionalen Argument newLength können Sie die Größe des Zielpuffers festlegen. Ist er kleiner als der Quellpuffer, werden die überzähligen Bytes abgeschnitten. Ist er größer, werden die zusätzlichen Bytes mit Nullen gefüllt. Engines können den Transfer oft ohne Kopieren umsetzen (Zero-Copy), besonders wenn die Länge gleich bleibt oder kleiner wird.

Parameter

Name	Typ	Default	Beschreibung
$newLength	number	this.byteLength	Die `byteLength` des neuen Puffers. Wird in eine Ganzzahl umgewandelt. Ohne Angabe wird die aktuelle Länge des Quellpuffers verwendet. Werte über der Engine-Grenze oder negative Werte lösen einen `RangeError` aus.

Rückgabewert

Typ

ArrayBuffer

Beschreibung

Ein neuer, nicht größenveränderbarer ArrayBuffer (resizable === false) mit dem Inhalt des ursprünglichen Puffers, gegebenenfalls gekürzt oder mit Nullen aufgefüllt. Der ursprüngliche Puffer ist danach abgetrennt.

Beispiele

Wachsenden Puffer abschließen und fixieren

// Daten in einem resizable Buffer sammeln
const buffer = new ArrayBuffer(4, { maxByteLength: 64 });
const view = new Uint8Array(buffer);
view.set([1, 2, 3, 4]);

buffer.resize(6);
new Uint8Array(buffer).set([5, 6], 4);

// Am Ende in einen Puffer mit fester Länge überführen
const fixed = buffer.transferToFixedLength();

console.log(fixed.resizable, fixed.byteLength);
console.log([...new Uint8Array(fixed)]);
console.log(buffer.detached, buffer.byteLength);

false 6 [1, 2, 3, 4, 5, 6] true 0

Kürzen und Auffüllen über newLength

const source = new Uint8Array([10, 20, 30, 40]).buffer;

// Kürzen: nur die ersten 2 Bytes bleiben erhalten
const shorter = source.transferToFixedLength(2);
console.log([...new Uint8Array(shorter)]);

// Vergrößern: neue Bytes werden mit 0 gefüllt
const longer = shorter.transferToFixedLength(5);
console.log([...new Uint8Array(longer)]);
console.log(shorter.detached);

[10, 20] [10, 20, 0, 0, 0] true

Vergleich mit transfer() und Zugriff nach dem Abtrennen

const growable = new ArrayBuffer(8, { maxByteLength: 16 });

const a = growable.transfer();          // bleibt resizable
console.log(a.resizable);

const b = a.transferToFixedLength();    // wird fest
console.log(b.resizable);

try {
  a.transferToFixedLength();            // a ist bereits abgetrennt
} catch (err) {
  console.log(err.name);
}

true false TypeError

// Wichtig · Fallstricke

Abgetrennter Quellpuffer: Nach dem Aufruf haben alle TypedArrays und DataViews auf den alten Puffer die Länge 0. Der Zugriff über eine DataView löst einen TypeError aus. Legen Sie daher neue Views auf den zurückgegebenen Puffer an.
Ein erneuter Aufruf auf einem bereits abgetrennten Puffer löst einen TypeError aus. Das gilt auch für SharedArrayBuffer, denn die Methode gibt es dort nicht.
Ein zu großer newLength kann einen RangeError auslösen, wenn nicht genug Speicher reserviert werden kann.
Ist Größenveränderbarkeit erwünscht, verwenden Sie transfer(). Für eine echte Kopie ohne Abtrennen eignet sich slice().
Kompatibilität: Die Methode ist neu (ES2024). In älteren Browsern und in Node.js vor Version 21 fehlt sie. Prüfen Sie das bei Bedarf mit 'transferToFixedLength' in ArrayBuffer.prototype. Ein Polyfill kann das Abtrennen nur über structuredClone(buf, { transfer: [buf] }) nachbilden.

Siehe auch

ArrayBuffer ArrayBuffer.prototype.transfer() ArrayBuffer.prototype.detached ArrayBuffer.prototype.resize() ArrayBuffer.prototype.resizable ArrayBuffer.prototype.slice()