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.
The transfer()
method of ArrayBuffer
instances creates a new ArrayBuffer
with the same byte content as this buffer, then detaches this buffer.
Syntax
transfer()
transfer(newByteLength)
Parameters
newByteLength
Optional-
The
byteLength
of the newArrayBuffer
. Defaults to thebyteLength
of thisArrayBuffer
.- If
newByteLength
is smaller than thebyteLength
of thisArrayBuffer
, the "overflowing" bytes are dropped. - If
newByteLength
is larger than thebyteLength
of thisArrayBuffer
, the extra bytes are filled with zeros. - If this
ArrayBuffer
is resizable,newByteLength
must not be greater than itsmaxByteLength
.
- If
Return value
A new ArrayBuffer
object. Its contents are initialized to the contents of this ArrayBuffer
, and extra bytes, if any, are filled with zeros. The new ArrayBuffer
is resizable if and only if this ArrayBuffer
is resizable, in which case its maxByteLength
is the same as this ArrayBuffer
's. The original ArrayBuffer
is detached.
Exceptions
RangeError
-
Thrown if this
ArrayBuffer
is resizable andnewByteLength
is greater than themaxByteLength
of thisArrayBuffer
. TypeError
-
Thrown if this
ArrayBuffer
is already detached.
Description
The transfer()
method performs the same operation as the structured clone algorithm. It copies the bytes of this ArrayBuffer
into a new ArrayBuffer
object, then detaches this ArrayBuffer
object. See transferring ArrayBuffers for more information.
transfer()
preserves the resizability of this ArrayBuffer
. If you want the new ArrayBuffer
to be non-resizable, use transferToFixedLength()
instead. There's no way to transfer a buffer that makes a fixed-length buffer become resizable.
transfer()
is very efficient because implementations may implement this method as a zero-copy move or a realloc
— there does not need to be an actual copy of the data.
Examples
Transferring an ArrayBuffer
// 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
Transferring a resizable ArrayBuffer
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
Specifications
Specification |
---|
ECMAScript Language Specification # sec-arraybuffer.prototype.transfer |
Browser compatibility
BCD tables only load in the browser