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 بت عديم الإشارة، مع اعتماد الترتيب الطبيعي (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]).
U	Integer	محرف مرمز بالترميز UTF-8.
w	Integer	عدد مضغوط وفقًا للصيغة BER.
موجهات من النوع 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	سلسلة نصية ثنائية عشوائية ( محشوة بمسافة بيضاء، و count هو العرض [width]).
a	String	سلسلة نصية ثنائية عشوائية ( محشوة بالقيمة null، و count هو العرض [width]).
Z	String	مثل "a" باستثناء أنّ 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، و 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 للمصفوفة التي استُدعيت معه.
• التابع unpack: يفك ترميز السلسلة النصية التي استدعي معها (والتي قد تحوي بيانات ثنائية) وفقًا إلى سلسلة التنسيق المعطاة، ويعيد مصفوفة من كل قيمة مستخرجة.

مصادر

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