عرض مصدر PHP/pack

= الدالة pack()‎ في PHP =
تحزمُ الدالةُ pack()‎ البيانات في سلسلة نصية ثنائية.

== الوصف ==
<syntaxhighlight lang="php">
string pack ( string $format [, mixed $args [, mixed $... ]] )
</syntaxhighlight>تحزمُ الدالةُ pack()‎ البيانات في سلسلة نصية ثنائية وِفْقَ المعامل format.

أُخِذَتْ فكرةُ الدالةِ pack()‎ من لغة البرمجة Perl وجميع رموز التنسيق تعمل كما هو الحال في Perl. ومع ذلك، هناك بعض رموز التنسيق مفقودة مثل رمز التنسيق "u" الخاص بلغة Perl.

لاحظ أن التمييز بين القيم المؤشرة وغير المؤشرة يؤثر فقط على الدالةِ ‎unpack()‎، إذ تعطي الدالةُ pack()‎ نفس النتيجة للشيفرات المؤشرة وغير المؤشرة.

== المعاملات ==

=== format ===
تتكون سلسلة المعامل format من شيفرات التنسيق متبوعةً بوسيط اختياري للتكرار. يمكن أن تكون الوسيط repeater إما قيمة صحيحة أو * للتكرار إلى نهاية بيانات الإدخال.

بالنسبة إلى a، و A، و h، و H يحدد عَدَّادُ التكرار عدد الأحرف التي أُخِذَت لوسيط وحيد يُمثِّل البيانات، أما بالنسبة للرمز @ فهو الموقع المطلق لوضع البيانات التالية، وبالنسبة لأي شيء آخر، فإن عَدَّادَ التكرار يحدد عدد وسائط البيانات التي استُهْلِكَت وحُزِمَت في السلسلة النصية الثنائية الناتجة.

التنسيقات المتاحة حاليًا مذكورةٌ في جدول حروف التنسيق الآتي:
{| class="wikitable"
|الرمز
|الوصف
|-
|a
|سلسلة نصية محشوة بالمحرف NULL.
|-
|A
|سلسلة نصية محشوة بمسافة.
|-
|h
|سلسلة نصية في نظام العد الست عشري، النايبل الصغرى أولًا (low nibble).
|-
|H
|سلسلة نصية في نظام العد الست عشري، النايبل الكبرى أولًا (high nibble).
|-
|c
|حرفٌ مؤشَّر.
|-
|C
|حرفٌ غير مؤشَّر.
|-
|s
|نوع البيانات short المؤشَّر (دائما 16 بت، ترتيب بايت للجهاز).
|-
|S
|نوع البيانات short غير المؤشَّر (دائما 16 بت، ترتيب بايت للجهاز).
|-
|n
|نوع البيانات short غير المؤشَّر (دائمًا 16 بت، ترتيب البايت endian الكبير).
|-
|v
|نوع البيانات short غير المؤشَّر (دائمًا 16 بت، ترتيب البايت endian الصغير).
|-
|i
|نوع البيانات integer المؤشَّر (الإعتماد على حجم الجهاز وترتيب البايت).
|-
|I
|نوع البيانات integer غير المؤشَّر (الإعتماد على حجم الجهاز وترتيب البايت).
|-
|l
|نوع البيانات long المؤشَّر (دائما 32 بت، ترتيب بايت للجهاز).
|-
|L
|نوع البيانات long غير المؤشَّر (دائما 32 بت، ترتيب بايت للجهاز).
|-
|N
|نوع البيانات long غير المؤشَّر (دائمًا 32 بت، ترتيب البايت endian الكبير).
|-
|V
|نوع البيانات long غير المؤشَّر (دائمًا 32 بت، ترتيب البايت endian الصغير).
|-
|q
|نوع البيانات long long المؤشَّر (دائما 64 بت، ترتيب بايت للجهاز).
|-
|Q
|نوع البيانات long long غير المؤشَّر (دائما 64 بت، ترتيب بايت للجهاز).
|-
|J
|نوع البيانات long long غير المؤشَّر (دائمًا 64 بت، ترتيب البايت endian الكبير).
|-
|P
|نوع البيانات long long غير المؤشَّر (دائمًا 64 بت، ترتيب البايت endian الصغير).
|-
|f
|نوع البيانات float (الإعتماد على حجم وتمثيل الجهاز).
|-
|g
|نوع البيانات float (الإعتماد على حجم الجهاز وترتيب البايت endian الصغير).
|-
|G
|نوع البيانات float (الإعتماد على حجم الجهاز وترتيب البايت endian الكبير).
|-
|d
|نوع البيانات double (الإعتماد على حجم وتمثيل الجهاز).
|-
|e
|نوع البيانات double (الإعتماد على حجم الجهاز وترتيب البايت endian الصغير).
|-
|E
|نوع البيانات double (الإعتماد على حجم الجهاز وترتيب البايت endian الكبير).
|-
|x
|نوع البيانات NULL byte.
|-
|X
|نَسْخ بايت واحد إحتياطيًا.
|-
|Z
|سلسلة نصية محشوة بالمحرف NULL (جديد في النسخة PHP 5.5).
|-
|@
|ملء بالمحرف NULL إلى الموقع المطلق.
|}

=== args ===

== القيم المعادة ==
تعيد الدالةُ pack()‎ سلسلة ثنائية تحتوي على بيانات.

== سجل التغييرات ==
{| class="wikitable"
|الإصدار
|الوصف
|-
|7.2.0
|يدعمُ نوعا البيانات float و double كلًا من endian الكبير و endian الصغير.
|-
|7.0.15 و7.1.1
|أُضِيْفَت الرموز "e" و"E" و"g" و"G" للسماح بدعم ترتيب البايت لنوعي البيانات float و double.
|-
|5.6.3
|أُضِيْفَت الرموز "q" و "Q" و "J" و "P" للسماح بالعمل باستخدام أرقام 64 بت.
|-
|5.5.0
|أُضِيْفَ الرمز "Z" مع تكافؤٍ وظيفي إلى "a" لموافقة لغة Perl.
|}

== أمثلة ==
المثال 1: مثال على الدالة pack()‎<syntaxhighlight lang="php">
<?php

$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);

?>
</syntaxhighlight>تكون السلسلة الثنائية الناتجة 6 بايت وتحتوي على تسلسل بايت 0x12 ، 0x34 ، 0x78 ، 0x56 ، 0x41 ، 0x42.

== ملاحظات ==
تحذير: لاحظ أن PHP تخزن نوع البيانات integer داخليًا كقيم مؤشرة ذاتُ حجمٍ يعتمد على الجهاز (نوع البيانات long في اللغة C). سَتُخَزَّنُ القيم الحرفية للأعداد الصحيحة والعمليات التي تنتج أعدادًا خارج حدود نوع البيانات integer على هيئة نوع البيانات float. عند تحزيم البيانات من النوع float كبيانات من النوع integer، فستُحوَّل أولًا إلى نوع البيانات integer. هذا قد يؤدي أ وقد لا يؤدي إلى النتيجة المطلوبة.

أكثر الحالة يمكن أن تلائم هذا التحذير هي عند تحزيم الأرقام غير المؤشرة التي يمكن تمثيلها مع نوع البيانات integer إذا لم يكن مؤشرًا.

في الأنظمة التي يحتوي فيها النوع integer على حجم 32 بت، تُنتج عملية التحويلعادةً نفس نمط البايت كما لو كان نوع البيانات integer غير مؤشَّر. في الأنظمة التي يكون فيها نوع البيانات integer يحتوي على حجم 64 بت، فإن نوع البيانات float على الأرجح لا يحتوي على الجزء العشري بما يكفي للاحتفاظ بالقيمة دون فقد الدقة. إذا امتلكت هذه الأنظمة أيضًا نوع البيانات int 64 بت الأصلي في لغة C (ينطبق هذا الكلام على كل الأنظمة ما عدا الأنظمة الشبيهة بيونكس)، فإن الطريقة الوحيدة لاستخدام تنسيق التحزيم "I" في النطاق الأعلى (upper range) هي إنشاء قيم سالبة صحيحة مع تمثيل البايت نفسه مثل القيمة المطلوبة غير المؤشرة.

== انظر أيضًا ==
* الدالة unpack()‎: فك تحزيم البيانات من السلسلة النصية الثنائية.

== مصادر ==
* [http://php.net/manual/en/function.pack.php صفحة الدالة pack في توثيق PHP الرسمي.]