عرض مصدر JavaScript/RegExp/@@replace

<noinclude>{{DISPLAYTITLE:<code>RegExp.prototype.[@@replace]()‎</code>}}</noinclude>
الدالة <code>RegExp.prototype.[@@replace]()‎</code> تُعيد سلسلةً نصيةً جديدةً فيها بعض أو جميع الأجزاء المُطابَقة عبر النمط <code>this</code> قد استبدلتها السلسلة النصية <code>replacement</code>. لاحظ أنَّ النمط <code>pattern</code> يمكن أن يكون سلسلةً نصيةً أو كائن <code>[[JavaScript/RegExp|RegExp]]</code>، ويمكن أن يكون الوسيط <code>replacement</code> سلسلةً نصيةً أو دالةً التي ستُستدعى لكل مُطابَقة.

== البنية العامة ==
<syntaxhighlight lang="javascript">
regexp[Symbol.replace](str, newSubStr|function)

</syntaxhighlight>

=== <code>str</code> ===
السلسلة النصية التي سنبحث عن مُطابَقة للتعبير النمطي فيها لاستبداله.

=== <code>newSubStr</code> ===
السلسلة النصية <code>[[JavaScript/String|String]]</code> التي ستستبدل السلسلة الفرعية، وهنالك عددٌ من الأنماط الفرعية المدعومة فيها، انظر قسم «<nowiki/>[[JavaScript/String/replace#تحديد سلسلة نصية كوسيط|تحديد سلسلة نصية كوسيط]]» في صفحة الدالة <code>[[JavaScript/String/replace|String.prototype.replace()‎]]</code> للتفاصيل.

=== <code>function</code> ===
الدالة التي ستُستدعى عند إنشاء السلسلة النصية الفرعية الجديدة، والوسائط التي تقبلها هذه الدالة مشروحة في قسم «<nowiki/>[[JavaScript/String/replace#تحديد دالة كوسيط|تحديد دالة كوسيط]]» في صفحة الدالة <code>[[JavaScript/String/replace|String.prototype.replace()‎]]</code> للتفاصيل.

=== القيمة المعادة ===
سلسلةٌ نصيةٌ جديدةٌ جرى فيها استبدال بعض أو جميع الأجزاء المُطابَقة.

==الوصف==
تُستدعى هذه الدالة داخليًا في الدالة <code>[[JavaScript/String/replace|String.prototype.replace()‎]]</code> وذلك إذا كان الوسيط <code>pattern</code> هو كائن <code>[[JavaScript/RegExp|RegExp]]</code>. فمثلًا، كلا المثالين الآتيين يُعيد النتيجة نفسها:<syntaxhighlight lang="javascript">
'abc'.replace(/a/, 'A');

/a/[Symbol.replace]('abc', 'A');

</syntaxhighlight>الغرض من وجود هذه الدالة هو السماح بإمكانية تخصيصها في الأصناف الفرعية المشتقة من <code>RegExp</code>.

إذا لم يكن الوسيط <code>pattern</code> هو كائن من النوع <code>[[JavaScript/RegExp|RegExp]]</code>، فلن تستدعي الدالة <code>[[JavaScript/String/replace|String.prototype.replace()‎]]</code> هذه الدالة، ولن تُنِشئ كائن <code>[[JavaScript/RegExp|RegExp]]</code> من الأساس.

== أمثلة ==

=== استدعاء مباشر ===
ستُستخدَم هذه الدالة بنفس طريقة استخدام الدالة <code>[[JavaScript/String/replace|String.prototype.replace()‎]]</code>:<syntaxhighlight lang="javascript">
var re = /-/g; 
var str = '2016-01-01';
var newstr = re[Symbol.replace](str, '.');
console.log(newstr);  // 2016.01.01

</syntaxhighlight>
=== استخدام ‎<code>@@replace</code> في الأصناف الفرعية ===
يمكن للأصناف الفرعية المشتقة من الصنف <code>[[JavaScript/RegExp|RegExp]]</code> إعادة تعريف الدالة <code>‎[@@replace]()‎</code> لتغيير سلوكها الافتراضي:<syntaxhighlight lang="javascript">
class MyRegExp extends RegExp {
  constructor(pattern, flags, count) {
    super(pattern, flags);
    this.count = count;
  }
  [Symbol.replace](str, replacement) {
    // Perform @@replace |count| times.
    var result = str;
    for (var i = 0; i < this.count; i++) {
      result = RegExp.prototype[Symbol.replace].call(this, result, replacement);
    }
    return result;
  }
}

var re = new MyRegExp('\\d', '', 3);
var str = '01234567';
var newstr = str.replace(re, '#'); // String.prototype.replace calls re[@@replace].
console.log(newstr); // ###34567

</syntaxhighlight>

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

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-regexp.prototype-@@replace ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-regexp.prototype-@@replace ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript]]
[[تصنيف:JavaScript Global Objects]]
[[تصنيف:JavaScript RegExp]]