printf

The format string is composed of zero or more directives: ordinary characters (excluding % ) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.

A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier .

Argnum

An integer followed by a dollar sign $ , to specify which number argument to treat in the conversion.

Flags

Flag	Description
-	Left-justify within the given field width; Right justification is the default
+	Prefix positive numbers with a plus sign + ; Default only negative are prefixed with a negative sign.
(space)	Pads the result with spaces. This is the default.
0	Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros.
' (char)	Pads the result with the character (char).

Width

Either an integer that says how many characters (minimum) this conversion should result in, or * . If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.

Precision

For e , E , f and F specifiers: this is the number of digits to be printed after the decimal point (by default, this is 6).
For g , G , h and H specifiers: this is the maximum number of significant digits to be printed.
For s specifier: it acts as a cutoff point, setting a maximum character limit to the string.

Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.

Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:

If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.

Warning

The c type specifier ignores padding and width.

Warning

Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results.

Variables will be co-erced to a suitable type for the specifier:

Type Handling

Type	Specifiers
string	s
int	d , u , c , o , x , X , b
float	e , E , f , F , g , G , h , H

Return Values

Returns the length of the outputted string.

Errors/Exceptions

As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.

As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX . Prior to PHP 8.0.0, a E_WARNING was emitted instead.

As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX . Prior to PHP 8.0.0, a E_WARNING was emitted instead.

As of PHP 8.0.0, a ArgumentCountError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.

Changelog

Version	Description
8.0.0	This function no longer returns false on failure.
8.0.0	Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
8.0.0	Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX ; previously this function emitted a E_WARNING instead.
8.0.0	Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX ; previously this function emitted a E_WARNING instead.
8.0.0	Throw a ArgumentCountError when less arguments are given than required; previously this function emitted a E_WARNING instead.

Examples

Example #1 printf() : various examples

$n = 43951789 ;
$u = - 43951789 ;
$c = 65 ; // ASCII 65 is 'A'

// notice the double %%, this prints a literal '%' character
printf ( "%%b = '%b'\n" , $n ); // binary representation
printf ( "%%c = '%c'\n" , $c ); // print the ascii character, same as chr() function
printf ( "%%d = '%d'\n" , $n ); // standard integer representation
printf ( "%%e = '%e'\n" , $n ); // scientific notation
printf ( "%%u = '%u'\n" , $n ); // unsigned integer representation of a positive integer
printf ( "%%u = '%u'\n" , $u ); // unsigned integer representation of a negative integer
printf ( "%%f = '%f'\n" , $n ); // floating point representation
printf ( "%%o = '%o'\n" , $n ); // octal representation
printf ( "%%s = '%s'\n" , $n ); // string representation
printf ( "%%x = '%x'\n" , $n ); // hexadecimal representation (lower-case)
printf ( "%%X = '%X'\n" , $n ); // hexadecimal representation (upper-case)

printf ( "%%+d = '%+d'\n" , $n ); // sign specifier on a positive integer
printf ( "%%+d = '%+d'\n" , $u ); // sign specifier on a negative integer
?>

The above example will output:

%b = '10100111101010011010101101' %c = 'A' %d = '43951789' %e = '4.39518e+7' %u = '43951789' %u = '4251015507' %f = '43951789.000000' %o = '247523255' %s = '43951789' %x = '29ea6ad' %X = '29EA6AD' %+d = '+43951789' %+d = '-43951789'

Example #2 printf() : string specifiers

printf ( "[%s]\n" , $s ); // standard string output
printf ( "[%10s]\n" , $s ); // right-justification with spaces
printf ( "[%-10s]\n" , $s ); // left-justification with spaces
printf ( "[%010s]\n" , $s ); // zero-padding works on strings too
printf ( "[%'#10s]\n" , $s ); // use the custom padding character '#'
printf ( "[%'#*s]\n" , 10 , $s ); // Provide the padding width as an additional argument
printf ( "[%10.9s]\n" , $t ); // right-justification but with a cutoff of 8 characters
printf ( "[%-10.9s]\n" , $t ); // left-justification but with a cutoff of 8 characters
?>

The above example will output:

[monkey] [ monkey] [monkey ] [0000monkey] [####monkey] [####monkey] [ many monk] [many monk ]

Improve This Page

User Contributed Notes 7 notes

24 years ago

Be careful:
printf ("(9.95 * 100) = %d \n", (9.95 * 100));

First %d converts a float to an int by truncation.

Second floats are notorious for tiny little rounding errors.

19 years ago

[Editor's Note: Or just use vprintf. ]

function printf_array ( $format , $arr )
<
return call_user_func_array ( 'printf' , array_merge ((array) $format , $arr ));
>
?>

Use it the following way:
$goodevil = array( 'good' , 'evil' );
printf_array ( 'There is a difference between %s and %s' , $goodevil );
?>
and it will print:
There is a difference between good and evil

13 days ago

A few things to note about printf:
1. The definition of specifier g (or G) is often wrongly stated as being "use e or f (or E or f), whichever results in the shorter string". The correct rule is given in the documentation and it does not always give this result.
2. For g/G/h/H, trailing zeros after the decimal point are removed (but not a zero just after the decimal point, in the e/E style).
3. g/G are locale-aware whether the e/E or f style is produced.
4. For b/o/x/X/u (that is, all integer styles except d) the result shown for negative values is the twos complement form of the number, 2**32 + v, where v is the (negative) value.

22 years ago

instead of writing a function to round off a float (let's call it 'x') accurately, it's much easier to add a small number to x and then truncate it.
For example: if you want to round off to the nearest integer, just add 0.5 to x and then truncate it. if x=12.6, then it would calculate 13.1, and truncate it to 13. If x=14.4, it would calculate 14.9 and truncate it to 14.