Array.prototype.with()

Метод 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 объекта this, а затем обращается к каждому свойству, ключ которого является неотрицательным целым числом, меньшим length. При доступе к каждому свойству this элемент массива, имеющий индекс, равный ключу свойства, устанавливается в значение свойства. Наконец, значение массива в index устанавливается в value.

const arrayLike = {
  length: 3,
  unrelated: "foo",
  0: 5,
  2: 4,
  3: 3, // ignored by with() since length is 3
};
console.log(Array.prototype.with.call(arrayLike, 0, 1));
// [ 1, undefined, 4 ]

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

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

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

• Полифил Array.prototype.with в core-js
• Полифил es-shims Array.prototype.with
• Руководство по Индексированным коллекциям
• Array.prototype.toReversed()
• Array.prototype.toSorted()
• Array.prototype.toSpliced()
• Array.prototype.at()
• TypedArray.prototype.with()