Array.prototype.with()

Baseline 2023
Newly available

Since July 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Метод with() экземпляров Array возвращает новый массив, в котором элемент по указанному индексу заменён указанным значением. Является копирующей версией замены значения элемента с помощью скобочной записи.

Синтаксис

js
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 и свойства с целочисленными индексами.

Примеры

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

js
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() можно обновить один элемент, а затем применить другие методы для получившегося массива.

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

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

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

js
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.

js
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 ]

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

Specification
ECMAScript® 2026 Language Specification
# sec-array.prototype.with

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

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