الفرق بين المراجعتين لصفحة: «Ruby/Kernel/format»

المراجعة الحالية بتاريخ 14:32، 17 نوفمبر 2018

يعيد التابع format السلسلة النصية المعطاة بعد تنسيقها بشكل معين.

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

format(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:

# تحدد الراية "+" والمسافة البيضاء إشارة الأعداد غير السالبة
sprintf("%d", 123)  #=> "123"
sprintf("%+d", 123) #=> "+123"
sprintf("% d", 123) #=> " 123"

# يرفع عدد المنازل العددية  "o" استخدام الراية "#" مع الحرف
# تغير الراية "+" والمسافة البيضاء تنسيق الأعداد غير السالبة
sprintf("%o", 123)   #=> "173"
sprintf("%#o", 123)  #=> "0173"
sprintf("%+o", -123) #=> "-173"
sprintf("%o", -123)  #=> "..7605"
sprintf("%#o", -123) #=> "..7605"

#  إلى الأعداد غير المعدومة x  يضيف البادئة   "x"  استخدام الراية "#" مع الحرف
# تعطل الراية "+" والمسافة البيضاء مكمل الأعداد غير السالبة
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"

# 0X تستخدم البادئة  "X" الراية "#" مع الحرف 

sprintf("%X", 123)  #=> "7B"
sprintf("%#X", 123) #=> "0X7B"

#  إلى الأعداد غير المعدومة b  يضيف البادئة   "b"  استخدام الراية "#" مع الحرف
# تعطل الراية "+" والمسافة البيضاء مكمل الأعداد غير السالبة
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"

# 0B تستخدم البادئة  "B" الراية "#" مع الحرف 

sprintf("%B", 123)  #=> "1111011"
sprintf("%#B", 123) #=> "0B1111011"

#  تؤدي إلى إظهار النقطة العشرية  "b" الراية "#" مع الحرف

sprintf("%.0e", 1)  #=> "1e+00"
sprintf("%#.0e", 1) #=> "1.e+00"

#  تؤدي إلى إظهار النقطة العشرية  "f" الراية "#" مع الحرف

sprintf("%.0f", 1234)  #=> "1234"
sprintf("%#.0f", 1234) #=> "1234."

#  تؤدي إلى إظهار النقطة العشرية  "g" الراية "#" مع الحرف
#  كما تعطل حذف الأصفار الدنيا

sprintf("%g", 123.4)   #=> "123.4"
sprintf("%#g", 123.4)  #=> "123.400"
sprintf("%g", 123456)  #=> "123456"
sprintf("%#g", 123456) #=> "123456."

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

# يتم التطويل عبر المسافات البيضاء ,       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:

# هو "d" و "x" و "o" و "b" دقة 
# الحد الأدنى من المنازل العددية         <------>
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"

#  في الدقة `#x' و `#b' مع "‎0x" , "0b" لا تحتسب في 
#  "‎#o‎" مع ‎0 ‎لكن تحتسب  <------>
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"

# هي عدد "e" دقة
# المنازل بعد النقطة العشرية           <------>
sprintf("%20.8e", 1234.56789) #=> "      1.23456789e+03"

# هي عدد "f" دقة
# المنازل بعد النقطة العشرية           <------>
sprintf("%20.8f", 1234.56789) #=> "       1234.56789000"

# هي عدد "g" دقة
# المنازل العشرية الهامة           <------>
sprintf("%20.8g", 1234.56789) #=> "           1234.5679"

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

# هي عدد "s" دقة
# الحد الأقصى للحروف           <------>
sprintf("%20.8s", "string test") #=> "            string t"

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

`arguments...‎`

القيم المراد تنسيقها وفقًا لسلسلة التنسيق 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‎ في توثيق روبي الرسمي.