ArrayBuffer.prototype.transfer()

Baseline 2024

Newly available

Since March 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Die transfer() Methode von ArrayBuffer Instanzen erstellt einen neuen ArrayBuffer mit demselben Byte-Inhalt wie dieser Puffer und trennt anschließend diesen Puffer.

Syntax

js
transfer()
transfer(newByteLength)

Parameter

newByteLength Optional

Die byteLength des neuen ArrayBuffer. Standardmäßig entspricht sie der byteLength dieses ArrayBuffer.

  • Wenn newByteLength kleiner als die byteLength dieses ArrayBuffer ist, werden die "überlaufenden" Bytes verworfen.
  • Wenn newByteLength größer als die byteLength dieses ArrayBuffer ist, werden die zusätzlichen Bytes mit Nullen gefüllt.
  • Wenn dieser ArrayBuffer anpassbar ist, darf newByteLength nicht größer als dessen maxByteLength sein.

Rückgabewert

Ein neues ArrayBuffer Objekt. Der Inhalt wird auf den Inhalt dieses ArrayBuffer initialisiert, und zusätzliche Bytes, falls vorhanden, werden mit Nullen gefüllt. Der neue ArrayBuffer ist anpassbar, wenn und nur wenn dieser ArrayBuffer anpassbar ist, dessen maxByteLength ist derselbe wie der dieses ArrayBuffer. Der ursprüngliche ArrayBuffer wird getrennt.

Ausnahmen

RangeError

Wird ausgelöst, wenn dieser ArrayBuffer anpassbar ist und newByteLength größer ist als die maxByteLength dieses ArrayBuffer.

TypeError

Wird ausgelöst, wenn dieser ArrayBuffer bereits getrennt ist.

Beschreibung

Die transfer() Methode führt die gleiche Operation aus wie der strukturierte Klon-Algorithmus. Sie kopiert die Bytes dieses ArrayBuffer in ein neues ArrayBuffer Objekt und trennt anschließend dieses ArrayBuffer Objekt. Siehe Übertragung von ArrayBuffers für weitere Informationen.

transfer() erhält die Anpassbarkeit dieses ArrayBuffer. Wenn Sie möchten, dass der neue ArrayBuffer nicht anpassbar ist, verwenden Sie stattdessen transferToFixedLength(). Es gibt keine Möglichkeit, einen Puffer zu übertragen, der einen Puffer mit fester Länge anpassbar macht.

transfer() ist sehr effizient, da Implementierungen diese Methode als Null-Kopie-Verschiebung oder als realloc implementieren können — es muss keine tatsächliche Kopie der Daten erfolgen.

Beispiele

Übertragen eines ArrayBuffer

js
// Create an ArrayBuffer and write a few bytes
const buffer = new ArrayBuffer(8);
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;

// Copy the buffer to the same size
const buffer2 = buffer.transfer();
console.log(buffer.detached); // true
console.log(buffer2.byteLength); // 8
const view2 = new Uint8Array(buffer2);
console.log(view2[1]); // 2
console.log(view2[7]); // 4

// Copy the buffer to a smaller size
const buffer3 = buffer2.transfer(4);
console.log(buffer3.byteLength); // 4
const view3 = new Uint8Array(buffer3);
console.log(view3[1]); // 2
console.log(view3[7]); // undefined

// Copy the buffer to a larger size
const buffer4 = buffer3.transfer(8);
console.log(buffer4.byteLength); // 8
const view4 = new Uint8Array(buffer4);
console.log(view4[1]); // 2
console.log(view4[7]); // 0

// Already detached, throws TypeError
buffer.transfer(); // TypeError: Cannot perform ArrayBuffer.prototype.transfer on a detached ArrayBuffer

Übertragen eines anpassbaren ArrayBuffer

js
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;

// Copy the buffer to a smaller size
const buffer2 = buffer.transfer(4);
console.log(buffer2.byteLength); // 4
console.log(buffer2.maxByteLength); // 16
const view2 = new Uint8Array(buffer2);
console.log(view2[1]); // 2
console.log(view2[7]); // undefined
buffer2.resize(8);
console.log(view2[7]); // 0

// Copy the buffer to a larger size within maxByteLength
const buffer3 = buffer2.transfer(12);
console.log(buffer3.byteLength); // 12

// Copy the buffer to a larger size than maxByteLength
buffer3.transfer(20); // RangeError: Invalid array buffer length

Spezifikationen

Specification
ECMAScript Language Specification
# sec-arraybuffer.prototype.transfer

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch