Array.prototype.copyWithin()

Метод copyWithin() додає дрібну копію частини масиву в іншу позицію в тому ж масиві та повертає його без зміни довжини.

Синтаксис

arr.copyWithin(target[, start[, end]])

Параметри

target
Індекс (нумерується з 0), куди потрібно скопіювати послідовність. Якщо індекс є від'ємним, target буде рахуватися з кінця масиву.
Якщо значення target дорівнює або більше за arr.length, нічого не скопіюється. Якщо індекс target більший за start, скопійована послідовність буде обрізана відповідно до arr.length.
start Optional
Індекс (нумерується з 0), з якого потрібно починати копіювання елементів. Якщо він від'ємний, start буде рахуватися з кінця.
Якщо параметр start не заданий, copyWithin буде копіювати, починаючи з індекса 0. 
end Optional
Індекс (нумерується з 0), на якому потрібно закінчити копіювання елементів. copyWithin копіює до, але не включаючи, end. Якщо індекс від'ємний, end буде рахуватися з кінця.
Якщо параметр end не заданий, copyWithin буде копіювати до останнього індекса (за замовченням arr.length).

Значення, яке повертається

Змінений масив.

Опис

Метод copyWithin працює, як memmove у C та C++, і є дуже продуктивним методом для зсунення даних у масиві. Це особливо стосується метода TypedArray з такою ж самою назвою. Послідовність копіюється та вставляється однією операцією; вставлена послідовність міститиме скопійовані значення, навіть коли ділянки копіювання та вставки накладаються.

Функція copyWithin є навмисно загальною, вона не вимагає, щоб її this був об'єктом Array.

Метод copyWithin є методом модифікації. Він не змінює довжину об'єкта this, але він змінює його зміст та створює нові властивості в разі необхідності.

Приклади

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

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

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

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

[].copyWithin.call({length: 5, 3: 1}, 0, 3);
// {0: 1, 3: 1, length: 5}

// ES2015 типізовані масиви є підкласами Array
var i32a = new Int32Array([1, 2, 3, 4, 5]);

i32a.copyWithin(0, 2);
// Int32Array [3, 4, 5, 4, 5]

// На платформах, які ще не сумісні з ES2015: 
[].copyWithin.call(new Int32Array([1, 2, 3, 4, 5]), 0, 3, 4);
// Int32Array [4, 2, 3, 4, 5]

Поліфіл

if (!Array.prototype.copyWithin) {
  Object.defineProperty(Array.prototype, 'copyWithin', {
    value: function(target, start/*, end*/) {
    // Кроки 1-2.
    if (this == null) {
      throw new TypeError('this is null or not defined');
    }

    var O = Object(this);

    // Кроки 3-5.
    var len = O.length >>> 0;

    // Кроки 6-8.
    var relativeTarget = target >> 0;

    var to = relativeTarget < 0 ?
      Math.max(len + relativeTarget, 0) :
      Math.min(relativeTarget, len);

    // Кроки 9-11.
    var relativeStart = start >> 0;

    var from = relativeStart < 0 ?
      Math.max(len + relativeStart, 0) :
      Math.min(relativeStart, len);

    // Кроки 12-14.
    var end = arguments[2];
    var relativeEnd = end === undefined ? len : end >> 0;

    var final = relativeEnd < 0 ?
      Math.max(len + relativeEnd, 0) :
      Math.min(relativeEnd, len);

    // Крок 15.
    var count = Math.min(final - from, len - to);

    // Кроки 16-17.
    var direction = 1;

    if (from < to && to < (from + count)) {
      direction = -1;
      from += count - 1;
      to += count - 1;
    }

    // Крок 18.
    while (count > 0) {
      if (from in O) {
        O[to] = O[from];
      } else {
        delete O[to];
      }

      from += direction;
      to += direction;
      count--;
    }

    // Крок 19.
    return O;
  },
  configurable: true,
  writable: true
  });
}

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

Специфікація Статус Коментар
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Array.prototype.copyWithin' in that specification.
Standard Початкове визначення.
ECMAScript 2016 (ECMA-262)
The definition of 'Array.prototype.copyWithin' in that specification.
Standard
ECMAScript Latest Draft (ECMA-262)
The definition of 'Array.prototype.copyWithin' in that specification.
Draft

Сумісність з веб-переглядачами

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
copyWithinChrome Full support 45Edge Full support 12Firefox Full support 32IE No support NoOpera Full support 32Safari Full support 9WebView Android Full support YesChrome Android Full support 45Firefox Android Full support 32Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 4.0.0

Legend

Full support  
Full support
No support  
No support

Див. також