summaryrefslogtreecommitdiff
path: root/sprintf.c
diff options
context:
space:
mode:
authordave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-28 06:33:07 +0000
committerdave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-28 06:33:07 +0000
commit2d491003aaab3e49a02f6126af9d03d429eed284 (patch)
treee6d8a2d76367ace555bc4e76e08f54dc1414a3dd /sprintf.c
parent8f71229356ce2be9c5da28d0f9a3f8ed383a53d4 (diff)
Add RDoc documentation for stuff in object.c
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@5330 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'sprintf.c')
-rw-r--r--sprintf.c99
1 files changed, 99 insertions, 0 deletions
diff --git a/sprintf.c b/sprintf.c
index 70bd270f2b..e1069a3318 100644
--- a/sprintf.c
+++ b/sprintf.c
@@ -129,6 +129,105 @@ sign_bits(base, p)
val = NUM2INT(tmp); \
} while (0)
+
+/*
+ * call-seq:
+ * format(format_string [, arguments...] ) => string
+ * 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
+ * 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
+ * <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:
+ *
+ * Flag | Applies to | Meaning
+ * ---------+--------------+-----------------------------------------
+ * space | bdeEfgGioxXu | Leave a space at the start of
+ * | | positive numbers.
+ * ---------+--------------+-----------------------------------------
+ * (digit)$ | all | Specifies the absolute argument number
+ * | | for this field. Absolute and relative
+ * | | argument numbers cannot be mixed in a
+ * | | sprintf string.
+ * ---------+--------------+-----------------------------------------
+ * # | beEfgGoxX | Use an alternative format. For the
+ * | | conversions `o', `x', `X', and `b',
+ * | | prefix the result with ``0'', ``0x'', ``0X'',
+ * | | 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.
+ * ---------+--------------+-----------------------------------------
+ * + | bdeEfgGioxXu | Add a leading plus sign to positive numbers.
+ * ---------+--------------+-----------------------------------------
+ * - | all | Left-justify the result of this conversion.
+ * ---------+--------------+-----------------------------------------
+ * 0 (zero) | all | Pad with zeros, not spaces.
+ * ---------+--------------+-----------------------------------------
+ * * | 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.
+ *
+ *
+ * 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
+ * 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
+ * sequence <code>%10.10s</code> will always contribute exactly ten
+ * characters to the result.)
+ *
+ * The field types are:
+ *
+ * Field | Conversion
+ * ------+--------------------------------------------------------------
+ * b | Convert argument as a binary number.
+ * c | Argument is the numeric code for a single character.
+ * d | Convert argument as a decimal number.
+ * 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.
+ * 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
+ * | sequence contains a precision, at most that many characters
+ * | will be copied.
+ * u | Treat argument as an unsigned decimal number.
+ * 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.
+ *
+ * Examples:
+ *
+ * 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"
+ */
+
VALUE
rb_f_sprintf(argc, argv)
int argc;