ArrayBuffer.prototype.transferToFixedLength()
The transferToFixedLength() method of ArrayBuffer instances creates a new non-resizable ArrayBuffer with the same byte content as this buffer, then detaches this buffer.
The transferToFixedLength() method of ArrayBuffer instances creates a new non-resizable ArrayBuffer with the same byte content as this buffer, then detaches this buffer.
Syntax
transferToFixedLength()
transferToFixedLength(newByteLength)
Parameters
newByteLength- : The byteLength of the new
ArrayBuffer. Defaults to thebyteLengthof thisArrayBuffer.- If
newByteLengthis smaller than thebyteLengthof thisArrayBuffer, the "overflowing" bytes are dropped. - If
newByteLengthis larger than thebyteLengthof thisArrayBuffer, the extra bytes are filled with zeros.
- 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 always non-resizable. The original ArrayBuffer is detached.
Exceptions
- TypeError
- : Thrown if this
ArrayBufferis already detached, or if it can only be detached by designated operations. Currently, only certain web APIs are capable of creatingArrayBufferobjects with designated detaching methods, such as GPUBuffer.getMappedRange() andWebAssembly.Memory.buffer.
Description
Unlike transfer(), transferToFixedLength() always creates a non-resizable ArrayBuffer. This means newByteLength can be larger than the maxByteLength, even if this ArrayBuffer is resizable. See transferring ArrayBuffers for more information.
Examples
Transferring a resizable ArrayBuffer to fixed-length
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;
const buffer2 = buffer.transferToFixedLength();
console.log(buffer2.byteLength); // 8
console.log(buffer2.resizable); // false
const view2 = new Uint8Array(buffer2);
console.log(view2[1]); // 2
console.log(view2[7]); // 4
Using transferToFixedLength, newByteLength can be larger than the maxByteLength of the original ArrayBuffer.
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;
const buffer2 = buffer.transferToFixedLength(20);
console.log(buffer2.byteLength); // 20
console.log(buffer2.resizable); // false
const view2 = new Uint8Array(buffer2);
console.log(view2[1]); // 2
console.log(view2[7]); // 4
Specifications
Browser compatibility
See also
- Polyfill of
ArrayBuffer.prototype.transferToFixedLengthincore-js - es-shims polyfill of
ArrayBuffer.prototype.transferToFixedLength - ArrayBuffer
- ArrayBuffer.prototype.detached
- ArrayBuffer.prototype.transfer()