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

Signatur

ArrayBuffer.prototype.resize(newLength)

Beschreibung

resize() ändert die Länge eines größenveränderbaren ArrayBuffer direkt am Objekt. Ein solcher Puffer entsteht nur, wenn du ihn mit der Option maxByteLength anlegst, z. B. new ArrayBuffer(8, { maxByteLength: 64 }). Du kannst den Puffer dann beliebig oft vergrößern oder verkleinern, solange die neue Größe zwischen 0 und maxByteLength liegt.

Beim Vergrößern werden die neuen Bytes mit 0 gefüllt. Beim Verkleinern gehen die Bytes am Ende verloren. Die Identität des Puffers bleibt erhalten. Anders als beim üblichen Muster „neuen Puffer anlegen und Daten umkopieren“ zeigen bestehende Referenzen und Views also weiter auf dasselbe Objekt.

Besonders praktisch ist das zusammen mit längenverfolgenden TypedArrays. Das sind Views, die ohne feste length erzeugt werden, z. B. new Uint8Array(buffer). Ihre Länge passt sich bei jedem resize() automatisch an. So baust du wachsende Byte-Puffer, Stream-Parser oder Speicherbereiche für WebAssembly, ohne ständig neue Speicherblöcke anzulegen.

Ob ein Puffer größenveränderbar ist, zeigt die Eigenschaft resizable. Die aktuelle Obergrenze steht in maxByteLength.

Parameter

Name	Typ	Default	Beschreibung
$newLength Pflicht	number		Neue Größe in Bytes. Der Wert wird in eine ganze Zahl umgewandelt und muss zwischen `0` und `maxByteLength` liegen (beide Grenzen eingeschlossen). Fehlt das Argument, wird `undefined` zu `0` umgewandelt.

Rückgabewert

Typ

undefined

Beschreibung

Gibt nichts zurück. Die Größe des Puffers wird direkt am Objekt geändert.

Beispiele

Puffer vergrößern und verkleinern

const buffer = new ArrayBuffer(4, { maxByteLength: 16 });
console.log(buffer.resizable, buffer.byteLength, buffer.maxByteLength);

buffer.resize(12);
console.log(buffer.byteLength);

buffer.resize(2);
console.log(buffer.byteLength);

true 4 16 12 2

Längenverfolgende TypedArray-View passt sich automatisch an

const buffer = new ArrayBuffer(2, { maxByteLength: 8 });
const bytes = new Uint8Array(buffer); // ohne length => wächst mit

bytes.set([1, 2]);
buffer.resize(5);

// Neue Bytes sind mit 0 gefüllt
console.log(bytes.length, [...bytes]);

5 [ 1, 2, 0, 0, 0 ]

Wachsender Schreibpuffer (z. B. für einen Encoder)

class ByteWriter {
  #buffer = new ArrayBuffer(4, { maxByteLength: 1024 });
  #view = new Uint8Array(this.#buffer);
  #pos = 0;

  write(byte) {
    if (this.#pos >= this.#buffer.byteLength) {
      const next = Math.min(this.#buffer.byteLength * 2, this.#buffer.maxByteLength);
      if (next === this.#buffer.byteLength) throw new RangeError('Puffer voll');
      this.#buffer.resize(next); // die View wächst automatisch mit
    }
    this.#view[this.#pos++] = byte;
  }

  result() {
    return this.#buffer.slice(0, this.#pos);
  }
}

const w = new ByteWriter();
[10, 20, 30, 40, 50, 60].forEach((b) => w.write(b));
console.log(new Uint8Array(w.result()));

Uint8Array(6) [ 10, 20, 30, 40, 50, 60 ]

Fehlerbehandlung bei nicht größenveränderbarem Puffer

const fixed = new ArrayBuffer(8);

try {
  fixed.resize(16);
} catch (err) {
  console.log(err.name);
}

const growable = new ArrayBuffer(8, { maxByteLength: 16 });
try {
  growable.resize(32); // größer als maxByteLength
} catch (err) {
  console.log(err.name);
}

TypeError RangeError

// Wichtig · Fallstricke

Nur für größenveränderbare Puffer: Bei einem Puffer ohne maxByteLength (resizable === false) wirft resize() einen TypeError. Dasselbe gilt für abgetrennte Puffer, etwa nach transfer() oder nach einer Übertragung mit postMessage.
RangeError: Kommt, wenn newLength negativ ist oder größer als maxByteLength.
Views mit fester Länge: Verkleinerst du den Puffer so weit, dass eine TypedArray- oder DataView-Ansicht mit fester Länge oder festem Offset nicht mehr hineinpasst, ist die Ansicht „außerhalb der Grenzen“. Ihre length bzw. byteLength ist dann 0, und Zugriffe über eine DataView werfen Fehler. Vergrößerst du den Puffer wieder, wird die Ansicht wieder nutzbar.
Speicher: Die Engine darf den Speicher bis maxByteLength vorab reservieren. Wähle diese Obergrenze also realistisch und nicht „vorsichtshalber“ riesig. Ist maxByteLength zu groß, kann schon der Konstruktor einen RangeError werfen.
SharedArrayBuffer: Ein SharedArrayBuffer hat stattdessen grow(). Er kann nur wachsen, nicht schrumpfen.
Kompatibilität: Teil von ES2024. Unterstützt ab Chrome/Edge 111, Safari 16.4, Firefox 128 und Node.js 20. In älteren Umgebungen fehlt die Methode. Prüfe sie dort mit typeof ArrayBuffer.prototype.resize === 'function'.

Siehe auch

ArrayBuffer ArrayBuffer.prototype.resizable ArrayBuffer.prototype.maxByteLength ArrayBuffer.prototype.byteLength ArrayBuffer.prototype.transfer() SharedArrayBuffer.prototype.grow() TypedArray DataView