الدالة sprintf()‎ في PHP

(PHP 4, PHP 5, PHP 7)

تعيد الدالة sprintf()‎ سلسلة نصية منسقة.

الوصف

string sprintf ( string $format [, mixed $args [, mixed $... ]] )

تعيد الدالة sprintf()‎ سلسلة نصية تثنتَجُ وِفقًا للسلسلة المنسقة format.

المعاملات

format

تتكون سلسلة التنسيق من صفر أو أكثر من التوجيهات: تُنسَخُ الأحرف العادية مباشرةً (باستثناء الرمز %) إلى النتيجة، ومحدِّدات التحويل (conversion specifications)، يؤدي كلُّ مُحدِّدٍ من محددات التحويل إلى جلب قيمة من قيم المعاملات المُمرَّرة إلى الدالة. وهذا ينطبق على كل من الدالة sprintf()‎ والدالة printf()‎.

يتكون كل مُحدِّد تحويل من علامة النسبة المئوية (%)، متبوعةً بواحد أو أكثر من هذه العناصر، بالترتيب:

1. يَفرض مُحدِّد الإشارة (sign specifier) الاختياري استخدامَ علامة - أو + مع الرقم. بشكل افتراضي، تستخدام العلامة - فقط مع الرقم إذا كان سالبًا. يجبر هذا المحدد الأرقام الموجبة على إرفاق علامة + أيضًا.
2. يُحدِّدُ محدد الحشو (padding specifier) الاختياري أَيَّ حرفٍ سَيُسْتَخدَمُ لحشو النتائج إلى حجم السلسلة المُحدَّد. قد يكون هذا الحرف حرف مسافة أو 0 (الرقم صفر). السلوك الافتراضي هو حشو المسافات. يمكن تحديد حرف بديل للحشو بإسباقه بعلامة اقتباس مفردة ('). انظر الأمثلة أدناه.
3. يوضح محدِّد المحاذاة (alignment specifier) الاختياري ما إذا كان يجب محاذاة النتيجة لليسار (left-justified) أو لليمين (right-justified). السلوك الافتراضي هو المحاذاة لليمين (right-justified). استخدام الحرف - هنا يجعلها محاذاة لليسار.
4. عدد اختياري، يضبط محدد العرض (width specifier) عدد الأحرف (الحد الأدنى) التي يجب أن يؤدي إليها هذا التحويل.
5. محدد الدقة (precision specifier) الاختياري الذي يكون على شكل نقطة (.) متبوعةً بسلسلة أرقام اختيارية توضح عدد المنازل العشرية التي يجب عرضها لأرقام الفاصلة. عند استخدام هذا المحدد على سلسلة نصية، فإنه يعمل لتحديد حد أقصى للحروف المطبوعة في السلسلة. بالإضافة إلى ذلك ، يمكن اختيار الحرف الذي سيتم استخدامه عند حشو رقم اختياريًا بين المدى العشري والرقم.
6. محدد نوع يوضح ما نوع بيانات الوسيطة التي يجب معاملتها. الأنواع الممكنة:
   • %: إشارة النسبة المئوية. لا تتطلب وسائط.
   • b: سيُعامل الوسيط كعدد صحيح ويُقدَّم كعدد ثنائي (binary number).
   • c: سيُعامَل الوسيط كعدد صحيح ويُقدَّم كحرف مع قيمة ASCII المقابلة له.
   • d: سيُعامَل الوسيط كعدد صحيح ويُقدَّم كعدد عشري (مع إشارة).
   • e: سيُعامَل الوسيط بالصيغة العلمية (على سبيل المثال، 1.2e + 2). يشير محدد الدقة إلى عدد الأرقام بعد النقطة العشرية منذ PHP 5.2.1. في الإصدارات السابقة، كانت تؤخذ كعدد من الأرقام المهمة (الأقل من واحد).
   • E: مثل ‎%e ولكنها تستخدم حرفًا كبيرًا (على سبيل المثال، 1.2E + 2).
   • f: سيُعامَل الوسيط كعدد عشري ويُعرَض كعدد ذي فاصلة عشرية (مع أخذ إعدادات المحليّة [locale] بالحسبان).
   • F: سيُعامَل الوسيط كعدد عشري ويُقَدَّم كعدد عشري ذي فاصلة (دون أخذ إعدادات المحليّة بالحسبان). متاح منذ PHP 5.0.3.
   • g: اختصار لاستعمال ‎%e و ‎%f.
   • G: اختصار لاستعمال ‎%E و ‎%f.
   • o: سيُعامَل الوسيط كعدد صحيح ويُقدَّم كعدد ثماني.
   • s: سيُعامَل الوسيط ويُقَدَّم كسلسلة نصية.
   • u: سيُعامَل الوسيط كعدد صحيح ويُقدَّم كعدد عشري (غير مُوَقَّع).
   • x: سيُعامَل الوسيط كعدد صحيح ويُقدَّم كعدد سداسي عشري (بأحرف صغيرة).
   • X: سيُعامَل الوسيط كعدد صحيح ويُقدَّم كعدد سداسي عشري (بأحرف كبيرة).

ستُجبَر المتغيرات على نوع مناسب للمُحدِّد:

النوع	المحددات
string	s
integer	d و u و c و o و x و X و b
double	g و G و e و E و f و F

تحذير: قد ينتج عن محاولة استخدام مجموعة من السلسلة النصية ومحددات العرض مع مجموعات الأحرف التي تتطلب أكثر من بايت لكل حرف نتائج غير متوقعة.

تدعم سلسلة التنسيق ترقيم وتبديل الوسائط. انظر إلى هذه الأمثلة للتوضيح:

المثال 1: تبديل الوسائط

<?php
$num = 5;
$location = 'tree';
$format = 'There are %d monkeys in the %s';
echo sprintf($format, $num, $location);
?>

سيُخرِج المثال "There are 5 monkeys in the tree". لكن تخيل أننا نقوم بإنشاء سلسلة تنسيق في ملف منفصل، عادة لأننا نرغب في تدويلها (internationalize) ونقوم بإعادة كتابتها كالتالي: المثال 2: تبديل الوسائط

<?php
$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
?>

لدينا الآن مشكلة. لا يتطابق ترتيب العناصر النائبة في سلسلة التنسيق مع ترتيب الوسائط في الشيفرة. نود أن نترك الشيفرة كما هي، ونخبر سلسلة التنسيق ما هي الوسائط التي تشير إلى العناصر النائبة. سنكتب سلسلة التنسيق بهذه الطريقة بدلاً من ذلك: المثال 3: تبديل الوسائط

<?php
$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
?>

فائدة إضافية هنا هي أنه يمكنك تكرار العناصر النائبة دون إضافة المزيد من الوسائط في الكود. فمثلًا: المثال 4: تبديل الوسائط

<?php
$format = 'The %2$s contains %1$d monkeys.
          That\'s a nice %2$s full of %1$d monkeys.';
echo sprintf($format, $num, $location);
?>

عند استخدام تبديل الوسائط، يجب أن يأتي محدد موقع ‎n$‎ مباشرةً بعد علامة النسبة المئوية (%)، قبل أي محددات أخرى، كما في المثال أدناه.

المثال 5: تبديل الوسائط

<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>

ناتج المثال السابق:

......123
000000123

المثال 6: محدد الموقع مع محددات أخرى

<?php
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>

ناتج المثال السابق:

The tree contains 0005 monkeys

ملاحظة: ستؤدي محاولة استخدام محدد الموقع أكبر من PHP_INT_MAX إلى إنشاء تحذيرات في الدالة sprintf()‎.

تحذير: يتجاهل محدد النوع c كلًا من مُحدِّد الحاشية (padding) ومُحدِّد العرض (width).

args

الوسائط المُمرَّرة إلى الدالة.

…

الوسائط المُمرَّرة إلى الدالة.

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

تعيد سلسلة نصية أُنتِجتْ وفقًا لتنسيق السلسلة النصية format، أو FALSE عند الفشل.

أمثلة

المثال 7: أمثلة مختلفة عن الدالة printf()‎

<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 = 'A'
//لاحظ أنَّ  %%, يطبع الحرف'%' ذاته
printf("%%b = '%b'\n", $n); // تمثيل ثنائي
printf("%%c = '%c'\n", $c); // تطبع رمز ASCII مثل الدالة chr()
printf("%%d = '%d'\n", $n); //تمثيل صحيح قياسي
printf("%%e = '%e'\n", $n); // الصيغة العلمية
printf("%%u = '%u'\n", $n); // تمثيل صحيح دون إشارة لعدد صحيح موجب
printf("%%u = '%u'\n", $u); // تمثيل صحيح دون إشارة لعدد صحيح سالب
printf("%%f = '%f'\n", $n); // تمثيل نقطة عدد عشري
printf("%%o = '%o'\n", $n); // التمثيل الثماني
printf("%%s = '%s'\n", $n); // تمثيل سلسلة نصية
printf("%%x = '%x'\n", $n); // لتمثيل الست عشري (أحرف صغيرة)
printf("%%X = '%X'\n", $n); // لتمثيل الست عشري (أحرف كبيرة)
printf("%%+d = '%+d'\n", $n); // مُحدِّد الإشارة على عدد صحيح موجب
printf("%%+d = '%+d'\n", $u); // مُحدِّد الإشارة على عدد صحيح سالب
?>

ناتج المثال السابق:

%b = '10100111101010011010101101'
%c = 'A'
%d = '43951789'
%e = '4.39518e+7'
%u = '43951789'
%u = '4251015507'
%f = '43951789.000000'
%o = '247523255'
%s = '43951789'
%x = '29ea6ad'
%X = '29EA6AD'
%+d = '+43951789'
%+d = '-43951789'

المثال 8: مُحدِّدات السلاسل النصية في printf()‎

<?php
$s = 'monkey';
$t = 'many monkeys';
printf("[%s]\n",      $s); // ناتج اعتيادي
printf("[%10s]\n",    $s); // المحاذاة لليمين مع المسافات
printf("[%-10s]\n",   $s); // المحاذاة لليسار مع المسافات
printf("[%010s]\n",   $s); // حشو 0 للسلسلة النصية
printf("[%'#10s]\n",  $s); // استخدام حرف الحشو الخاص '#'
printf("[%10.10s]\n", $t); // المحاذاة لليسار ولكن مع إظهار أول 10 أحرف
?>

ناتج المثال السابق:

[monkey]
[    monkey]
[monkey    ]
[0000monkey]
[####monkey]
[many monke]

المثال 9: أعداد صحيحة دون حشو مع الدالة sprintf()‎

<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>

المثال 10: تنسيق العملات مع الدالة sprintf()‎

<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// "123.1"

$formatted = sprintf("%01.2f", $money);
// "123.10"
?>

المثال 11: الصيغة العلمية مع الدالة sprintf()‎

<?php
$number = 362525200;
echo sprintf("%.3e", $number); // 3.625e+8
?>

انظر أيضًا

• الدالة printf()‎: إنتاج سلسلة نصيّة مُنسَّقة.
• الدالة sscanf()‎: تحويل المُدْخَلَ من سلسلة نصية حسب الصيغة المطلوبة.
• الدالة fscanf()‎: تحويل المُدْخَلَ من ملف حسب الصيغة المطلوبة.
• الدالة vscanf()‎: إعادة سلسلة نصيّة مُنسَّقة.
• الدالة number_format()‎: تنسيق رقم مع آلاف مجمَّعة.
• الدالة date()‎: تنسيق الوقت والتاريخ المحلي.

مصادر

• صفحة الدالة sprintf في توثيق PHP الرسمي.