TypedArray
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
TypedArray 객체는 이진 데이터 버퍼에 기초하여 배열과 같은 보기를 만들어냅니다.
하지만 TypedArray
라는 전역 속성은 존재하지 않으며, 직접 볼 수 있는 TypedArray
생성자도 존재하지 않습니다. 대신 아래에 있는 특정 요소 유형에 대한 형식화 배열 생성자를 가지는 다양한 전역 속성을 사용할 수 있습니다. 다음 페이지에서는 모든 유형의 요소를 포함하는 모든 유형의 배열에서 사용할 수 있는 공통 속성과 메서드를 살펴보겠습니다.
시도해보기
설명
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 Language Specification # sec-typedarray-objects |
브라우저 호환성
BCD tables only load in the browser