Python/bytearray

مصفوفات البايتات bytearray هي الكائنات القابلة للتغيير والتي تقابل كائنات البايتات bytes.

يُعيد الصّنف bytearray()‎ (والذي يُعامَل مُعاملة الدّالة) مصفوفة بايتات جديدة، ويكون الصّنف تسلسُلًا قابلًا للتّغيير يحتوي على الأعداد الصّحيحة ضمن المدى ‎0 <= x < 256. ويملك مُعظم التّوابع التي تملكها التّسلسلات الأخرى (كالقوائم والصّفوف مثلًا)، والمشروحة في صفحة أنواع التسلسلات القابلة للتّغيير، إضافةً إلى امتلاك مُعظم التّوابع التي يملكها النّوع bytes.

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

bytearray([source[, encoding[, errors]]])

المعاملات

source

مُعامل اختياريّ يُستعمل لتهيئة المصفوفة عبر عدّة طُرق مختلفة:

• إن كان سلسلةً نصيّة، فيجب تمرير قيمة للمعامل encoding (وقيمة للمُعامل errors اختياريًّا)، يُحوّل الصّنف بعدها السّلسلةَ النّصيّة إلى بايتات باستخدام التّابع str.encode()‎.
• إن كان عددًا صحيحًا، فستُهيّأ المصفوفة ببايتات فارغة وسيُحدّد المُعامل حجم المصفوفة.
• إن كان كائنًا متعلّقًا بواجهة طول الذاكرة المؤقتة (buffer)، فسيُستعمل طول ذاكرة مؤقتة قابل للقراءة فقط للكائن لتهيئة مصفوفة البايتات.
• إن كان كائنًا قابلًا للتّكرار (iterable) فيجب أن يحتوي على الأعداد الصّحيحة من 0 إلى 256، والتي تُستعمَل كمحتويات مبدئيّة للمصفوفة.

encoding

ترميز المحارف إن كانت قيمة المُعامل source سلسلةً نصيّة.

errors

يُحدّد طريقة التّعامل مع أخطاء ترميز المحارف.

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

تعيد الدالة ()bytearray مصفوفة جديدة من البايتات، وهي تسلسل من الأعداد الصحيحة قابل للتغيير ضمن المدى ‎0 <= x < 256.

إن لم تُحدّد أية مُعاملات للصّنف، فستُعاد مصفوفة حجمها صفر.

أمثلة

الأمثلة التّالية تُوضّح كيفيّة استعمال هذا الصّنف:

>>> bytearray('ABCD', 'UTF-8') # مصفوفة بايتات من سلسلة نصيّة
bytearray(b'ABCD')
>>> bytearray([1, 2, 3]) # مصفوفة بايتات من قائمة أعداد
bytearray(b'\x01\x02\x03')
>>> bytearray() # مصفوفة بايتات فارغة
bytearray(b'')
>>> bytearray(10) # مصفوفة بايتات فارغة ولها طول محدّد
bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')

ملاحظات

• يكون التصريح عن مصفوفات البايتات باستخدام الدالة bytearray()‎ حصرًا، ولا توجد طريقة أخرى.

• لمّا كانت مصفوفات البايتات قابلةً للتغيير فإنّها تدعم العمليات التي تُجرى على التسلسلات القابلة للتغيير، إضافةً إلى العمليات الشائعة والتي تُجرى على البايتات ومصفوفات البايتات.

التوابع الخاصّة بالكائن bytearray

bytearray.fromhex()‎

تفكّ الدالة ترميز سلسلة نصية تتضمن أعداد ست عشرية إلى كائن bytes.

bytearray.hex()‎

ترمّز الدالة كائن bytearray إلى سلسلة نصية تتضمن عددين ستّ عشريين مقابل كلّ بايت.

bytearray.count()‎

تعيد هذه الدالة عدد مرات ظهور تسلسل فرعي ضمن كائن bytearray.

bytearray.decode()‎

تفك الدالة ترميز البايتات الممرّرة إليها إلى سلسلة نصية.

bytearray.endswith()‎

تتحقّق الدالة من وجود تسلسل فرعي في نهاية البيانات الثنائية الأصلية.

bytearray.find()‎

تعيد الدالة‎ أدنى قيمة للفهرس والذي يكون التسلسل الفرعي موجودًا في ضمن البيانات الثنائية.

bytearray.index()‎

تؤدي هذه الدالة نفس وظيفة الدالة bytearray.find()‎ ولكنّها تطلق الخطأ ValueError إن لم تعثر على التسلسل الفرعي.

bytearray.join()‎

تعيد الدالة  كائن البياتات أو كائن مصفوفة البايتات الناتج عن ربط البيانات الثنائية التابعة لكائن قابل للتكرار (iterable).

bytearray.maketrans()‎

تعيد هذه الدالة الساكنة جدول ترجمة (translation table) يمكن استخدامه بواسطة الدالة bytearray.translate()‎.

bytearray.partition()‎

تقسم هذه الدالة التسلسل عند أول ظهور للقيمة التي يحدّدها المستخدم.

bytearray.replace()‎

تبدّل هذه الدالة العبارة التي يختارها المستخدم - مهما تكرّرت في تسلسل البيانات الثنائية - بالقيمة الجديدة التي يحدّدها.

bytearray.rfind()‎

تعيد الدالة أعلى قيمة للفهرس في التسلسل الأصلي حيث تجد فيه التسلسل الفرعي.

bytearray.rindex()‎

تشبه الدالة bytearray.rfind()‎ في أنّها تحدّد أعلى قيمة للفهرس تجد فيه التسلسل الفرعي ضمن التسلسل الأصلي، وتختلف عنها في أنّها تطلق الخطأ ValueError إن لم تعثر على التسلسل الفرعي.

bytearray.rpartition()‎

تقسم هذه الدالة البيانات الثنائية عند آخر ظهور للقيمة التي يحدّدها المستخدم.

bytearray.startswith()‎

تتحقّق الدالة من أنّ البيانات الثنائية تبدأ بالقيمة التي يحدّدها المستخدم.

bytearray.translate()‎

تعيد الدالة تسلسل البيانات الثنائية بعد إجراء عمليات الربط والحذف بالاعتماد على جدول الترجمة الذي تنشئه الدالة bytearray.maketrans()‎.

ملاحظة: تفترض الدوال التالية استخدام بيانات ثنائية متوافقة مع الترميز ASCII ولكن يمكن استخدامها مع أي نوع من البيانات الثنائية عن طريق تمرير المعاملات المناسبة.

bytearray.center()‎

تعيد الدالة البيانات الثنائية مزاحة نحو الوسط ضمن تسلسل يحمل طولًا يحدّده المستخدم.

bytearray.ljust()‎

تعيد الدالة نسخة من البيانات الثنائية مزاحة نحو اليسار ضمن تسلسل ذي طول محدّد.

bytearray.lstrip()‎

تحذف الدالة البايتات المحدّدة من بداية التسلسل.

bytearray.rjust()‎

تعيد الدالة نسخة من البيانات الثنائية مزاحة نحو اليمين ضمن تسلسل ذي طول محدّد.

bytearray.rsplit()‎

تقسّم الدالة التسلسل الثنائي إلى تسلسلات فرعية من النوع ذاته بالاعتماد على تسلسل ثنائي يحدّد الفاصل.

bytearray.rstrip()‎

تحذف الدالة البايتات المحدّدة من نهاية التسلسل.

bytearray.split()‎

تقسّم الدالة التسلسل الثنائي إلى قائمة من تسلسلات ثنائية فرعية من النوع ذاته، بالاعتماد على فاصل محدّد.

bytearray.strip()‎

تحذف الدالة البايتات المحدّدة من قبل المستخدم من نهاية وبداية التسلسل.

ملاحظة: تفترض الدوال التالية استخدام بيانات ثنائية متوافقة مع الترميز ASCII ولا يمكن استخدامها مع الأنواع الأخرى من البيانات الثنائية.

bytearray.capitalize()‎

تفسر الدالة البيانات الثنائية كحروف في ترميز ASCII وتحوّل الحرف الأول إلى حرف كبير، والحروف الأخرى إلى حروف صغيرة.

bytebytearray.expandtabs()‎

تحوّل الدالة جميع علامات الجدولة في ترميز ASCII إلى مسافة بيضاء واحدة أو أكثر في الترميز ذاته.

bytebytearray.isalnum()‎

تتحقّق هذه الدالة ممّا إذا كانت جميع البايتات في التسلسل الثنائي حروفًا أو أرقامًا عشرية في ترميز ASCII، ومن أنّ التسلسل ليس فارغًا.

bytebytearray.isalpha()‎

تتحقّق الدالة ممّا إذا كان تسلسل البيانات الثنائية يحتوي على الحروف بترميز ASCII فقط، وأنّ التسلسل ليس فارغًا.

bytebytearray.isdigit()‎

تتحقّق الدالة ممّا إذا كان التسلسل الثنائي مكوّنًا من الأعداد العشرية بترميز ASCII فقط، وأنّ التسلسل ليس فارغًا.

bytebytearray.islower()‎

تتحقّق الدالة ممّا إذا كان التسلسل الثنائي يحتوي على حرف واحد صغير على الأقل بترميز ASCII، وتتحقّق من عدم وجود حروف كبيرة.

bytebytearray.isspace()‎

تتحقّق الدالة ممّا إذا كانت جميع البايتات في التسلسل الثنائي هي بايتات المسافة البيضاء في ترميز ASCII، ومن أنّ التسلسل ليس فارغًا.

bytebytearray.istitle()‎

تتحقّق الدالة ممّا إذا كان التسلسل الثنائي هو تسلسل ASCII بحالة titlecase، ومن أنّ التسلسل ليس فارغًا.

bytebytearray.isupper()‎

تتحقّق الدالة ممّا إذا كان التسلسل الثنائي يحتوي على حرف واحد كبير على الأقل بترميز ASCII، وتتحقّق من عدم وجود حروف صغيرة.

bytebytearray.lower()‎

تحول الدالة جميع الحروف بترميز ASCII في التسلسل الثنائي إلى حروف صغيرة.

bytebytearray.splitlines()‎

تقسم الدالة التسلسل الثنائي إلى قائمة من الأسطر.

bytebytearray.swapcase()‎

تقلب الدالة‎ حالة الحروف بترميز ASCII في التسلسل الثنائي.

bytebytearray.title()‎

تحوّل الدالة‎ أوائل الكلمات في التسلسل الثنائي إلى أحرف كبيرة Title Case بترميز ASCII.

bytebytearray.upper()‎

تحول الدالة جميع الحروف بترميز ASCII في التسلسل الثنائي إلى حروف كبيرة.

bytebytearray.zfill()‎

تضيف الدالة‎ العدد ‎b'0'‎ من الترميز ASCII إلى يسار التسلسل الثنائي ليصبح التسلسل بالطول المحدد من قبل المستخدم.

انظر أيضًا

• البايتات byte في بايثون.

مصادر

• صفحة Built-in Types في توثيق بايثون الرسمي.
• قسم الدالة bytearray في صفحة Functions في توثيق Python الرسمي.