Output with format
[Classification]
Standard library
[Syntax]
#include <stdio.h>
int sprintf(char *s, const char *format[, arg, ...]);
[Return value]
The number of characters that were output (excluding the null character (\0)) is returned.
Error return does not occur.
[Description]
This function applies the format specified by the string pointed to by format to the respective arg arguments, and writes out the formatted data that was output as a result to the array pointed to by s.
If there are not sufficient arguments for the format, the operation is undefined. If the end of the formatted string is reached, control returns. If there are more arguments that those required by the format, the excess arguments are ignored. If the area of s overlaps one of the arguments, the operation is undefined.
The argument format specifies "the output to which the subsequent argument is to be converted". The null character (\0) is appended at the end of written characters (the null character (\0) is not counted in a return value).
The format consists of the following two types of directives:
|
Ordinary characters
|
Characters that are copied directly without conversion (other than "%").
|
|
Conversion specifications
|
Specifications that fetch zero or more arguments and assign a specification.
|
Each conversion specification begins with character "%" (to insert "%" in the output, specify "%%" in the format string). The following appear after the "%":
%[flag][field-width][precision][size][type-specification-character]
The meaning of each conversion specification is explained below.
Zero or more flags, which qualify the meaning of the conversion specification, are placed in any order.
The flag characters and their meanings are as follows:
|
-
|
The result of the conversion will be left-justified in the field, with the right side filled with blanks (if this flag is not specified, the result of the conversion is right-justified).
|
|
+
|
The result of a signed conversion will start with a + or - sign (if this flag is not specified, the result of the conversion starts with a sign only when a negative value has been converted).
|
|
Space
|
If the first character of a signed conversion is not a sign and a signed conversion is not generated a character, a space (" ") will be appended to the beginning of result of the conversion. If both the space flag and + flag appear, the space flag is ignored.
|
|
#
|
The result is to be converted to an alternate format. For o conversion, the precision is increased so that the first digit of the conversion result is 0. For x or X conversion, 0x or 0X is appended to the beginning of a non-zero conversion result. For e, f, g, E, or G conversion, a decimal point "." is added to the conversion result even if no digits follow the decimal pointNote. For g or G conversion, trailing zeros will not be removed from the conversion result. The operation is undefined for conversions other than the above.
|
|
0
|
For d, e, f, g, i, o, u, x, E, G, or X conversion, zeros are added following the specification of the sign or base to fill the field width.
If both the 0 flag and - flag are specified, the 0 flag is ignored. For d, i, o, u, x, or X conversion, when the precision is specified, the zero (0) flag is ignored.
Note that 0 is interpreted as a flag and not as the beginning of the field width.
The operation is undefined for conversion other than the above.
|
Note | Normally, a decimal point appears only when a digit follows it. |
This is an optional minimum field width. If the converted value is smaller than this field width, the left side is filled with spaces (if the left justification flag explained above is assigned, the right side will be filled with spaces). This field width takes the form of "*" or a decimal integer. If "*" is specified, an int type argument is used as the field width. A negative field width is not supported. If an attempt is made to specify a negative field width, it is interpreted as a minus (-) flag appended to the beginning of a positive field width.
For d, i, o, u, x, or X conversion, the value assigned for the precision is the minimum number of digits to appear. For e, f, or E conversion, it is the number of digits to appear after the decimal point. For g or G conversion, it is the maximum number of significant digits. The precision takes the form of "*" or "." followed by a decimal integer. If "*" is specified, an int type argument is used as the precision. If a negative precision is specified, it is treated as if the precision were omitted. If only "." is specified, the precision is assumed to be 0. If the precision appears together with a conversion specification other than the above, the operation is undefined.
This is an arbitrary optional size character h, l, ll, or L, which changes the default method for interpreting the data type of the corresponding argument.
When h is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a short or unsigned short argument.
When l is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a long or unsigned long argument. l is also causes a following n type specification to be forcibly applied to a pointer to long argument. If another type specification character is used together with h or l, the operation is undefined.
When ll is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a long long and unsigned long long argument. Furthermore, for ll, a following n type specification is forcibly applied to a long long pointer. If another type specification character is used together with ll, the operation is undefined.
When L is specified, a following e, E, f, g, or G type specification is forcibly applied to a long double argument. If another type specification character is used together with L, the operation is undefined.
(5) | type specification character |
These are characters that specify the type of conversion that is to be applied.
The characters that specify conversion types and their meanings are as follows.
|
%
|
Output the character "%". No argument is converted. The conversion specification is "%%".
|
|
c
|
Convert an int type argument to unsigned char type and output the characters of the conversion result.
|
|
d
|
Convert an int type argument to a signed decimal number.
|
|
e, E
|
Convert a double type argument to [-]d.dddde+dd format, which has one digit before the decimal point (not 0 if the argument is not 0) and the number of digits after the decimal point is equal to the precision. The E conversion specification generates a number in which the exponent part starts with "E" instead of "e".
|
|
f
|
Convert a double type argument to decimal notation of the form [-]dddd.dddd.
|
|
g, G
|
Convert a double type argument to e (E for a G conversion specification) or f format, with the number of digits in the mantissa specified for the precision. Trailing zeros of the conversion result are excluded from the fractional part. The decimal point appears only when it is followed by a digit.
|
|
i
|
Perform the same conversion as d.
|
|
n
|
Store the number of characters that were output in the same object. A pointer to int type is used as the argument.
|
|
p
|
Output a pointer in an implementation-defined format. The CC-RH handles a pointer as unsigned long (this is the same as the lu specification).
|
|
o, u, x, X
|
Convert an unsigned int type argument to octal notation (o), unsigned decimal notation (u), or unsigned hexadecimal notation (x or X) with dddd format. For x conversion, the letters abcdef are used. For X conversion, the letters ABCDEF are used.
|
|
s
|
The argument must be a pointer pointing to a character type array. Characters from this array are output up until the null character (\0) indicating termination (the null character (\0) itself is not included). If the precision is specified, no more than the specified number of characters will be output. If the precision is not specified or if the precision is greater than the size of this array, make sure that this array includes the null character (\0).
|
[Example]
#include <stdio.h>
void func(int val) {
char s[20];
sprintf(s, "%-10.51x\n", val); /*Specifies left-justification, field width 10,
precision 5, size long, and hexadecimal
notation for the value of val, and outputs
the result with an appended new-line
character to the array pointed to by s.*/
}
|