HELP PRINTF                                    Andrew Law, February 1986

         CONTENTS - (Use <ENTER> g to access required sections)

 -- General description
 -- Examples
 -- WARNING

-- General description ------------------------------------------------

    printf(<string>, [<item1> <item2> ... <itemN>]);
or
    printf(<itemN>, ..., <item2>, <item1>, <string>);

This procedure provides formatted printing. The string is printed as
usual, except that field specifiers occurring in the string cause items
(from the list, in the first format, or from the arguments, in the
second) to be selected and printed according to the specifier. A field
specifier is the character "%" immediately followed by a selector
character, which may (currently) be one of the following:

    p  -  any pop item, printed with *PR
    P  -  any pop item, printed with *SYS_SYSPR
    s  -  a string printed recursively with PRINTF
    S  -  a string or word printed literally
    c  -  an integer interpreted as an *ASCII character code

    (The characters b, d, i and x are also meaningful, but
     are reserved for system use.)

The N'th field specifier in the string selects the N'th argument item.
In the first form of the call, the arguments are supplied in a list,
whereas in the second form the arguments are taken off the stack (and
therefore expected in REVERSE order). "%" may be followed by another "%"
to print a single "%".


-- Examples -----------------------------------------------------------

For example

    printf('the sum of %p and %p is not %p', [65 66 67]);
or
    printf(67, 66, 65, 'the sum of %p and %p is not %p');

will print out:

    the sum of 65 and 66 is not 67

or, if the arguments are interpreted as ASCII code, then

  printf('the first three letters of the alphabet are %c %c %c',
         [65 66 67]);

will print out:

    the first three letters of the alphabet are A B C

Variables can be used in both forms and if the first format is used the
variables in the list should be treated in the normal manner e.g.:

    vars a b c;
    3 -> a;  5 -> b;  8 -> c;

    printf('the sum of %p and %p is %p', [% a, b, c, %]);
or
    printf('the sum of %p and %p is %p', [^a ^b ^c]);

These will print out:

    the sum of 3 and 5 is 8

Otherwise, they will be treated as normal list elements:

    printf('the sum of %p and %p is %p', [a b c]);

will print out:

    the sum of a and b is c


-- WARNING ------------------------------------------------------------

NOTE: The second form is incompatible with contexts in which *CUCHAROUT
is redefined to leave characters on the stack, so the first form is the
preferred one. This can occur when trying to obtain the print string of
an object, eg. by using >< or sys_><.  Thus the form of printf that
takes the items to be printed as a list is the ONLY one which should be
used as part of a -class_print- procedure etc.

See also:

HELP *ASCII   - on character codes
HELP *STRINGS - on construction and use of strings in POP-11
HELP *PRINT   - for more information on printing things



--- C.all/help/printf --------------------------------------------------
--- Copyright University of Sussex 1987. All rights reserved. ----------
