11.3.81 format/[2,3]

Synopsis

format(+Control, +Arguments)

format(+Stream, +Control, +Arguments)

Interprets the Arguments according to the Control string and prints the result on Stream.

Arguments

Stream
stream_object, must be ground

Defaults to the current output stream.

Control
chars or codes or atom, must be ground

A string, which can contain control sequences of the form `~<n><c>':

<c>
a format control option
<n>
optional; if given, must be `*' or a non-negative integer.

Any characters that are not part of a control sequence are written to the specified output stream.

:Arguments
list of term, must be proper list

List of arguments, which will be interpreted and possibly printed by format control options.

Description

If <n> can be specified, then it can be the character `*'. In this case <n> will be taken as the next argument from Arguments.

The following control options cause formatted printing of the next element from Arguments to the current output stream.

`~a'
The argument is an atom. The atom is printed without quoting.
`~Nc'
(Print character.) The argument is a number that will be interpreted as a code. N defaults to one and is interpreted as the number of times to print the character.
`~Ne'
`~NE'
(Print float in exponential notation.) The argument is a float, which will be printed in exponential notation with one digit before the decimal point and N digits after it. If N is zero, one digit appears after the decimal point. A sign and at least two digits appear in the exponent, which is introduced by the letter used in the control sequence. N defaults to 6.
`~Nf'
`~NF'
(Print float in fixed-point notation.) The argument is a float, which will be printed in fixed-point notation with N digits after the decimal point. N may be zero, in which case a zero appears after the decimal point. At least one digit appears before it and at least one after it. N defaults to 6.
`~Ng'
`~NG'
(Print float in generic notation.) The argument is a float, which will be printed in `f' or `e' (or `E' if `G' is used) notation with N significant digits. If N is zero, one significant digit is printed. `E' notation is used if the exponent from its conversion is less than -4 or greater than or equal to N, otherwise `f' notation. Trailing zeroes are removed from the fractional part of the result. A decimal point and at least one digit after it always appear. N defaults to 6.
`~Nh'
`~NH'
(Print float precisely.) The argument is a float, which will be printed in `f' or `e' (or `E' if `H' is used) notation with d significant digits, where d is the smallest number of digits that will yield the same float when read in. `E' notation is used if N<0 or if the exponent is less than -N-1 or greater than or equal to N+d, otherwise `f' notation. N defaults to 3.

The intuition is that for numbers like 123000000.0, at most N consecutive zeroes before the decimal point are allowed in `f' notation. Similarly for numbers like 0.000000123.

`E' notation is forced by using `~-1H'. `F' is forced by using `~999H'.

`~Nd'
(Print decimal.) The argument is an integer. N is interpreted as the number of digits after the decimal point. If N is 0 or missing, no decimal point will be printed.
`~ND'
(Print decimal.) The argument is an integer. Identical to `~Nd' except that `,' will separate groups of three digits to the left of the decimal point.
`~Nr'
(Print radix.) The argument is an integer. N is interpreted as a radix, 2 \leq N \leq 36. If N is missing the radix defaults to 8. The letters `a-z' will denote digits larger than 9.
`~NR'
(Print radix.) The argument is an integer. Identical to `~Nr' except that the letters `A-Z' will denote digits larger than 9.
`~Ns'
(Print string.) The argument is a code-list. Exactly N characters will be printed. N defaults to the length of the string.
`~i'
(Ignore.) The argument, which may be of any type, is ignored. Example:
`~k'
(Print canonical.) The argument may be of any type. The argument will be passed to write_canonical/1 (see ref-iou-tou).
`~p'
(Print.) The argument may be of any type. The argument will be passed to print/1 (see ref-iou-tou).
`~q'
(Print quoted.) The argument may be of any type. The argument will be passed to writeq/1 (see ref-iou-tou).
`~w'
(Write.) The argument may be of any type. The argument will be passed to write/1 (see ref-iou-tou).
`~@'
(Call.) The argument Arg is a goal, which will be called as if by \+ \+ Arg and is expected to print on the current output stream. If the goal performs other side-effects, the behavior is undefined.
`~~'
(Print tilde.) Takes no argument. Prints `~'.
`~Nn'
(Print newline.) Takes no argument. Prints N newlines. N defaults to 1.
`~N'
(Print Newline.) Prints a newline if not at the beginning of a line.

The following control sequences set column boundaries and specify padding. A column is defined as the available space between two consecutive column boundaries on the same line. A boundary is initially assumed at line position 0. The specifications only apply to the line currently being written.

When a column boundary is set (`~|' or `~+') and there are fewer characters written in the column than its specified width, the remaining space is divided equally amongst the pad sequences (`~t') in the column. If there are no pad sequences, the column is space padded at the end.

If `~|' or `~+' specifies a position preceding the current position, the boundary is set at the current position.

`~N|'
Set a column boundary at line position N. N defaults to the current position.
`~N+'
Set a column boundary at N positions past the previous column boundary. N defaults to 8.
`~Nt'
Specify padding in a column. N is the fill character code. N may also be specified as `C where C is the fill character. The default fill character is <SPC>. Any (`~t') after the last column boundary on a line is ignored.

Exceptions

Stream errors (see ref-iou-sfh-est), plus:

consistency_error
Wrong number of arguments, or argument of the wrong type.

Examples

     | ?- Pi=3.14159265, format('~e ~2E ~0E\n', [Pi,Pi,Pi]).
     3.141593e+00 3.14E+00 3.0E+00
     | ?- Pi=3.14159265, format('~f, ~2F, ~0F\n', [Pi,Pi,Pi]).
     3.141593, 3.14, 3.0
     | ?- format('~g ~2G ~0G\n', [1.23456789e+10, 3.14159265, 0.0123]).
     1.23457e+10 3.1 0.01
     | ?- F = 123000.0, G = 0.000123,
          format('~h ~h ~2h ~2H ~-1H\n', [F,G,F,G,3.14]).
     123000.0 0.000123 1.23e+05 1.23E-04 3.14E+00
     | ?- format('Hello ~1d world!\n', [42]).
     Hello 4.2 world!
     
     | ?- format('Hello ~d world!\n', [42]).
     Hello 42 world!
     | ?- format('Hello ~1D world!\n', [12345]).
     Hello 1,234.5 world!
     | ?- format('Hello ~2r world!\n', [15]).
     Hello 1111 world!
     
     | ?- format('Hello ~16r world!\n', [15]).
     Hello f world!
     | ?- format('Hello ~16R world!\n', [15]).
     Hello F world!
     | ?- format('Hello ~4s ~4s!\n', ["new","world"]).
     Hello new  worl!
     
     | ?- format('Hello ~s world!\n', ["new"]).
     Hello new world!
     | ?- format('Hello ~i~s world!\n', ["old","new"]).
     Hello new world!
     | ?- format('Hello ~k world!\n', [[a,b,c]]).
     Hello .(a,.(b,.(c,[]))) world!
     | ?- assert((portray([X|Y]) :- print(cons(X,Y)))).
     | ?- format('Hello ~p world!\n', [[a,b,c]]).
     Hello cons(a,cons(b,cons(c,[]))) world!
     | ?- format('Hello ~q world!\n', [['A','B']]).
     Hello ['A','B'] world!
     | ?- format('Hello ~w world!\n', [['A','B']]).
     Hello [A,B] world!
     | ?- format('Hello ~@ world!\n', [write(new)]).
     Hello new world!
     | ?- format('Hello ~~ world!\n', []).
     Hello ~ world!
     | ?- format('Hello ~n world!\n', []).
     Hello
      world!
     | ?-    format('~`*t NICE TABLE ~`*t~61|~n', []),
             format('*~t*~61|~n', []),
             format('*~t~a~20|~t~a~t~20+~a~t~20+~t*~61|~n',
                    ['Right aligned','Centered','Left aligned']),
             format('*~t~d~20|~t~d~t~20+~d~t~20+~t*~61|~n',
                    [123,45,678]),
             format('*~t~d~20|~t~d~t~20+~d~t~20+~t*~61|~n',
                    [1,2345,6789]),
             format('~`*t~61|~n', []).
     ************************ NICE TABLE *************************
     *                                                           *
     *      Right aligned      Centered      Left aligned        *
     *                123         45         678                 *
     *                  1        2345        6789                *
     *************************************************************
     | ?-
         format('Table of Contents ~t ~a~72|~*n', [i,3]),
         format('~tTable of Contents~t~72|~*n', 2),
         format("1. Documentation supplement for ~s~1f \c
           ~`.t ~d~72|~*n", ["Quintus Prolog Release ",1.5,2,2]),
         format("~t~*+~w Definition of the term \"loaded\" \c
           ~`.t ~d~72|~n", [3,1-1,2]),
         format("~t~*+~w Finding all solutions ~`.t ~d~72|~n", [3,1-2,3]),
         format("~t~*+~w Searching for a file in a library \c
           ~`.t ~d~72|~n", [3,1-3,4]),
         format("~t~*+~w New Built-in Predicates ~`.t ~d~72|~n", [3,1-4,5]),
         format("~t~*+~w write_canonical (?Term) ~`.t ~d~72|~n", [7,1-4-1,5]),
         format("~*+.~n~*+.~n~*+.~n", [20,20,20]),
         format("~t~*+~w File Specifications ~`.t ~d~72|~n", [3,1-7,17]),
         format("~t~*+~w multifile(+PredSpec) ~`.t ~d~72|~n", [7,1-7-1,18]).
                                Table of Contents
     
     1. Documentation supplement for Quintus Prolog Release 1.5 ........... 2
     
        1-1 Definition of the term "loaded" ............................... 2
        1-2 Finding all solutions ......................................... 3
        1-3 Searching for a file in a library ............................. 4
        1-4 New Built-in Predicates ....................................... 5
            1-4-1 write_canonical (?Term) ................................. 5
                         .
                         .
                         .
        1-7 File Specifications .......................................... 17
            1-7-1 multifile(+PredSpec) ................................... 18

See Also

ref-iou-tou.


Send feedback on this subject.