
printf(+Stream, +Format, ?ArgList)

   The arguments in the argument list ArgList are interpreted according to the
Format string and the result is printed on the output Stream

Arguments
   Stream              Stream handle or alias (atom)
   Format              String or Atom.
   ArgList             List or any Term.

Type
   Term I/O

Description

   Format is an atom or a string which can contain embedded format control
   sequences.  ArgList is a list of arguments that will be interpreted,
   and possibly printed, under control of these format options.
   Any part of Format that is not a control sequence is written to the
   output stream Stream unchanged.  As far as the functionality overlaps,
   the behaviour is similar to the 'C' function printf().

   Format control sequences take one of the following forms:

       %[-+ 0][minwidth][.precision]{d|u|o|x|X}
       %[-+ 0][minwidth][.precision]{f|g|e|E}
       %[-+ 0][minwidth.]radix{r|R}
       %[-][minwidth][.precision]{s|a|A}
       %[depth][modifiers]{w|W}
       %[count]{c|i|n|t}
       %{b|k|p|q|%}

   Each control sequence starts with a percent character, followed by a
   number of optional flags/parameters, and ends in one of the conversion
   control characters (described below in detail).

   The meaning of the flags and parameters are:

    -
        Left-justify the output (if the field width is greater than the
	length of the printed representation).  Default is right-justified.
    
    +
        Print a plus sign in front of non-negative numbers.  By default,
	only negative numbers are printed with a sign.
    
    (space)
        Print a blank space in front of non-negative numbers.  If a plus
	sign is specified as well, the space is ignored.
    
    0
	If the width of a right-justified field is greater than the length
	of the printed representation, fill the space with leading zeros
	instead of spaces.
    
    minwidth
	An optional minimum field width, which causes the printed
	representation to be padded (left or right) in case it is shorter
	than the specified minimum.  The width is given either as an
	unsigned decimal integer, or as a '*' character, in which case
	the number is taken from the next element of ArgList.
    
    precision
	An optional precision, determining the number of places after
	the decimal point (for floating point arguments), the minimum
	number of digits (for integer arguments), or the maximum number
	of characters (for atom/string arguments).  The precision is given
	either as an unsigned decimal integer, or as a '*' character, in
	which case the number is taken from the next element of ArgList.
    
    radix
	A number between 2 and 36, giving the number base in which the
	argument is to be printed.  For instance, 2 for binary, 16 for
	hexadecimal, 8 for octal, or 36 to use all the digits 0-9a-z.
	The radix is given either as a decimal integer, or as a '*'
	character, in which case it is taken from the next element
	of ArgList.
    
    count, depth
	An optional count (determining how many times an option will be
	repeated), or depth (determining the maximum nesting depth for
	printing terms).  It is given either as an unsigned decimal
	integer, or as a '*' character, in which case the number is
	taken from the next element of ArgList.
    


   The meaning of the conversion control characters is:

  a
    The argument has to be an atom (or string) and is printed without
    any quoting.  Optionally, field width, justification, and maximum
    length can be specified.  Identical to the s format.

  A
    The argument has to be an atom (or string), is converted to upper
    case, and then printed without quoting.  Optionally, field width,
    justification, and maximum length can be specified.

  b
    The stream's output buffer is flushed, buffered data is written
    to the device attached to the stream.

  c
    The argument has to be an integer character code and is printed
    as a character.  Optionally, a repeat count can be specified.

  d
    The argument has to be an integer and is printed in signed decimal
    notation.  Optionally, details regarding field width, number of
    digits, padding and sign representation can be specified.
    See r for non-decimal notation.

  e
    The argument has to be a floating-point number and is printed according
    to the substring A in exponential notation.('e' is used for
    exponentiation)

  E
    The argument has to be a floating-point number and is printed according
    to the substring A in exponential notation.  ('E' is used for
    exponentiation)

  f
    The argument has to be a floating-point number and is printed according
    to the substring A in non-exponential form.

  g
    The argument has to be a floating-point number and is printed according
    to the substring A in exponential or non-exponential form, whichever
    gives the best precision in minimum space.('e' is used for
    exponentiation)

  i
    The next argument of ArgList is ignored.  An optional repeat count
    can be specified.

  k
    The argument is passed to display/1.  It is a synonym for %O.w.

  n
    A newline sequences is printed.  An optional repeat count can be given.
    Which newline characters are printed depends on the setting of the
    stream's end_of_line property. If the stream's flush-property is set
    to end_of_line, the stream is also flushed.

  o
    The argument has to be an integer and its least significant 32 bits
    are printed in unsigned octal notation.  Optionally, details regarding
    field width, number of digits, padding and sign representation can be
    specified. DEPRECATED, see r.

  r
    The argument has to be an integer and is printed in signed notation
    in the given base (radix) between 2 and 36.  The digits are
    represented as the characters 0-9a-z.  Optionally, details regarding
    field width, padding and sign representation can be specified.

  R
    The argument has to be an integer and is printed in signed notation
    in the given base (radix) between 2 and 36.  The digits are
    represented as the characters 0-9A-Z.  Optionally, details regarding
    field width, padding and sign representation can be specified.

  p
    The argument is passed to print/1.  It is a synonym for %Pw.

  q
    The argument is passed to writeq/1.  It is a synonym for %QDvw.

  s
    The argument has to be an string or atom and is printed without
    any quoting.  Optionally, field width, justification, and maximum
    length can be specified.

  t
    A tab character is printed.  An optional repeat count can be given.

  u
    The argument has to be an integer and its least significant 32 bits
    are printed in unsigned decimal notation.  Optionally, details
    regarding field width, number of digits, padding and sign representation
    specified. DEPRECATED.

  w
   The argument is by default passed to write/1.
   However, the %w format recognises a number of modifier characters,
   placed between the percent sign and w.  They give the user full
   control over the various possibilities of printing Prolog terms.
   A number immediately after the percent sign determines the depth
   to which the term is printed, if an asterisk is used instead, the
   depth is taken from the next argument in ArgList. The default depth
   is determined by the setting of the (stream-specific or global)
   print_depth flag.
   After the optional depth, the following modifiers are recognized:

      O
        omit operator declarations.  All terms are written in the canonical
        notation without operators.

      Q
        quote atoms and strings if necessary.

      .
        write lists in the dot functor notation rather than using the
        square bracket notation, e.g. .(1, .(2, [])) rather than [1, 2].

      G
        print the term as a goal, i.e.  goal write transformations will
        be taken into account.

      P
        call the user-defined predicate portray/1, 2 in the way print/1, 2
        does.

      D
        disregard the depth restriction of the print-depth flag and print
        the whole term.

      U
        call portray/1, 2 even on variables.  This is to be used in
        conjunction with the P option.  Note that attributed variables
        are always portrayed.

      V
        print the full variable name, if available, either in the form
        Name_Number, e.g. Alpha_132, or Name#Number, if the variable had
        been given a name via lib(var_name). This is necessary to 
        distinguish different variables with the same name.

      v
        print only the short variable form, i.e. even when available, the
        variable name is not printed.  This is useful if a term should be
        written and read back in several times.  If neither V nor v is
        specified, variables are printed only with their name, if it is
        available.  Variable without names are always printed in the v form.

      _
        print every variable as a simple underscore. Any information about
        multiple occurrences of a variable is lost with this format. It is
        mainly useful to produce output that can be compared easily with
        the output of a different Eclipse session.

      I
        any term of the form '$VAR'(N), where N is a non-negative integer,
        is printed as a variable name consisting of a capital letter
        followed by a number. The capital letter is the ((N mod 26)+1)st
        letter of the alphabet, and the integer is N//26.
        If N is an atom, this atom gets printed instead of the term.

      K
        don't print blank space (around operators, after commas, etc.)
        unless necessary.

      M
        print the full contents of all variable attributes.  This is
        necessary if the term is to be written out and read back in.

      m
        variable attributes are printed using the corresponding print
        handlers.  If neither M nor m is specified, attributed variables
        are printed as variables, without any attribute.

      N
        print newline (NL) characters as newlines rather than as an
        escape sequence, even when they occur in quoted atoms or strings.
        This only makes sense together with the Q modifier.

      T
        do not apply any write transformations.

      C
        print the term as a clause, i.e.  clause macros will be taken into
        account.

      F
	print a fullstop after the term, separated from the term by an
	extra space, if necessary.

      L
	print a newline after the term (or as part of the fullstop
	sequence, if used together with the F option).


  W
    Like %w, but the stream's default output options are taken into
    account, unless overridden by the format options specified here.
    Note in particular that a default setting may be cancelled by
    prefixing the format character with a minus sign. E.g. if the stream
    defaults specify that quotes should be printed (quoted(true)), this
    can be overridden by a %-QW format string.

  x
    The argument has to be an integer and its least significant 32 bits
    are printed in unsigned hexadecimal notation (using letters abcdef).
    Optionally, details regarding field width, number of digits, padding
    and sign representation can be specified.  DEPRECATED, see r.

  X
    The argument has to be an integer and its least significant 32 bits
    are printed in unsigned hexadecimal notation (using letters ABCDEF).
    Optionally, details regarding field width, number of digits, padding
    and sign representation can be specified.  DEPRECATED, see R.

  %
    One % is printed.

   For backward compatibility, if ArgList contains only one argument,
   it need not be in a list.


Modes and Determinism
   printf(+, +, ?) is det

Modules
   This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions
     4 --- Stream is not instantiated.
     5 --- Stream is not an atom or a stream handle.
     5 --- Format is not an atom or a string.
     5 --- ArgList contains argument whose type does not correspond to    the control sequence.
     7 --- Format is not correct, it contains too many asterisks or a    control character is missing or there is a redundant character before    the control character.
     8 --- ArgList has not enough or too many arguments.
   192 --- Stream is not an output stream.
   193 --- Stream is not a stream specification.

Examples
   
Success:
?- printf(output, "abc %s ghi %+*.*E...",
        ["def", 2, 3, 12.34]).
abc def ghi +1.234E+01...
yes.
?- printf(output, "abc %12c %*n", [77, 3]).
abc MMMMMMMMMMMM



yes.
?- printf(output, "abc %i def %a%2t%%", [123, ghi]).
abc  def ghi            %
yes.
?- printf(output, "%w", ['A'+'B']).
A + B
yes.
?- printf(output, "%q", ['A'+'B']).
'A' + 'B'
yes.
?- printf(output, "%k", ['A'+'B']).
+(A, B)
yes.

Error:
      printf(S, "%s", ["eclipse"]).          (Error 4).
      printf(output, F, eclipse).            (Error 4).
      printf("output", "%s", ["eclipse"]).   (Error 5).
      printf(output, "%a", 1).               (Error 5).
      printf(output, "%*.*.*s", [2, 3, 4,  "eclipse"]).
                                             (Error 7).
      printf(output, "%d %d %d", [1, 9]).    (Error 8).
      printf(9, "%s", ["eclipse"]).
                       (Error 192). % stream not open
      printf(atom, "%s", ["eclipse"]).       (Error 193).
      printf(s, comment%s, eclipse).
                                 '%' starts a comment





See Also
   display / 1, display / 2, print / 1, print / 2, printf / 2, sprintf / 3, write / 1, write / 2, write_term / 2, write_term / 3, writeq / 1, writeq / 2
