From 67151cd7af01f97524f0a14cf5abd9567f856155 Mon Sep 17 00:00:00 2001 From: akr Date: Fri, 7 Mar 2008 08:31:41 +0000 Subject: update sprintf rdoc. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@15722 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- sprintf.c | 213 +++++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 164 insertions(+), 49 deletions(-) (limited to 'sprintf.c') diff --git a/sprintf.c b/sprintf.c index b49b9ab2ea..62c68a12cb 100644 --- a/sprintf.c +++ b/sprintf.c @@ -144,118 +144,233 @@ sign_bits(int base, const char *p) * sprintf(format_string [, arguments...] ) => string * * Returns the string resulting from applying format_string 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 * sprintf 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 %10.10s 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: * -- cgit v1.2.3