Ruby/Kernel/format

يعيد التابع format السلسلة النصية الناتجة عن تطبيق التابع المُعطى format_string (انظر فقرة البنية العامة) على الوسائط الإضافية المُمرّرة. داخل السلسلة النصية format_string، ستُنسخ كل الأحرف في النتيجة باستثناء تسلسلات التنسيق (format sequences).

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

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

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

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

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

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

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

المعاملات

format_string‎

التنسيق المراد تطبيقه

arguments...‎

الوسائط الممرة إلى format_string‎.

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

سلسلة نصية بعد تنسيقها.

أمثلة

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

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"

انظر أيضا

• التابع sprintf: ينسق السلاسل النصية.

مصادر

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