Array.prototype.copyWithin()‎

الدالة Array.prototype.copyWithin()‎ تنسخ جزءًا من المصفوفة إلى مكانٍ آخر فيها نسخًا سطحيًا، وتُعيد هذا الجزء دون تعديل طول المصفوفة.

['alpha', 'bravo', 'charlie', 'delta'].copyWithin(2, 0);

// ["alpha", "bravo", "alpha", "bravo"]

البنية العامة

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

target

الفهرس (العد يبدأ من الصفر) الذي ستوضع العناصر المنسوخة فيه، وإذا كانت هذه القيمة سالبةً فسيبدأ العد من النهاية.

إذا كانت قيمة هذا الوسيط تساوي أو أكبر من arr.length، فلن يُنسَخ أيّ عنصر، وإذا كانت هذه القيمة أكبر من start، فسيُقتَطَع الجزء المنسوخ ليتسع في arr.length.

start

الفهرس الذي ستبدأ هذه الدالة بنسخ العناصر منه، وإذا كانت هذه القيمة سالبةً فسيبدأ العد من النهاية.

إذا لم تُحدَّد قيمة لهذا الوسيط، فستبدأ الدالة copyWithin النسخ من أوّل المصفوفة (أي من الفهرس 0).

end

الفهرس الذي ستنتهي فيه هذه الدالة من نسخ العناصر، وإذا كانت هذه القيمة سالبةً فسيبدأ العد من النهاية.

إذا لم تُحدَّد قيمة لهذا الوسيط، فستنهي الدالة copyWithin النسخ في آخر المصفوفة (أي حتى arr.length).

القيمة المعادة

المصفوفة المُعدَّلة.

الوصف

الدالة copyWithin تشبه عمل memmove في لغتَي C و ++C، وهي دالةٌ ذات أداءٍ عالٍ لنسخ عناصر المصفوفات؛ لاحظ أنَّ العناصر ستُنسَخ وتلصَق بعملية واحدة، وستُنسَخ العناصر حتى لو كانت منطقة النسخ واللصق تتقاطع مع بعضها بعضًا.

الدالة copyWithin هي دالة تحويل، فهي تُغيّر محتوى المصفوفة وتُنشِئ خاصيات جديدة إن كان ذلك ضروريًا، لكنها لا تُغيّر طول (length) القيمة 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 Typed Arrays
var i32a = new Int32Array([1, 2, 3, 4, 5]);

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

// في المتصفحات التي لا تدعم ES6
[].copyWithin.call(new Int32Array([1, 2, 3, 4, 5]), 0, 3, 4);
// Int32Array [4, 2, 3, 4, 5]

تعويض نقص دعم المتصفحات

الشيفرة الآتية تُعيد تعريف هذه الدالة لكي نستطيع استخدامها في المتصفحات التي لا تدعم معيار ECMAScript 2015 (أي ES6):

if (!Array.prototype.copyWithin) {
  Array.prototype.copyWithin =
  // Array: Number[, Number[, Number]]
  function copyWithin(target, start, stop) {
    var positiveT = target >= 0,
        positiveS = (start = start | 0) >= 0,
        length    = this.length,
        zero      = 0,
        r         = function() {return ((+new Date) * Math.random()).toString(36)},
        delimiter = "\b" + r() + "-" + r() + "-" + r() + "\b",
        hold;

    stop = stop || this.length;
    hold = this.slice.apply(this,
      positiveT?
        [start, stop]:
      positiveS?
        [start, -target]:
      [start])
    .join(delimiter);

    return this.splice.apply(this,
      positiveT?
        [target, stop - start, hold]:
      positiveS?
        [target, stop, hold]:
      [target, start, hold]),
            this.join(delimiter).split(delimiter).slice(zero, length);
  }
}

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	45	32	غير مدعومة	32	9

على النقيض من متصفح IE، يدعم Edge هذه الميزة بدءًا من الإصدار 12.

مصادر ومواصفات

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2016.
• معيار ECMAScript 2015 (6th Edition)‎.