عرض مصدر Python/re/subn

<noinclude>{{DISPLAYTITLE:الدالة <code>re.subn()‎</code> في بايثون‎}}</noinclude>
تؤدي هذه الدالة نفس عمل الدالة <code>[[Python/re/sub|re.sub()‎]]</code> ولكنّها تعيد الناتج على هيئة [[Python/tuples|صفّ]] (السلسلة الجديدة، عدد الاستبدالات المجراة). 

== البنية العامة ==
<syntaxhighlight lang="python3">
re.subn(pattern, repl, string, count=0, flags=0)
</syntaxhighlight>

== المعاملات ==
<code>pattern</code>

التعبير النمطي المستخدم لإجراء عملية المطابقة. يمكن للنمط أن يكون سلسلة نصية أو كائن نمط pattern object.

<code>repl</code>

يمكن للبديل <code>repl</code> أن يكون سلسلة نصية أو دالة، وإن كان سلسلة نصية، فإنّ الدالة تعالج جميع المحارف المهرّبة فيها. بمعنى أنّ <code>‎\n</code> تحوّل إلى محرف سطر جديد مفرد، و <code>‎\r</code> تحوّل إلى حرف إرجاع، وهكذا. أما المحارف المجهولة مثل <code>‎\&</code>‎ فتترك على حالها. وفي حال وجود إشارات خلفية مثل <code>‎\6‎K</code>، فإنّ السلسلة النصية الفرعية المطابقة بواسطة المجموعة <code>6</code> في النمط ستحلّ محل السلسلة الأصلية.

عندما يكون المعامل <code>repl</code> سلسلة نصية، فبالإضافة إلى ما ورد أعلاه بخصوص محارف التهريب والإشارات الخلفية، فإنّ التسلسل <code>‎\g<name></code>‎ سيستخدم السلسلة النصية الفرعية المطابقة بواسطة المجموعة التي تحمل الاسم <code>name</code>، وعلى النحو المبيّن في صيغة <code>(‎?P<name>...‎)</code>.

يستخدم التسلسل <code>‎\g<number></code>‎ عدد المجموعة المقابل، فمثلًا يكون التسلسل <code>‎\g<2></code>‎ مكافئًا للتسلسل <code>‎\2</code>، ولن يتسبب هذا التسلسل بحدوث لبس في حالات مثل <code>‎\g<2>0</code>، إذ قد يُفسّر التسلسل <code>‎\20</code> كإشارة إلى المجموعة <code>20</code> وليس كإشارة إلى المجموعة <code>2</code> متبوعة بالحرف <code>'0'</code>.

تستبدل الإشارة الخلفية <code>‎\g<0></code>‎ في كامل السلسلة الفرعية المطابقة للتعبير النمطي.

إن كان البديل <code>repl</code> دالّة، فإنّها تُستدعى عند كل حالة تطابق غير متداخلة. تأخذ الدالة معاملًا واحدًا وهو كائن <code>match</code>، وتعيد السلسلة النصية البديلة.

<code>string</code>

السلسلة النصية التي ستبحث فيها الدالة عن حالات التطابق.

<code>count</code>

يعيّن المعامل الاختياري <code>count</code> الحد الأقصى لحالات التطابق التي سيجري استبدالها، ويجب أن يكون عددًا صحيحًا غير سالب. إن لم يأخذ هذا المعامل أيّ قيمة أو أخذ القيمة <code>0</code> فإنّ الدالة ستستبدل جميع حالات التطابق.

<code>flags</code>

الرايات المستخدمة لضبط عملية البحث. يأخذ هذا المعامل القيمة <code>0</code> كقيمة افتراضية. راجع قسم المعاملات في توثيق الدالة <code>[[Python/re/compile|()re.compile]]</code> للمزيد من المعلومات.

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

في حال عدم العثور على النمط المطلوب، تعيد الدالة صفًّا القيمة الأولى فيه هي السلسلة النصية الأصلية، والقيمة الثانية هي <code>0</code> .

== ملاحظات ==

1- أضيف معامل الرايات الاختياري في الإصدار 3.1 من اللغة.

2- في الإصدار 3.5 من اللغة تستبدل المجموعات غير المطابقة بسلاسل نصية فارغة.

== أمثلة ==
يبين المثال التالي النتائج المعادة من استخدام الدالة:

<syntaxhighlight lang="python3">
>>> import re
>>> re.subn(r'(blue|white|red)', 'colour', 'blue socks and red shoes')
('colour socks and colour shoes', 2)
>>> re.subn(r'(blue|white|red)', 'colour', 'no colours at all')
('no colours at all', 0)
</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[Python/re/sub|re.subn()‎]]</code> : تبدل الدالة حالات التطابق غير المتداخلة في أقصى اليسار -والناتجة عن تطبيق التعبير النمطي المعطى على السلسلة النصية المعطاة- بسلسلة نصية أو بالقيمة المعادة من دالة.
* التابع <code>[[Python/regex/sub|regex.subn()]]‎</code> : يبدل التابع حالات التطابق غير المتداخلة في أقصى اليسار -والناتجة عن تطبيق التعبير النمطي المصرّف على السلسلة النصية المعطاة- بسلسلة نصية أو بالقيمة المعادة من دالة.

== مصادر ==
* [https://docs.python.org/3/library/re.html#re.subn قسم Module Contents في صفحة Regular expressions operations في توثيق بايثون الرسمي.]
* [https://docs.python.org/3/howto/regex.html صفحة Regular Expression HOWTO في توثيق بايثون الرسمي.]
[[تصنيف:Python]]
[[تصنيف:Python Regular Expressions]]
[[تصنيف:Python Modules]]