format

Type:	-	function (subr)
Source:	-	xlfio.c

Syntax

(format destination format [expr1 ... ])

destination - a required destination [see below]
format - a format string
exprN - an expression
returns - output string if stream is NIL , NIL otherwise

The 'destination' must be a file pointer, a stream, NIL [to create a string] or  T  [to print to *standard-output*].

Description

The 'format' function prints the specified expressions [if any] to the specified 'destination' using the 'format' string to control the print format. If the 'destination' is NIL , a string is created and returned with the contents of the 'format'. If the 'destination' is  T  , the printing occurs to *standard-output*. The 'format' function returns NIL , if the 'destination' was non-NIL. The 'format' string is a string [surrounded by double-quote characters]. This string contains ASCII text to be printed along with formatting directives [identified by a preceeding tilde '~' character]. The character following the tilde character is not case sensitive ['~a' and '~A' will function equivalently].

Examples

(format T "Now is the time for")         ; prints  Now is the time for
(format T "all ~A ~S to" 'good 'men)     ; prints  all GOOD MEN to
(format T "come to the")                 ; prints  come to the
(format T "~A of their ~S"               ; prints  aid of their "party"
          "aid" "party")
(format *standard-ouput* "Hello there")  ; prints  Hello there
(format nil "ho ho ~S" 'ho)              ; returns "ho ho HO"
(format T "this is ~%a break")           ; prints  this is
                                         ;         a break
(format T "this is a long ~
           string")                      ; prints  this is a long string

Supported format directives: The 'format' string in XLISP supports the following format directives:

~A	-	ASCII, prints the 'expr'. If it is a string print it without quotes. This is like the princ function.
~S	-	s-expr, prints the 'expr'. If it is a string print it with quotes. This is like the prin1 function.
~%	-	prints a 'newline' control character.
~~	-	prints a single tilde '~' character.
~<newline>	-	continue the 'format' string on the next line. This signals a line break in the format. The 'format' function will ignore all white-space [blanks, tabs, newlines]. This is useful when the 'format' string is longer than a program line. Note that the 'newline' character must immediately follow the tilde character.

Common Lisp: The 'format' function in Common Lisp is quite impressive. It includes 26 different formatting directives. XLISP, as shown above, does not include most of these. The more difficult ones that you might encounter are the decimal, octal, hexidecimal, fixed-format floating-point and exponential floating-point. It is possible to print in octal and hexadecimal notation by setting *integer-format*. It is possible to print in fixed format and exponential by setting *float-format*. However, neither of these system variables are supported in Common Lisp and neither gives control over field size.

See the format function in the XLISP 2.0 manual.

  Back to Top