ArrayBuffer.prototype.transfer()

Метод transfer() объекта ArrayBuffer создает новый ArrayBuffer с тем же байтовым содержимым, что и этот буфер, а затем отсоединяет этот буфер.

Синтаксис

transfer()
transfer(newByteLength)

Параметры

newByteLength Необязательный

byteLength нового ArrayBuffer. По умолчанию используется byteLength этого ArrayBuffer.

• Если newByteLength меньше byteLength этого ArrayBuffer, "избыточные" байты отбрасываются.
• Если newByteLength больше byteLength этого ArrayBuffer, дополнительные байты заполняются нулями.
• Если этот ArrayBuffer можно изменять в размере, newByteLength не должен быть больше его maxByteLength.

Возвращаемое значение

Новый объект ArrayBuffer. Его содержимое инициализируется содержимым этого ArrayBuffer, а дополнительные байты, если они есть, заполняются нулями. Новый ArrayBuffer можно изменять в размере тогда и только тогда, когда этот ArrayBuffer можно изменять в размере, в этом случае его maxByteLength такой же, как у этого ArrayBuffer. Исходный ArrayBuffer отсоединен.

Исключения

RangeError

Выбрасывается, если этот ArrayBuffer можно изменять в размере, а newByteLength больше maxByteLength этого ArrayBuffer.

TypeError

Выбрасывается, если этот ArrayBuffer уже отсоединен, или если он может быть отсоединен только назначенными операциями. В настоящее время только некоторые веб-API способны создавать объекты ArrayBuffer с назначенными методами отсоединения, такие как GPUBuffer.getMappedRange() и WebAssembly.Memory.buffer.

Описание

Метод transfer() выполняет ту же операцию, что и алгоритм структурированного клонирования. Он копирует байты этого ArrayBuffer в новый объект ArrayBuffer, а затем отсоединяет этот объект ArrayBuffer. Дополнительную информацию см. в разделе передача ArrayBuffers.

transfer() сохраняет возможность изменения размера этого ArrayBuffer. Если вы хотите, чтобы новый ArrayBuffer был фиксированного размера, вместо этого используйте transferToFixedLength(). Нет способа передать буфер, который сделает буфер фиксированного размера изменяемым.

transfer() очень эффективен, поскольку реализации могут реализовать этот метод как передачу с нулевым копированием или realloc — фактического копирования данных не требуется.

Примеры

Передача 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

Передача изменяемого 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

Спецификации

Совместимость с браузерами

См. также

• Polyfill для ArrayBuffer.prototype.transfer в core-js
• es-shims polyfill для ArrayBuffer.prototype.transfer
• ArrayBuffer
• ArrayBuffer.prototype.detached
• ArrayBuffer.prototype.transferToFixedLength()