format/2

"format(+ T, :L" )

"format(+Stream+ T, :ListWithArguments" )

"format(+ T, :ListWithArguments" )

Print formatted output to the current output stream. The arguments in list L are output according to the string, list of codes or characters, or by the atom T.

A control sequence is introduced by a ~. The following control sequences are available in YAP:

  • ~~ Print a single tilde.

  • ~a The next argument must be an atom, that will be printed as if by write.

  • ~Nc The next argument must be an integer, that will be printed as a character code. The number N is the number of times to print the character (default 1).

  • ~Ne

  • ~NE

  • ~Nf

  • ~Ng

  • ~NG The next argument must be a floating point number. The float F, the number N and the control code c will be passed to printf as:


 printf( "%s.Nc" , F)

As an example:


 ?- format( "~8e, ~8E, ~8f, ~8g, ~8G~w" ,
 [3.14,3.14,3.14,3.14,3.14,3.14]).
 3.140000e+00, 3.140000E+00, 3.140000, 3.14, 3.143.14
  • ~Nd The next argument must be an integer, and N is the number of digits after the decimal point. If N is 0 no decimal points will be printed. The default is N = 0.

 ?- format( "~2d, ~d" ,[15000, 15000]).
 150.00, 15000
  • ~ND Identical to ~Nd, except that commas are used to separate groups of three digits.

 ?- format( "~2D, ~D" ,[150000, 150000]).
 1,500.00, 150,000
  • ~i Ignore the next argument in the list of arguments:

 ?- format( 'The ~i met the boregrove' ,[mimsy]).
 The met the boregrove
  • ~k Print the next argument with write_canonical:

 ?- format( "Good night ~k" ,a+[1,2]).
 Good night +(a,[1,2])

  • ~Nn Print N newlines (where N defaults to 1).

  • ~NN Print N newlines if at the beginning of the line (where N defaults to 1).

  • ~Nr The next argument must be an integer, and N is interpreted as a radix, such that 2 <= N <= 36 (the default is 8).


 ?- format( "~2r, 0x~16r, ~r" ,
 [150000, 150000, 150000]).
 100100100111110000, 0x249f0, 444760

Note that the letters a-z denote digits larger than 9.

  • ~NR Similar to ~NR. The next argument must be an integer, and N is interpreted as a radix, such that 2 <= N <= 36 (the default is 8).

 ?- format( "~2r, 0x~16r, ~r" ,
 [150000, 150000, 150000]).
 100100100111110000, 0x249F0, 444760

The only difference is that letters A-Z denote digits larger than 9.

  • ~p Print the next argument with print_49 "print/1":

@icode ?- format("Good night ~p",a+[1,2]). Good night a+[1,2] @endicode

  • ~q Print the next argument with @ref writeq_49 @"writeq/1":

@icode ?- format("Good night ~q",'Hello'+[1,2]). Good night 'Hello'+[1,2] @endicode

  • ~Ns The next argument must be a list of character codes.The system then outputs their representation as a string, where N is the maximum number of characters for the string ( N defaults to the length of the string).

@icode ?- format("The ~s are ~4s",["woods","lovely"]). The woods are love @endicode

  • ~w Print the next argument with @ref write_49 @"write/1":

@icode ?- format("Good night ~w",'Hello'+[1,2]). Good night Hello+[1,2] @endicode

  • ~W Give the next two arguments to @ref write_term_50 @"write_term/2". The first is the term to print, and the second is a list of @ref write_term_50 @"write_term/2" options. For example:

@icode format(string(S), '~W', [Term, [singletons(true)]]). @endicode

This option is SWI-Prolog specific.

The number of arguments, N, may be given as an integer, or it may be given as an extra argument. The next example shows a small procedure to write a variable number of a characters:

@icode write_many_as(N) :- format("~*c",[N,0'a]). @endicode

The @ref format_50 @"format/2" built-in also allows for formatted output. One can specify column boundaries and fill the intermediate space by a padding character:

  • ~N| Set a column boundary at position N, where N defaults to the current position.

  • ~N+ Set a column boundary at N characters past the current position, where N defaults to 8.

  • ~Nt Set padding for a column, where N is the fill code (default is SPC).

The next example shows how to align columns and padding. We first show left-alignment:

@icode ?- format("~nHello~16+~n",[]). *Hello * @endicode

Note that we reserve 16 characters for the column.

The following example shows how to do right-alignment:

@icode ?- format("~tHello~16+~n",[]). Hello*

@endicode

The ~t escape sequence forces filling before Hello.

We next show how to do centering:

@icode ?- format("~tHello~t~16+~n",[]). Hello * @endicode

The two ~t escape sequence force filling both before and after Hello. Space is then evenly divided between the right and the left sides.

  • ~\@ Evaluate the next argument as a goal whose standard output is directed to the stream used by @ref format_50 @"format/2".

Print formatted output to the current output stream.

Print formatted output to the stream _Stream_.