mpg-ref-format - SICStus Prolog

11.3.84 `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.

‘~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.
type_error
domain_error: Argument of the wrong type or domain.

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 ~`.t ~d~72|~*n", ["Quintus Prolog Release ",1.5,2,2]),
         format("~t~*+~w Definition of the term \"loaded\" ~`.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 ~`.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

11.3.84 format/[2,3]