ArrayBuffer.prototype.transfer()

Syntax

transfer()
transfer(newByteLength)

Parameter

newByteLength Optional

Die byteLength des neuen ArrayBuffer. Standardmäßig wird die byteLength dieses ArrayBuffer verwendet.

• Wenn newByteLength kleiner als die byteLength dieses ArrayBuffer ist, werden die überzähligen Bytes verworfen.
• Wenn newByteLength größer als die byteLength dieses ArrayBuffer ist, werden die zusätzlichen Bytes mit Nullen gefüllt.
• Wenn dieser ArrayBuffer in der Größe veränderbar ist, darf newByteLength nicht größer als seine maxByteLength sein.

Rückgabewert

Ein neues ArrayBuffer-Objekt. Sein Inhalt wird mit dem Inhalt dieses ArrayBuffer initialisiert; zusätzliche Bytes werden, falls vorhanden, mit Nullen gefüllt. Der neue ArrayBuffer ist genau dann in der Größe veränderbar, wenn dieser ArrayBuffer in der Größe veränderbar ist. In diesem Fall hat er dieselbe maxByteLength wie dieser ArrayBuffer. Der ursprüngliche ArrayBuffer wird abgetrennt.

Ausnahmen

RangeError

Wird ausgelöst, wenn dieser ArrayBuffer in der Größe veränderbar ist und newByteLength größer als die maxByteLength dieses ArrayBuffer ist.

TypeError

Wird ausgelöst, wenn dieser ArrayBuffer bereits abgetrennt ist oder nur durch dafür vorgesehene Operationen abgetrennt werden kann. Derzeit können nur bestimmte Web-APIs ArrayBuffer-Objekte erstellen, die ausschließlich mit dafür vorgesehenen Methoden abgetrennt werden können, beispielsweise GPUBuffer.getMappedRange() und WebAssembly.Memory.buffer.

Beschreibung

Die Methode transfer() führt denselben Vorgang wie der Algorithmus zum strukturierten Klonen aus. Sie kopiert die Bytes dieses ArrayBuffer in ein neues ArrayBuffer-Objekt und trennt anschließend das ursprüngliche ArrayBuffer-Objekt ab. Weitere Informationen finden Sie unter Übertragen von ArrayBuffers.

transfer() erhält die Größenveränderbarkeit dieses ArrayBuffer. Wenn der neue ArrayBuffer nicht in der Größe veränderbar sein soll, verwenden Sie stattdessen transferToFixedLength(). Es gibt keine Möglichkeit, einen Puffer so zu übertragen, dass ein Puffer mit fester Länge in der Größe veränderbar wird.

transfer() ist sehr effizient, da Implementierungen diese Methode als Verschieben ohne Kopieren oder als realloc umsetzen können – die Daten müssen nicht tatsächlich kopiert werden.

Beispiele

Einen ArrayBuffer übertragen

// 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

Einen in der Größe veränderbaren ArrayBuffer übertragen

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

Browser-Kompatibilität

Siehe auch

• Polyfill für ArrayBuffer.prototype.transfer in core-js
• Polyfill für ArrayBuffer.prototype.transfer von es-shims
• ArrayBuffer
• ArrayBuffer.prototype.detached
• ArrayBuffer.prototype.transferToFixedLength()