التابع String.unpack في روبي

يفك التابع unpack ترميز السلسلة النصية التي استدعي معها (والتي قد تحوي بيانات ثنائية) وفقًا إلى سلسلة التنسيق المعطاة، ويعيد مصفوفة من كل قيمة مستخرجة.

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

unpack(format) → anArray

المعاملات

format

سلسلة نصية تمثِّل سلسلة التنسيق. تتكون سلسلة التنسيق من سلسلة من الموجهات ذات المحارف الفردية (اطلع على الجدول الآتي). يمكن أن يعقب كل موجِّه عددٌ يشير إلى عدد مرات تكرار هذا الموجه. سيستعمل الرمز * كل العناصر المتبقية. يمكن أن يلي كل موجه من الموجهات sSiIlL شرطة سفلية أو إشارة تعجب لاستعمال الحجم الأصلي للنوع الذي توفره المنصة المُشِّغلة؛ خلا ذلك، سيُستخدَم حجم ثابت مستقل عن المنصة. يجري تجاهل المسافات الفارغة في سلسلة التنسيق هذه.

يختصر الجدول التالي مختلف التنسيقات مع أصناف روبي المعادة لكل منها:

موجهات من النوع Integer	الصنف المعاد	شرح
C	Integer	عدد بحجم 8 بايتات عديمة الإشارة (‎8-bit unsigned).
S	Integer	عدد بحجم 16 بت عديم الإشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات uint16_t)‎).
L	Integer	عدد بحجم 32 بت عديم الإشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات uint32_t)‎).
Q	Integer	عدد بحجم 64 بت عديم الإشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات uint64_t)‎).
J	Integer	عرض المؤشر عديم الإشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات uintptr_t)‎). متاح منذ Ruby 2.3.
c	Integer	عدد بحجم 8 بايتات ذات إشارة (‎8-bit signed).
s	Integer	عدد بحجم 16 بت ذو إشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات int16_t)‎).
l	Integer	عدد بحجم 32 بت ذو إشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات int32_t)‎).
q	Integer	عدد بحجم 16 بت ذو إشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات int64_t)‎).
j	Integer	عرض المؤشر ذي الإشارة، مع اعتماد الترتيب الطبيعي (native endian) للبايتات intptr_t)‎). متاح منذ Ruby 2.3.
S_ S!‎	Integer	عدد صغير عديم الإشارة، مع اعتماد الترتيب الطبيعي للبايتات (unsigned short, native endian).
I I_ I!‎	Integer	عدد صحيح عديم الإشارة، مع اعتماد الترتيب الطبيعي للبايتات (unsigned int, native endian).
L_ L!‎	Integer	عدد كبير عديم الإشارة، مع اعتماد الترتيب الطبيعي للبايتات (unsigned long, native endian).
Q_ Q!‎	Integer	عدد كبير جدًا عديم الإشارة، مع اعتماد الترتيب الطبيعي للبايتات (unsigned long long, native endian). يطلق الخطأ ArgumentError في حال لم يكن في المنصة النوع long long. متاح منذ Ruby 2.1.
J!‎	Integer	عرض المؤشر عديم الإشارة، مع اعتماد الترتيب الطبيعي للبايتات (مثل الموجه J). متاح منذ Ruby 2.3.
s_ s!‎	Integer	عدد صغير ذو إشارة، مع اعتماد الترتيب الطبيعي للبايتات (signed short, native endian).
i i_ i!‎	Integer	عدد صحيح ذو إشارة، مع اعتماد الترتيب الطبيعي للبايتات (signed int, native endian).
l_ l!‎	Integer	عدد كبير بإشارة، مع اعتماد الترتيب الطبيعي للبايتات (signed long, native endian).
q_ q!‎	Integer	عدد كبير جدًا ذو إشارة، مع اعتماد الترتيب الطبيعي للبايتات (signed long long, native endian). يطلق الخطأ ArgumentError في حال لم يكن في المنصة النوع long long. متاح منذ Ruby 2.1
j!‎	Integer	عرض المؤشر ذي الإشارة، مع اعتماد الترتيب الطبيعي للبايتات (مثل j). متاح منذ Ruby 2.3.
S> s> S!> s!>‎L> l> L!> l!>‎ I!> i!> ‎ Q> q> Q!> q!>‎ J> j> J!> j!>‎	Integer	مثل الموجهات التي لا تحتوي "<"، باستثناء كون البايتات الأقل أهمية مخزنة أولًا (big endian). إن I!> i!>‎ متاحة منذ Ruby 1.9.3. "S>‎" مثله مثل "n" "L>‎" مثله مثل "N"
S< s< S!< s!<‎L< l< L!< l!<‎ I!< i!<‎ Q< q< Q!< q!<‎ J< j< J!< j!<‎	Integer	مثل الموجهات التي لا تحتوي ">"، باستثناء كون البايتات الأكثر أهمية مخزنة أولًا (little endian). إن I!< i!<‎ متاحة منذ Ruby 1.9.3. "S<‎" مثله مثل "v" "L<‎" مثله مثل "V"
n	Integer	عدد بحجم 16 بت عديم الإشارة، ترتيب بايت شبكي (network byte order، أي البايت الأكثر أهمية مخزَّن أولًا [big-endian]).
N	Integer	عدد بحجم 32 بت عديم الإشارة، ترتيب بايت شبكي (network byte order، أي البايت الأكثر أهمية مخزَّن أولًا [big-endian]).
v	Integer	عدد بحجم 16 بت عديم الإشارة، ترتيب البايت بحسب VAX (أي VAX byte order، البايت الأقل أهمية مخزَّن أولًا [little-endian]).
V	Integer	عدد بحجم 32 بت عديم الإشارة، ترتيب البايت بحسب VAX (أي VAX byte order، البايت الأقل أهمية مخزَّن أولًا [little-endian]).
v	Integer	عدد بحجم 16 بت عديم الإشارة، ترتيب البايت بحسب VAX (أي VAX byte order، البايت الأقل أهمية مخزَّن أولًا [little-endian]).
v	Integer	عدد بحجم 16 بت عديم الإشارة، ترتيب البايت بحسب VAX (أي VAX byte order، البايت الأقل أهمية مخزَّن أولًا [little-endian]).
موجهات من النوع Float	عناصر المصفوفة	شرح
D d	Float	عدد عشري مضاعف، مع اعتماد الترتيب الطبيعي للبايتات (double-precision, native format).
F f	Float	عدد عشري، مع اعتماد الترتيب الطبيعي للبايتات (single-precision, native format).
E	Float	عدد عشري مضاعف، مع ترتيب البايتات الأكثر أهمية أولًا (double-precision, little-endian byte order).
e	Float	عدد عشري، مع ترتيب البايتات الأكثر أهمية أولًا (single-precision, little-endian byte order).
G	Float	عدد عشري مضاعف، مع ترتيب البايتات الأقل أهمية أولًا (double-precision, network [big-endian] byte order).
g	Float	عدد عشري، مع ترتيب البايتات الأقل أهمية أولًا (single-precision, network [big-endian] byte order).
موجهات من النوع String	عناصر المصفوفة	شرح
A	String	سلسلة نصية ثنائية عشوائية ( حذف المحارف null الزائدة والمسافات الفارغة المرمزة بترميز ASCII ).
a	String	سلسلة نصية ثنائية عشوائية.
Z	String	سلسلة نصية تنتهي بالمحرف null.
B	String	سلسلة نصية من البتات ‎(bit string)‎ البتات الأكثر أهمية أولًا.
b	String	سلسلة نصية من البتات ‎(bit string)‎ البتات الأقل أهمية أولًا.
H	String	سلسلة نصية ست عشرية (البايت العلوي [high nibble] أولًا).
h	String	سلسلة نصية ست عشرية (البايت السفلي [low nibble] أولًا).
u	String	سلسلة نصية مُرمّزة بالترميز UU.
M	String	ترميز MIME مقتبس قابل للطباعة (quoted-printable, MIME encoding). اطلع على RFC2045.
m	String	سلسلة نصية مُرمّز بالترميز base64 (انظر RFC 2045) (الافتراضي) سلسلة نصية مرمزة بالترميز base64 (انظر RFC 4648) إن اتبِعَت بصفر 0.
P	String	مؤشر لبنية (pointer to a structure، سلسلة نصية ذات طول ثابت)
p	String	مؤشر لسلسة نصية تنتهي بالقيمة null (‏null-terminated string).
موجهات من النوع Misc	عناصر المصفوفة	شرح
@	String	التخطي للموضع المعطى عبر المعامل length.
X	String	التخطي للخلف (backward) بايت واحد.
x	String	التخطي للأمام بايت واحد.

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

تعاد مصفوفة من كل قيمة مستخرجة من السلسلة النصية المعطاة بعد فك ترميزها وفقًا لسلسلة التنسيق format.

أمثلة

مثال على استعمال التابع unpack:

"abc \0\0abc \0\0".unpack('A6Z6')   #=> ["abc", "abc "]
"abc \0\0".unpack('a3a3')           #=> ["abc", " \000\000"]
"abc \0abc \0".unpack('Z*Z*')       #=> ["abc ", "abc "]
"aa".unpack('b8B8')                 #=> ["10000110", "01100001"]
"aaa".unpack('h2H2c')               #=> ["16", "61", 97]
"\xfe\xff\xfe\xff".unpack('sS')     #=> [-2, 65534]
"now=20is".unpack('M*')             #=> ["now is"]
"whole".unpack('xax2aX2aX1aX2a')    #=> ["h", "e", "l", "l", "o"]

انظر أيضًا

• التابع unpack1: يفك ترميز السلسلة النصية التي استدعي معها (والتي قد تحوي بيانات ثنائية) وفقًا إلى سلسلة التنسيق المعطاة، ويعيد أول قيمة مستخرجة. 
• التابع codepoints: يُعيد نقاط الترميز المقابلة لمحارف السلسلة النصية في مصفوفة.
• التابع pack: يُحزِّمُ محتويات المصفوفة التي استُدعيت معه على شكل تسلسل ثنائي (binary sequence) وفقًا للمُوجِّهات المعطاة.

مصادر

• قسم التابع unpack‎ في الصنف String في توثيق روبي الرسمي.