format/[2,3]

Synopsis

format(+Control, +Arguments)

format(+Stream, +Control, +Arguments)

Interprets the Arguments according to the Control string and prints the result on the current or specified output stream.

Arguments

Stream stream_object

Control list of char or atom

either an atom or a string, which can contain control sequences of the form ~<n><c>

<c>

a format control option

<n>

is its optional argument.

<n> must be a non-negative integer.

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

Arguments term

list of arguments, which will be interpreted and possibly printed by format control options. If there is only one argument then this argument need not be enclosed in a list.

Description

Please note: In the case where there is only one argument and that argument is a list, then that argument must be enclosed in a list.

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. The argument must be of the type specified, or format/1 will raise a consistency error.

~<n>a

argument is an atom, which is printed without quoting. The maximum number of characters printed is <n>. If <n> is omitted the entire atom is printed.

          | ?- format('~a', foo).
          foo
          

~<n>c

argument is a numeric ASCII code (0 =< code =< 127), which is printed <n> times. If <n> is omitted, it defaults to 1.

          | ?- format('~2c', 97).
          aa
          

~<n>e

argument is a floating-point number, which is printed in exponential notation with precision <n>. The form of output is (in left-to-right order):

• an optional -,
• a digit,
• a . if <n> is greater than 0,
• <n> digits,
• an e,
• a + or a -, and
• two or more digits.

If <n> is omitted, it defaults to 6.

          | ?- format('~3e', 1.33333).
          1.333e+00
          

See ref-ari-ove for detailed information on precision.

Notes:

1. ~<n>e coerces integers to floats
2. If n is greater than 60, only 60 digits will be printed.

~<n>E

same as ~<n>e, except E is used for exponentiation instead of e.

          | ?- format('~3E', 1.33333).
          1.333E+00
          

~<n>f

argument is a floating-point number, which is printed in non-exponential format, with <n> digits to the right of the decimal point. If <n> is omitted, it defaults to 6. If <n> is equal to 0, no decimal point is printed.

          | ?- format('~3f', 1.33333).
          1.333
          

Notes:

1. ~<n>f coerces integers to floats
2. If n is greater than 60, only 60 digits will be printed.

See the section on floating-point arithmetic for detailed information on precision.

~<n>g

argument is a floating-point number, which is printed in either ~<n>e or ~<n>f form, whichever gives the best precision in minimal space, with the exception that no trailing zeroes are printed unless one is necessary immediately after the decimal point to make the resultant number syntactically valid. At most <n> significant digits are printed. If <n> is omitted, it defaults to 6.

          | ?- format('~g', 1000000000.0).
          1e+09
          
          | ?- format('~20g', 1000000000.0).
          1000000000
          

See the section on floating-point arithmetic for detailed information on precision.

~<n>G

same as ~<n>g, except E is used for exponentiation instead of e.

          | ?- format('~G', 1000000.0).
          1E+06
          

~<n>d

argument is an integer, which is printed as a signed decimal number, shifted right <n> decimal places. If <n> is omitted, it defaults to 0. If <n> is 0, the decimal point is not printed.

          | ?- format('~d', 29).
          29
          
          | ?- format('~1d', 29).
          2.9
          

~<n>D

same as ~<n>d, except that commas are inserted to separate groups of three digits to the left of the decimal point.

          | ?- format('~1D', 29876).
          2,987.6
          

~<n>r

argument is an integer, which is printed in radix <n> (where 2 =< n =< 36) using the digits 0-9 and the letters a-z. If <n> is omitted, it defaults to 8.

          | ?- format('~2r', 13).
          1101
          
          | ?- format('~r', 13).
          15
          
          | ?- format('~16r', 13).
          d
          

~<n>R

same as ~<n>r, except it uses the digits 0-9 and the letters A-Z instead of a-z.

          | ?- format('~16R', 13).
          D
          

~<n>s

argument is a string (list of numeric ASCII codes), from which at most the first <n> codes are printed as ASCII characters. If <n> is zero or if <n> is omitted, it defaults to the length of the string. If the string is shorter than <n> then all the ASCII codes that make up the string are printed.

          | ?- format('~s', ["string"]).
          string
          
          | ?- format('~3s', ["string"]).
          str
          
          | ?- format('~a', "string").
          ! Consistency error: a and
            [115,116,114,105,110,103] are inconsistent
          ! the argument for the format control
            option "a" must be of type "atom".
          ! goal:  format('~a',
            [115,116,114,105,110,103])
          

The following control options can take an argument of any type:

~i

argument is ignored.

          | ?- format('~i', 10).
          

~k

argument is passed to write_canonical/[1,2].

          | ?- format('~k', 'A'+'B').
          +('A','B')
          

~p

argument is passed to print/[1,2].

          | ?- asserta((portray(X+Y) :-
                   write(X), write(' plus '),
                   write(Y))).
          
          | ?- format('~p', 'A'+'B').
          A plus B
          

~q

argument is passed to writeq/[1,2].

          | ?- format('~q', 'A'+'B').
          'A'+'B'
          

~w

argument is passed to write/[1,2].

          | ?- format('~w', 'A'+'B').
          A+B
          

The following control options do not have a corresponding argument:

~~

prints one ~.

          | ?- format('~~', []).
          ~
          

~<n>n

prints <n> newline characters. If <n> is omitted, it defaults to 1.

          | ?- format('begin~nend', []).
          begin
          end
          

~N

prints nothing if at the beginning of a line, otherwise prints one newline character.

          | ?- format('~Nbegin~N~Nend', []).
          begin
          end
          

The following control options manipulate column boundaries (tab positions). These column boundaries only apply to the line currently being written. A column boundary is initially assumed to be in line position 0.

~<n>|

sets a column boundary at line position <n> and moves the cursor to that line position. If <n> is omitted, a column boundary is set at the current line position. See extended example below (also see ref-iou-cou-fou).

~<n>+

sets a column boundary at <n> positions past the previous column boundary and moves the cursor to that line position. If <n> is omitted, it defaults to 8. See extended example below.

~<n>t

When fewer characters are written between two column boundaries than the width of the column, the space remaining in the column is divided equally amongst all the ~t's, if any, in the column, and each ~t fills its allotted space with characters of ASCII code <n>. If <n> is omitted, it defaults to ASCII 32 (space). <n> can also be of the form `<c>, where <c> is the fill character. See extended example below.

Exceptions

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

consistency_error

wrong number of arguments

domain_error

wrong format option type

Examples

1. The following is an extended example of the use of format/[2,3] and the character escaping facility.

     | ?- prolog_flag(character_escapes, _, on).
     
     yes
     | ?- compile(user).
     | toc(Rel) :-
         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 ",Rel,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]).
     | ^D
     % user compiled, 20.783 sec 4888 bytes
     
     yes
     | ?- toc(1.5).
                                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
     
     yes
     

2. Misc. examples:

     | ?- X=12, format('X =:= ~2d', X).     % These three
     | ?- X=12, format("X=:= ~2d", X).      %  have the
     | ?- X=12, format('X =:= ~*d', [2,X]). %  same results
     
     | ?- format('~s', ["string"]).     % These two have
     | ?- format('string', []).         % the same results
     
     | ?- X=12, Y= 123, format('X = ~d, Y = ~d', [X,Y]).
     

See Also

write_canonical/[1,2], print/[1,2], write/[1,2] ref-iou