Array.prototype.copyWithin()

Метод copyWithin() экземпляров Array осуществляет поверхностное копирование части этого массива в другую область того же массива и возвращает этот массив без изменения его длины.

Попробовать

const array = ["a", "b", "c", "d", "e"];

// Copy to index 0 the element at index 3
console.log(array.copyWithin(0, 3, 4));
// Expected output: Array ["d", "b", "c", "d", "e"]

// Copy to index 1 all elements from index 3 to the end
console.log(array.copyWithin(1, 3));
// Expected output: Array ["d", "d", "e", "d", "e"]

Синтаксис

copyWithin(target, start)
copyWithin(target, start, end)

Параметры

target

Индекс (начиная с 0), куда копируется последовательность, преобразованный в целое число. Это соответствует месту, куда будет скопирован элемент с start, и все элементы между start и end копируются в последующие индексы.

• Отрицательный индекс отсчитывается с конца массива — если -array.length <= target < 0, используется target + array.length.
• Если target < -array.length, используется 0.
• Если target >= array.length, ничего не копируется.
• Если target после нормализации позиционируется после start, копирование происходит только до конца array.length (другими словами, copyWithin() никогда не расширяет массив).

start

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

• Отрицательный индекс отсчитывается с конца массива — если -array.length <= start < 0, используется start + array.length.
• Если start < -array.length, используется 0.
• Если start >= array.length, ничего не копируется.

end Необязательный

Индекс (начиная с 0), на котором заканчивать копирование элементов, преобразованный в целое число. copyWithin() копирует до, но не включая end.

• Отрицательный индекс отсчитывается с конца массива — если -array.length <= end < 0, используется end + array.length.
• Если end < -array.length, используется 0.
• Если end >= array.length или end опущен, или undefined, используется array.length, в результате чего копируются все элементы до конца.
• Если end подразумевает позицию до или в позиции, подразумеваемой start, ничего не копируется.

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

Модифицированный массив.

Описание

Метод copyWithin() работает подобно memmove в C и C++ и является высокопроизводительным способом сдвига данных в Array. Это особенно применимо к одноимённому методу TypedArray. Последовательность копируется и вставляется за одну операцию; вставленная последовательность будет содержать скопированные значения, даже если области копирования и вставки перекрываются.

Поскольку undefined становится 0 при преобразовании в целое число, пропуск параметра start имеет тот же эффект, что и передача 0, которая копирует весь массив в целевую позицию, что эквивалентно сдвигу вправо, при котором правая граница обрезается, а левая дублируется. Такое поведение может сбить с толку читателей вашего кода, поэтому вам следует явно передавать 0 как start.

console.log([1, 2, 3, 4, 5].copyWithin(2));
// [1, 2, 1, 2, 3]; move all elements to the right by 2 positions

Метод copyWithin() является мутирующим методом (методом, изменяющим массив). Он не изменяет длину this, но изменяет содержимое this и при необходимости может создавать новые свойства или удалять существующие.

Метод copyWithin() сохраняет пустые слоты. Если область, из которой производится копирование, является разреженной, соответствующие новые индексы пустых слотов удаляются и также становятся пустыми слотами.

Метод copyWithin() является обобщённым (generic). Он ожидает, что значение this будет иметь свойство length и свойства с целочисленными ключами. Хотя строки также являются массивоподобными, этот метод не подходит для применения к ним, поскольку строки неизменяемы.

Примеры

Использование copyWithin()

console.log([1, 2, 3, 4, 5].copyWithin(0, 3));
// [4, 5, 3, 4, 5]

console.log([1, 2, 3, 4, 5].copyWithin(0, 3, 4));
// [4, 2, 3, 4, 5]

console.log([1, 2, 3, 4, 5].copyWithin(-2, -3, -1));
// [1, 2, 3, 3, 4]

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

copyWithin() будет распространять пустые слоты.

console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]

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

Метод copyWithin() считывает свойство length из this, а затем манипулирует задействованными целочисленными индексами.

const arrayLike = {
  length: 5,
  3: 1,
};
console.log(Array.prototype.copyWithin.call(arrayLike, 0, 3));
// { '0': 1, '3': 1, length: 5 }
console.log(Array.prototype.copyWithin.call(arrayLike, 3, 1));
// { '0': 1, length: 5 }
// The '3' property is deleted because the copied source is an empty slot

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

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

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

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