ruby-changes:4232
From: ko1@a...
Date: Fri, 7 Mar 2008 17:31:52 +0900 (JST)
Subject: [ruby-changes:4232] akr - Ruby:r15722 (trunk): update sprintf rdoc.
akr 2008-03-07 17:31:41 +0900 (Fri, 07 Mar 2008)
New Revision: 15722
Modified files:
trunk/sprintf.c
trunk/test/ruby/test_sprintf_comb.rb
Log:
update sprintf rdoc.
http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/sprintf.c?r1=15722&r2=15721&diff_format=u
http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/test/ruby/test_sprintf_comb.rb?r1=15722&r2=15721&diff_format=u
Index: sprintf.c
===================================================================
--- sprintf.c (revision 15721)
+++ sprintf.c (revision 15722)
@@ -144,118 +144,233 @@
* sprintf(format_string [, arguments...] ) => string
*
* Returns the string resulting from applying <i>format_string</i> to
- * any additional arguments. Within the format string, any characters
- * other than format sequences are copied to the result. A format
+ * any additional arguments. Within the format string, any characters
+ * other than format sequences are copied to the result.
+ *
+ * The syntax of a format sequence is follows.
+ *
+ * %[flags][width][.precision]type
+ *
+ * A format
* sequence consists of a percent sign, followed by optional flags,
* width, and precision indicators, then terminated with a field type
- * character. The field type controls how the corresponding
+ * character. The field type controls how the corresponding
* <code>sprintf</code> argument is to be interpreted, while the flags
- * modify that interpretation. The field type characters are listed
- * in the table at the end of this section. The flag characters are:
+ * modify that interpretation. The field type characters are listed
+ * in the table at the end of this section. The flag characters are:
*
* Flag | Applies to | Meaning
* ---------+---------------+-----------------------------------------
* space | bBdeEfgGiouxX | Leave a space at the start of
- * | | positive numbers.
+ * | | non-negative numbers.
+ * | | For `o', `x', `X', `b' and `B', use
+ * | | a minus sign with absolute value for
+ * | | negative values.
* ---------+---------------+-----------------------------------------
* (digit)$ | all | Specifies the absolute argument number
- * | | for this field. Absolute and relative
+ * | | for this field. Absolute and relative
* | | argument numbers cannot be mixed in a
* | | sprintf string.
* ---------+---------------+-----------------------------------------
- * # | bBeEfgGoxX | Use an alternative format. For the
- * | | conversions `o', raise the precision until
- * | | the first character will be `0'.
- * | | For the conversions `x', `X', `b' and `B',
- * | | prefix the result with ``0x'', ``0X'',
- * | | ``0b'' and ``0B'', respectively. For `e',
- * | | `E', `f', `g', and 'G', force a decimal
- * | | point to be added, even if no digits follow.
+ * # | bBeEfgGoxX | Use an alternative format.
+ * | | For the conversions `o', increase the precision
+ * | | until the first digit will be `0' if
+ * | | it is not formatted as complements.
+ * | | For the conversions `x', `X', `b' and `B'
+ * | | on non-zero, prefix the result with ``0x'',
+ * | | ``0X'', ``0b'' and ``0B'', respectively.
+ * | | For `e', `E', `f', `g', and 'G',
+ * | | force a decimal point to be added,
+ * | | even if no digits follow.
* | | For `g' and 'G', do not remove trailing zeros.
* ---------+---------------+-----------------------------------------
- * + | bBdeEfgGiouxX | Add a leading plus sign to non-negative numbers.
+ * + | bBdeEfgGiouxX | Add a leading plus sign to non-negative
+ * | | numbers.
+ * | | For `o', `x', `X', `b' and `B', use
+ * | | a minus sign with absolute value for
+ * | | negative values.
* ---------+---------------+-----------------------------------------
* - | all | Left-justify the result of this conversion.
* ---------+---------------+-----------------------------------------
* 0 (zero) | bBdeEfgGiouxX | Pad with zeros, not spaces.
+ * | | For `o', `x', `X', `b' and `B', radix-1
+ * | | is used for negative numbers formatted as
+ * | | complements.
* ---------+---------------+-----------------------------------------
* * | all | Use the next argument as the field width.
* | | If negative, left-justify the result. If the
* | | asterisk is followed by a number and a dollar
* | | sign, use the indicated argument as the width.
*
+ * For `o', `x', `X', `b' and `B',
+ * negative values are formatted by compelements
+ * prefixed with `..' and radix-1.
+ * If a space or `+' flag is specified,
+ * a minus sign and absolute value is used instead.
+ *
+ * Examples of 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."
*
* The field width is an optional integer, followed optionally by a
- * period and a precision. The width specifies the minimum number of
- * characters that will be written to the result for this field. For
+ * period and a precision. The width specifies the minimum number of
+ * characters that will be written to the result for this field.
+ *
+ * Examples of 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"
+ *
+ * For
* numeric fields, the precision controls the number of decimal places
- * displayed. For string fields, the precision determines the maximum
- * number of characters to be copied from the string. (Thus, the format
+ * displayed. For string fields, the precision determines the maximum
+ * number of characters to be copied from the string. (Thus, the format
* sequence <code>%10.10s</code> will always contribute exactly ten
* characters to the result.)
*
- * width=20
- * <------------------>
- * sprintf("%20.8e", 1234.56789) => " 1.23456789e+03"
- * <------>
- * number of fractional digits : precision=8
+ * Examples of precisions:
+ *
+ * # 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"
*
- * sprintf("%20.8f", 1234.56789) => " 1234.56789000"
- * <------>
- * number of digits after the decimal point : precision=8
+ * # precision for `f' is number of
+ * # digits after the decimal point <------>
+ * sprintf("%20.8f", 1234.56789) #=> " 1234.56789000"
*
- * sprintf("%20.8g", 1234.56789) => " 1234.5679"
- * <------->
- * number of significant digits : precision=8
+ * # precision for `g' is number of
+ * # significant digits <------->
+ * sprintf("%20.8g", 1234.56789) #=> " 1234.5679"
*
- * sprintf("%20.8g", 123456789) => " 1.2345679e+08"
- * <------->
- * number of significant digits : precision=8
+ * <------->
+ * sprintf("%20.8g", 123456789) #=> " 1.2345679e+08"
*
- * width=20
- * <------------------>
- * sprintf("%20.8s", "string test") => " string t"
- * <------>
- * maximum number of characters : precision=8
+ * # precision for `s' is
+ * # maximum number of characters <------>
+ * sprintf("%20.8s", "string test") #=> " string t"
*
* The field types are:
*
* Field | Conversion
* ------+--------------------------------------------------------------
+ * b | Convert argument as a binary number.
* B | Equivalent to `b', but uses an uppercase 0B for prefix
* | in the alternative format by #.
- * b | Convert argument as a binary number.
* c | Argument is the numeric code for a single character or
* | a single character string itself.
* d | Convert argument as a decimal number.
+ * e | Convert floating point argument into exponential notation
+ * | with one digit before the decimal point. The precision
+ * | determines the number of digits after the decimal point
+ * | (defaulting to six).
* E | Equivalent to `e', but uses an uppercase E to indicate
* | the exponent.
- * e | Convert floating point argument into exponential notation
- * | with one digit before the decimal point. The precision
- * | determines the number of fractional digits (defaulting to six).
* f | Convert floating point argument as [-]ddd.ddd,
* | where the precision determines the number of digits after
* | the decimal point.
- * G | Equivalent to `g', but use an uppercase `E' in exponent form.
* g | Convert a floating point number using exponential form
* | if the exponent is less than -4 or greater than or
* | equal to the precision, or in d.dddd form otherwise.
* | The precision specifies the number of significant digits.
+ * G | Equivalent to `g', but use an uppercase `E' in exponent form.
* i | Identical to `d'.
* o | Convert argument as an octal number.
* p | The valuing of argument.inspect.
- * s | Argument is a string to be substituted. If the format
+ * s | Argument is a string to be substituted. If the format
* | sequence contains a precision, at most that many characters
* | will be copied.
* u | Identical to `d'.
- * X | Convert argument as a hexadecimal number using uppercase
- * | letters. Negative numbers will be displayed with two
- * | leading periods (representing an infinite string of
- * | leading 'FF's.
* x | Convert argument as a hexadecimal number.
* | Negative numbers will be displayed with two
* | leading periods (representing an infinite string of
* | leading 'ff's.
+ * X | Convert argument as a hexadecimal number using uppercase
+ * | letters. Negative numbers will be displayed with two
+ * | leading periods (representing an infinite string of
+ * | leading 'FF's.
*
* Examples:
*
Index: test/ruby/test_sprintf_comb.rb
===================================================================
--- test/ruby/test_sprintf_comb.rb (revision 15721)
+++ test/ruby/test_sprintf_comb.rb (revision 15722)
@@ -297,6 +297,7 @@
0.0,
0.01,
1/3.0,
+ 2/3.0,
1.0,
2.0,
9.99999999,
--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/