Array.prototype.with()

Синтаксис

arrayInstance.with(index, value)

Параметры

index

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

• Отрицательный индекс позволяет обращаться к элементам с конца массива: если -array.length <= index < 0, то используется index + array.length.
• Если индекс после нормализации выходит за пределы допустимых значений, возникает ошибка RangeError.

value

Новое значение изменяемого элемента.

Возвращаемое значение

Новый массив, в котором значение элемента с индексом index изменено на новое значение value.

Исключительные ситуации

RangeError

Возникает, если index >= array.length или index < -array.length.

Описание

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

Сочетая with() с at(), можно использовать отрицательные индексы для чтения и записи массивов.

Метод with() никогда не возвращает разрежённый массив. Если исходный массив разрежённый, то в новом массиве пустые слоты будут заменены на undefined.

Метод with() является универсальным. Для его работы необходимо только, чтобы значение this имело свойство length и свойства с целочисленными индексами.

Примеры

Создание нового массива с одним изменённым элементом

const arr = [1, 2, 3, 4, 5];
console.log(arr.with(2, 6)); // [1, 2, 6, 4, 5]
console.log(arr); // [1, 2, 3, 4, 5]

Создание цепочки вызовов

С помощью метода with() можно обновить один элемент, а затем применить другие методы для получившегося массива.

const arr = [1, 2, 3, 4, 5];
console.log(arr.with(2, 6).map((x) => x ** 2)); // [1, 4, 36, 16, 25]

Использование with() с разрежёнными массивами

Метод with() всегда создаёт плотный массив.

const arr = [1, , 3, 4, , 6];
console.log(arr.with(0, 2)); // [2, undefined, 3, 4, undefined, 6]

Вызов with() для объектов, не являющихся массивами

Метод with() создаёт и возвращает новый массив. Он читает свойство length и обращается к каждому свойству, ключ которого является неотрицательным числом меньшим length. При обращении к каждому свойству this элементу массива с индексом, равным ключу этого свойства, присваивается значение этого свойства. В итоге элементу массива с индексом index присваивается value.

const arrayLike = {
  length: 3,
  unrelated: "foo",
  0: 5,
  2: 4,
  3: 3, // игнорируется, так как длина равна 3
};
console.log(Array.prototype.with.call(arrayLike, 0, 1));
// [ 1, undefined, 4 ]

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

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

Смотрите также

• Полифил Array.prototype.with в core-js
• Упорядоченные наборы данных
• Array.prototype.toReversed()
• Array.prototype.toSorted()
• Array.prototype.toSpliced()
• Array.prototype.at()
• TypedArray.prototype.with()