Next: mpg-ref-freeze, Previous: mpg-ref-foreign_resource, Up: mpg-bpr [Contents][Index]
format/[2,3]format(+Control, +Arguments)
format(+Stream, +Control, +Arguments)
Interprets the Arguments according to the Control string and prints the result on Stream.
stream_object, must be ground
Defaults to the current output stream.
chars or codes or atom, must be ground
A string, which can contain control sequences of the form ‘~N<c>’:
a format control option
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.
list of term, must be proper list
List of arguments, which will be interpreted and possibly printed by format control options.
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.
The argument is an atom. The atom is printed without quoting.
(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.
(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.
(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.
(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.
(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.
(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.
(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.
(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.
(Print radix.) The argument is an integer. Identical to ‘~Nr’ except that the letters ‘A-Z’ will denote digits larger than 9.
(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.
(Ignore.) The argument, which may be of any type, is ignored.
(Print canonical.) The argument may be of any type. The
argument will be passed to write_canonical/1 (see ref-iou-tou).
(Print.) The argument may be of any type. The argument will
be passed to print/1 (see ref-iou-tou).
(Print quoted.) The argument may be of any type. The
argument will be passed to writeq/1 (see ref-iou-tou).
(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 ‘~’.
(Print newline.) Takes no argument. Prints N newlines. N defaults to 1.
If N is negative or zero, then no newlines are output.
(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.
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 streams10, e.g. those created by
library(sockets). A workaround for bi-directional streams may
be to use ‘~|’ (without explicit N) and ‘~N+’,
see below.
Set a column boundary at N positions past the previous column boundary. N defaults to 8.
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.
Stream errors (see ref-iou-sfh-est), plus:
consistency_errorWrong number of Arguments.
type_errordomain_errorArgument of the wrong type or domain.
| ?- 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
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).