Outputting messages or other texts which are composed of literal
strings, variable contents, newlines and other formatting can be
cumbersome, when only the standard procedures like
newline are available. Additionally, one
often wants to collect the output in strings. With the standard
routines, the user is required to set up a string port, add this port
as a parameter to the output procedure calls and then retrieve the
resulting string from the string port.
format procedure, to be found in module
format), can do all this, and even more. If you are a C programmer,
you can think of this procedure as Guile's
The second parameter is the format string. It has a similar function
to the format string in calls to
fprintf in C.
It is output to the specified destination, but all escape sequences
are replaced by the results of formatting the corresponding sequence.
Note that escape sequences are marked with the character
(tilde), and not with a
% (percent sign), as in C.
The escape sequences in the following table are supported. When there
appears "corresponding arg', that means any of the additional
arguments, after dropping all arguments which have been used up by
escape sequences which have been processed earlier. Some of the
format characters (the characters following the tilde) can be prefixed
:@, to modify the behaviour of the
format character. How the modified behaviour differs from the default
behaviour is described for every character in the table where
ten. If prefixed with
tenthis printed, if prefixed with
:@, Roman numbers are printed.
~e, whichever produces less characters to be written.
~f, but only with two digits after the decimal point.
@, it is printed like with
write. If prefixed with
:, control characters are treated specially, for example
#\newlinewill be printed as
yif prefixed with
sis printed (or
iesif prefixed with
:, jump backwards in the argument list, if prefixed by
:@, jump to the parameter with the absolute index, otherwise jump forward in the argument list.
:, the following output string will be capitalized, if prefixed by
@, the first character will be capitalized, if prefixed by
:@it will be upcased and otherwise it will be downcased. Conversion stops when the "Case conversion end"
~)sequence is encountered.
~0 ... ~9, ~-, ~+
If any type conversions should fail (for example when using an escape sequence for number output, but the argument is a string), an error will be signalled.
You may have noticed that Guile contains a
even when the module
(ice-9 format) is not loaded. The default
format procedure does not support all escape sequences
documented in this chapter, and will signal an error if you try to use
one of them. The reason for providing two versions of
is that the full-featured module is fairly large and requires some
time to get loaded. So the Guile maintainers decided not to load the
large version of
format by default, so that the start-up time
of the interpreter is not unnecessarily increased.
Go to the first, previous, next, last section, table of contents.