#### 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("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