2.5. دوال السلاسل والتنسيق¶

تأتي السلاسل مزوّدة بصندوق أدوات مدمج من الدوال للفحص وإعادة التشكيل. وبما أن السلاسل غير قابلة للتغيير، فإن كل دالة تُعيد سلسلة جديدة -- وتبقى الأصلية دون تغيير.

2.5.1. فحص السلاسل¶

str.startswith() / str.endswith() -- اختبار بادئة أو لاحقة؛ يُعيد bool.
str.find() -- موضع أول ظهور لسلسلة فرعية، أو -1 عند غيابها. تفعل str.index() الأمر نفسه لكنها تثير ValueError عند الغياب.
str.count() -- عدد مرات الظهور غير المتداخلة.
الكلمة المفتاحية in -- إن "MV" in name يُعيد True إذا كانت السلسلة الفرعية موجودة في أي مكان داخل السلسلة.

>>> name = "OpenMV Cam"
>>> name.startswith("Open")
True
>>> name.find("MV")
4
>>> name.count("m")
1
>>> "Cam" in name
True

2.5.2. التنظيف وحالة الأحرف¶

str.strip() -- إزالة المسافات البيضاء البادئة والختامية. مرّر سلسلة من الأحرف لإزالة مجموعة مخصصة (s.strip("/")).
str.lower() / str.upper() -- تحويل حالة الأحرف.
str.replace() -- استبدال سلسلة فرعية.

>>> "  hello  ".strip()
'hello'
>>> "abc-123".replace("-", "_")
'abc_123'
>>> "OpenMV".lower()
'openmv'

2.5.3. التقسيم والدمج¶

str.split() -- تقسيم سلسلة إلى قائمة عند كل ظهور لفاصل (الافتراضي: أي مقطع مسافة بيضاء).
str.join() -- العملية العكسية: لصق سلسلة من السلاسل معاً باستخدام المستقبِل كفاصل. هذه هي الطريقة الفعّالة لبناء سلسلة طويلة من أجزاء.

>>> "1,2,3".split(",")
['1', '2', '3']
>>> "hello world".split()
['hello', 'world']
>>> ", ".join(["a", "b", "c"])
'a, b, c'

2.5.4. السلاسل المنسّقة (f-strings)¶

أبسط طريقة لإدراج القيم داخل سلسلة هي السلسلة المنسّقة (f-string) -- وهي سلسلة حرفية مسبوقة بـ f. يُقيَّم أي تعبير داخل {} ويُدرَج:

>>> name = "OpenMV"
>>> count = 42
>>> f"{name} saw {count} blobs"
'OpenMV saw 42 blobs'

النقطتان داخل الأقواس المعقوفة تُدخلان مواصفة تنسيق تتحكم في كيفية عرض القيمة:

{x:.2f} -- عدد عشري بخانتين بعد الفاصلة العشرية.
{x:>10} -- محاذاة إلى اليمين في حقل بعرض 10 أحرف.
{x:<10} -- محاذاة إلى اليسار.
{x:0>4} -- حشو بأصفار بادئة حتى عرض 4.
{x:#x} -- ست عشري مع بادئة 0x.
{x:b} -- التمثيل الثنائي.

>>> f"pi is roughly {3.14159:.3f}"
'pi is roughly 3.142'
>>> f"reg = {0xAB:#x}"
'reg = 0xab'
>>> for i in range(3):
...     print(f"line {i:0>3}")
line 000
line 001
line 002

إن = مفردة بعد اسم التعبير تطبع الاسم والقيمة معاً -- مفيدة لطباعات التنقيح السريعة:

>>> v = 3.14
>>> print(f"{v=}")
v=3.14

2.5.4.1. تحويلات أساس الأعداد الصحيحة¶

ثلاث دوال مدمجة تؤدي العمل نفسه الذي تؤديه مواصفات التنسيق :b / :o / :x لكنها تُعيد السلسلة المُحوَّلة مباشرةً:

bin() -- الأساس 2، مع بادئة "0b".
oct() -- الأساس 8، مع بادئة "0o".
hex() -- الأساس 16، مع بادئة "0x".

>>> hex(255)
'0xff'
>>> bin(10)
'0b1010'
>>> oct(8)
'0o10'

الاتجاه العكسي -- تحويل سلسلة بأساس N إلى عدد صحيح -- يستخدم المُنشئ int مع أساس صريح:

>>> int("ff", 16)
255
>>> int("0b1010", 2)         # the "0b" prefix is allowed
10

ألجأ إلى هذه عندما تريد السلسلة الخام لعدد صحيح (لسطر سجل، أو ملف إعدادات، أو تفريغ سجل). والجأ إلى مواصفة التنسيق عندما تريد الحشو أو العرض، أو لمزج القيمة مع نص آخر في السلسلة المنسّقة نفسها.

2.5.5. أنماط تنسيق أقدم¶

السلاسل المنسّقة هي النمط الموصى به، لكن هناك أسلوبين أقدم لا يزالان يعملان ويظهران في الكود الموجود:

str.format() -- أقواس معقوفة مع وسائط موضعية أو مفتاحية تُمرَّر إلى الدالة .format() على سلسلة قالب:

>>> "Hello, {}".format(name)
'Hello, OpenMV'
>>> "{0} + {0} = {1}".format(2, 4)
'2 + 2 = 4'
>>> "{name}: {value}".format(name="frames", value=42)
'frames: 42'

تعمل مواصفات التنسيق ({:.2f} و{:>10} و...) بالطريقة نفسها كما في السلاسل المنسّقة؛ والفرق الوحيد هو أين تُزوَّد القيمة.

تنسيق % (بأسلوب printf) -- مُعامِل % واحد يستبدل القيم في رموز التنسيق، قيمة واحدة لكل رمز. مرّر قيماً متعددة كصف (tuple):

>>> "Hello, %s" % name
'Hello, OpenMV'
>>> "%d + %d = %d" % (2, 2, 4)
'2 + 2 = 4'
>>> "%.2f" % 3.14159
'3.14'

أكثر رموز الأنواع شيوعاً هي %s (سلسلة)، و%d (عدد صحيح)، و%f (عدد عشري)، و%x (ست عشري).

يمكن لكل رمز % أن يحمل مُعدِّلات بين % وحرف النوع. الشكل الكامل هو %[flags][width][.precision]type:

العرض -- الحد الأدنى لعدد الأحرف التي يجب أن يأخذها الحقل. تُحشى القيم الأقصر بمسافات؛ وتفيض القيم الأطول. إن %10d يحجز 10 أحرف ويحاذي العدد إلى اليمين.
الدقة -- يتوقف معناها على النوع. بالنسبة للأعداد العشرية، هي عدد الخانات بعد الفاصلة العشرية. إن %.2f يعطي خانتين عشريتين. وبالنسبة للسلاسل، هي الحد الأقصى لعدد الأحرف المأخوذة (%.5s يقتطع إلى خمسة).
المحاذاة إلى اليسار -- الراية - تضع الحقل على اليسار. إن %-10d يضع الأرقام في الجانب الأيسر مع مسافات ختامية.
الحشو بالأصفار -- الراية 0 تحشو بأصفار بادئة بدلاً من المسافات (للأنواع العددية). إن %05d يحشو بالأصفار حتى خمس خانات.
الإشارة -- الراية + تُظهر الإشارة دائماً على الأعداد، بما في ذلك + للأعداد الموجبة.
الشكل البديل -- الراية #. بالنسبة لـ %x تضيف بادئة 0x للمخرَج؛ وبالنسبة لـ %o تضيف بادئة 0o.

يمكن دمج الرايات والعرض والدقة:

>>> "%10d" % 42
'        42'                 # width 10, space-padded, right-aligned
>>> "%-10d|" % 42
'42        |'                # width 10, left-aligned
>>> "%05d" % 42
'00042'                      # width 5, zero-padded
>>> "%8.2f" % 3.14159
'    3.14'                   # width 8, 2 decimal places
>>> "%08.2f" % 3.14159
'00003.14'                   # width 8, zero-padded
>>> "%+d" % 42
'+42'                        # explicit sign
>>> "%#06x" % 0xAB
'0x00ab'                     # 0x prefix, zero-pad to 6 chars total

كلا الأسلوبين الأقدم أبطأ في القراءة وأكثر عرضة للخطأ من السلاسل المنسّقة -- الجأ إلى السلاسل المنسّقة في الكود الجديد، واعرف الأشكال الأقدم عند قراءة الكود الموجود.