Типизированный массив

Объект TypedArray описывает представление, подобное массиву, базового буфера двоичных данных. Глобального свойства с именем TypedArray не существует, как и непосредственно видимого конструктора TypedArray. Вместо этого существует несколько различных глобальных свойств, значениями которых являются конструкторы типизированных массивов для конкретных типов элементов, перечисленных ниже. На следующих страницах вы найдете общие свойства и методы, которые можно использовать с любым типизированным массивом, содержащим элементы любого типа.

Описание

Конструктор TypedArray (часто называемый %TypedArray%, чтобы подчеркнуть его «внутренний» характер, поскольку он не соответствует никакому глобальному объекту, доступному программе JavaScript) служит общим суперклассом всех подклассов TypedArray. Считайте %TypedArray% «абстрактным классом», предоставляющим общий интерфейс вспомогательных методов для всех подклассов типизированных массивов. Этот конструктор недоступен напрямую: глобального свойства TypedArray не существует. Доступ к нему возможен только через Object.getPrototypeOf(Int8Array) и аналогичные объекты.

При создании экземпляра подкласса TypedArray (например, Int8Array) буфер массива создается во внутренней памяти или, если в качестве аргумента конструктора передан объект ArrayBuffer, вместо него используется этот объект ArrayBuffer. Адрес буфера сохраняется как внутреннее свойство экземпляра, и все методы %TypedArray%.prototype задают и получают значения, используя этот адрес буфера массива.

Объекты TypedArray

Кодирование и нормализация значений

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

• Массивы беззнаковых целых чисел (Uint8Array, Uint16Array, Uint32Array и BigUint64Array) хранят число напрямую в двоичном виде.
• Массивы знаковых целых чисел (Int8Array, Int16Array, Int32Array и BigInt64Array) хранят число в дополнительном коде.
• Массивы чисел с плавающей точкой (Float16Array, Float32Array и Float64Array) хранят число в формате чисел с плавающей точкой IEEE 754. В справочнике Number приведены дополнительные сведения о точном формате. По умолчанию числа JavaScript используют формат чисел с плавающей точкой двойной точности, совпадающий с Float64Array. В Float32Array для мантиссы используются 23 бита (вместо 52), а для экспоненты — 8 бит (вместо 11). В Float16Array для мантиссы используются 10 бит, а для экспоненты — 5 бит. Обратите внимание: спецификация требует, чтобы для всех значений NaN использовалась одна и та же битовая кодировка, однако конкретный шаблон бит зависит от реализации.
• Uint8ClampedArray — особый случай. Он хранит число в двоичном виде, как Uint8Array, но при сохранении числа за пределами диапазона ограничивает его диапазоном от 0 до 255 согласно математическому значению, а не отбрасывает старшие биты.

Все типизированные массивы, кроме Int8Array, Uint8Array и Uint8ClampedArray, хранят каждый элемент с использованием нескольких байтов. Эти байты могут располагаться от старшего к младшему (порядок от старшего к младшему байту) или от младшего к старшему (порядок от младшего к старшему байту). Дополнительные пояснения см. в статье Порядок байтов. Типизированные массивы всегда используют собственный порядок байтов платформы. Если при чтении и записи в буферы необходимо указать порядок байтов, используйте вместо этого DataView.

При записи в эти типизированные массивы значения, выходящие за пределы представимого диапазона, нормализуются.

• Во всех массивах целых чисел (кроме Uint8ClampedArray) используется преобразование чисел фиксированной разрядности, которое сначала отбрасывает десятичную часть числа, а затем оставляет младшие биты.
• Uint8ClampedArray сначала ограничивает число диапазоном от 0 до 255 (значения больше 255 становятся равны 255, а значения меньше 0 — 0). Затем результат округляется (а не округляется вниз) до ближайшего целого по правилу округления к ближайшему четному: если число находится ровно посередине между двумя целыми, оно округляется до ближайшего четного. Например, 0.5 становится 0, 1.5 становится 2, а 2.5 становится 2.
• Float16Array и Float32Array выполняют округление к ближайшему четному при преобразовании 64-разрядных чисел с плавающей точкой в 32-разрядные и 16-разрядные. Используются те же алгоритмы, что и в функциях Math.fround() и Math.f16round().

Поведение при просмотре изменяемого размера буфера

Если TypedArray создан как представление буфера с изменяемым размером, изменение размера базового буфера по-разному влияет на размер TypedArray в зависимости от того, создан ли TypedArray с отслеживанием длины.

Если типизированный массив создан без указания размера — третий параметр опущен или передан undefined, — он будет отслеживать длину и автоматически изменять размер в соответствии с базовым buffer по мере изменения его размера:

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2

buffer.resize(12);

console.log(float32.byteLength); // 12
console.log(float32.length); // 3

Если типизированный массив создан с указанием размера с помощью третьего параметра length, его размер не будет увеличиваться вслед за ростом buffer:

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 0, 2);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0, the initial value

buffer.resize(12);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0, the initial value

При уменьшении размера buffer просматривающий его типизированный массив может выйти за границы буфера. В этом случае наблюдаемый размер типизированного массива уменьшится до 0. Это единственный случай, когда длина типизированного массива, не отслеживающего длину, может измениться.

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 0, 2);

buffer.resize(7);

console.log(float32.byteLength); // 0
console.log(float32.length); // 0
console.log(float32[0]); // undefined

Если затем снова увеличить размер buffer так, чтобы типизированный массив снова оказался в границах буфера, его размер восстановится до исходного значения.

buffer.resize(8);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0 - back in bounds again!

То же может произойти и с типизированными массивами, отслеживающими длину, если размер буфера уменьшить ниже byteOffset.

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 4);
// float32 is length-tracking, but it only extends from the 4th byte
// to the end of the buffer, so if the buffer is resized to be shorter
// than 4 bytes, the typed array will become out of bounds
buffer.resize(3);
console.log(float32.byteLength); // 0

Конструктор

Непосредственно создать экземпляр этого объекта нельзя: попытка вызвать его конструктор с помощью new приводит к исключению TypeError.

new (Object.getPrototypeOf(Int8Array))();
// TypeError: Abstract class TypedArray not directly constructable

Вместо этого создайте экземпляр типизированного массива определенного типа, например 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 — конструктор одного из конкретных типов.

Параметры

typedArray

При передаче экземпляра подкласса TypedArray объект typedArray копируется в новый типизированный массив. Для конструктора TypedArray, не относящегося к bigint, параметр typedArray может иметь только один из типов, не относящихся к bigint (например, Int32Array). Аналогично, для конструктора TypedArray типа bigint (BigInt64Array или BigUint64Array) параметр typedArray может иметь только один из типов bigint. Каждое значение в typedArray перед копированием в новый массив преобразуется в соответствующий тип конструктора. Длина нового типизированного массива будет равна длине аргумента typedArray.

object

Если передан объект, не являющийся экземпляром TypedArray, новый типизированный массив создается так же, как методом TypedArray.from().

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

Если передано значение, не являющееся объектом, параметр рассматривается как число, указывающее длину типизированного массива. Во внутренней памяти создается буфер массива размером length, умноженным на BYTES_PER_ELEMENT байт, и заполняется нулями. Если опустить все параметры, это равносильно использованию 0 в качестве length.

buffer, byteOffset Необязательный, length Необязательный

Если передан экземпляр ArrayBuffer или SharedArrayBuffer, а также, при необходимости, аргументы byteOffset и length, создается новое представление типизированного массива для указанного буфера. Параметры byteOffset (в байтах) и length (в количестве элементов, каждый из которых занимает BYTES_PER_ELEMENT байт) задают диапазон памяти, доступный через представление типизированного массива. Если опущены оба параметра, просматривается весь buffer; если опущен только length, просматривается оставшаяся часть buffer, начиная с byteOffset. Если опущен length, типизированный массив будет отслеживать длину.

Исключения

Конструкторы всех подклассов TypeArray работают одинаково. Все они могут вызывать следующие исключения:

TypeError

Вызывается в одном из следующих случаев:

• Передан объект typedArray типа bigint, а текущий конструктор не относится к этому типу, или наоборот.
• Передан объект typedArray, но просматриваемый им буфер отсоединен, либо напрямую передан отсоединенный buffer.

RangeError

Вызывается в одном из следующих случаев:

• Длина нового типизированного массива слишком велика.
• Длина buffer (если параметр length не указан) или byteOffset не кратна размеру элемента нового типизированного массива.
• byteOffset не является допустимым индексом массива (целым числом от 0 до 2⁵³ - 1).
• При создании представления буфера его границы выходят за пределы буфера. Другими словами, byteOffset + length * TypedArray.BYTES_PER_ELEMENT > buffer.byteLength.

Статические свойства

Эти свойства определены у объекта-конструктора TypedArray и поэтому являются общими для всех конструкторов подклассов TypedArray.

TypedArray[Symbol.species]

Функция-конструктор, используемая для создания производных объектов.

У всех подклассов TypedArray также есть следующие статические свойства:

TypedArray.BYTES_PER_ELEMENT

Возвращает числовое значение размера элемента для различных объектов TypedArray.

Статические методы

Эти методы определены у объекта-конструктора TypedArray и поэтому являются общими для всех конструкторов подклассов TypedArray.

TypedArray.from()

Создает новый TypedArray из объекта, подобного массиву, или итерируемого объекта. См. также Array.from().

TypedArray.of()

Создает новый TypedArray с переменным количеством аргументов. См. также Array.of().

Свойства экземпляров

Эти свойства определены в TypedArray.prototype и являются общими для всех экземпляров подклассов TypedArray.

TypedArray.prototype.buffer

Возвращает ArrayBuffer, на который ссылается типизированный массив.

TypedArray.prototype.byteLength

Возвращает длину типизированного массива в байтах.

TypedArray.prototype.byteOffset

Возвращает смещение типизированного массива в байтах относительно начала его ArrayBuffer.

TypedArray.prototype.constructor

Функция-конструктор, создавшая объект-экземпляр. TypedArray.prototype.constructor — это скрытая функция-конструктор TypedArray, но каждый подкласс типизированного массива также определяет собственное свойство constructor.

TypedArray.prototype.length

Возвращает количество элементов в типизированном массиве.

TypedArray.prototype[Symbol.toStringTag]

Изначальное значение свойства TypedArray.prototype[Symbol.toStringTag] — геттер, возвращающий ту же строку, что и имя конструктора типизированного массива. Он возвращает undefined, если значение this не является одним из подклассов типизированных массивов. Это свойство используется в Object.prototype.toString(). Однако у TypedArray также есть собственный метод toString(), поэтому это свойство не используется, если только вы не вызываете Object.prototype.toString.call(), передав типизированный массив в качестве thisArg.

У всех подклассов TypedArray также есть следующие свойства экземпляров:

TypedArray.prototype.BYTES_PER_ELEMENT

Возвращает числовое значение размера элемента для различных объектов TypedArray.

Методы экземпляров

Эти методы определены в объекте-прототипе TypedArray и поэтому являются общими для всех экземпляров подклассов TypedArray.

TypedArray.prototype.at()

Принимает целочисленное значение и возвращает элемент по указанному индексу. Метод допускает отрицательные целые числа, отсчитываемые от последнего элемента.

TypedArray.prototype.copyWithin()

Копирует последовательность элементов массива внутри массива. См. также Array.prototype.copyWithin().

TypedArray.prototype.entries()

Возвращает новый объект итератора массива, содержащий пары ключ/значение для каждого индекса массива. См. также Array.prototype.entries().

TypedArray.prototype.every()

Возвращает false, если в массиве найдется элемент, не удовлетворяющий заданной проверочной функции. В противном случае возвращает true. См. также 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, если в массиве найдется элемент, удовлетворяющий заданной проверочной функции. В противном случае возвращает false. См. также Array.prototype.some().

TypedArray.prototype.sort()

Сортирует элементы массива на месте и возвращает массив. См. также Array.prototype.sort().

TypedArray.prototype.subarray()

Возвращает новый TypedArray для указанного начального и конечного индексов элементов.

TypedArray.prototype.toLocaleString()

Возвращает строку, представляющую массив и его элементы с учетом локали. См. также Array.prototype.toLocaleString().

TypedArray.prototype.toReversed()

Возвращает новый массив с элементами в обратном порядке, не изменяя исходный массив.

TypedArray.prototype.toSorted()

Возвращает новый массив с элементами, отсортированными по возрастанию, не изменяя исходный массив.

TypedArray.prototype.toString()

Возвращает строку, представляющую массив и его элементы. См. также Array.prototype.toString().

TypedArray.prototype.values()

Возвращает новый объект итератора массива, содержащий значения для каждого индекса массива. См. также Array.prototype.values().

TypedArray.prototype.with()

Возвращает новый массив, в котором элемент по указанному индексу заменен заданным значением, не изменяя исходный массив.

TypedArray.prototype[Symbol.iterator]()

Возвращает новый объект итератора массива, содержащий значения для каждого индекса массива.

Примеры

Доступ к свойствам

Можно обращаться к элементам массива с помощью стандартного синтаксиса индексов массива (то есть используя квадратные скобки). Однако при чтении или установке индексированных свойств типизированных массивов поиск этого свойства в цепочке прототипов не выполняется, даже если индексы выходят за границы. При обращении к индексированным свойствам проверяется ArrayBuffer, но поиск свойств объекта не выполняется. Именованные свойства по-прежнему можно использовать, как и у любых других объектов.

// Setting and getting using standard array syntax
const int16 = new Int16Array(2);
int16[0] = 42;
console.log(int16[0]); // 42

// Indexed properties on prototypes are not consulted (Fx 25)
Int8Array.prototype[20] = "foo";
new Int8Array(32)[20]; // 0
// even when out of bound
Int8Array.prototype[20] = "foo";
new Int8Array(8)[20]; // undefined
// or with negative integers
Int8Array.prototype[-1] = "foo";
new Int8Array(8)[-1]; // undefined

// Named properties are allowed, though (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, свойство byteLength объекта ArrayBuffer, переданного конструктору TypedArray, должно быть кратно значению 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));

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

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

См. также

• Полифил типизированных массивов в core-js
• Руководство по типизированным массивам JavaScript
• ArrayBuffer
• DataView
• TextDecoder