[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.18.7 Output

For the following procedures, the optional port argument must be an output port, and when omitted, the current output port is assumed.

Function: write obj &optional port

Function: display obj &optional port

Function: print expr ...
Displays exprs (using display) to the current output port, then writes a newline.

Method: write-object (obj <object>) port
You can customize how the object is printed out by this method.

Function: newline &optional port
[R5RS] Writes a newline character to port

Function: flush &optional port
Function: flush-all-ports
Output the buffered data in port, or all ports, respectively.

The function "flush" is called in variety of ways on the various Scheme implementations: force-output (Scsh, SCM), flush-output (Gambit), or flush-output-port (Bigloo). The name flush is taken from STk and STklos.

Function: write-char char &optional port
[R5RS] Write a single character char to the output port port.

Function: write-byte byte &optional port
Write a byte byte to the port. byte must be an exact integer in range between 0 and 255.

Function: write* obj &optional port

Function: format port string arg ...
Function: format string arg ...
[SRFI-28+] Format arg ... according to string. This function is a subset of CommonLisp's format function, with a bit of extension. It is also a superset of SRFi-28, Basic format strings (SRFI-28).

port specifies the destination; if it is an output port, the formatted result is written to it; if it is #t, the result is written to the current output port; if it is #f, the formatted result is returned as a string. Port can be omitted, as SRFI-28 format; it has the same effects as giving #f to the port.

string is a string that contains format directives. A format directive is a character sequence begins with tilda, `~', and ends with some specific characters. A format directive takes the corresponding arg and formats it. The rest of string is copied to the output as is.

(format #f "the answer is ~s" 42)
  => "the answer is 42"

The format directive can take one or more parameters, separated by comma characters. A parameter may be an integer or a character; if it is a character, it should be preceded by a quote character. Parameter can be omitted, in such case the system default value is used. The interpretation of the parameters depends on the format directive.

Furthermore, a format directive can take two additional flags: atmark `@' and colon `:'. One or both of them may modify the behavior of the format directive. Those flags must be placed immediately before the directive character.

If a character `v' or `V' is in the place of the parameter, the value of the parameter is taken from the format's argument. The argument must be either an integer, a character, or #f (indicating that the parameter is effectively omitted).

Some examples:

A format directive ~s, with two parameters, 10 and 2.
A format directive ~a, with 12 for the first parameter and a character `*' for the fourth parameter. The second and third parameters are omitted.
A format directive ~d, with 10 for the first parameter and `@' flag.
A format directive ~x, whose first and second parameter will be taken from the arguments.

The following is a complete list of the supported format directives. Either upper case or lower case character can be used for the format directive; usually they have no distinction, except noted.

Ascii output. The corresponding argument is printed by display. If an integer mincol is given, it specifies the minimum number of characters to be output; if the formatted result is shorter than mincol, a whitespace is padded to the right (i.e. the result is left justified).

The colinc, minpad and padchar parameters control, if given, further padding. A character padchar replaces the padding character for the whitespace. If an integer minpad is given and greater than 0, at least minpad padding character is used, regardless of the resulting width. If an integer colinc is given, the padding character is added (after minpad) in chunk of colinc characters, until the entire width exceeds mincol.

If atmark-flag is given, the format result is right justified, i.e. padding is added to the left.

The maxcol parameter, if given, limits the maximum number of characters to be written. If the length of formatted string exceeds maxcol, only maxcol characters are written. If colon-flag is given as well and the length of formatted string exceeds maxcol, maxcol - 4 characters are written and a string " ..." is attached after it.

(format #f "|~a|" "oops")
  => "|oops|"
(format #f "|~10a|" "oops")
  => "|oops      |"
(format #f "|~10@a|" "oops")
  => "|      oops|"
(format #f "|~10,,,'*@a|" "oops")
  => "|******oops|"

(format #f "|~,,,,10a|" '(abc def ghi jkl)
  => "|(abc def gh|" 
(format #f "|~,,,,10:a|" '(abc def ghi jkl)
  => "|(abc de ...|" 

S-expression output. The corresponding argument is printed by write. The semantics of parameters and flags are the same as ~A directive.

(format #f "|~s|" "oops")
  => "|\"oops\"|"
(format #f "|~10s|" "oops")
  => "|\"oops\"    |"
(format #f "|~10@s|" "oops")
  => "|    \"oops\"|"
(format #f "|~10,,,'*@s|" "oops")
  => "|****\"oops\"|"

Decimal output. The argument is formatted as an decimal integer. If the argument is not an integer, all parameters are ignored (after processing `v' parameters) and it is formatted by ~A directive.

If an integer parameter mincol is given, it specifies minimum width of the formatted result; if the result is shorter than it, padchar is padded on the left (i.e. the result is right justified). The default of padchar is a whitespace.

(format #f "|~d|" 12345)
  => "|12345|"
(format #f "|~10d|" 12345)
  => "|     12345|"
(format #f "|~10,'0d|" 12345)
  => "|0000012345|"

If atmark-flag is given, the sign `+' is printed for the positive argument.

If colon-flag is given, every interval-th digit of the result is grouped and commachar is inserted between them. The default of commachar is `,', and the default of interval is 3.

(format #f "|~:d|" 12345)
  => "|12,345|"
(format #f "|~,,'_,4:d|" -12345678)
  => "|-1234_5678|"

Binary output. The argument is formatted as a binary integer. The semantics of parameters and flags are the same as the ~D directive.

Octal output. The argument is formatted as an octal integer. The semantics of parameters and flags are the same as the ~D directive.

Hexadecimal output. The argument is formatted as a hexadecimal integer. If `X' is used, upper case alphabets are used for the digits larger than 10. If `x' is used, lower case alphabets are used. The semantics of parameters and flags are the same as the ~D directive.

(format #f "~8,'0x" 259847592)
  => "0f7cf5a8"
(format #f "~8,'0X" 259847592)
  => "0F7CF5A8"

Moves the argument counter count times forward, effectively skips next count arguments. The default value of count is 1, hence skip the next argument. If a colon-flag is given, moves the argument counter backwards, e.g. ~:* makes the next directive to process last argument again. If an atmark-flag is given, count specifies absolute position of the arguments, starting from 0.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ken Dickey on November, 28 2002 using texi2html