PLOGHELP FORMAT                                Robert Duncan, April 1992

    ?- format(Control).
    ?- format(Control, Args).

Formatted output.


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

 -- Introduction
 -- Format Control Characters
 -- ... Printing General Terms
 -- ... Printing Numbers
 -- ... Printing Other Typed Arguments
 -- ... Special Controls
 -- See Also


-- Introduction -------------------------------------------------------

The predicates format/1 and format/2 display formatted output on the
current output stream. Args is a list of items to be printed and Control
is an atom or string which determines their layout. Characters from
Control are printed as they occur, except for sequences of the form

    ~<n><c>

where <c> is one of the format control characters described below: most
of these cause the next item from Args to be displayed, although some
are used just for layout purposes. <n> is an optional, non-negative
integer count which influences the formatting: if the character * is
given in place of <n>, then the next item from Args is taken as the
count.

In most cases, if Args contains just a single item, then it need not be
enclosed in a list; the exceptions are variables and lists (including
character strings) which must always be enclosed in a list to avoid
ambiguity.

In a call of format/1, Args is assumed to be empty, so the Control
string should contain no sequences which require an argument.


-- Format Control Characters ------------------------------------------

The following sections summarise the available format control
characters; specifying any character not listed here will cause an
error. In each case where <n> is shown, then its value has some
influence on the output from the control sequence; otherwise, the value
of <n> is ignored.


-- ... Printing General Terms -----------------------------------------

These controls display a single item from the argument list using the
specified output predicate.

~p
    The next argument is printed using print/1.

    Example:

        ?- format("~p", 'P' -> 'Q').
        P -> Q

~w
    The next argument is printed using write/1.

    Example:

        ?- format("~w", 'P' -> 'Q').
        P -> Q

~q
    The next argument is printed using writeq/1.

    Example:

        ?- format("~q", 'P' -> 'Q').
        'P' -> 'Q'

~k
    The next argument is printed using display/1.

    Example:

        ?- format("~k", 'P' -> 'Q').
        ->('P', 'Q')

~i
    The next argument is ignored.

    Example:

        ?- format("~i", 'P' -> 'Q').


-- ... Printing Numbers -----------------------------------------------

These controls display numbers only: using them with non-numeric
arguments will cause an error.

~<n>d
    The next argument is printed as a decimal integer; non-integer
    arguments are rounded. If <n> is present and is greater than 0, the
    number is shifted right that number of decimal places before
    printing, i.e. a decimal point is inserted before the last <n>
    digits are printed.

    Example:

        ?- format("~d", 12).
        12

        ?- format("~2d", 12).
        0.12

        ?- format("~4d", 12).
        0.0012

~<n>f
    The next argument is printed as a floating-point number; non-float
    arguments are coerced to double precision. The number of digits
    after the decimal point is exactly <n>; if <n> is 0, the decimal
    point is not printed. The default value for <n> is 6.

    Example:

        ?- format("~f", 18.5).
        18.500000

        ?- format("~1f", 18.5).
        18.5

~<n>e
    The next argument is printed as a floating-point number using
    exponential notation; non-float arguments are coerced to double
    precision. The number of digits after the decimal point is exactly
    <n>; if <n> is 0, the decimal point is not printed. The default
    value for <n> is 6.

    Example:

        ?- format("~e", 18.5).
        1.850000e+1

        ?- format("~1e", 18.5).
        1.9e+1

~<n>E
    Same as ~<n>e, except that an upper-case 'E' is used to indicate the
    exponent.

    Example:

        ?- format("~E", 18.5).
        1.850000E+1

        ?- format("~1E", 18.5).
        1.9E+1

~<n>r
    The next argument is printed as an integer in base <n>; non-integer
    arguments are rounded. Only values for <n> in the range 2 ... 36 are
    meaningful; any other value is treated as 10. The letters 'a' .. 'z'
    are used for digit values above 9. The default value for <n> is 8.

    Example:

        ?- format("~r", 1742).
        3316

        ?- format("~16r", 1742).
        6ce

~<n>R
    Same as ~<n>r, except that upper-case letters are used for the
    additional digits.

    Example:

        ?- format("~R", 1742).
        3316

        ?- format("~16R", 1742).
        6CE


-- ... Printing Other Typed Arguments ---------------------------------

These controls display arguments of a specified type: using them with
arguments of a different type will cause an error.

~a
    The next argument is printed as an atom without quotes.

    Example:

        ?- format("~a", example).
        example

        ?- format("~a", 'a b c').
        a b c

~<n>c
    The next argument is printed as a character code; if <n> is present,
    the character is repeated that number of times.

    Example:

        ?- format("~c", 120).
        x

        ?- format("~10c", 120).
        xxxxxxxxxx

~<n>s
    The next argument is printed as a character string; if <n> is
    present, then at most that number of characters are printed.

    Example:

        ?- format("~s", ["Hello world"]).
        Hello world

        ?- format("~5s", ["Hello world"]).
        Hello

    Remember that a single character string argument must always be
    enclosed in a list, or format will try to print just the first
    character.


-- ... Special Controls -----------------------------------------------

The remaining controls are special cases and do not expect an argument.

~~
    Prints a single ~.

~<n>n
    Prints <n> newlines; the default value for <n> is 1.


-- See Also -----------------------------------------------------------

PLOGHELP * I_O
    Overview of input/output operations in Prolog

PLOGHELP * PRINT, * WRITE, * WRITEQ, * DISPLAY
    Basic output predicates


--- C.all/plog/help/format
--- Copyright University of Sussex 1992. All rights reserved. ----------