عرض مصدر JavaScript/Array/copyWithin

<noinclude>{{DISPLAYTITLE:<code>Array.prototype.copyWithin()‎</code>}}</noinclude>
الدالة <code>Array.prototype.copyWithin()‎</code> تنسخ جزءًا من المصفوفة إلى مكانٍ آخر فيها نسخًا سطحيًا، وتُعيد هذا الجزء دون تعديل طول المصفوفة.<syntaxhighlight lang="javascript">
['alpha', 'bravo', 'charlie', 'delta'].copyWithin(2, 0);

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

</syntaxhighlight>

== البنية العامة ==
<syntaxhighlight lang="javascript">
arr.copyWithin(target[, start[, end]])

</syntaxhighlight>

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

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

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

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

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

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

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

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

الدالة <code>copyWithin</code> هي دالة تحويل، فهي تُغيّر محتوى المصفوفة وتُنشِئ خاصيات جديدة إن كان ذلك ضروريًا، لكنها لا تُغيّر طول (<code>[[JavaScript/Array/length|length]]</code>) القيمة <code>this</code>.

== أمثلة ==
<syntaxhighlight lang="javascript">
[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]

</syntaxhighlight>

== تعويض نقص دعم المتصفحات ==
الشيفرة الآتية تُعيد تعريف هذه الدالة لكي نستطيع استخدامها في المتصفحات التي لا تدعم معيار ECMAScript 2015 (أي ES6):<syntaxhighlight lang="javascript">
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);
  }
}

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|45
|32
|غير مدعومة
|32
|9
|}
على النقيض من متصفح IE، يدعم Edge هذه الميزة بدءًا من الإصدار 12.

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-array.prototype.copywithin ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/7.0/#sec-array.prototype.copywithin ECMAScript 2016].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.copywithin ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Array|{{SUBPAGENAME}}]]