Array.prototype.with()
Baseline 2023Newly 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
возвращает новый массив, в котором элемент по указанному индексу заменён указанным значением. Является копирующей версией замены значения элемента с помощью скобочной записи.
Синтаксис
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 ]
Спецификации
Specification |
---|
ECMAScript® 2026 Language Specification # sec-array.prototype.with |