عرض مصدر Ruby/Kernel/sprintf

<noinclude>{{DISPLAYTITLE: التابع <code>sprintf‎</code> الخاص بالصنف <code>Kernel</code> في روبي}}</noinclude>
[[تصنيف: Ruby]]
[[تصنيف: Ruby Method]]
[[تصنيف: Ruby Kernel]]
يعيد التابع <code>sprintf</code> السلسلة النصية المُمرَّرة إليه بعد تنسيقها بنمط معيَّن. داخل سلسلة التنسيق، تُنسَخ كل محارفها في السلسلة النصية الناتجة باستثناء سلسلة التنسيق (format sequences).
==البنية العامة==
<syntaxhighlight lang="ruby">sprintf(format_string [, arguments...] )  → string‎</syntaxhighlight>
==المعاملات==
===<code>format_string‎</code>===
السلسلة التي تحدد التنسيق. داخل سلسلة التنسيق <code>format_string</code>، ستُنسخ كل المحارف إلى السلسلة النصية الناتجة باستثناء سلسلة التنسيق (format sequences).

صيغة سلسلة محارف التنسيق تأخذ الشكل التالي:<syntaxhighlight lang="ruby">%[flags][width][.precision]type‎</syntaxhighlight>تتألف سلسلة محارف التنسيق من علامة النسبة المئوية، متبوعةً بثلاث حقول اختيارية هي: <code>flags</code> و <code>width</code> و <code>precision</code> ثم تنتهي بمحرف يحدد حقل النوع <code>type</code>.  يتحكم حثل النوع في كيفية تأويل الوسيط المقابل <code>sprintf</code>، بينما تعدل الحقول <code>flags</code> ذلك التأويل.

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

(numeric fmt)
|يترك مسافة بيضاء في بداية الأعداد غير السالبة.
بالنسبة للتحويلات 'o' و 'x' و 'X' و 'b' و 'B'، تُستخدم علامة الإشارة ناقص مع القيمة المطلقة للأعداد السالبة.
|-
|<code>(digit)$</code>
|الكل
|يحدد قيمة الوسيط المطلقة (absolute argument number) لهذا الحقل. قيم الوسيط المطلقة والنسبية لا يمكن خلطها في النصوص المراد طباعتها عبر <code>sprintf</code>.
|-
|<code>#</code>
|bBoxX
aAeEfgG
|تستخدم تنسيقًا بديلًا.
بالنسبة للتحويل '<code>o</code>'، ترفع الدقة إلى أن يصير الرقم الأول '<code>0</code>'  إن لم يتم تنسيقه كمتمم (complements).

بالنسبة للتحويلات  'x' و 'X' و 'b' و 'B'، بالنسبة للأعداد المخالفة للصفر، تُبدأ النتيجة بالبادئة

<code><nowiki>''</nowiki>0x<nowiki>''</nowiki></code>و  <code><nowiki>''</nowiki>0X<nowiki>''</nowiki></code> و <code><nowiki>''</nowiki>0b<nowiki>''</nowiki></code>  و <code><nowiki>''</nowiki>0B<nowiki>''</nowiki></code> على التوالي.

بالنسبة لتحويلات 'a' و 'A' و 'e' و 'E' و 'f' و 'g' و 'G'، تُفرض إضافة النقطة العشرية، حتى لو لم يكن بعدها أي أرقام.

بالنسبة للتحويلات 'g' و  'G'، لا تزال الأصفار الإضافية.
|-
|<code>+</code>
|bBdiouxX
aAeEfgG

(numeric fmt)
|تضاف العلامة <code>+</code> في بداية الأعداد الموجبة.
بالنسبة للتحويلات 'o' و 'x' و 'X' و 'b' و 'B'، تُستخدم علامة إشارة السالبة <code>-</code> مع القيمة المطلقة للأعداد السالبة.
|-
|<code>-</code>
|الكل
|تعدِّل نتيحة تنسيق السلسلة النصية إلى الجهة اليسرى.
|-
|<code>0</code>
|bBdiouxX
aAeEfgG

(numeric fmt)
|تملأ المنازل الرقمية الفارغة بالأصفار، وليس المسافات البيضاء.
بالنسبة للتحويلات 'o' و 'x' و 'X' و 'b' و 'B'، تُستخدم الأساسradix-1  للأعداد السالبة المُنسّقة على شكل متممات.
|-
|<code>*</code>
|الكل
|يستخدم الوسيط الموالي كعرض للسلسلة النصية المراد تنسيقها. إن كان سالبًا، فستعدل نتيحة التحويل إلى الجهة اليسرى. إن اتبِعت العلامة <code>*</code> بعدد وبالعلامة <code>$</code>، فسيُستخدم الوسيط كعرض للسلسلة النصية.
|}أمثلة على استعمال الرايات <code>flags</code>:<syntaxhighlight lang="ruby"># `+' 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."</syntaxhighlight>الحقل <code>width</code> هو عدد صحيح اختياري يُتبَع اختياريًا بنقطة وبقيمة تمثِّل حقل الدقة <code>precision</code>.  يحدد الحقل <code>width</code> الحد الأدنى لعدد محارف السلسلة النصية الناتجة.

أمثلة على الحقل <code>width</code>:<syntaxhighlight lang="ruby"># 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"
</syntaxhighlight>بالنسبة للحقول العددية، يتحكم الحقل <code>precision</code> في عدد المنازل العشرية المعروضة (دقة العدد العشري). بالنسبة للحقول النصية، يحدد الحقل <code>precision</code> الحد الأقصى لعدد الأحرف التي ستُنسخ من السلسلة (بناءً على ذلك، فإن سلسلة التنسيق ‎<code>%10.10s</code> ستخصص دائمًا عشرة أحرف بالضبط للسلسلة النصية المعادة).

أمثلة على الحقل <code>precision</code>:<syntaxhighlight lang="ruby"># 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"
</syntaxhighlight><span> </span>بالنسبة للتنسيقات الأكثر تعقيدًا، تدعم روبي المراجع الاسمية (reference by name). حيث يستخدم النمط ‎<code>%<name>s</code> نمط التنسيق (format style)، وذلك على خلافًا للنمط <code>{name‎}%</code>.
===<code>arguments...‎</code>===
المحارف التي ستمرر إلى سلسلة التنسيق <code>format_string‎</code> لتنسيقها قبل إعادتها.
==القيمة المعادة==
تُعاد سلسلة نصية تحوي قيمة المعاملات <code>arguments...‎</code> المعطاة بعد تنسيقها وفقًا لسلسلة التنسيق <code>format_string‎</code>.
==أمثلة==
مثال على استخدام التابع <code>sprintf‎</code>:<syntaxhighlight lang="ruby">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"</syntaxhighlight>
==انظر أيضا==
* التابع <code>[[Ruby/Kernel/format|format]]</code>: ينسق السلسلة النصية المعطاة ثم يعيدها.

==مصادر==
*[http://ruby-doc.org/core-2.5.1/Kernel.html#method-i-sprintf قسم التابع sprintf‎ في الصنف Kernel‎ في توثيق روبي الرسمي.]