TypedArray
Baseline
Widely available
*
This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2015년 7월.
* Some parts of this feature may have varying levels of support.
TypedArray 객체는 이진 데이터 버퍼에 기초하여 배열과 같은 보기를 만들어냅니다.
하지만 TypedArray라는 전역 속성은 존재하지 않으며, 직접 볼 수 있는 TypedArray 생성자도 존재하지 않습니다. 대신 아래에 있는 특정 요소 유형에 대한 형식화 배열 생성자를 가지는 다양한 전역 속성을 사용할 수 있습니다. 다음 페이지에서는 모든 유형의 요소를 포함하는 모든 유형의 배열에서 사용할 수 있는 공통 속성과 메서드를 살펴보겠습니다.
시도해 보기
// Create a TypedArray with a size in bytes
const typedArray1 = new Int8Array(8);
typedArray1[0] = 32;
const typedArray2 = new Int8Array(typedArray1);
typedArray2[1] = 42;
console.log(typedArray1);
// Expected output: Int8Array [32, 0, 0, 0, 0, 0, 0, 0]
console.log(typedArray2);
// Expected output: Int8Array [32, 42, 0, 0, 0, 0, 0, 0]
설명
TypedArray 생성자는 모든 TypedArray 생성자의 [[Prototype]] 역할을 하는 숨겨진 전역입니다.
이 생성자는 직접 노출되지 않아 전역 %TypedArray% 또는 TypedArray 속성이 없습니다. 그래서 Object.getPrototypeOf(Int8Array) 등을 통해서만 직접 액세스할 수 있습니다. 모든 TypedArrays 생성자는 %TypedArray% 생성자 함수에서 공통 속성을 상속받고, 모든 형식화 배열의 프로토타입(TypedArray.prototype)은 %TypedArray%.prototype을 [[Prototype]]으로 가지고 있습니다.
TypedArray(예: Int8Array)의 인스턴스를 생성하거나 배열 버퍼가 내부적으로 메모리에 생성되거나 ArrayBuffer 객체가 생성자 인수로 주어지면 이들이 대신 사용됩니다. 버퍼 주소는 인스턴스의 내부 속성으로 저장되며 %TypedArray%.prototype의 모든 메서드(예: 값 설정 및 값 가져오기 등)는 해당 배열 버퍼 주소에서 작동합니다.
TypedArray 객체
| 형식 | 값 범위 | 바이트 크기 | 설명 | Web IDL 형식 | 동일한 C 형식 |
|---|---|---|---|---|---|
Int8Array |
-128 to 127 | 1 | 부호 있는 8비트 2의 보수 정수 | byte |
int8_t |
Uint8Array |
0 to 255 | 1 | 부호 없는 8비트 정수 | octet |
uint8_t |
Uint8ClampedArray |
0 to 255 | 1 | 부호 없는 8비트 정수 (고정) | octet |
uint8_t |
Int16Array |
-32768 to 32767 | 2 | 부호 있는 16비트 2의 보수 정수 | short |
int16_t |
Uint16Array |
0 to 65535 | 2 | 부호 없는 16비트 정수 | unsigned short |
uint16_t |
Int32Array |
-2147483648 to 2147483647 | 4 | 부호 있는 32비트 2의 보수 정수 | long |
int32_t |
Uint32Array |
0 to 4294967295 | 4 | 부호 없는 32비트 정수 | unsigned long |
uint32_t |
Float32Array |
-3.4E38에서 3.4E38. 1.2E-38은 최초 양수 |
4 | 32비트 IEEE 부동 소수점 숫자 (유효한 7자리 숫자, 예: 1.234567) |
unrestricted float |
float |
Float64Array |
-1.8E308에서 1.8E308. 5E-324는 최소 양수 |
8 | 64비트 IEEE 부동 소수점 숫자 (유효한 16자리 숫자, 예: 1.23456789012345) |
unrestricted double |
double |
BigInt64Array |
-263에서 263 - 1 | 8 | 부호 있는 64비트 2의 보수 정수 | bigint |
int64_t (signed long long) |
BigUint64Array |
0 에서 264 - 1 | 8 | 부호 없는 64비트 정수 | bigint |
uint64_t (unsigned long long) |
생성자
이 객체는 직접 인스턴스화할 수 없습니다. 대신 Int8Array 또는 BigInt64Array와 같은 특정 유형의 배열 인스턴스를 만들 수 있습니다. 이러한 객체에는 모두 생성자에 대한 공통적인 구문이 있습니다.
new TypedArray();
new TypedArray(length);
new TypedArray(typedArray);
new TypedArray(object);
new TypedArray(buffer);
new TypedArray(buffer, byteOffset);
new TypedArray(buffer, byteOffset, length);
여기서 TypedArray 는 구체적인 유형 중 하나의 생성자입니다.
매개변수
length-
length인수와 함께 호출되면,length에BYTES_PER_ELEMENT바이트를 곱한 크기의 0으로 채워진 내부 배열 버퍼가 메모리에 생성됩니다. typedArray-
typedArray인수를 사용하여 호출하면,typedArray가 새 형식화 배열에 복사됩니다. non-bigintTypedArray의 경우,typedArray매개변수는 오직 non-bigint 종류의 형식화 배열 객체만(예:Int32Array) 될 수 있습니다. 마찬가지로 bigintTypedArray의 경우,typedArray매개변수는 bigint 형식화 배열 종류의 객체(예:BigInt64Array)만 될 수 있습니다.typedArray의 각 값은 새 배열에 복사되기 전에 해당 생성자의 형식으로 변환됩니다. 새로운 형식화 배열의 길이는typedArray인수의 길이와 동일합니다. object-
object인수를 사용하여 호출하면,TypedArray.from()메서드에서와 같이 새로운 형식화 배열이 생성됩니다. buffer,byteOffset,length-
buffer와 선택적으로 전달할 수 있는byteOffset및length인수가 함께 호출되면, 지정된ArrayBuffer를 보는 새로운 형식화 배열 뷰가 생성됩니다.byteOffset및length매개변수는 형식화 배열 보기에 의해 노출될 메모리 범위를 지정합니다. 둘 다 생략하면 모든 버퍼가 표시되고,length만 생략하면buffer의 나머지 부분이 표시됩니다.
예외
모든 TypeArray 하위 클래스 생성자는 같은 방식으로 동작합니다. 생성자는 모두 아래와 같은 예외를 발생시킵니다.
TypeError-
다음 상황 중 하나일 경우 발생합니다.
typedArray가 전달되었으나, bigint 유형이지만 현 생성자가 그렇지 않을 경우 혹은 그 반대의 경우입니다.typeArray가 전달되었으나, 바라보는 버퍼가 분리되었거나 혹은 분리된buffer가 바로 전달될 경우입니다.
RangeError-
다음 상황 중 하나일 경우 발생합니다.
- 새로운 형식화 배열의 길이가 너무 클 경우입니다.
buffer의 길이(length매개변수가 명시되지 않을 경우) 혹은byteOffset이 새로운 형식화 배열의 요소 크기의 정수 배수가 아닐 경우입니다.byteOffset이 유효한 배열 인덱스(0부터 253 - 1 사이의 정수)가 아닐 경우입니다.- 버퍼에서 뷰를 만들 때 뷰가 버퍼를 벗어날 경우입니다. 즉,
byteOffset + length * TypedArray.BYTES_PER_ELEMENT > buffer.byteLength입니다.
정적 속성
TypedArray.BYTES_PER_ELEMENT-
TypedArray객체 요소의 크기를 숫자 값으로 반환합니다. TypedArray.name-
생성자 이름을 문자열로 반환합니다(예:
"Int8Array"). get TypedArray[@@species]-
파생된 객체를 만드는 데 사용되는 생성자 함수입니다.
TypedArray-
TypedArray객체의 프로토타입.
정적 메서드
TypedArray.from()-
배열과 유사하거나 반복 가능한 객체에서 새
TypedArray를 만듭니다.Array.from()도 참조하시기 바랍니다. TypedArray.of()-
가변 개수의 인수를 사용하여 새
TypedArray를 만듭니다.Array.of()도 참조하시기 바랍니다.
인스턴스 속성
TypedArray.prototype.buffer-
형식화 배열이 참조하는
ArrayBuffer반환합니다. 생성 시 고정되는 값으로 읽기 전용입니다. TypedArray.prototype.byteLength-
형식화 배열의 길이(바이트)를 반환합니다. 생성 시 고정되는 값으로 읽기 전용입니다.
TypedArray.prototype.byteOffset-
ArrayBuffer의 시작 부터 형식화 배열의 지정된 오프셋(바이트)을 반환합니다. 생성시 시 고정되는 값으로 읽기 전용입니다. TypedArray.prototype.length-
형식화 배열에 포함된 요소의 수를 반환합니다. 생성 시 고정되는 값으로 읽기 전용입니다.
인스턴스 메서드
TypedArray.prototype.at()-
정수 값으로 해당 인덱스의 항목을 반환합니다. 이 메서드는 마지막 항목부터 접근하는 음의 정수를 허용합니다.
TypedArray.prototype.copyWithin()-
배열 내의 배열 요소 시퀀스를 복사합니다.
Array.prototype.copyWithin()도 참조하시기 바랍니다. TypedArray.prototype.entries()-
배열의 각 인덱스에 대한 키/값 쌍을 포함하는 새 배열 반복기 객체를 반환합니다.
Array.prototype.entries()도 참조하시기 바랍니다. TypedArray.prototype.every()-
배열의 모든 요소가 함수에서 제공하는 테스트를 통과하는지 확인합니다.
Array.prototype.every()도 참조하시기 바랍니다. TypedArray.prototype.fill()-
시작 인덱스에서 끝 인덱스까지 배열의 모든 요소를 정적 값으로 채웁니다.
Array.prototype.fill()도 참조하시기 바랍니다. TypedArray.prototype.filter()-
제공된 필터링 함수가
true를 반환하는 이 배열의 모든 요소를 사용하여 새 배열을 만듭니다.Array.prototype.filter()도 참조하시기 바랍니다. TypedArray.prototype.find()-
제공된 테스트 함수를 충족하는 첫번 째
element를 반환하고, 찾지 못하면undefined를 반환합니다.Array.prototype.find()도 참조하시기 바랍니다. TypedArray.prototype.findIndex()-
제공된 테스트 함수를 충족하는 첫 번째 요소의 인덱스 값을 반환하고, 찾지 못한 경우는
-1을 반환합니다.Array.prototype.findIndex()도 참조하시기 바랍니다. TypedArray.prototype.findLast()-
제공된 테스트 함수를 충족하는 배열의 마지막 요소 값을 반환하고, 요소가 없으면
undefined를 반환합니다.Array.prototype.findLast()도 참조하시기 바랍니다. TypedArray.prototype.findLastIndex()-
제공된 테스트 함수를 충족하는 배열의 마지막 요소의 인덱스를 반환하고, 요소를 찾지 못한 경우는
-1을 반환합니다.Array.prototype.findLastIndex()도 참조하시기 바랍니다.. TypedArray.prototype.forEach()-
배열의 각 요소에 대해 함수를 호출합니다.
Array.prototype.forEach()도 참조하시기 바랍니다. TypedArray.prototype.includes()-
형식화 배열에 특정 요소가 포함되어 있는지 여부를 결정하여
true또는false를 반환합니다Array.prototype.includes()도 참조하시기 바랍니다. TypedArray.prototype.indexOf()-
지정된 값과 동일한 배열 내 요소의 첫 번째(최소) 인덱스를 반환하고, 아무 것도 발견되지 않으면
-1을 반환합니다.Array.prototype.indexOf()도 참조하시기 바랍니다. TypedArray.prototype.join()-
배열의 모든 요소를 문자열로 결합합니다.
Array.prototype.join()도 참조하시기 바랍니다. TypedArray.prototype.keys()-
배열의 각 인덱스에 대한 키를 포함하는 새 배열 반복자를 반환합니다.
Array.prototype.keys()도 참조하시기 바랍니다. TypedArray.prototype.lastIndexOf()-
지정된 값과 동일한 배열 내 요소의 마지막(가장 큰) 인덱스를 반환고, 찾지 못한 경우엔
-1을 반환합니다.Array.prototype.lastIndexOf()도 참조하시기 바랍니다.. TypedArray.prototype.map()-
배열의 모든 요소에 대해 제공된 함수를 호출한 결과로 새 배열을 만듭니다.
Array.prototype.map()도 참조하시기 바랍니다. TypedArray.prototype.reduce()-
누산기와 배열의 각 값(왼쪽에서 오른쪽으로)에 대해 함수를 적용하여 단일 값으로 줄입니다.
Array.prototype.reduce()도 참조하시기 바랍니다. TypedArray.prototype.reduceRight()-
누산기와 배열의 각 값(오른쪽에서 왼쪽으로)에 대해 함수를 적용하여 단일 값으로 줄입니다.
Array.prototype.reduceRight()도 참조하시기 바랍니다. TypedArray.prototype.reverse()-
배열 요소의 순서를 뒤집습니다. 첫 번째 요소가 마지막 요소가 되고 마지막 요소가 첫 번째 요소가 됩니다.
Array.prototype.reverse()도 참조하시기 바랍니다. TypedArray.prototype.set()-
형식화 배열에 여러 값을 저장하고 지정된 배열에서 입력 값을 읽습니다.
TypedArray.prototype.slice()-
배열의 부분을 추출하여 새 배열을 반환합니다.
Array.prototype.slice()도 참조하시기 바랍니다. TypedArray.prototype.some()-
이 배열의 하나 이상의 요소가 제공된 테스트 함수를 충족하는 경우,
true를 반환합니다.Array.prototype.some()도 참조하시기 바랍니다. TypedArray.prototype.sort()-
배열의 요소를 정렬하고 배열을 반환합니다.
Array.prototype.sort()도 참조하시기 바랍니다. TypedArray.prototype.subarray()-
주어진 시작 인덱스에서 끝 인덱스 까지의 요소로 만든 새로운
TypedArray를 반환합니다. TypedArray.prototype.values()-
배열의 각 인덱스에 대한 값을 포함하는 새 배열 반복기 객체를 반환합니다.
Array.prototype.values()도 참조하시기 바랍니다. TypedArray.prototype.toLocaleString()-
배열 및 해당 요소를 나타내는 지역화된 문자열을 반환합니다.
Array.prototype.toLocaleString()도 참조하시기 바랍니다. TypedArray.prototype.toString()-
배열과 해당 요소를 나타내는 문자열을 반환합니다.
Array.prototype.toString()도 참조하시기 바랍니다. TypedArray.prototype[@@iterator]()-
배열의 각 인덱스에 대한 값을 포함하는 새 배열 반복기 객체를 반환합니다.
예제
속성 접근
표준 배열 인덱스 구문(즉, 대괄호 표기법 사용)을 사용하여 배열의 요소를 참조할 수 있습니다.
그러나 형식화 배열에서는 인덱스된 속성을 가져오거나 설정하면 인덱스가 범위를 벗어난 경우에도 프로토타입 체인에서 이 속성을 검색하지 않습니다.
인덱싱된 속성은 ArrayBuffer 참조하고 객체 속성을 절대 확인하지 않습니다.
모든 객체와 마찬가지로 이름을 지정한 속성은 계속 사용할 수 있습니다.
// 표준 배열 구문을 사용하여 설정 및 가져오기
const int16 = new Int16Array(2);
int16[0] = 42;
console.log(int16[0]); // 42
// 프로토타입의 인덱싱된 속성이 참조되지 않음 (Fx 25)
Int8Array.prototype[20] = "foo";
new Int8Array(32)[20]; // 0
// 범위를 벗어나더라도
Int8Array.prototype[20] = "foo";
new Int8Array(8)[20]; // undefined
// 또는 음수를 사용하더라도
Int8Array.prototype[-1] = "foo";
new Int8Array(8)[-1]; // undefined
// 그래도 이름을 지정한 속성은 허용됨 (Fx 30)
Int8Array.prototype.foo = "bar";
new Int8Array(32).foo; // "bar"
고정될 수 없음
비어 있지 않은 TypedArray는 고정될 수 없습니다. 기본 ArrayBuffer가 버퍼의 다른 TypedArray 보기를 통해 변경될 수 있기 때문입니다. 이것은 객체가 고정되지 않을것 임을 의미합니다.
const i8 = Int8Array.of(1, 2, 3);
Object.freeze(i8);
// TypeError: Cannot freeze array buffer views with elements
ByteOffset는 반드시 정렬되어야 합니다
TypedArray를 ArrayBuffer에 대한 보기로 구성할 때 byteOffset 인수는 요소 크기에 맞춰 정렬되어야 합니다. 즉, 오프셋은 BYTES_PER_ELEMENT의 배수여야 합니다.
const i32 = new Int32Array(new ArrayBuffer(4), 1);
// RangeError: start offset of Int32Array should be a multiple of 4
const i32 = new Int32Array(new ArrayBuffer(4), 0);
ByteLength는 반드시 정렬되어야 합니다
byteOffset 매개변수와 마찬가지로 TypedArray의 생성자에 전달된 ArrayBuffer의 byteLength 속성은 생성자의 BYTES_PER_ELEMENT의 배수여야 합니다.
const i32 = new Int32Array(new ArrayBuffer(3));
// RangeError: byte length of Int32Array should be a multiple of 4
const i32 = new Int32Array(new ArrayBuffer(4));
명세서
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-typedarray-objects |
브라우저 호환성
Loading…