عرض مصدر Ruby/String/gsub-21

<noinclude>{{DISPLAYTITLE:التابع <code>String.gsub!‎</code> في روبي}}</noinclude>
[[تصنيف: Ruby]]
[[تصنيف: Ruby Method]]
[[تصنيف: Ruby String]]
يبدل التابع <code>gsub!‎</code> قيمة (أو قيم) محدَّدة مكان جميع الأنماط المتطابقة في السلسلة النصية التي استدعي معها.

هذا التابع مماثل تمامًا للتابع <code>[[Ruby/String/gsub|gsub]]</code> ولكن يعدل على السلسلة المعطاة نفسها.
==البنية العامة==
<syntaxhighlight lang="ruby">gsub!(pattern, replacement) → str or nil
gsub!(pattern, hash) → str or nil
gsub!(pattern) {|match| block } → str or nil
gsub!(pattern) → an_enumerator</syntaxhighlight>

== المعاملات ==

=== <code>pattern</code> ===
يكون عادةً [[Ruby/Regexp|تعبيرًا نمطيًّا]]. إن كان [[Ruby/String|سلسلة نصية]]، فستُفسَّر أية محارف خاصة بالتعبيرات النمطية الموجودة فيها حرفيًّا؛ أي '‎\\d' سيطابق خط مائل عكسي يتبعه الحرف 'd' مباشرةً بدلًا من عددٍ.

=== <code>replacement</code> ===
إن كان [[Ruby/String|سلسلة نصية]]، فسيحل مكان النصي المتطابق. قد يحوي على مراجع خلفية (back-references) للمجموعات الملتقطة عبر النمط <code>pattern</code> مثل النموذج ‎<code>\\d</code> إذ <code>d</code> هو عدد المجموعة أو ‎<code>\\k<n>‎</code> إذ <code>n</code> هو اسم المجموعة. إن كان سلسلة نصية مقتبسة بعلامتي اقتباس مزدوجتين، يجب أن يُسبّق كلا المرجعين الخلفيين بخط مائل عكسي إضافي. على أي حال، لن تشير المتغيرات الخاصة بالمجموعات الملتقطة (المتطابقة) - مثل ‎<code>$&‎</code> - إلى العنصر الملتقط الحالي.

=== <code>hash</code> ===
[[Ruby/Hash|جدول Hash]]. إن مُرِّر كمعامل ثاني إلى التابع وكانت إحدى القيم المتطابقة مساويةً لإحدى قيم مفاتيحه، فستُبدَل به القيمة المقابلة لهذا المفتاح. أي تُمثِّل تلك القيمة المقابلة سلسلة الاستبدال.

==القيمة المعادة==
تعاد السلسلة النصية المعطاة نفسها بعد تبديل القيمة <code>replacment</code> أو <code>hash</code> مكان جميع الأنماط المتطابقة عبر <code>pattern</code> في السلسلة النصية المعطاة. 

إن لم تُعطَ كتلة ولم يُمرَّر معامل ثانٍ (المعامل <code>replacement</code> أو <code>hash</code>)، فسيُعاد كائن من النوع <code>[[Ruby/Enumerator|Enumerator]]</code>. 

==انظر أيضًا==
* التابع <code>[[Ruby/String/gsub|gsub]]</code>: يعيد نسخة من السلسلة النصية التي استدعيت معه مع تبديل قيمة (أو قيم) محدَّدة مكان جميع الأنماط المتطابقة فيها.
* التابع <code>[[Ruby/String/sub-21|sub!‎]]</code>: يبدل قيمة محدَّدة مكان أول تطابق للنمط معطى في السلسلة النصية التي استدعي معها.
* التابع <code>[[Ruby/String/reverse-21|reverse!‎]]</code>: يعدل على السلسلة النصية التي استدعي معها بعكس ترتيب المحارف فيها.
* التابع <code>[[Ruby/String/scrub-21|scrub!‎]]</code>: يستبدل البايتات غير الصالحة في السلسلة النصية التي استدعي معها بمحرف محدَّد أو بالقيمة التي تعيدها الكتلة إن أعطيت.
* التابع <code>[[Ruby/String/slice-21|slice!‎]]</code>: يقتطع محرفًا ذا فهرس محدد، أو جزءًا محددًا ببداية وطول، أو مجالًا محددًا ببداية ونهاية من السلسلة النصية التي استدعيت معه.

==مصادر==
*[http://ruby-doc.org/core-2.5.1/String.html#method-i-gsub-21 قسم التابع ‎gsub!‎ في الصنف String في توثيق روبي الرسمي.]