Класс BigUint64Array

Класс BigUint64Array описывает типизированный массив, содержащий значения в диапазоне от 0n до 18 446 744 073 709 551 615n:

let arr = new BigUint64Array([0n, 18446744073709551615n]);
console.log(arr);
// BigUint64Array(2) [0n, 18446744073709551615n]
console.log(BigUint64Array.BYTES_PER_ELEMENT); // 8
console.log(BigUint64Array.name);              // BigUint64Array

Создание объекта

Создать массив позволяют следующие конструкторы:

<Массив> = new BigUint64Array();
<Массив> = new BigUint64Array(<Количество элементов>);
<Массив> = new BigUint64Array(<Типизированный массив>);
<Массив> = new BigUint64Array(<Объект, поддерживающий итерации>);
<Массив> = new BigUint64Array(<ArrayBuffer>[, <byteOffset>[, <length>]]);

Первый конструктор создает массив нулевого размера:

let arr = new BigUint64Array();
console.log(arr.length); // 0

Второй конструктор позволяет указать количество элементов. Все элементы получат значение 0n:

let arr = new BigUint64Array(5);
console.log(arr); // BigUint64Array(5) [0n, 0n, 0n, 0n, 0n]

Третий конструктор создает массив на основе другого типизированного массива:

let arr1 = new BigUint64Array([1n, 2n, 3n]);
let arr2 = new BigUint64Array(arr1);
arr2[0] = 0n;
console.log(arr1); // BigUint64Array(3) [1n, 2n, 3n]
console.log(arr2); // BigUint64Array(3) [0n, 2n, 3n]

Четвертый конструктор в качестве параметра принимает объект, поддерживающий итерации. Можно указать, например, обычный массив или множество:

let arr1 = new BigUint64Array([1n, 2n, 3n]);
console.log(arr1); // BigUint64Array(3) [1n, 2n, 3n]
let arr2 = new BigUint64Array(new Set([1n, 2n, 2n]));
console.log(arr2); // BigUint64Array(2) [1n, 2n]

Пятый конструктор создает массив на основе объекта ArrayBuffer:

let buf = new ArrayBuffer(24);
let arr1 = new BigUint64Array(buf);
console.log(arr1);        // BigUint64Array(3) [0n, 0n, 0n]
let arr2 = new BigUint64Array(buf, 8, 2);
console.log(arr2.length); // 2

Обратите внимание: данные не копируются. Два объекта будут ссылаться на один и тот же фрагмент памяти:

let arr1 = new BigUint64Array([1n, 2n, 3n]);
let arr2 = new BigUint64Array(arr1.buffer, arr1.byteOffset,
               arr1.byteLength / BigUint64Array.BYTES_PER_ELEMENT);
arr2[0] = 5n;
console.log( arr1 ); // BigUint64Array(3) [5n, 2n, 3n]
console.log( arr2 ); // BigUint64Array(3) [5n, 2n, 3n]

Изменились оба массива!

В этом примере мы воспользовались следующими свойствами:

buffer — содержит ссылку на объект ArrayBuffer, лежащий в основе массива;
byteOffset — смещение внутри объекта ArrayBuffer;
byteLength — длина фрагмента в байтах.

Для создания массива можно также использовать статический метод from():

<Массив> = BigUint64Array.from(<Объект>[, <Функция>[, <this>]]);

В первом параметре указывается объект, поддерживающий итерации:

let arr1 = BigUint64Array.from([1n, 2n, 3n]);
console.log(arr1);        // BigUint64Array(3) [1n, 2n, 3n]
let arr2 = BigUint64Array.from('123');
console.log(arr2);        // BigUint64Array(3) [1n, 2n, 3n]

Во втором параметре можно указать ссылку на функцию, которая будет вызвана для каждого элемента. Функция имеет следующий формат:

function name(value, index, array) {
   return value;
}

Значение, возвращаемое функцией, станет новым значением элемента массива:

let arr = BigUint64Array.from([1n, 2n, 3n], (value) => {
   return value * 2n;
});
console.log(arr);        // BigUint64Array(3) [2n, 4n, 6n]

Создать массив на основе списка значений позволяет статический метод of(). Значения указываются через запятую:

let arr = BigUint64Array.of(1n, 2n, 3n);
console.log(arr);        // BigUint64Array(3) [1n, 2n, 3n]

Определение числа элементов массива

Получить количество элементов массива позволяет свойство length:

let arr = BigUint64Array.of(1n, 2n, 3n);
console.log(arr.length); // 3

Размер типизированного массива является фиксированным. Изменить размер после создания объекта нельзя.

Получение и изменение элементов массива

Получить значение элемента массива можно, указав его индекс в квадратных скобках. Нумерация элементов массива начинается с нуля:

let arr = BigUint64Array.of(1n, 2n, 3n);
console.log( arr[0] ); // 1n
console.log( arr[1] ); // 2n
console.log( arr[2] ); // 3n

Если элемент с указанным индексом не существует, то будет возвращено значение undefined:

console.log( arr[3] ); // undefined

При желании можно изменить значение существующего элемента:

arr[0] = 5n;
arr[1] = 6n;
console.log( arr[0] ); // 5n
console.log( arr[1] ); // 6n

Если указано число меньше минимального значения или больше максимального значения, то произойдет усечение числа:

arr[0] = -1n;
arr[1] = 18446744073709551616n;
console.log( arr[0] ); // 18446744073709551615n
console.log( arr[1] ); // 0n

С помощью метода fill() можно заполнить весь массив или только диапазон одинаковым значением. Формат метода:

fill(<Значение>[, <Начало>[, <Конец>]])

В первом параметре указывается вставляемое значение, которое заполнит весь массив или только указанный фрагмент:

let arr = new BigUint64Array(5);
console.log(arr); // BigUint64Array(5) [0n, 0n, 0n, 0n, 0n]
arr.fill(1n);
console.log(arr); // BigUint64Array(5) [1n, 1n, 1n, 1n, 1n]

В параметре <Начало> можно указать начальный индекс диапазона (значение по умолчанию: 0), а в параметре <Конец> — конечный индекс (значение по умолчанию: число элементов массива). Метод fill() возвращает ссылку на массив, поэтому можно строить цепочки из вызовов:

let arr = new BigUint64Array(5);
arr.fill(1n, 1, 4);
console.log(arr); // BigUint64Array(5) [0n, 1n, 1n, 1n, 0n]

С помощью метода set(<Массив>[, <Смещение>]) можно скопировать данные из обычного массива или типизированного массива:

let arr = new BigUint64Array(5);
arr.set( [1n, 2n, 3n] );
console.log( arr ); // BigUint64Array(5) [1n, 2n, 3n, 0n, 0n]
arr.set( [4n, 5n], 3 );
console.log( arr ); // BigUint64Array(5) [1n, 2n, 3n, 4n, 5n]
arr.set( BigUint64Array.of(6n, 7n, 8n) );
console.log( arr ); // BigUint64Array(5) [6n, 7n, 8n, 4n, 5n]

Для сохранения значений элементов массива в переменных можно использовать операцию распаковки массива. В этом случае массив указывается справа от оператора =, а переменные внутри квадратных скобок — слева от оператора =:

let arr = BigUint64Array.of(1n, 2n);
let [a, b] = arr;
console.log( a + ' ' + b );   // 1 2

Количество элементов массива может не совпадать с количеством переменных внутри квадратных скобок. Кроме того, если элемент не нужен, то достаточно указать переменные только в нужных позициях:

let arr = BigUint64Array.of(1n, 2n, 3n, 4n, 5n);
let a = 0n, b = 0n;
[a, , b] = arr;
console.log( a + ' ' + b );   // 1 3

Значения отдельных элементов массива можно сохранить в переменных, а оставшиеся элементы добавить в массив, указав перед ним оператор три точки:

let arr = BigUint64Array.of(1n, 2n, 3n, 4n, 5n);
let [a, b, ...other] = arr;
console.log( a + ' ' + b );   // 1 2
console.log( other );         // [3n, 4n, 5n]

Создание копии массива

Следует учитывать, что операция присваивания сохраняет в переменной ссылку на массив, а не все его значения. Например, если попробовать сделать так, то изменение arr2 затронет arr1:

let arr1, arr2;
arr1 = BigUint64Array.of(1n, 2n, 3n, 4n);
arr2 = arr1;          // Присваивается ссылка на массив!!!
arr2[0] = 88n;
console.log(arr1);    // BigUint64Array(4) [88n, 2n, 3n, 4n]
console.log(arr2);    // BigUint64Array(4) [88n, 2n, 3n, 4n]

Для создания полной копии можно воспользоваться конструктором класса BigUint64Array или статическим методом from():

let arr1, arr2;
arr1 = BigUint64Array.of(1n, 2n, 3n, 4n);
arr2 = new BigUint64Array(arr1);
arr2[0] = 88n;
console.log(arr1);    // BigUint64Array(4) [1n, 2n, 3n, 4n]
console.log(arr2);    // BigUint64Array(4) [88n, 2n, 3n, 4n]
arr2 = BigUint64Array.from(arr1);
arr2[0] = 88n;
console.log(arr1);    // BigUint64Array(4) [1n, 2n, 3n, 4n]
console.log(arr2);    // BigUint64Array(4) [88n, 2n, 3n, 4n]

Скопировать фрагмент позволяет метод slice([<Начало>[, <Конец>]). Если параметры не указаны, то создается полная копия. В первом параметре можно указать начальный индекс, а во втором — конечный индекс (не включая элемент с этим индексом). Если второй параметр не задан, то копируется фрагмент, начиная с индекса <Начало> до конца массива:

let arr1, arr2;
arr1 = BigUint64Array.of(1n, 2n, 3n, 4n);
arr2 = arr1.slice();
arr2[0] = 88n;
console.log(arr1);    // BigUint64Array(4) [1n, 2n, 3n, 4n]
console.log(arr2);    // BigUint64Array(4) [88n, 2n, 3n, 4n]
arr2 = arr1.slice(2);
console.log(arr2);    // BigUint64Array(2) [3n, 4n]
arr2 = arr1.slice(2, 3);
console.log(arr2);    // BigUint64Array [3n]

Перебор элементов массива

Для перебора массивов удобно использовать цикл for. Умножим все элементы массива на 2:

let arr = BigUint64Array.of(1n, 2n, 3n);
for (let i = 0; i < arr.length; i++) {
   arr[i] *= 2n;
}
console.log(arr); // BigUint64Array(3) [2n, 4n, 6n]

Перебрать элементы массива позволяет также цикл for...of, который на каждой итерации присваивает переменной копию значения элемента массива:

let arr = BigUint64Array.of(1n, 2n, 3n);
for (const value of arr) {
   console.log(value);
}

Можно также воспользоваться методом forEach(). Формат метода:

forEach(<Функция>[, <this>])

В первом параметре указывается ссылка на функцию, которая будет вызвана для каждого элемента массива. Функция принимает три параметра. Через первый параметр доступно значение текущего элемента, через второй — его индекс, а через третий — ссылка на массив. Значение, указанное в параметре <this>, будет доступно через указатель this внутри функции:

let arr = BigUint64Array.of(1n, 2n, 3n);
arr.forEach( function(value, index, array) {
   array[index] = value * 2n;
});
console.log(arr); // BigUint64Array(3) [2n, 4n, 6n]

Методы, возвращающие итераторы

Следующие методы возвращают специальный объект — итератор:

keys() — возвращает итератор, содержащий индексы элементов массива:

let arr = BigUint64Array.of(1n, 2n, 3n, 4n);
let iterator = arr.keys();
console.log(iterator); // Array Iterator {}
// Перебор всех элементов
for (const key of iterator) {
   console.log(`${key} `);
} // 0 1 2 3
// Преобразование в массив
let arrKeys = [...arr.keys()];
console.log(arrKeys);  // [0, 1, 2, 3]

values() — возвращает итератор, содержащий значения элементов массива:

let arr = BigUint64Array.of(5n, 6n, 7n, 8n);
let iterator = arr.values();
// Перебор всех элементов
for (const value of iterator) {
   console.log(value);
} // 5n 6n 7n 8n
console.log();
// Преобразование в массив
let arrValues = [...arr.values()];
console.log(arrValues);  // [5n, 6n, 7n, 8n]
arrValues = [...arr];
console.log(arrValues);  // [5n, 6n, 7n, 8n]

entries() — возвращает итератор, содержащий пары индекс/значение всех элементов массива:

let arr = BigUint64Array.of(5n, 6n, 7n);
let iterator = arr.entries();
// Перебор всех элементов
for (const [key, value] of iterator) {
   console.log(`${key} => ${value} `);
} // 0 => 5 1 => 6 2 => 7
// Преобразование в массив
let arrEntries = [...arr.entries()];
console.log(arrEntries); // [ [ 0, 5n ], [ 1, 6n ], [ 2, 7n ] ]

Фильтрация массива

Метод filter(<Функция>[, <this>]) позволяет выполнить фильтрацию массива. В первом параметре указывается ссылка на функцию, которая будет вызвана для каждого элемента массива. Функция принимает три параметра. Через первый параметр доступно значение текущего элемента, через второй — его индекс, а через третий — ссылка на массив. Функция должна вернуть значение true, если элемент соответствует условию, и false — в противном случае. Значение, указанное во втором параметре, будет доступно внутри функции через указатель this. Метод возвращает массив элементов, соответствующих условию (для которых функция вернула значение true). Исходный массив не изменяется. Пример:

let arr = BigUint64Array.of(1n, 2n, 3n, 4n, 5n, 6n);
let arr2 = arr.filter( function(value, index, ar) {
   return value < 4n;
});
console.log(arr2);                  // BigUint64Array(3) [1n, 2n, 3n]

С помощью метода map(<Функция>[, <this>]) можно применить пользовательскую функцию ко всем элементам массива. Внутри функции нужно вернуть новое значение элемента. Метод map() возвращает отфильтрованный массив. Пример умножения всех элементов массива на 2:

let arr = BigUint64Array.of(1n, 2n, 3n, 4n, 5n, 6n);
let arr2 = arr.map( function(value, index, ar) {
   return value * 2n;
});
console.log(arr2); // BigUint64Array(6) [2n, 4n, 6n, 8n, 10n, 12n]

Метод reduce(<Функция>[, <Начальное значение>]) применяет функцию к парам элементов и накапливает результат. В первом параметре указывается ссылка на функцию, которая будет вызвана для каждого элемента массива. Функция принимает четыре параметра. Через первый параметр доступен результат предыдущих вычислений или <Начальное значение> при первом вызове, через второй — значение текущего элемента, через третий — его индекс, а через четвертый — ссылка на массив. Внутри функции нужно вернуть результат текущих вычислений. Метод reduce() возвращает общий результат вычислений. Пример получения суммы всех элементов массива:

let arr = BigUint64Array.of(1n, 2n, 3n);
let sum = arr.reduce( function(value1, value2, index, ar) {
   return value1 + value2;
}, 0n);
console.log(sum);              // 6n

Метод reduceRight() аналогичен методу reduce(), но перебирает элементы не слева направо, а справа налево:

let arr = BigUint64Array.of(1n, 2n, 3n);
let sum = arr.reduceRight( function(value1, value2, index, ar) {
   return value1 + value2;
}, 0n);
console.log(sum);              // 6n

Переворачивание массива

Метод reverse() переворачивает массив. Элементы будут следовать в обратном порядке относительно исходного массива:

let arr = BigUint64Array.of(1n, 2n, 3n);
arr.reverse();
console.log(arr);               // BigUint64Array(3) [3n, 2n, 1n]

Получение части массива

Метод slice([<Начало>[, <Конец>]]) возвращает срез массива, начиная от индекса <Начало> и заканчивая индексом <Конец>, но не включает элемент с этим индексом. Если первый параметр не указан, то он будет иметь значение 0. Если второй параметр не указан, то возвращаются все элементы до конца массива:

let arr1, arr2;
arr1 = BigUint64Array.of(1n, 2n, 3n, 4n);
arr2 = arr1.slice();
arr2[0] = 88n;
console.log(arr1);    // BigUint64Array(4) [1n, 2n, 3n, 4n]
console.log(arr2);    // BigUint64Array(4) [88n, 2n, 3n, 4n]
arr2 = arr1.slice(2);
console.log(arr2);    // BigUint64Array(2) [3n, 4n]
arr2 = arr1.slice(2, 3);
console.log(arr2);    // BigUint64Array [3n]

Вместо метода slice() можно воспользоваться методом subarray([<Начало>[, <Конец>]]):

let arr1, arr2;
arr1 = BigUint64Array.of(1n, 2n, 3n, 4n);
arr2 = arr1.subarray();
arr2[0] = 88n;
console.log(arr1);    // BigUint64Array(4) [88n, 2n, 3n, 4n] !!!
console.log(arr2);    // BigUint64Array(4) [88n, 2n, 3n, 4n]
arr2 = arr1.subarray(2);
console.log(arr2);    // BigUint64Array(2) [3n, 4n]
arr2 = arr1.subarray(2, 3);
console.log(arr2);    // BigUint64Array [3n]

Обратите внимание

Метод subarray() не копируют элементы, а лишь создают ссылку на ту же самую область памяти. Изменение первого массива приведет к изменению второго массива.

Сортировка массива

Отсортировать массив позволяет метод sort([Функция сортировки]). Если функция сортировки не указана, будет выполнена обычная сортировка:

let arr = BigUint64Array.of(4n, 1n, 3n, 2n);
arr.sort();
console.log(arr); // BigUint64Array(4) [1n, 2n, 3n, 4n]

Если нужно изменить стандартный порядок сортировки, это можно сделать с помощью пользовательской функции сортировки. Функция принимает две переменные и должна возвращать:

положительное число — если первый элемент больше второго;
отрицательное число — если второй элемент больше первого;
0 — если элементы равны.

Отсортируем массив в обратном порядке:

let arr = BigUint64Array.of(4n, 1n, 3n, 2n);
arr.sort( function(a, b) {
   if (a > b) return -1;
   if (a < b) return 1;
   return 0;
});
console.log(arr); // BigUint64Array(4) [4n, 3n, 2n, 1n]

Проверка наличия значения в массиве

Выполнить поиск элемента в массиве позволяют следующие методы:

indexOf(<Элемент>[, <Индекс>]) — ищет первое вхождение элемента в массиве. Возвращает индекс найденного элемента или значение -1, если элемент не найден. Во втором параметре можно указать индекс, с которого начнется поиск. Если второй параметр не указан, то поиск начинается с начала массива:

let arr = BigUint64Array.of(1n, 2n, 1n, 2n, 3n);
console.log( arr.indexOf(2n) );        // 1
console.log( arr.indexOf(2n, 2) );     // 3
console.log( arr.indexOf(3n) );        // 4
console.log( arr.indexOf(8n) );        // -1

lastIndexOf(<Элемент>[, <Индекс>]) — ищет последнее вхождение элемента в массиве:

let arr = BigUint64Array.of(1n, 2n, 1n, 2n, 3n);
console.log( arr.lastIndexOf(2n) );    // 3
console.log( arr.lastIndexOf(2n, 2) ); // 1
console.log( arr.lastIndexOf(3n) );    // 4
console.log( arr.lastIndexOf(8n) );    // -1

includes(<Элемент>[, <Индекс>]) — возвращает значение true, если элемент присутствует в массиве, и false — в противном случае. Во втором параметре можно указать индекс элемента с которого начнется поиск. Пример:

let arr = BigUint64Array.of(1n, 2n, 3n);
console.log( arr.includes(1n) );    // true
console.log( arr.includes(1n, 1) ); // false
console.log( arr.includes(4n) );    // false

every(<Функция>[, <this>]) — возвращает значение true, если все элементы массива соответствуют заданному условию, и false — в противном случае. В первом параметре указывается ссылка на функцию, которая будет вызвана для каждого элемента массива. Функция принимает три параметра. Через первый параметр доступно значение текущего элемента, через второй — его индекс, а через третий — ссылка на массив. Функция должна вернуть значение true, если элемент соответствует условию, и false — в противном случае. Если функция для всех элементов вернула true, то метод every() также возвращает значение true. Если функция вернет значение false, то проверка прекращается и метод every() возвращает значение false. Значение, указанное во втором параметре, будет доступно внутри функции через указатель this. Пример проверки:

function test(value, index, ar) {
   return value > 1n;
}
let arr = BigUint64Array.of(2n, 3n),
    arr2 = BigUint64Array.of(1n, 2n, 0n);
console.log( arr.every(test) );    // true
console.log( arr2.every(test) );   // false

some(<Функция>[, <this>]) — возвращает значение true, если хотя бы один элемент массива соответствует заданному условию, и false — в противном случае. Если функция вернет значение true, то проверка прекращается и метод some() возвращает значение true. Если функция для всех элементов вернула false, то метод some() также возвращает значение false. Пример:

function test(value, index, ar) {
   return value < 1n;
}
let arr = BigUint64Array.of(2n, 3n),
    arr2 = BigUint64Array.of(1n, 2n, 0n);
console.log( arr.some(test) );    // false
console.log( arr2.some(test) );   // true

find(<Функция>[, <this>]) — возвращает значение первого элемента, для которого функция вернула true, или значение undefined, если функция для всех элементов вернула false. Пример:

function test(value, index, ar) {
   return value < 1n;
}
let arr = BigUint64Array.of(2n, 3n),
    arr2 = BigUint64Array.of(1n, 2n, 0n);
console.log( arr.find(test) );    // undefined
console.log( arr2.find(test) );   // 0n

findIndex(<Функция>[, <this>]) — возвращает индекс первого элемента, для которого функция вернула true, или значение -1, если функция для всех элементов вернула false. Пример:

function test(value, index, ar) {
   return value < 1n;
}
let arr = BigUint64Array.of(2n, 3n),
    arr2 = BigUint64Array.of(1n, 2n, 0n);
console.log( arr.findIndex(test) );    // -1
console.log( arr2.findIndex(test) );   // 2

Преобразование массива в строку или другой объект

Преобразовать массив в строку позволяют следующие методы:

join([<Разделитель>]) — возвращает строку, полученную в результате объединения всех элементов массива через разделитель:

let arr = BigUint64Array.of(1n, 2n, 3n);
let str = arr.join(' - ');
console.log(str); // 1 - 2 - 3

Если параметр не указан, то в качестве символа-разделителя будет использоваться запятая:

let arr = BigUint64Array.of(1n, 2n, 3n);
let str = arr.join();
console.log(str); // 1,2,3

toString() — преобразует массив в строку. Элементы перечисляются через запятую без пробела. Метод вызывается автоматически при использовании строкового контекста. Пример:

let arr = BigUint64Array.of(1n, 2n, 65535n);
console.log( arr.toString() ); // 1,2,65535
console.log(arr + '');         // 1,2,65535

toLocaleString([<Локаль>[, <Опции>]]) — преобразует массив в строку. Элементы указываются через запятую без пробела:

let arr = BigUint64Array.of(1n, 2n, 65535n);
console.log( arr.toLocaleString('en-US') ); // 1,2,65,535
console.log( arr.toLocaleString('ru-RU') ); // 1,2,65 535

Для преобразования типизированного массива в обычный массив можно воспользоваться оператором SPREAD:

let arr = BigUint64Array.of(1n, 2n, 3n);
let arr2 = [...arr];
console.log(arr2); // [1n, 2n, 3n]