1029 lines
45 KiB
HTML
1029 lines
45 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<!-- This manual documents Guile version 3.0.10.
|
||
|
|
|
||
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
||
|
|
Inc.
|
||
|
|
|
||
|
|
Copyright (C) 2021 Maxime Devos
|
||
|
|
|
||
|
|
Copyright (C) 2024 Tomas Volf
|
||
|
|
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with no
|
||
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
||
|
|
copy of the license is included in the section entitled "GNU Free
|
||
|
|
Documentation License." -->
|
||
|
|
<title>Formatted Output (Guile Reference Manual)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Formatted Output (Guile Reference Manual)">
|
||
|
|
<meta name="keywords" content="Formatted Output (Guile Reference Manual)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content=".texi2any-real">
|
||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
|
|
||
|
|
<link href="index.html" rel="start" title="Top">
|
||
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Guile-Modules.html" rel="up" title="Guile Modules">
|
||
|
|
<link href="File-Tree-Walk.html" rel="next" title="File Tree Walk">
|
||
|
|
<link href="Pretty-Printing.html" rel="prev" title="Pretty Printing">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
span:hover a.copiable-link {visibility: visible}
|
||
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
||
|
|
ul.mark-none {list-style-type: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<div class="section-level-extent" id="Formatted-Output">
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="File-Tree-Walk.html" accesskey="n" rel="next">File Tree Walk</a>, Previous: <a href="Pretty-Printing.html" accesskey="p" rel="prev">Pretty Printing</a>, Up: <a href="Guile-Modules.html" accesskey="u" rel="up">Guile Modules</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<h3 class="section" id="Formatted-Output-1"><span>7.11 Formatted Output<a class="copiable-link" href="#Formatted-Output-1"> ¶</a></span></h3>
|
||
|
|
<a class="index-entry-id" id="index-formatted-output"></a>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The <code class="code">format</code> function is a powerful way to print numbers, strings
|
||
|
|
and other objects together with literal text under the control of a
|
||
|
|
format string. This function is available from
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(use-modules (ice-9 format))
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>A format string is generally more compact and easier than using just
|
||
|
|
the standard procedures like <code class="code">display</code>, <code class="code">write</code> and
|
||
|
|
<code class="code">newline</code>. Parameters in the output string allow various output
|
||
|
|
styles, and parameters can be taken from the arguments for runtime
|
||
|
|
flexibility.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">format</code> is similar to the Common Lisp procedure of the same
|
||
|
|
name, but it’s not identical and doesn’t have quite all the features
|
||
|
|
found in Common Lisp.
|
||
|
|
</p>
|
||
|
|
<p>C programmers will note the similarity between <code class="code">format</code> and
|
||
|
|
<code class="code">printf</code>, though escape sequences are marked with <code class="code">~</code>
|
||
|
|
instead of <code class="code">%</code>, and are more powerful.
|
||
|
|
</p>
|
||
|
|
<br>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-format-1"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">format</strong> <var class="def-var-arguments">dest fmt arg …</var><a class="copiable-link" href="#index-format-1"> ¶</a></span></dt>
|
||
|
|
<dd><p>Write output specified by the <var class="var">fmt</var> string to <var class="var">dest</var>.
|
||
|
|
<var class="var">dest</var> can be an output port, <code class="code">#t</code> for
|
||
|
|
<code class="code">current-output-port</code> (see <a class="pxref" href="Default-Ports.html">Default Ports for Input, Output and Errors</a>), or <code class="code">#f</code> to
|
||
|
|
return the output as a string.
|
||
|
|
</p>
|
||
|
|
<p><var class="var">fmt</var> can contain literal text to be output, and <code class="code">~</code>
|
||
|
|
escapes. Each escape has the form
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">~ [param [, param...] [:] [@] code
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">code</code> is a character determining the escape sequence. The
|
||
|
|
<code class="code">:</code> and <code class="code">@</code> characters are optional modifiers, one or
|
||
|
|
both of which change the way various codes operate. Optional
|
||
|
|
parameters are accepted by some codes too. Parameters have the
|
||
|
|
following forms,
|
||
|
|
</p>
|
||
|
|
<dl class="table">
|
||
|
|
<dt><code class="code">[+/-]number</code></dt>
|
||
|
|
<dd><p>An integer, with optional <code class="code">+</code> or <code class="code">-</code>.
|
||
|
|
</p></dd>
|
||
|
|
<dt><code class="code">'</code> (apostrophe)</dt>
|
||
|
|
<dd><p>The following character in the format string, for instance <code class="code">'z</code>
|
||
|
|
for <code class="code">z</code>.
|
||
|
|
</p></dd>
|
||
|
|
<dt><code class="code">v</code></dt>
|
||
|
|
<dd><p>The next function argument as the parameter. <code class="code">v</code> stands for
|
||
|
|
“variable”, a parameter can be calculated at runtime and included in
|
||
|
|
the arguments. Upper case <code class="code">V</code> can be used too.
|
||
|
|
</p></dd>
|
||
|
|
<dt><code class="code">#</code></dt>
|
||
|
|
<dd><p>The number of arguments remaining. (See <code class="code">~*</code> below for some
|
||
|
|
usages.)
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Parameters are separated by commas (<code class="code">,</code>). A parameter can be
|
||
|
|
left empty to keep its default value when supplying later parameters.
|
||
|
|
</p>
|
||
|
|
<br>
|
||
|
|
<p>The following escapes are available. The code letters are not
|
||
|
|
case-sensitive, upper and lower case are the same.
|
||
|
|
</p>
|
||
|
|
<dl class="table">
|
||
|
|
<dt><code class="code">~a</code></dt>
|
||
|
|
<dt><code class="code">~s</code></dt>
|
||
|
|
<dd><p>Object output. Parameters: <var class="var">minwidth</var>, <var class="var">padinc</var>,
|
||
|
|
<var class="var">minpad</var>, <var class="var">padchar</var>.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">~a</code> outputs an argument like <code class="code">display</code>, <code class="code">~s</code>
|
||
|
|
outputs an argument like <code class="code">write</code> (see <a class="pxref" href="Scheme-Write.html">Writing Scheme Values</a>).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~a" "foo") -| foo
|
||
|
|
(format #t "~s" "foo") -| "foo"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~:a</code> and <code class="code">~:s</code> put objects that don’t have an external
|
||
|
|
representation in quotes like a string.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~:a" car) -| "#<primitive-procedure car>"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the output is less than <var class="var">minwidth</var> characters (default 0), it’s
|
||
|
|
padded on the right with <var class="var">padchar</var> (default space). <code class="code">~@a</code>
|
||
|
|
and <code class="code">~@s</code> put the padding on the left instead.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~5a" 'abc) ⇒ "abc "
|
||
|
|
(format #f "~5,,,'-@a" 'abc) ⇒ "--abc"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var class="var">minpad</var> is a minimum for the padding then plus a multiple of
|
||
|
|
<var class="var">padinc</var>. Ie. the padding is <em class="math"><var class="var">minpad</var> + <var class="var">N</var> *
|
||
|
|
<var class="var">padinc</var></em>, where <var class="var">n</var> is the smallest integer making the total
|
||
|
|
object plus padding greater than or equal to <var class="var">minwidth</var>. The
|
||
|
|
default <var class="var">minpad</var> is 0 and the default <var class="var">padinc</var> is 1 (imposing
|
||
|
|
no minimum or multiple).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~5,1,4a" 'abc) ⇒ "abc "
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~c</code></dt>
|
||
|
|
<dd><p>Character. Parameter: <var class="var">charnum</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a character. The default is to simply output, as per
|
||
|
|
<code class="code">write-char</code> (see <a class="pxref" href="Venerable-Port-Interfaces.html">Venerable Port Interfaces</a>). <code class="code">~@c</code>
|
||
|
|
prints in <code class="code">write</code> style. <code class="code">~:c</code> prints control characters
|
||
|
|
(ASCII 0 to 31) in <code class="code">^X</code> form.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~c" #\z) -| z
|
||
|
|
(format #t "~@c" #\z) -| #\z
|
||
|
|
(format #t "~:c" #\newline) -| ^J
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the <var class="var">charnum</var> parameter is given then an argument is not taken
|
||
|
|
but instead the character is <code class="code">(integer->char <var class="var">charnum</var>)</code>
|
||
|
|
(see <a class="pxref" href="Characters.html">Characters</a>). This can be used for instance to output
|
||
|
|
characters given by their ASCII code.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~65c") -| A
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~d</code></dt>
|
||
|
|
<dt><code class="code">~x</code></dt>
|
||
|
|
<dt><code class="code">~o</code></dt>
|
||
|
|
<dt><code class="code">~b</code></dt>
|
||
|
|
<dd><p>Integer. Parameters: <var class="var">minwidth</var>, <var class="var">padchar</var>, <var class="var">commachar</var>,
|
||
|
|
<var class="var">commawidth</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output an integer argument as a decimal, hexadecimal, octal or binary
|
||
|
|
integer (respectively), in a locale-independent way.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~d" 123) -| 123
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@d</code> etc shows a <code class="code">+</code> sign is shown on positive
|
||
|
|
numbers.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~@b" 12) -| +1100
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the output is less than the <var class="var">minwidth</var> parameter (default no
|
||
|
|
minimum), it’s padded on the left with the <var class="var">padchar</var> parameter
|
||
|
|
(default space).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~5,'*d" 12) -| ***12
|
||
|
|
(format #t "~5,'0d" 12) -| 00012
|
||
|
|
(format #t "~3d" 1234) -| 1234
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~:d</code> adds commas (or the <var class="var">commachar</var> parameter) every
|
||
|
|
three digits (or the <var class="var">commawidth</var> parameter many). However, when
|
||
|
|
your intent is to write numbers in a way that follows typographical
|
||
|
|
conventions, using <code class="code">~h</code> is recommended.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~:d" 1234567) -| 1,234,567
|
||
|
|
(format #t "~10,'*,'/,2:d" 12345) -| ***1/23/45
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Hexadecimal <code class="code">~x</code> output is in lower case, but the <code class="code">~(</code>
|
||
|
|
and <code class="code">~)</code> case conversion directives described below can be used
|
||
|
|
to get upper case.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~x" 65261) -| feed
|
||
|
|
(format #t "~:@(~x~)" 65261) -| FEED
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~r</code></dt>
|
||
|
|
<dd><p>Integer in words, roman numerals, or a specified radix. Parameters:
|
||
|
|
<var class="var">radix</var>, <var class="var">minwidth</var>, <var class="var">padchar</var>, <var class="var">commachar</var>,
|
||
|
|
<var class="var">commawidth</var>.
|
||
|
|
</p>
|
||
|
|
<p>With no parameters output is in words as a cardinal like “ten”, or
|
||
|
|
<code class="code">~:r</code> prints an ordinal like “tenth”.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~r" 9) -| nine ;; cardinal
|
||
|
|
(format #t "~r" -9) -| minus nine ;; cardinal
|
||
|
|
(format #t "~:r" 9) -| ninth ;; ordinal
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>And also with no parameters, <code class="code">~@r</code> gives roman numerals and
|
||
|
|
<code class="code">~:@r</code> gives old roman numerals. In old roman numerals
|
||
|
|
there’s no “subtraction”, so 9 is <code class="code">VIIII</code> instead of
|
||
|
|
<code class="code">IX</code>. In both cases only positive numbers can be output.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~@r" 89) -| LXXXIX ;; roman
|
||
|
|
(format #t "~:@r" 89) -| LXXXVIIII ;; old roman
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>When a parameter is given it means numeric output in the specified
|
||
|
|
<var class="var">radix</var>. The modifiers and parameters following the radix are the
|
||
|
|
same as described for <code class="code">~d</code> etc above.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~3r" 27) ⇒ "1000" ;; base 3
|
||
|
|
(format #f "~3,5r" 26) ⇒ " 222" ;; base 3 width 5
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~f</code></dt>
|
||
|
|
<dd><p>Fixed-point float. Parameters: <var class="var">width</var>, <var class="var">decimals</var>,
|
||
|
|
<var class="var">scale</var>, <var class="var">overflowchar</var>, <var class="var">padchar</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a number or number string in fixed-point format, ie. with a
|
||
|
|
decimal point.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~f" 5) -| 5.0
|
||
|
|
(format #t "~f" "123") -| 123.0
|
||
|
|
(format #t "~f" "1e-1") -| 0.1
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@f</code> prints a <code class="code">+</code> sign on positive numbers (including
|
||
|
|
zero).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~@f" 0) -| +0.0
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the output is less than <var class="var">width</var> characters it’s padded on the
|
||
|
|
left with <var class="var">padchar</var> (space by default). If the output equals or
|
||
|
|
exceeds <var class="var">width</var> then there’s no padding. The default for
|
||
|
|
<var class="var">width</var> is no padding.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~6f" -1.5) ⇒ " -1.5"
|
||
|
|
(format #f "~6,,,,'*f" 23) ⇒ "**23.0"
|
||
|
|
(format #f "~6f" 1234567.0) ⇒ "1234567.0"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var class="var">decimals</var> is how many digits to print after the decimal point,
|
||
|
|
with the value rounded or padded with zeros as necessary. (The
|
||
|
|
default is to output as many decimals as required.)
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~1,2f" 3.125) -| 3.13
|
||
|
|
(format #t "~1,2f" 1.5) -| 1.50
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var class="var">scale</var> is a power of 10 applied to the value, moving the decimal
|
||
|
|
point that many places. A positive <var class="var">scale</var> increases the value
|
||
|
|
shown, a negative decreases it.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~,,2f" 1234) -| 123400.0
|
||
|
|
(format #t "~,,-2f" 1234) -| 12.34
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If <var class="var">overflowchar</var> and <var class="var">width</var> are both given and if the output
|
||
|
|
would exceed <var class="var">width</var>, then that many <var class="var">overflowchar</var>s are
|
||
|
|
printed instead of the value.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~6,,,'xf" 12345) -| 12345.
|
||
|
|
(format #t "~5,,,'xf" 12345) -| xxxxx
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~h</code></dt>
|
||
|
|
<dd><p>Localized number<a class="footnote" id="DOCF27" href="#FOOT27"><sup>27</sup></a>. Parameters: <var class="var">width</var>,
|
||
|
|
<var class="var">decimals</var>, <var class="var">padchar</var>.
|
||
|
|
</p>
|
||
|
|
<p>Like <code class="code">~f</code>, output an exact or floating point number, but do so
|
||
|
|
according to the current locale, or according to the given locale object
|
||
|
|
when the <code class="code">:</code> modifier is used (see <a class="pxref" href="Number-Input-and-Output.html"><code class="code">number->locale-string</code></a>).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~h" 12345.5678) ; with "C" as the current locale
|
||
|
|
-| 12345.5678
|
||
|
|
|
||
|
|
(format #t "~14,,'*:h" 12345.5678
|
||
|
|
(make-locale LC_ALL "en_US"))
|
||
|
|
-| ***12,345.5678
|
||
|
|
|
||
|
|
(format #t "~,2:h" 12345.5678
|
||
|
|
(make-locale LC_NUMERIC "fr_FR"))
|
||
|
|
-| 12 345,56
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~e</code></dt>
|
||
|
|
<dd><p>Exponential float. Parameters: <var class="var">width</var>, <var class="var">mantdigits</var>,
|
||
|
|
<var class="var">expdigits</var>, <var class="var">intdigits</var>, <var class="var">overflowchar</var>, <var class="var">padchar</var>,
|
||
|
|
<var class="var">expchar</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a number or number string in exponential notation.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~e" 5000.25) -| 5.00025E+3
|
||
|
|
(format #t "~e" "123.4") -| 1.234E+2
|
||
|
|
(format #t "~e" "1e4") -| 1.0E+4
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@e</code> prints a <code class="code">+</code> sign on positive numbers (including
|
||
|
|
zero). (This is for the mantissa, a <code class="code">+</code> or <code class="code">-</code> sign is
|
||
|
|
always shown on the exponent.)
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~@e" 5000.0) -| +5.0E+3
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the output is less than <var class="var">width</var> characters it’s padded on the
|
||
|
|
left with <var class="var">padchar</var> (space by default). The default for
|
||
|
|
<var class="var">width</var> is to output with no padding.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~10e" 1234.0) ⇒ " 1.234E+3"
|
||
|
|
(format #f "~10,,,,,'*e" 0.5) ⇒ "****5.0E-1"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
|
||
|
|
<p><var class="var">mantdigits</var> is the number of digits shown in the mantissa after
|
||
|
|
the decimal point. The value is rounded or trailing zeros are added
|
||
|
|
as necessary. The default <var class="var">mantdigits</var> is to show as much as
|
||
|
|
needed by the value.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~,3e" 11111.0) ⇒ "1.111E+4"
|
||
|
|
(format #f "~,8e" 123.0) ⇒ "1.23000000E+2"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var class="var">expdigits</var> is the minimum number of digits shown for the
|
||
|
|
exponent, with leading zeros added if necessary. The default for
|
||
|
|
<var class="var">expdigits</var> is to show only as many digits as required. At least
|
||
|
|
1 digit is always shown.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~,,1e" 1.0e99) ⇒ "1.0E+99"
|
||
|
|
(format #f "~,,6e" 1.0e99) ⇒ "1.0E+000099"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var class="var">intdigits</var> (default 1) is the number of digits to show before the
|
||
|
|
decimal point in the mantissa. <var class="var">intdigits</var> can be zero, in which
|
||
|
|
case the integer part is a single <code class="code">0</code>, or it can be negative,
|
||
|
|
in which case leading zeros are shown after the decimal point.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~,,,3e" 12345.0) -| 123.45E+2
|
||
|
|
(format #t "~,,,0e" 12345.0) -| 0.12345E+5
|
||
|
|
(format #t "~,,,-3e" 12345.0) -| 0.00012345E+8
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
|
||
|
|
<p>If <var class="var">overflowchar</var> is given then <var class="var">width</var> is a hard limit. If
|
||
|
|
the output would exceed <var class="var">width</var> then instead that many
|
||
|
|
<var class="var">overflowchar</var>s are printed.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~6,,,,'xe" 100.0) ⇒ "1.0E+2"
|
||
|
|
(format #f "~3,,,,'xe" 100.0) ⇒ "xxx"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var class="var">expchar</var> is the exponent marker character (default <code class="code">E</code>).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~,,,,,,'ee" 100.0) -| 1.0e+2
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~g</code></dt>
|
||
|
|
<dd><p>General float. Parameters: <var class="var">width</var>, <var class="var">mantdigits</var>,
|
||
|
|
<var class="var">expdigits</var>, <var class="var">intdigits</var>, <var class="var">overflowchar</var>, <var class="var">padchar</var>,
|
||
|
|
<var class="var">expchar</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a number or number string in either exponential format the same
|
||
|
|
as <code class="code">~e</code>, or fixed-point format like <code class="code">~f</code> but aligned
|
||
|
|
where the mantissa would have been and followed by padding where the
|
||
|
|
exponent would have been.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>Fixed-point is used when the absolute value is 0.1 or more and it
|
||
|
|
takes no more space than the mantissa in exponential format, ie.
|
||
|
|
basically up to <var class="var">mantdigits</var> digits.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~12,4,2g" 999.0) ⇒ " 999.0 "
|
||
|
|
(format #f "~12,4,2g" "100000") ⇒ " 1.0000E+05"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The parameters are interpreted as per <code class="code">~e</code> above. When
|
||
|
|
fixed-point is used, the <var class="var">decimals</var> parameter to <code class="code">~f</code> is
|
||
|
|
established from <var class="var">mantdigits</var>, so as to give a total
|
||
|
|
<em class="math"><var class="var">mantdigits</var>+1</em> figures.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~$</code></dt>
|
||
|
|
<dd><p>Monetary style fixed-point float. Parameters: <var class="var">decimals</var>,
|
||
|
|
<var class="var">intdigits</var>, <var class="var">width</var>, <var class="var">padchar</var>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>Output a number or number string in fixed-point format, ie. with a
|
||
|
|
decimal point. <var class="var">decimals</var> is the number of decimal places to
|
||
|
|
show, default 2.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~$" 5) -| 5.00
|
||
|
|
(format #t "~4$" "2.25") -| 2.2500
|
||
|
|
(format #t "~4$" "1e-2") -| 0.0100
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@$</code> prints a <code class="code">+</code> sign on positive numbers (including
|
||
|
|
zero).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~@$" 0) -| +0.00
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var class="var">intdigits</var> is a minimum number of digits to show in the integer
|
||
|
|
part of the value (default 1).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~,3$" 9.5) -| 009.50
|
||
|
|
(format #t "~,0$" 0.125) -| .13
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the output is less than <var class="var">width</var> characters (default 0), it’s
|
||
|
|
padded on the left with <var class="var">padchar</var> (default space). <code class="code">~:$</code>
|
||
|
|
puts the padding after the sign.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~,,8$" -1.5) ⇒ " -1.50"
|
||
|
|
(format #f "~,,8:$" -1.5) ⇒ "- 1.50"
|
||
|
|
(format #f "~,,8,'.:@$" 3) ⇒ "+...3.00"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Note that floating point for dollar amounts is generally not a good
|
||
|
|
idea, because a cent <em class="math">0.01</em> cannot be represented exactly in the
|
||
|
|
binary floating point Guile uses, which leads to slowly accumulating
|
||
|
|
rounding errors. Keeping values as cents (or fractions of a cent) in
|
||
|
|
integers then printing with the scale option in <code class="code">~f</code> may be a
|
||
|
|
better approach.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~i</code></dt>
|
||
|
|
<dd><p>Complex fixed-point float. Parameters: <var class="var">width</var>, <var class="var">decimals</var>,
|
||
|
|
<var class="var">scale</var>, <var class="var">overflowchar</var>, <var class="var">padchar</var>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>Output the argument as a complex number, with both real and imaginary
|
||
|
|
part shown (even if one or both are zero).
|
||
|
|
</p>
|
||
|
|
<p>The parameters and modifiers are the same as for fixed-point
|
||
|
|
<code class="code">~f</code> described above. The real and imaginary parts are both
|
||
|
|
output with the same given parameters and modifiers, except that for
|
||
|
|
the imaginary part the <code class="code">@</code> modifier is always enabled, so as
|
||
|
|
to print a <code class="code">+</code> sign between the real and imaginary parts.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~i" 1) -| 1.0+0.0i
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~p</code></dt>
|
||
|
|
<dd><p>Plural. No parameters.
|
||
|
|
</p>
|
||
|
|
<p>Output nothing if the argument is 1, or ‘<samp class="samp">s</samp>’ for any other
|
||
|
|
value.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "enter name~p" 1) -| enter name
|
||
|
|
(format #t "enter name~p" 2) -| enter names
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@p</code> prints ‘<samp class="samp">y</samp>’ for 1 or ‘<samp class="samp">ies</samp>’ otherwise.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "pupp~@p" 1) -| puppy
|
||
|
|
(format #t "pupp~@p" 2) -| puppies
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~:p</code> re-uses the preceding argument instead of taking a new
|
||
|
|
one, which can be convenient when printing some sort of count.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~d cat~:p" 9) -| 9 cats
|
||
|
|
(format #t "~d pupp~:@p" 5) -| 5 puppies
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~p</code> is designed for English plurals and there’s no attempt to
|
||
|
|
support other languages. <code class="code">~[</code> conditionals (below) may be able
|
||
|
|
to help. When using <code class="code">gettext</code> to translate messages
|
||
|
|
<code class="code">ngettext</code> is probably best though
|
||
|
|
(see <a class="pxref" href="Internationalization.html">Support for Internationalization</a>).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~y</code></dt>
|
||
|
|
<dd><p>Structured printing. Parameters: <var class="var">width</var>.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">~y</code> outputs an argument using <code class="code">pretty-print</code>
|
||
|
|
(see <a class="pxref" href="Pretty-Printing.html">Pretty Printing</a>). The result will be formatted to fit within
|
||
|
|
<var class="var">width</var> columns (79 by default), consuming multiple lines if
|
||
|
|
necessary.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">~@y</code> outputs an argument using <code class="code">truncated-print</code>
|
||
|
|
(see <a class="pxref" href="Pretty-Printing.html">Pretty Printing</a>). The resulting code will be formatted to fit
|
||
|
|
within <var class="var">width</var> columns (79 by default), on a single line. The
|
||
|
|
output will be truncated if necessary.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">~:@y</code> is like <code class="code">~@y</code>, except the <var class="var">width</var> parameter
|
||
|
|
is interpreted to be the maximum column to which to output. That is to
|
||
|
|
say, if you are at column 10, and <code class="code">~60:@y</code> is seen, the datum
|
||
|
|
will be truncated to 50 columns.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~?</code></dt>
|
||
|
|
<dt><code class="code">~k</code></dt>
|
||
|
|
<dd><p>Sub-format. No parameters.
|
||
|
|
</p>
|
||
|
|
<p>Take a format string argument and a second argument which is a list of
|
||
|
|
arguments for that string, and output the result.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~?" "~d ~d" '(1 2)) -| 1 2
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@?</code> takes arguments for the sub-format directly rather than
|
||
|
|
in a list.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~@? ~s" "~d ~d" 1 2 "foo") -| 1 2 "foo"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~?</code> and <code class="code">~k</code> are the same, <code class="code">~k</code> is provided for
|
||
|
|
T-Scheme compatibility.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~*</code></dt>
|
||
|
|
<dd><p>Argument jumping. Parameter: <var class="var">N</var>.
|
||
|
|
</p>
|
||
|
|
<p>Move forward <var class="var">N</var> arguments (default 1) in the argument list.
|
||
|
|
<code class="code">~:*</code> moves backwards. (<var class="var">N</var> cannot be negative.)
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~d ~2*~d" 1 2 3 4) ⇒ "1 4"
|
||
|
|
(format #f "~d ~:*~d" 6) ⇒ "6 6"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@*</code> moves to argument number <var class="var">N</var>. The first argument is
|
||
|
|
number 0 (and that’s the default for <var class="var">N</var>).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~d~d again ~@*~d~d" 1 2) ⇒ "12 again 12"
|
||
|
|
(format #f "~d~d~d ~1@*~d~d" 1 2 3) ⇒ "123 23"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>A <code class="code">#</code> move to the end followed by a <code class="code">:</code> modifier move
|
||
|
|
back can be used for an absolute position relative to the end of the
|
||
|
|
argument list, a reverse of what the <code class="code">@</code> modifier does.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~#*~2:*~a" 'a 'b 'c 'd) -| c
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>At the end of the format string the current argument position doesn’t
|
||
|
|
matter, any further arguments are ignored.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~t</code></dt>
|
||
|
|
<dd><p>Advance to a column position. Parameters: <var class="var">colnum</var>, <var class="var">colinc</var>,
|
||
|
|
<var class="var">padchar</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output <var class="var">padchar</var> (space by default) to move to the given
|
||
|
|
<var class="var">colnum</var> column. The start of the line is column 0, the default
|
||
|
|
for <var class="var">colnum</var> is 1.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~tX") ⇒ " X"
|
||
|
|
(format #f "~3tX") ⇒ " X"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the current column is already past <var class="var">colnum</var>, then the move is
|
||
|
|
to there plus a multiple of <var class="var">colinc</var>, ie. column
|
||
|
|
<em class="math"><var class="var">colnum</var> + <var class="var">N</var> * <var class="var">colinc</var></em> for the smallest <var class="var">N</var>
|
||
|
|
which makes that value greater than or equal to the current column.
|
||
|
|
The default <var class="var">colinc</var> is 1 (which means no further move).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "abcd~2,5,'.tx") ⇒ "abcd...x"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@t</code> takes <var class="var">colnum</var> as an offset from the current column.
|
||
|
|
<var class="var">colnum</var> many pad characters are output, then further padding to
|
||
|
|
make the current column a multiple of <var class="var">colinc</var>, if it isn’t
|
||
|
|
already so.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "a~3,5'*@tx") ⇒ "a****x"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~t</code> is implemented using <code class="code">port-column</code> (see <a class="pxref" href="Textual-I_002fO.html">Textual I/O</a>), so it works even there has been other output before
|
||
|
|
<code class="code">format</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~~</code></dt>
|
||
|
|
<dd><p>Tilde character. Parameter: <var class="var">n</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a tilde character <code class="code">~</code>, or <var class="var">n</var> many if a parameter is
|
||
|
|
given. Normally <code class="code">~</code> introduces an escape sequence, <code class="code">~~</code>
|
||
|
|
is the way to output a literal tilde.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~%</code></dt>
|
||
|
|
<dd><p>Newline. Parameter: <var class="var">n</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a newline character, or <var class="var">n</var> many if a parameter is given.
|
||
|
|
A newline (or a few newlines) can of course be output just by
|
||
|
|
including them in the format string.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~&</code></dt>
|
||
|
|
<dd><p>Start a new line. Parameter: <var class="var">n</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a newline if not already at the start of a line. With a
|
||
|
|
parameter, output that many newlines, but with the first only if not
|
||
|
|
already at the start of a line. So for instance 3 would be a newline
|
||
|
|
if not already at the start of a line, and 2 further newlines.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~_</code></dt>
|
||
|
|
<dd><p>Space character. Parameter: <var class="var">n</var>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>Output a space character, or <var class="var">n</var> many if a parameter is given.
|
||
|
|
</p>
|
||
|
|
<p>With a variable parameter this is one way to insert runtime calculated
|
||
|
|
padding (<code class="code">~t</code> or the various field widths can do similar
|
||
|
|
things).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~v_foo" 4) ⇒ " foo"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~/</code></dt>
|
||
|
|
<dd><p>Tab character. Parameter: <var class="var">n</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a tab character, or <var class="var">n</var> many if a parameter is given.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~|</code></dt>
|
||
|
|
<dd><p>Formfeed character. Parameter: <var class="var">n</var>.
|
||
|
|
</p>
|
||
|
|
<p>Output a formfeed character, or <var class="var">n</var> many if a parameter is given.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~!</code></dt>
|
||
|
|
<dd><p>Force output. No parameters.
|
||
|
|
</p>
|
||
|
|
<p>At the end of output, call <code class="code">force-output</code> to flush any buffers on
|
||
|
|
the destination (see <a class="pxref" href="Buffering.html">Buffering</a>). <code class="code">~!</code> can occur anywhere in
|
||
|
|
the format string, but the force is done at the end of output.
|
||
|
|
</p>
|
||
|
|
<p>When output is to a string (destination <code class="code">#f</code>), <code class="code">~!</code> does
|
||
|
|
nothing.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~newline</code> (ie. newline character)</dt>
|
||
|
|
<dd><p>Continuation line. No parameters.
|
||
|
|
</p>
|
||
|
|
<p>Skip this newline and any following whitespace in the format string,
|
||
|
|
ie. don’t send it to the output. This can be used to break up a
|
||
|
|
long format string for readability, but not print the extra
|
||
|
|
whitespace.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "abc~
|
||
|
|
~d def~
|
||
|
|
~d" 1 2) ⇒ "abc1 def2"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~:newline</code> skips the newline but leaves any further whitespace
|
||
|
|
to be printed normally.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">~@newline</code> prints the newline then skips following
|
||
|
|
whitespace.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~(</code> <code class="code">~)</code></dt>
|
||
|
|
<dd><p>Case conversion. No parameters.
|
||
|
|
</p>
|
||
|
|
<p>Between <code class="code">~(</code> and <code class="code">~)</code> the case of all output is changed.
|
||
|
|
The modifiers on <code class="code">~(</code> control the conversion.
|
||
|
|
</p>
|
||
|
|
<ul class="itemize mark-none">
|
||
|
|
<li><code class="code">~(</code> — lower case.
|
||
|
|
</li><li><code class="code">~:@(</code> — upper case.
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>For example,
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~(Hello~)") -| hello
|
||
|
|
(format #t "~:@(Hello~)") -| HELLO
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>In the future it’s intended the modifiers <code class="code">:</code> and <code class="code">@</code>
|
||
|
|
alone will capitalize the first letters of words, as per Common Lisp
|
||
|
|
<code class="code">format</code>, but the current implementation of this is flawed and
|
||
|
|
not recommended for use.
|
||
|
|
</p>
|
||
|
|
<p>Case conversions do not nest, currently. This might change in the
|
||
|
|
future, but if it does then it will be to Common Lisp style where the
|
||
|
|
outermost conversion has priority, overriding inner ones (making those
|
||
|
|
fairly pointless).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~{</code> <code class="code">~}</code></dt>
|
||
|
|
<dd><p>Iteration. Parameter: <var class="var">maxreps</var> (for <code class="code">~{</code>).
|
||
|
|
</p>
|
||
|
|
<p>The format between <code class="code">~{</code> and <code class="code">~}</code> is iterated. The
|
||
|
|
modifiers to <code class="code">~{</code> determine how arguments are taken. The
|
||
|
|
default is a list argument with each iteration successively consuming
|
||
|
|
elements from it. This is a convenient way to output a whole list.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~{~d~}" '(1 2 3)) -| 123
|
||
|
|
(format #t "~{~s=~d ~}" '("x" 1 "y" 2)) -| "x"=1 "y"=2
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~:{</code> takes a single argument which is a list of lists, each
|
||
|
|
of those contained lists gives the arguments for the iterated format.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~:{~dx~d ~}" '((1 2) (3 4) (5 6)))
|
||
|
|
-| 1x2 3x4 5x6
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@{</code> takes arguments directly, with each iteration
|
||
|
|
successively consuming arguments.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~@{~d~}" 1 2 3) -| 123
|
||
|
|
(format #t "~@{~s=~d ~}" "x" 1 "y" 2) -| "x"=1 "y"=2
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~:@{</code> takes list arguments, one argument for each iteration,
|
||
|
|
using that list for the format.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~:@{~dx~d ~}" '(1 2) '(3 4) '(5 6))
|
||
|
|
-| 1x2 3x4 5x6
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Iterating stops when there are no more arguments or when the
|
||
|
|
<var class="var">maxreps</var> parameter to <code class="code">~{</code> is reached (default no
|
||
|
|
maximum).
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~2{~d~}" '(1 2 3 4)) -| 12
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the format between <code class="code">~{</code> and <code class="code">~}</code> is empty, then a
|
||
|
|
format string argument is taken (before iteration argument(s)) and
|
||
|
|
used instead. This allows a sub-format (like <code class="code">~?</code> above) to be
|
||
|
|
iterated.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~{~}" "~d" '(1 2 3)) -| 123
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
|
||
|
|
<p>Iterations can be nested, an inner iteration operates in the same way
|
||
|
|
as described, but of course on the arguments the outer iteration
|
||
|
|
provides it. This can be used to work into nested list structures.
|
||
|
|
For example in the following the inner <code class="code">~{~d~}x</code> is applied
|
||
|
|
to <code class="code">(1 2)</code> then <code class="code">(3 4 5)</code> etc.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~{~{~d~}x~}" '((1 2) (3 4 5))) -| 12x345x
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>See also <code class="code">~^</code> below for escaping from iteration.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~[</code> <code class="code">~;</code> <code class="code">~]</code></dt>
|
||
|
|
<dd><p>Conditional. Parameter: <var class="var">selector</var>.
|
||
|
|
</p>
|
||
|
|
<p>A conditional block is delimited by <code class="code">~[</code> and <code class="code">~]</code>, and
|
||
|
|
<code class="code">~;</code> separates clauses within the block. <code class="code">~[</code> takes an
|
||
|
|
integer argument and that number clause is used. The first clause is
|
||
|
|
number 0.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~[peach~;banana~;mango~]" 1) ⇒ "banana"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The <var class="var">selector</var> parameter can be used for the clause number,
|
||
|
|
instead of taking an argument.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~2[peach~;banana~;mango~]") ⇒ "mango"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If the clause number is out of range then nothing is output. Or the
|
||
|
|
last clause can be <code class="code">~:;</code> to use that for a number out of range.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~[banana~;mango~]" 99) ⇒ ""
|
||
|
|
(format #f "~[banana~;mango~:;fruit~]" 99) ⇒ "fruit"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~:[</code> treats the argument as a flag, and expects two clauses.
|
||
|
|
The first is used if the argument is <code class="code">#f</code> or the second
|
||
|
|
otherwise.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~:[false~;not false~]" #f) ⇒ "false"
|
||
|
|
(format #f "~:[false~;not false~]" 'abc) ⇒ "not false"
|
||
|
|
|
||
|
|
(let ((n 3))
|
||
|
|
(format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
|
||
|
|
-| 3 gnus are here
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code class="code">~@[</code> also treats the argument as a flag, and expects one
|
||
|
|
clause. If the argument is <code class="code">#f</code> then no output is produced and
|
||
|
|
the argument is consumed, otherwise the clause is used and the
|
||
|
|
argument is not consumed, it’s left for the clause. This can be used
|
||
|
|
for instance to suppress output if <code class="code">#f</code> means something not
|
||
|
|
available.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~@[temperature=~d~]" 27) ⇒ "temperature=27"
|
||
|
|
(format #f "~@[temperature=~d~]" #f) ⇒ ""
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~^</code></dt>
|
||
|
|
<dd><p>Escape. Parameters: <var class="var">val1</var>, <var class="var">val2</var>, <var class="var">val3</var>.
|
||
|
|
</p>
|
||
|
|
<p>Stop formatting if there are no more arguments. This can be used for
|
||
|
|
instance to have a format string adapt to a variable number of
|
||
|
|
arguments.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~d~^ ~d" 1) -| 1
|
||
|
|
(format #t "~d~^ ~d" 1 2) -| 1 2
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Within a <code class="code">~{</code> <code class="code">~}</code> iteration, <code class="code">~^</code> stops the
|
||
|
|
current iteration step if there are no more arguments to that step,
|
||
|
|
but continuing with possible further steps and the rest of the format.
|
||
|
|
This can be used for instance to avoid a separator on the last
|
||
|
|
iteration, or to adapt to variable length argument lists.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #f "~{~d~^/~} go" '(1 2 3)) ⇒ "1/2/3 go"
|
||
|
|
(format #f "~:{ ~d~^~d~} go" '((1) (2 3))) ⇒ " 1 23 go"
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<p>Within a <code class="code">~?</code> sub-format, <code class="code">~^</code> operates just on that
|
||
|
|
sub-format. If it terminates the sub-format then the originating
|
||
|
|
format will still continue.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~? items" "~d~^ ~d" '(1)) -| 1 items
|
||
|
|
(format #t "~? items" "~d~^ ~d" '(1 2)) -| 1 2 items
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The parameters to <code class="code">~^</code> (which are numbers) change the condition
|
||
|
|
used to terminate. For a single parameter, termination is when that
|
||
|
|
value is zero (notice this makes plain <code class="code">~^</code> equivalent to
|
||
|
|
<code class="code">~#^</code>). For two parameters, termination is when those two are
|
||
|
|
equal. For three parameters, termination is when <em class="math"><var class="var">val1</var>
|
||
|
|
<= <var class="var">val2</var></em> and <em class="math"><var class="var">val2</var> <= <var class="var">val3</var></em>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">~q</code></dt>
|
||
|
|
<dd><p>Inquiry message. Insert a copyright message into the output.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">~:q</code> inserts the format implementation version.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<p>It’s an error if there are not enough arguments for the escapes in the
|
||
|
|
format string, but any excess arguments are ignored.
|
||
|
|
</p>
|
||
|
|
<p>Iterations <code class="code">~{</code> <code class="code">~}</code> and conditionals <code class="code">~[</code>
|
||
|
|
<code class="code">~;</code> <code class="code">~]</code> can be nested, but must be properly nested,
|
||
|
|
meaning the inner form must be entirely within the outer form. So
|
||
|
|
it’s not possible, for instance, to try to conditionalize the endpoint
|
||
|
|
of an iteration.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(format #t "~{ ~[ ... ~] ~}" ...) ;; good
|
||
|
|
(format #t "~{ ~[ ... ~} ... ~]" ...) ;; bad
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The same applies to case conversions <code class="code">~(</code> <code class="code">~)</code>, they
|
||
|
|
must properly nest with respect to iterations and conditionals (though
|
||
|
|
currently a case conversion cannot nest within another case
|
||
|
|
conversion).
|
||
|
|
</p>
|
||
|
|
<p>When a sub-format (<code class="code">~?</code>) is used, that sub-format string must
|
||
|
|
be self-contained. It cannot for instance give a <code class="code">~{</code> to
|
||
|
|
begin an iteration form and have the <code class="code">~}</code> up in the
|
||
|
|
originating format, or similar.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<p>Guile contains a <code class="code">format</code> procedure even when the module
|
||
|
|
<code class="code">(ice-9 format)</code> is not loaded. The default <code class="code">format</code> is
|
||
|
|
<code class="code">simple-format</code> (see <a class="pxref" href="Simple-Output.html">Simple Textual Output</a>), it doesn’t support all
|
||
|
|
escape sequences documented in this section, and will signal an error if
|
||
|
|
you try to use one of them. The reason for two versions is that the
|
||
|
|
full <code class="code">format</code> is fairly large and requires some time to load.
|
||
|
|
<code class="code">simple-format</code> is often adequate too.
|
||
|
|
</p>
|
||
|
|
<blockquote class="quotation">
|
||
|
|
<p><b class="b">Note:</b> Beware that when <code class="code">(ice-9 format)</code> is loaded, it replaces the
|
||
|
|
binding for <code class="code">format</code> on the toplevel. If your module loads
|
||
|
|
another module that loads <code class="code">(ice-9 format)</code>, then your module
|
||
|
|
will see the <code class="code">format</code> function from <code class="code">(ice-9 format)</code>,
|
||
|
|
even if it does not itself import <code class="code">(ice-9 format)</code>.
|
||
|
|
</p>
|
||
|
|
<p><em class="emph">This is legacy behavior and may be removed in a future Guile
|
||
|
|
version.</em>
|
||
|
|
</p></blockquote>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
<div class="footnotes-segment">
|
||
|
|
<hr>
|
||
|
|
<h4 class="footnotes-heading">Footnotes</h4>
|
||
|
|
|
||
|
|
<h5 class="footnote-body-heading"><a id="FOOT27" href="#DOCF27">(27)</a></h5>
|
||
|
|
<p>The <code class="code">~h</code> format specifier first
|
||
|
|
appeared in Guile version 2.0.6.</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="File-Tree-Walk.html">File Tree Walk</a>, Previous: <a href="Pretty-Printing.html">Pretty Printing</a>, Up: <a href="Guile-Modules.html">Guile Modules</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|