Next: , Previous: , Up: mpg-bpr   [Contents][Index]


11.3.85 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 an 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 a parameter N can be specified, then it can be either an integer, specified as an optional minus sign followed by a sequence of decimal digits, or the character ‘*’.

If the parameter is specified as ‘*’, then the value used will be the truncated integer value of the next element from Arguments interpreted as a numerical expression.

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. If N is zero, or negative, then the character is not printed.

~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, or negative, then 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.

The magnitude of N must be less than 100000, but useful values are much smaller than that.

~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, or negative, in which case a single zero appears after the decimal point. At least one digit appears before the decimal point and at least one after it. N defaults to 6.

The magnitude of N must be less than 100000, but useful values are much smaller than that.

~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, then 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.

The magnitude of N must be less than 100000, but useful values are much smaller than that.

~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’.

The magnitude of N must be less than 100000, but useful values are much smaller than that.

~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, then no decimal point will be printed.

N must be non-negative.

~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, then 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. If N is zero, or negative, then no characters are output.

If N is positive, then the first N characters of the code list will be written, and if the code list is exhausted, then extra SPC characters will be written, for a total of N characters output.

~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, then the behavior is undefined.

~~

(Print tilde.) Takes no argument. Prints ‘~’.

~Nn

(Print newline.) Takes no argument. Prints N newlines. N defaults to 1.

If N is negative or zero, then no newlines are output.

~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, then the column is space padded at the end.

If ‘~|’ or ‘~+’ specifies a position preceding the current position, then the boundary is set at the current position.

~N|

Set a column boundary at line position N. N defaults to the current position.

The control sequence ‘~N|’ (with explicit N) will not work correctly on bi-directional streams12, e.g. those created by library(sockets). A workaround for bi-directional streams may be to use ‘~|’ (without explicit N) and ‘~N+’, see below.

~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

See Also

ref-iou-tou.


Footnotes

(12)

This is because streams only have one counter for line position, and for bidirectional streams that counter tracks the input direction (see cpg-ref-SP_get_stream_counts).



Send feedback on this subject.