Ruby/Kernel/sprintf

يعيد التابع sprintf السلسلة النصية المُمرَّرة إليه بعد تنسيقها بنمط معيَّن. داخل سلسلة التنسيق، تُنسَخ كل محارفها في السلسلة النصية الناتجة باستثناء سلسلة التنسيق (format sequences).

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

sprintf(format_string [, arguments...] )  → string‎

المعاملات

format_string‎

السلسلة التي تحدد التنسيق. داخل سلسلة التنسيق format_string، ستُنسخ كل المحارف إلى السلسلة النصية الناتجة باستثناء سلسلة التنسيق (format sequences).

صيغة سلسلة محارف التنسيق تأخذ الشكل التالي:

%[flags][width][.precision]type‎

تتألف سلسلة محارف التنسيق من علامة النسبة المئوية، متبوعةً بثلاث حقول اختيارية هي: flags و width و precision ثم تنتهي بمحرف يحدد حقل النوع type. يتحكم حثل النوع في كيفية تأويل الوسيط المقابل sprintf، بينما تعدل الحقول flags ذلك التأويل.

محارف حقل النوع type هي:

حقل النوع	تنسيق الأعداد الصحيحة
b	يحول الوسيط arguments...‎ إلى عدد ثنائي (binary number). الأعداد السالبة ستُعرض كمتمم ثنائي مع البادئة "‎..1‎".
B	يشبه النوع b إلا أنَّه يستخدم حرفًا كبيرًا 0B للبادئة في التنسيق البديل عبر #.
d	يحول الوسيط arguments...‎ إلى عدد عشري (decimal number).
i	مشابه تمامًا للنوع "d".
o	يحول الوسيط إلى عدد ثماني (octal number). الأعداد السالبة ستُعرَض كمتمم ثنائي مع البادئة "‎..7‎".
u	مشابه تمامًا للنوع "d".
x	يحول الوسيط arguments...‎ إلى عدد ست عشري (hexadecimal number). الأعداد السالبة ستُعرض كمتمم ثنائي مع البادئة "‎..f" (تمثل سلسلة نصية لا منتهية بالمحارف f).
X	مكافئ للنوع x لكن مع استخدام الحروف الكبيرة.
حقل النوع	تنسيق الأعداد العشرية
e	يحول الوسائط arguments...‎ العددية الكسرية (floating point) إلى الشكل الأسي مع رقم واحد قبل النقطة العشرية على الشكل ‎[-]d.dddddde[+-]dd. تحدد الدقة (‎precision) عدد الأرقام بعد النقطة العشرية (القيمة الافتراضية تساوي 6).
E	يكافئ "e" لكن يستخدم الحرف E الكبير للدلالة على الأس.
f	يحول الوسائط arguments...‎ العددية الكسرية إلى الشكل الأسي بالشكل ‎[-]ddd.dddddd، حيث تحدد الدقة عدد الأرقام بعد النقطة العشرية.
g	يحول الوسائط arguments...‎ العددية الكسرية (floating point) باستخدام الشكل الأسي إن كان الأسّ أصغر من ‎ -4‎أو أكبر من أو يساوي الدقة (precision)، أو يحوله إلى الشكل dd.dddd خلاف ذلك. تحدد الدقة (‎precision) عدد الأرقام المهمة (significant digits).
G	يكافئ "g" لكن يستخدم الحرف E الكبير للدلالة على الأس.
a	يحول الوسائط arguments...‎ العددية الكسرية إلى الشكل ‎،[-]0xh.hhhhp[+-]dd والذي يتألف من علامة إشارة اختيارية و "0x" و والجزء الكسري على الشكل الست عشري و "p" والجزء الأسي على شكل عدد عشري.
A	يكافئ "a" لكن يستخدم الحرفين X و P الكبيرين.
حقل النوع	تنسيقات أخرى
c	الوسيط arguments...‎ هو شيفرة رقمية لحرف واحد أو سلسلة نصية.
p	قيمة التعبير argument.inspect.
s	الوسيط arguments...‎ هو سلسلة نصية يراد استبدالها. إن احتوى شكل التنسيق على دقة محددة (precision)، فسيكون عدد الأحرف المنسوخة أصغر من تلك الدقة.
%	ستُعرض علامة النسبة المئوية بنفسها، ولن تأخذ مكان أي وسيط.

تعدل الحقول flags سلوك عملية التنسيق. الرايات التي يمكن استعمال مع الحقل flag هي كالتالي:

الراية	تطبق على	شرح
مسافة بيضاء	bBdiouxX aAeEfgG (numeric fmt)	يترك مسافة بيضاء في بداية الأعداد غير السالبة. بالنسبة للتحويلات 'o' و 'x' و 'X' و 'b' و 'B'، تُستخدم علامة الإشارة ناقص مع القيمة المطلقة للأعداد السالبة.
(digit)$	الكل	يحدد قيمة الوسيط المطلقة (absolute argument number) لهذا الحقل. قيم الوسيط المطلقة والنسبية لا يمكن خلطها في النصوص المراد طباعتها عبر sprintf.
#	bBoxX aAeEfgG	تستخدم تنسيقًا بديلًا. بالنسبة للتحويل 'o'، ترفع الدقة إلى أن يصير الرقم الأول '0' إن لم يتم تنسيقه كمتمم (complements). بالنسبة للتحويلات 'x' و 'X' و 'b' و 'B'، بالنسبة للأعداد المخالفة للصفر، تُبدأ النتيجة بالبادئة ''0x''و ''0X'' و ''0b'' و ''0B'' على التوالي. بالنسبة لتحويلات 'a' و 'A' و 'e' و 'E' و 'f' و 'g' و 'G'، تُفرض إضافة النقطة العشرية، حتى لو لم يكن بعدها أي أرقام. بالنسبة للتحويلات 'g' و 'G'، لا تزال الأصفار الإضافية.
+	bBdiouxX aAeEfgG (numeric fmt)	تضاف العلامة + في بداية الأعداد الموجبة. بالنسبة للتحويلات 'o' و 'x' و 'X' و 'b' و 'B'، تُستخدم علامة إشارة السالبة - مع القيمة المطلقة للأعداد السالبة.
-	الكل	تعدِّل نتيحة تنسيق السلسلة النصية إلى الجهة اليسرى.
0	bBdiouxX aAeEfgG (numeric fmt)	تملأ المنازل الرقمية الفارغة بالأصفار، وليس المسافات البيضاء. بالنسبة للتحويلات 'o' و 'x' و 'X' و 'b' و 'B'، تُستخدم الأساسradix-1 للأعداد السالبة المُنسّقة على شكل متممات.
*	الكل	يستخدم الوسيط الموالي كعرض للسلسلة النصية المراد تنسيقها. إن كان سالبًا، فستعدل نتيحة التحويل إلى الجهة اليسرى. إن اتبِعت العلامة * بعدد وبالعلامة $، فسيُستخدم الوسيط كعرض للسلسلة النصية.

أمثلة على استعمال الرايات flags:

# `+' and space flag specifies the sign of non-negative numbers.
sprintf("%d", 123)  #=> "123"
sprintf("%+d", 123) #=> "+123"
sprintf("% d", 123) #=> " 123"

# `#' flag for `o' increases number of digits to show `0'.
# `+' and space flag changes format of negative numbers.
sprintf("%o", 123)   #=> "173"
sprintf("%#o", 123)  #=> "0173"
sprintf("%+o", -123) #=> "-173"
sprintf("%o", -123)  #=> "..7605"
sprintf("%#o", -123) #=> "..7605"

# `#' flag for `x' add a prefix `0x' for non-zero numbers.
# `+' and space flag disables complements for negative numbers.
sprintf("%x", 123)   #=> "7b"
sprintf("%#x", 123)  #=> "0x7b"
sprintf("%+x", -123) #=> "-7b"
sprintf("%x", -123)  #=> "..f85"
sprintf("%#x", -123) #=> "0x..f85"
sprintf("%#x", 0)    #=> "0"

# `#' for `X' uses the prefix `0X'.
sprintf("%X", 123)  #=> "7B"
sprintf("%#X", 123) #=> "0X7B"

# `#' flag for `b' add a prefix `0b' for non-zero numbers.
# `+' and space flag disables complements for negative numbers.
sprintf("%b", 123)   #=> "1111011"
sprintf("%#b", 123)  #=> "0b1111011"
sprintf("%+b", -123) #=> "-1111011"
sprintf("%b", -123)  #=> "..10000101"
sprintf("%#b", -123) #=> "0b..10000101"
sprintf("%#b", 0)    #=> "0"

# `#' for `B' uses the prefix `0B'.
sprintf("%B", 123)  #=> "1111011"
sprintf("%#B", 123) #=> "0B1111011"

# `#' for `e' forces to show the decimal point.
sprintf("%.0e", 1)  #=> "1e+00"
sprintf("%#.0e", 1) #=> "1.e+00"

# `#' for `f' forces to show the decimal point.
sprintf("%.0f", 1234)  #=> "1234"
sprintf("%#.0f", 1234) #=> "1234."

# `#' for `g' forces to show the decimal point.
# It also disables stripping lowest zeros.
sprintf("%g", 123.4)   #=> "123.4"
sprintf("%#g", 123.4)  #=> "123.400"
sprintf("%g", 123456)  #=> "123456"
sprintf("%#g", 123456) #=> "123456."

الحقل width هو عدد صحيح اختياري يُتبَع اختياريًا بنقطة وبقيمة تمثِّل حقل الدقة precision. يحدد الحقل width الحد الأدنى لعدد محارف السلسلة النصية الناتجة. أمثلة على الحقل width:

# padding is done by spaces,       width=20
# 0 or radix-1.             <------------------>
sprintf("%20d", 123)   #=> "                 123"
sprintf("%+20d", 123)  #=> "                +123"
sprintf("%020d", 123)  #=> "00000000000000000123"
sprintf("%+020d", 123) #=> "+0000000000000000123"
sprintf("% 020d", 123) #=> " 0000000000000000123"
sprintf("%-20d", 123)  #=> "123                 "
sprintf("%-+20d", 123) #=> "+123                "
sprintf("%- 20d", 123) #=> " 123                "
sprintf("%020x", -123) #=> "..ffffffffffffffff85"

بالنسبة للحقول العددية، يتحكم الحقل precision في عدد المنازل العشرية المعروضة (دقة العدد العشري). بالنسبة للحقول النصية، يحدد الحقل precision الحد الأقصى لعدد الأحرف التي ستُنسخ من السلسلة (بناءً على ذلك، فإن سلسلة التنسيق ‎%10.10s ستخصص دائمًا عشرة أحرف بالضبط للسلسلة النصية المعادة). أمثلة على الحقل precision:

# precision for `d', 'o', 'x' and 'b' is
# minimum number of digits               <------>
sprintf("%20.8d", 123)  #=> "            00000123"
sprintf("%20.8o", 123)  #=> "            00000173"
sprintf("%20.8x", 123)  #=> "            0000007b"
sprintf("%20.8b", 123)  #=> "            01111011"
sprintf("%20.8d", -123) #=> "           -00000123"
sprintf("%20.8o", -123) #=> "            ..777605"
sprintf("%20.8x", -123) #=> "            ..ffff85"
sprintf("%20.8b", -11)  #=> "            ..110101"

# "0x" and "0b" for `#x' and `#b' is not counted for
# precision but "0" for `#o' is counted.  <------>
sprintf("%#20.8d", 123)  #=> "            00000123"
sprintf("%#20.8o", 123)  #=> "            00000173"
sprintf("%#20.8x", 123)  #=> "          0x0000007b"
sprintf("%#20.8b", 123)  #=> "          0b01111011"
sprintf("%#20.8d", -123) #=> "           -00000123"
sprintf("%#20.8o", -123) #=> "            ..777605"
sprintf("%#20.8x", -123) #=> "          0x..ffff85"
sprintf("%#20.8b", -11)  #=> "          0b..110101"

# precision for `e' is number of
# digits after the decimal point           <------>
sprintf("%20.8e", 1234.56789) #=> "      1.23456789e+03"

# precision for `f' is number of
# digits after the decimal point               <------>
sprintf("%20.8f", 1234.56789) #=> "       1234.56789000"

# precision for `g' is number of
# significant digits                          <------->
sprintf("%20.8g", 1234.56789) #=> "           1234.5679"

#                                         <------->
sprintf("%20.8g", 123456789)  #=> "       1.2345679e+08"

# precision for `s' is
# maximum number of characters                    <------>
sprintf("%20.8s", "string test") #=> "            string t"

بالنسبة للتنسيقات الأكثر تعقيدًا، تدعم روبي المراجع الاسمية (reference by name). حيث يستخدم النمط ‎%<name>s نمط التنسيق (format style)، وذلك على خلافًا للنمط {name‎}%.

arguments...‎

المحارف التي ستمرر إلى سلسلة التنسيق format_string‎ لتنسيقها قبل إعادتها.

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

تُعاد سلسلة نصية تحوي قيمة المعاملات arguments...‎ المعطاة بعد تنسيقها وفقًا لسلسلة التنسيق format_string‎.

أمثلة

مثال على استخدام التابع sprintf‎:

sprintf("%d %04x", 123, 123)               #=> "123 007b"
sprintf("%08b '%4s'", 123, 123)            #=> "01111011 ' 123'"
sprintf("%1$*2$s %2$d %1$s", "hello", 8)   #=> "   hello 8 hello"
sprintf("%1$*2$s %2$d", "hello", -8)       #=> "hello    -8"
sprintf("%+g:% g:%-g", 1.23, 1.23, 1.23)   #=> "+1.23: 1.23:1.23"
sprintf("%u", -123)                        #=> "-123"

sprintf("%<foo>d : %<bar>f", { :foo => 1, :bar => 2 })
  #=> 1 : 2.000000
sprintf("%{foo}f", { :foo => 1 })
  # => "1f"

انظر أيضا

• التابع format: ينسق السلسلة النصية المعطاة ثم يعيدها.

مصادر

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