This page was translated from English by the community. Learn more and join the MDN Web Docs community.

View in English Always switch to English

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.

ArrayBuffer ์ธ์Šคํ„ด์Šค์˜ transfer() ๋ฉ”์„œ๋“œ๋Š” ์ด ๋ฒ„ํผ์™€ ๋™์ผํ•œ ๋ฐ”์ดํŠธ ๋‚ด์šฉ์„ ๊ฐ€์ง„ ์ƒˆ ArrayBuffer๋ฅผ ์ƒ์„ฑํ•œ ๋‹ค์Œ ์ด ๋ฒ„ํผ๋ฅผ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค.

๊ตฌ๋ฌธ

js
transfer()
transfer(newByteLength)

๋งค๊ฐœ๋ณ€์ˆ˜

newByteLength Optional

์ƒˆ ArrayBuffer์˜ byteLength์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ ์ด ArrayBuffer์˜ byteLength์ž…๋‹ˆ๋‹ค.

  • newByteLength๊ฐ€ ์ด ArrayBuffer์˜ byteLength๋ณด๋‹ค ์ž‘์œผ๋ฉด ํ•ด๋‹น ๋ฒ„ํผ์— ๋‹ด์ง€ ๋ชปํ•ด "๋„˜์น˜๋Š”" ๋ฐ”์ดํŠธ๋Š” ์‚ญ์ œ๋ฉ๋‹ˆ๋‹ค.
  • newByteLength๊ฐ€ ์ด ArrayBuffer์˜ byteLength๋ณด๋‹ค ํฌ๋‹ค๋ฉด ๋‚จ๋Š” ๋ฐ”์ดํŠธ๋Š” 0์œผ๋กœ ์ฑ„์›Œ์ง‘๋‹ˆ๋‹ค.
  • ์ด ArrayBuffer์˜ ํฌ๊ธฐ๋ฅผ ์กฐ์ •ํ•  ์ˆ˜ ์žˆ๋Š” ๊ฒฝ์šฐ newByteLength๋Š” ํ•ด๋‹น maxByteLength๋ณด๋‹ค ํฌ์ง€ ์•Š์•„์•ผ ํ•ฉ๋‹ˆ๋‹ค.

๋ฐ˜ํ™˜ ๊ฐ’

์ƒˆ๋กœ์šด ArrayBuffer ๊ฐ์ฒด์ž…๋‹ˆ๋‹ค. ํ•ด๋‹น ๊ฐ์ฒด์˜ ๋‚ด์šฉ์€ ์ด ArrayBuffer์˜ ๋‚ด์šฉ์œผ๋กœ ์ดˆ๊ธฐํ™”๋˜๋ฉฐ, ์—ฌ๋ถ„์˜ ๋ฐ”์ดํŠธ๊ฐ€ ์žˆ์œผ๋ฉด 0์œผ๋กœ ์ฑ„์›Œ์ง‘๋‹ˆ๋‹ค. ์ƒˆ๋กœ์šด ArrayBuffer๋Š” ์ด ArrayBuffer๊ฐ€ ํฌ๊ธฐ ์กฐ์ •์ด ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ์—๋งŒ ํฌ๊ธฐ๋ฅผ ์กฐ์ •ํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์ด ๊ฒฝ์šฐ ์ƒˆ๋กœ์šด ๊ฐ์ฒด์˜ maxByteLength๋Š” ์ด ArrayBuffer์˜ ๊ฒƒ๊ณผ ๋™์ผํ•ฉ๋‹ˆ๋‹ค. ์›๋ž˜์˜ ArrayBuffer๋Š” ๋ถ„๋ฆฌ๋ฉ๋‹ˆ๋‹ค.

์˜ˆ์™ธ

RangeError

์ด ArrayBuffer๊ฐ€ ํฌ๊ธฐ ์กฐ์ ˆ์ด ๊ฐ€๋Šฅํ•˜๊ณ  newByteLength๊ฐ€ ์ด ArrayBuffer์˜ maxByteLength๋ณด๋‹ค ํฌ๋‹ค๋ฉด ๋ฐœ์ƒํ•ฉ๋‹ˆ๋‹ค.

TypeError

ArrayBuffer๊ฐ€ ์ด๋ฏธ ๋ถ„๋ฆฌ๋œ ๊ฒฝ์šฐ ๋ฐœ์ƒํ•ฉ๋‹ˆ๋‹ค.

์„ค๋ช…

transfer() ๋ฉ”์„œ๋“œ๋Š” ๊ตฌ์กฐํ™”๋œ ๋ณต์ œ ์•Œ๊ณ ๋ฆฌ์ฆ˜๊ณผ ๋™์ผํ•œ ์—ฐ์‚ฐ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. ์ด ArrayBuffer์˜ ๋ฐ”์ดํŠธ๋ฅผ ์ƒˆ ArrayBuffer ๊ฐ์ฒด์— ๋ณต์‚ฌํ•œ ๋‹ค์Œ ์ด ArrayBuffer ๊ฐ์ฒด๋ฅผ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค. ์ž์„ธํ•œ ๋‚ด์šฉ์€ ์ „์†กํ•˜๋Š” ๋ฐฐ์—ด ๋ฒ„ํผ๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค.

transfer()๋Š” ์ด ArrayBuffer์˜ ํฌ๊ธฐ ์กฐ์ • ๊ฐ€๋Šฅ ์—ฌ๋ถ€ ๊ฐ’์„ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ƒˆ ArrayBuffer์˜ ํฌ๊ธฐ๋ฅผ ์กฐ์ •ํ•  ์ˆ˜ ์—†๊ฒŒ ํ•˜๋ ค๋ฉด transferToFixedLength()๋ฅผ ๋Œ€์‹  ์‚ฌ์šฉํ•˜์‹œ๊ธฐ ๋ฐ”๋ž๋‹ˆ๋‹ค. ๊ณ ์ • ๊ธธ์ด ๋ฒ„ํผ๋ฅผ ํฌ๊ธฐ ์กฐ์ •์ด ๊ฐ€๋Šฅํ•˜๋„๋ก ๋งŒ๋“œ๋Š” ๋ฒ„ํผ๋ฅผ ์ „์†กํ•˜๋Š” ๋ฐฉ๋ฒ•์€ ์—†์Šต๋‹ˆ๋‹ค.

transfer()๋Š” ๊ตฌํ˜„์—์„œ ์ด ๋ฉ”์„œ๋“œ๋ฅผ ์ œ๋กœ ์นดํ”ผ ์ด๋™ ๋˜๋Š” realloc์œผ๋กœ ๊ตฌํ˜„ํ•  ์ˆ˜ ์žˆ์œผ๋ฏ€๋กœ ๋ฐ์ดํ„ฐ์˜ ์‹ค์ œ ๋ณต์‚ฌ๋ณธ์ด ์—†์–ด๋„ ๋˜๋ฏ€๋กœ ๋งค์šฐ ํšจ์œจ์ ์ž…๋‹ˆ๋‹ค.

์˜ˆ์ œ

ArrayBuffer ์ „์†กํ•˜๊ธฐ

js
// ArrayBuffer๋ฅผ ์ƒ์„ฑํ•˜๊ณ  ๋ช‡ ๋ฐ”์ดํŠธ๋ฅผ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค
const buffer = new ArrayBuffer(8);
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;

// ๋ฒ„ํผ๋ฅผ ๊ฐ™์€ ํฌ๊ธฐ๋กœ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค
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

// ๋ฒ„ํผ๋ฅผ ๋” ์ž‘์€ ํฌ๊ธฐ๋กœ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค
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

// ๋ฒ„ํผ๋ฅผ ๋” ํฐ ํฌ๊ธฐ๋กœ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค
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

// ์ด๋ฏธ ๋ถ„๋ฆฌ๋จ, TypeError ๋ฐœ์ƒ
buffer.transfer(); // TypeError: Cannot perform ArrayBuffer.prototype.transfer on a detached ArrayBuffer

ํฌ๊ธฐ ์กฐ์ ˆ์ด ๊ฐ€๋Šฅํ•œ ArrayBuffer ์ „์†กํ•˜๊ธฐ

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

// ๋ฒ„ํผ๋ฅผ ๋” ์ž‘์€ ํฌ๊ธฐ๋กœ ๋ณต์‚ฌ
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

// maxByteLength ๋ฒ”์œ„ ๋‚ด์—์„œ ๋” ํฐ ํฌ๊ธฐ๋กœ ๋ฒ„ํผ ๋ณต์‚ฌ
const buffer3 = buffer2.transfer(12);
console.log(buffer3.byteLength); // 12

// maxByteLength ๋ฒ”์œ„ ๋ณด๋‹ค ๋” ํฐ ํฌ๊ธฐ๋กœ ๋ฒ„ํผ ๋ณต์‚ฌ
buffer3.transfer(20); // RangeError: Invalid array buffer length

๋ช…์„ธ์„œ

Specification
ECMAScriptยฎ 2026 Language Specification
# sec-arraybuffer.prototype.transfer

๋ธŒ๋ผ์šฐ์ € ํ˜ธํ™˜์„ฑ

๊ฐ™์ด ๋ณด๊ธฐ