PRINTF - formatted print.

Alternate entries: .PRNTF

Usage:

B:
   ret = printf( [unit, ] format, arg1, arg2, ..., argn );
/* C users see "expl c lib printf" */

Where:

unit
is an open output unit (possibly associated with a string). If "unit" is not specified, the current write unit is used.
format
is a format string as described below.
arg1, arg2, ..., argn
are arguments to be formatted according to "format" and printed out.
ret
is an integer telling how many characters PRINTF actually printed out.

Description:

PRINTF writes "arg1" through "argn" out (in ASCII) according to the given "format" string. Any non-formatting characters in "format" are copied to the output unit directly. A format specification has the form

%FW.N,PA
where F indicates optional modifier flag characters chosen from the list "-+ #", W is an optional field width, N is an optional "precision", P is an optional fill character, and A is a conversion code consisting of one or two characters. The '.' is required only if N is supplied, and the ',' is required only if P is present. Although N is called "precision", this is a misnomer and its meaning varies with different conversion characters.

The modifier flags have the following meanings:

"-"
Justify in the reverse of the normal justify. For most formats this means left justify within the field (i.e. pad with fill characters on the right).
"+"
The first digit of a signed conversion should always begin with a sign character (+ or -).
" "
Similar to '+' but tells PRINTF to use a blank in the sign position for non-negative numbers.
"#"
Verbose format. The meaning of this flag varies with each conversion type, and is described later.

Below we list the possible conversion codes and their meanings.

a
The argument is taken to be a pointer to a sequence of ASCII characters, of which exactly W are printed. If N is specifed, the W characters are printed starting at the Nth character from the given pointer; thus if the argument was "abcdef" and the format was "%3.2a", PRINTF would print "cde". '*e' (*000) characters will be stripped if they are included in the printed ASCII characters. P is not applicable in "a"-type formats. Neither are the modifier flags (F).
_a
accepts a string pointer as its corresponding argument. The string will be printed in a manner that resembles strings in source code: non-printable characters will be printed as escape sequences. Escape sequences begin with a backslash '\' rather than an asterisk '*'. For example, a new-line character will be printed as '\n'; a non-standard character will be printed as a blackslash followed by three octal digits. The width gives the minimum number of characters in the output field; the precision gives the number of characters to be printed from the string. If there is no precision specified, the entire string is printed (up to but not including the terminating '*e' character). If you specify the '#' modifier, double quotes will be printed to enclose the output string. If you specify the '-' modifier, output will be left-justified; otherwise, it will be right-justified. If you specify the '+' modifier, '*e' characters will not be considered to be the end of the string; in this case, a precision must be specified to tell "printf" how many characters to print.
b
The argument is taken to be a pointer to a BCD string, W characters in length. These characters are translated into lower case ASCII and printed. N is interpreted as it is in %a. W defaults to six. Trailing BCD blanks are not considered to be part of the the BCD string, and are stripped; they can be preserved by specifying the '#' modifier. If P is not specified, no fill is done. Unless the modifier '-' is specified, the string is left-justified.
B
This is the same as "%b", except that BCD letters are translated into upper case ASCII.
c
The argument is printed as one to four ASCII characters, right-justified. '*e' characters occurring in the argument are not printed. Thus if the argument is 'ab*ec' and the format "%c", PRINTF prints "abc". If W is not specified, the default is zero; if P is not specified, the default is ' '.
_c
The argument is interpreted as a single word containing up to six BCD characters. If you specify a precision of zero, PRINTF will strip off high order zeroes at the beginning of the argument word and interpret the rest as BCD characters. If you specify a width W, the precision is automatically set to the same value. If you do not specify either a precision or width, the default is "%6.0_c". BCD letters are printed in lower case.
_C
This is the same as "%_c" except that BCD letters are printed in upper case.
d
The argument is printed as a signed decimal number, right-justified. If W is not specified, the default is zero; if P is not specified, the default is ' '. N specifies the minimum number of digits to be printed (default 1).
e
The argument is assumed to be a single precision floating point number. It is printed in Fortran-style E format, right-justified and zero-filled. If there are no digits after the decimal point, the decimal point is not printed either; if you want the decimal point to be printed, specify the '#' modifier. W is the field width, and N is the number of decimal places. In the output, the 'e' marking the exponent is in lower case.
_e
This is the same as "%e" except that the argument is assumed to be a double precision floating point number aligned on a double-word boundary.
E
This is the same as "%e", except that the 'E' marking the exponent is in upper case.
_E
This is the same as "%_e", except that the 'E' marking the exponent is in upper case.
f
The argument is assumed to be a single precision floating point number. It is printed in normal notation (nnnn.nn), right-justified and zero-filled. If there are no digits after the decimal point, the decimal point is not printed either; if you want the decimal point to be printed, specify the '#' modifier. W is the field width and N is the number of decimal places. If the specified width W is not large enough to represent the value to the requested precision, "printf" will print the value in either scientific notation or standard format, whichever gives the desired precision in the fewest characters.
_f
This is the same as "%f" except that the argument is expected to be a double precision floating point number, aligned on a double-word boundary.
g
The argument is assumed to be a single precision floating point number. It is printed in either scientific notation or standard format, depending on the value. Standard format is normally used; however, if the exponent of the value is less than -4 or greater than or equal to the precision N, scientific notation is used. The 'e' to mark the exponent will be in lower case. If no precision is specified, 1 is used. Trailing zeros are removed from the fractional part of the value. If there are no digits after the decimal point, the decimal point is not printed either; if you want the decimal point to be printed, specify the '#' modifier.
_g
This is the same as "%g" except that the argument is expected to be a double precision floating point number, aligned on a double-word boundary.
G
This is the same as "%g", except that an upper case 'E' is used to mark the exponent if scientific notation is used.
_G
This is the same as "%_g", except that an upper case 'E' is used to mark the exponent if scientific notation is used.
h
This is equivalent to "%_c".
i
This is equivalent to "%d".
le
This is the same as "%e", except that the argument is taken as a POINTER to a double precision floating point number.
lE
This is the same as "%E", except that the argument is taken as a POINTER to the double precision floating point number to be printed.
lf
This is the same as "%f", except that the argument is taken as a POINTER to the double precision floating point number to be printed.
n
The associated argument is taken to be a pointer to an integer variable. PRINTF assigns this variable the number of characters that have been printed out so far.
o
The argument is printed as an unsigned octal number, right-justified. If W is not specified, the default is zero; if P is not specified, the default is '0'. N is the minimum number of digits to print (default 1). Using the flag '#' will force the first digit to be zero.
r
The argument is taken as a pointer to a "remote" argument list consisting of a format string pointer followed by appropriate arguments. The format string is interpreted as described here. The rest of the format in which the "%r" occurred is ignored. If W is supplied, it is interpreted as the length of the new argument list; if W is not supplied, the end of the list will be determined from the new format string. F, N and P are not applicable in "r"-type formats.
s
The argument is taken as a pointer to an ASCII string. The string is printed left-justified. W gives the minimum field width; N gives the maximum field width. If the string is shorter than W characters, it will be padded with character P (default ' '); if it is longer than N, only the first N characters will be printed.
_s
The argument is assumed to be a pointer to a BCD string. W is the width of the output field; N is the number of BCD characters to print. If N is not specified, W is used; if W is not specified, N is used. If neither is given, W=6. The BCD characters will be converted to lower case ASCII and output. Normally, trailing blanks will be discarded; however, if you specify '#' trailing blanks will be retained.
_S
This is the same as "%_s" except that BCD letters are converted to upper case ASCII.
u
The argument is printed as an unsigned decimal number, right justified. M specifies the minimum number of digits to print (default 1).
_v
This is only useful when "printf" is being called from a single segment C program. The format is equivalent to the "%_v" format of the C package's "printf". See "expl c lib printf" for more information.
x
The argument is specified as an unsigned hexadecimal number, right-justified. N specifies the minimum number of digits to print (default 1). Specifying the '#' flag will prepend "0x" to any non-zero output. Alphabetic hexadecimal digits are printed in lower case.
X
This is the same as "%x" except that alphabetic hexadecimal digits are printed in upper case.
y
This indicates the next argument is a user-supplied formatting function. It will be called with a first argument of the following PRINTF argument, and then the values of M, N and P (specified by M.N,P). Missing values for M, N, and P will be indicated by the value 0400000000000. A fifth argument gives the modifier flag bits. (See "expl b bmac prnt.f" for more details.)
z
This obsolete format is the same as "%0d".

For W, N, or P, you may specify the character '?', indicating that the next available argument is to be used as the field width, precision, or fill character. Variable field widths supplied in this way must be integers. It is an error to say

printf("%?f", 5.3, num );
Instead, use
printf( "%?.?f", 5, 3, num );

You may also use '?' to specify that the fill character P is to be obtained from the argument list. If you need a fill character '?', you must supply an argument of '?' in the argument list.

Except where noted above, supplied field widths are minimum values and the field will be longer if the argument does not fit.

The floating point formats only work when your program uses at least one floating point operator, or when you specify

extrn .float;
to force the loading of a routine which understands floating point format.

If "unit" is specified, the current output unit is switched to "unit" for the duration of the call and restored upon return.

Examples:

The following examples show differences in handling leading zeros. We use the letter 'b' to show where spaces will be printed out. In all cases, the value printed out is the integer -1.

Format     Output
 %5d       bbb-1
 %05d      -0001
 %5.5d     -00001  (precision requires 5 sig. digits)
 %5,0d     000-1   (zero is fill character)

Notes:

To obtain the character "%" in a format string, enter "%%", e.g.

printf("The percentage is %d %%.*n",5);
   yields
The percentage is 5 %.

Most users will find that "%g" is the best choice for printing out floating point numbers. "%f" is only for specialized situations, and "%e" is rarely useful.

If the "format" string argument has the format of a B pointer (upper half of the word zero, lower half the pointer value), PRINTF behaves as explained in this file. If the "format" string argument has the format of a C pointer (upper half of the word non-zero), PRINTF behaves according to the ANSI standard rules for C (as explained in "expl c lib printf"). There are slight differences between the two behaviors.

See Also:

expl b lib print
for outputting result into a string.
expl c lib printf
(if your site has installed the single segment C package)

Copyright © 2000, Thinkage Ltd.