الدالة `re.sub()‎` في بايثون‎

تبدل الدالة حالات التطابق غير المتداخلة في أقصى اليسار -والناتجة عن تطبيق التعبير النمطي المعطى على السلسلة النصية المعطاة- بسلسلة نصية أو بالقيمة المعادة من دالة.

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

re.sub(pattern, repl, string, count=0, flags=0)

المعاملات

pattern

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

repl

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

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

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

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

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

string

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

count

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

تستبدل حالات التطابق الفارغة فقط عندما لا تكون مجاورة لحالة تطابق سابقة، لذا فإنّ الدالة sub('x*'‎, '-', 'abc')‎ تعيد السلسلة '-a-b-c-'.

flags

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

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

تعيد الدالة السلسلة النصية الناتجة من تبديل حالات التطابق غير المتداخلة في أقصى اليسار والناتجة عن تطبيق التعبير النمطي المعطى على السلسلة النصية المعطاة، ليحل محلها البديل repl.

في حال عدم العثور على النمط المطلوب، تعيد الدالة السلسلة النصية دون المساس بها.

ملاحظات

أضيف معامل الرايات الاختياري في الإصدار 3.1 من اللغة.
في الإصدار 3.5 من اللغة تستبدل المجموعات غير المطابقة بسلاسل نصية فارغة.
تعدّ تسلسلات التهريب المجهولة في التعابير النمطية والتي تتضمّن المحرف '\' وحرفًا بترميز ASCII أخطاءً في الإصدار 3.6 من اللغة.
أصبحت تسلسلات التهريب المجهولة في المعامل repl والتي تتكوّن من الحرف '\' وحرف بترميز ASCII تطلق تحذير الاستخدام المهمل deprecation في الإصدار 3.5 من اللغة، ولن يسمح باستخدامها في الإصدار 3.7.

أمثلة

تبيّن الأمثلة التالية طرق استخدام الدالة re.sub()‎:

1- في هذه المثال البديل repl هو سلسل نصية:

>>> import re
>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
...        r'static PyObject*\npy_\1(void)\n{',
...        'def myfunc():')
'static PyObject*\npy_myfunc(void)\n{'

أما في هذا المثال فالبديل هو دالة:

>>> import re
>>> def hexrepl(match):
...     "Return the hex string for a decimal number"
...     value = int(match.group())
...     return hex(value)
... 
>>> re.sub(r'\d+', hexrepl, 'Call 65490 for printing, 49152 for user code.')
'Call 0xffd2 for printing, 0xc000 for user code.'

مثال آخر:

>>> import re
>>> def dashrepl(matchobj):
...     if matchobj.group(0) == '-': return ' '
...     else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
>>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)
'Baked Beans & Spam'

انظر أيضًا

الدالةre.subn()‎ : تؤدي هذه الدالة نفس عمل الدالة re.sub()‎ ولكنّها تعيد الناتج على هيئة صفّ (السلسلة الجديدة، عدد الاستبدالات المجراة).
التابع regex.sub()‎: يبدل التابع حالات التطابق غير المتداخلة في أقصى اليسار -والناتجة عن تطبيق التعبير النمطي المصرّف على السلسلة النصية المعطاة- بسلسلة نصية أو بالقيمة المعادة من دالة.

مصادر