OpenEuphoria

printf

<built-in> procedure printf(integer fn, sequence format, object values) 

prints one or more values to a file or device, using a format string to embed them in and define how they should be represented.

Parameters:

1. fn : an integer, the handle to a file or device to output to
2. format : a sequence, the text to print. This text may contain format specifiers.
3. values : usually, a sequence of values. It should have as many elements as format specifiers in format, as these values will be substituted to the specifiers.

Errors:

If there are less values to show than format specifiers, a run time error will occur.

The target file or device must be open.

Comments:

A format specifier is a string of characters starting with a percent sign ( % ) and ending in a letter. Some extra information may come in between those.

This procedure writes out the format text to the output file fn, replacing format specifiers with the corresponding data from the values parameter. Whenever a format specifiers is found in format, the n-th item in values will be turned into a string according to the format specifier. The resulting string will the format specifier. This means that the first format specifier uses the first item in values, the second format specifier the second item, and so on.

You must have at least as many items in values as there are format specifiers in format. This means that if there is only one format specifier then values can be either an atom, integer or a non-empty sequence. And when there are more than one format specifier in format then values must be a sequence with a length that is greater than or equal to the number of format specifiers present.

This way, printf always takes exactly three arguments no matter how many values are to be printed.

The basic format specifiers are:

• %d -- print an atom as a decimal integer
• %x -- print an atom as a hexadecimal integer. Negative numbers are printed in two's complement, so -1 will print as FFFFFFFF
• %o -- print an atom as an octal integer
• %s -- print a sequence as a string of characters, or print an atom as a single character
• %e -- print an atom as a floating-point number with exponential notation
• %f -- print an atom as a floating-point number with a decimal point but no exponent
• %g -- print an atom as a floating-point number using whichever format seems appropriate, given the magnitude of the number
• %% -- print the '%' character itself. This is not an actual format specifier.

Field widths can be added to the basic formats (for example: %5d, %8.2f, %10.4s). The number before the decimal point is the minimum field width to be used. The number after the decimal point is the precision to be used for numeric values.

If the field width is negative (for example %-5d) then the value will be left-justified within the field. Normally it will be right-justified, even strings. If the field width starts with a leading 0 (for example %08d) then leading zeros will be supplied to fill up the field. If the field width starts with a '+' (for example %+7d ) then a plus sign will be printed for positive values.

Comments:

Watch out for the following common mistake. The intention is to output all the characters in the third argument but actually only outputs the first character:

include std/io.e 
sequence name="John Smith" 
printf(STDOUT, "My name is %s", name) 
   --> My name is J 

The output of this will be My name is J because each format specifier uses exactly one item from the values parameter. In this case we have only one specifier so it uses the first item in the values parameter, which is the character 'J'. To fix this situation, you must ensure that the first item in the values parameter is the entire text string and not just a character, so you need code this instead:

include std/io.e 
name="John Smith" 
printf(STDOUT, "My name is %s", {name}) 
   --> My name is John Smith 

Now, the third argument of printf is a one-element sequence containing all the text to be formatted.

Also note that if there is only one format specifier then values can simply be an atom or integer.

Example 1:

include std/io.e 
atom rate = 7.875 
printf(STDOUT, "The interest rate is: %8.2f\n", rate) 
 
--      The interest rate is:     7.88 

Example 2:

include std/io.e 
sequence name="John Smith" 
integer score=97 
printf(STDOUT, "%15s, %5d\n", {name, score}) 
 
-- "     John Smith,    97" 

Example 3:

include std/io.e 
printf(STDOUT, "%-10.4s $ %s", {"ABCDEFGHIJKLMNOP", "XXX"}) 
--      ABCD       $ XXX 

Example 4:

include std/io.e 
printf(STDOUT, "%d  %e  %f  %g", repeat(7.75, 4))  
                  -- same value in different formats 
 
--      7  7.750000e+000  7.750000  7.75 

NOTE that printf cannot use an item in values that contains nested sequences. Thus this is an error ...

include std/io.e 
sequence name = {"John", "Smith"} 
printf(STDOUT, "%s", {name} ) 

because the item that is used from the values parameter contains two subsequences (strings in this case). To get the correct output you would need to do this instead ...

include std/io.e 
sequence name = {"John", "Smith"} 
printf(STDOUT, "%s %s", {name[1], name[2]} ) 

See Also:

sprintf, sprint, print