Ruby/Array/pack

يُحزِّمُ (packs) التابع pack محتويات المصفوفة التي استُدعيت معه على شكل تسلسل ثنائي (binary sequence) وفقًا للمُوجِّهات (directives) الواردة في المعامل aTemplateString؛ يمكن أن يتبع المُوجِّهات ","" و "A"" و ""a"" عددًا يحدّد عرض الحقل الناتج. قد تأخذ المُوجّهات المتبقية عددًا أيضًا مما يشير إلى عدد عناصر المصفوفة المطلوب تحويلها.

إذا كان العدد يمثِّل محرف النجمة ("*")، فستُحوَّل جميع عناصر المصفوفة المتبقية. يمكن أن تُتبَع أيٌّ من المُوجّهات "sSiIlL" بشرطة سفلية ("_") أو إشارة تعجب ("!") لاستخدام الحجم الأصلي للمنصة الأساسية (underlying platform) للنوع المحدد؛ خلا ذلك، ستستخدم حجمًا مستقلًا عن المنصة (platform-independent size). يتم تجاهل المسافات البيضاء في سلسلة القالب.

في حال تمرير المعامل aBufferString وكانت سعته (capacity) كافية، فسيستخدمها التابع pack كمخزن مؤقت (buffer) ثمَّ يعيدها. عندما تُحدَّد الإزاحة (offset) ببداية aTemplateString، فستُملَأ النتيجة بعد الإزاحة. في حالة وجود محتويات سابقة في aBufferString وكان طولها أكبر من الإزاحة offset، فسيُكتَب الناتج فوق ما بقي من offsetOfBuffer. أمّا إذا كان طولها أصغر، فسيُملَأ الفراغ المتبقي بالمحرف "‎\0".

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

 pack( aTemplateString ) → aBinaryString
pack( aTemplateString, buffer: aBufferString ) → aBufferString

المعاملات

aTemplateString

يأخذ هذا المعامل إحدى قيم الموجهات المستعملة مع التابع pack وهي:

---

موجهات من النوع Integer	عناصر المصفوفة	شرح
C	Integer	8 بتات بدون إشارة (‎8-bit unsigned)
S	Integer	16 بتة بدون إشارة، هندي أولي ‎16-bit unsigned, native endian [uint16_t] )‎)
L	Integer	32 بتة بدون إشارة، هندي أولي ‎32-bit unsigned, native endian [uint32_t] )‎)
Q	Integer	64 بتة بدون إشارة، هندي أولي ‎64-bit unsigned, native endian [uint64_t] )‎)
J	Integer	عرض المؤشر بدون إشارة، هندي أولي (pointer width unsigned, native endian [uintptr_t]‎ ) هذا الموجه متاح منذ Ruby 2.3
c	Integer	8 بتات بإشارة (‎8-bit signed)
s	Integer	16 بتة بإشارة، هندي أولي ‎16-bit signed, native endian [int16_t] )‎)
l	Integer	32 بتة بإشارة، هندي أولي ‎32-bit signed, native endian [int32_t] )‎)
q	Integer	64 بتة بإشارة، هندي أولي ‎64-bit signed, native endian [int64_t] )‎)
j	Integer	عرض المؤشر بإشارة، هندي أولي (pointer width signed, 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.3
J!‎	Integer	uintptr_t، هندي أولي (مثل 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	عدد long long بإشارة، هندي أولي (signed long long, native endian) يطلق الخطأ ArgumentError في حال لم يكن في المنصة النوع long long. متاح منذ Ruby 2.3
j!‎	Integer	intptr_t، هندي أولي (مثل 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). متاحة منذ 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). متاحة منذ Ruby 1.9.3 "S<‎" مثلها مثل "v" "L<‎" مثلها مثل "V"
n	Integer	‎16-bit unsigned, network (big-endian) byte order‎
N	Integer	‎32-bit unsigned, network (big-endian) byte order‎
v	Integer	‎16-bit unsigned, VAX (little-endian) byte order‎
V	Integer	‎32-bit unsigned, VAX (little-endian) byte order‎
موجهات من النوع Float	عناصر المصفوفة	شرح
D d	Float	توضيب أولي ‎(double-precision)، native format‎
F f	Float	توضيب أولي ‎(single-precision)، native format‎
E	Float	double-precision, little-endian byte orde
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	سلسلة نصية ثنائية عشوائية ( مُزاحة (padded) بالمسافة البيضاء (space) و count هو العرض (width) )
a	String	سلسلة نصية ثنائية عشوائية ( مُزاحة (padded) بالقيمة المعدومة null و count هو العرض (width) )
Z	String	مثل "a" باستثناء أنّ nullمٌضافة مع *
B	String	بتّة نصية ‎(bit string)‎‏ ‎[‏ MSB‏ أولًا]‎‎‎
b	String	بتّة نصية ‎(bit string)‎‏ ‎[‏ LSB أولًا]‎‎‎
H	String	أثمون نصي ‎(hex string)‎‏ ‎[‏ high nibble first‏]‎‎‎
h	String	أثمون نصي ‎(hex string)‎‏ ‎[‏ low nibble first‏]‎‎‎
u	String	سلسلة نصية مُرمّزة بالترميز UU-encoded
M	String	مطبوعة بعلامات التنصيص (quoted printable)، ومرمزة بالترميز MIME (أنظر RFC2045)
m	String	سلسلة نصية مُرمّز بالترميز base64 (انظر RFC 2045، و count هو العرض (width)) في حال كان count يساوي 0،فلن يُضاف أي سطر، أنظر RFC 4648
P	String	مؤشر لبنية (pointer to a structure) [سلسلة نصية ذات طول ثابت (fixed-length) ]
p	String	مؤشر لسلسة نصية مَنهِيّة بالقيمة null (‏null-terminated string)
موجهات من النوع Misc	عناصر المصفوفة	شرح
@	String	التحرك للموضع المطلق (absolute position)
X	String	العودة بمقدار بتة (byte) واحد
x	String	بتة معدومة (null byte)

buffer: aBufferString

مخزن مؤقت يستعمل -إن كانت سعته كافية- لتخزين ناتج تنفيذ التابع pack فيه. انتبه إلى أنَّ الخيار "buffer:‎'' لا يضمن عدم تخصيص الذاكرة في التابع pack. إذا كانت سعة aBufferString غير كافية، فسيَحجز التابع pack حجمًا مناسبًا من الذاكرة.

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

يعاد كائنٌ من النوع aBinaryString، أو تخزَّن هذه البيانات المعادة في المعامل aBufferString (إن أعطي) ثم يعاد.

أمثلة

أمثلة على استخدام التابع pack:

 a = [ "a", "b", "c" ]
n = [ 65, 66, 67 ]
a.pack("A3A3A3")   #=> "a  b  c  "
a.pack("a3a3a3")   #=> "a\000\000b\000\000c\000\000"
n.pack("ccc")      #=> "ABC"

انظر أيضًا

• التابع hash: يعيد قيمة Hash للمصفوفة التي استُدعيت معه.

مصادر

• قسم التابع pack في الصنف Array في توثيق روبي الرسمي.