5178 lines
No EOL
120 KiB
HTML
5178 lines
No EOL
120 KiB
HTML
<!DOCTYPE HTML>
|
|
<HTML LANG="en-us"
|
|
><HEAD
|
|
><TITLE
|
|
>22.3 Formatted Output | Common Lisp Nova Spec</TITLE
|
|
><META CHARSET="US-ASCII"
|
|
><LINK REL="canonical" HREF="22_3_Formatted_Output.html"
|
|
><LINK REL="next" HREF="22_4_Printer_Dictionary.html" TYPE="text/html" TITLE="22.4 Printer Dictionary"
|
|
><LINK REL="prev" HREF="22_2_The_Lisp_Pretty_Printer.html" TYPE="text/html" TITLE="22.2 The Lisp Pretty Printer"
|
|
><LINK REL="up" HREF="22_Printer.html" TYPE="text/html" TITLE="22. Printer"
|
|
><LINK REL="start" HREF="index.html" TYPE="text/html" TITLE="Common Lisp Nova Spec"
|
|
><META NAME="VIEWPORT" CONTENT="width=device-width, initial-scale=1.0"
|
|
><LINK REL="STYLESHEET" HREF="dpans.css%3F3909942064.css"
|
|
><SCRIPT SRC="dpans.js%3F3909942064"
|
|
></SCRIPT
|
|
><SCRIPT SRC="apropos.js%3F3909942064"
|
|
></SCRIPT
|
|
></HEAD
|
|
><BODY
|
|
><DIV
|
|
><DIV CLASS="topnav"
|
|
><DIV CLASS="breadcrumb"
|
|
><SPAN CLASS="breadcrumb-item"
|
|
><A HREF="index.html"
|
|
>Common Lisp Nova Spec</A
|
|
></SPAN
|
|
> <SPAN CLASS="breadcrumb-item"
|
|
>→ <A HREF="22_Printer.html"
|
|
>22. Printer</A
|
|
></SPAN
|
|
> <SPAN CLASS="breadcrumb-item"
|
|
>→ <A HREF="22_3_Formatted_Output.html"
|
|
>22.3 Formatted Output</A
|
|
></SPAN
|
|
></DIV
|
|
><DIV CLASS="apropos"
|
|
><DIV CLASS="apropos-io"
|
|
><A HREF="22_2_The_Lisp_Pretty_Printer.html" CLASS="prev"
|
|
>←</A
|
|
><SPAN ID="apropos-label"
|
|
>Apropos </SPAN
|
|
><INPUT ID="apropos" AUTOFOCUS="AUTOFOCUS" PLACEHOLDER="Type here to search" ONINPUT="aproposInput(this);" ONKEYUP="aproposKeyup(event);" ONCHANGE="aproposChange(this);" ONFOCUS="aproposFocus(this);" ONFOCUSOUT="aproposFocusout(this);"
|
|
><A HREF="22_4_Printer_Dictionary.html" CLASS="next"
|
|
>→</A
|
|
></DIV
|
|
><DIV ID="apropos-res"
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV CLASS="matter"
|
|
><SECTION
|
|
><H2 ID="sec_22_3" CLASS="HeadII"
|
|
>22.3 Formatted Output</H2
|
|
><UL CLASS="subtoc"
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_1"
|
|
>22.3.1 FORMAT Basic Output</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_1_1"
|
|
>22.3.1.1 Tilde C: Character</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_1_2"
|
|
>22.3.1.2 Tilde Percent: Newline</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_1_3"
|
|
>22.3.1.3 Tilde Ampersand: Fresh-Line</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_1_4"
|
|
>22.3.1.4 Tilde Vertical-Bar: Page</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_1_5"
|
|
>22.3.1.5 Tilde Tilde: Tilde</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_2"
|
|
>22.3.2 FORMAT Radix Control</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_2_1"
|
|
>22.3.2.1 Tilde R: Radix</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_2_2"
|
|
>22.3.2.2 Tilde D: Decimal</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_2_3"
|
|
>22.3.2.3 Tilde B: Binary</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_2_4"
|
|
>22.3.2.4 Tilde O: Octal</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_2_5"
|
|
>22.3.2.5 Tilde X: Hexadecimal</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_3"
|
|
>22.3.3 FORMAT Floating-Point Printers</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_3_1"
|
|
>22.3.3.1 Tilde F: Fixed-Format Floating-Point</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_3_2"
|
|
>22.3.3.2 Tilde E: Exponential Floating-Point</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_3_3"
|
|
>22.3.3.3 Tilde G: General Floating-Point</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_3_4"
|
|
>22.3.3.4 Tilde Dollarsign: Monetary Floating-Point</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_4"
|
|
>22.3.4 FORMAT Printer Operations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_4_1"
|
|
>22.3.4.1 Tilde A: Aesthetic</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_4_2"
|
|
>22.3.4.2 Tilde S: Standard</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_4_3"
|
|
>22.3.4.3 Tilde W: Write</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_5"
|
|
>22.3.5 FORMAT Pretty Printer Operations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_5_1"
|
|
>22.3.5.1 Tilde Underscore: Conditional Newline</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_5_2"
|
|
>22.3.5.2 Tilde Less-Than-Sign: Logical Block</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_5_3"
|
|
>22.3.5.3 Tilde I: Indent</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_5_4"
|
|
>22.3.5.4 Tilde Slash: Call Function</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_6"
|
|
>22.3.6 FORMAT Layout Control</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_6_1"
|
|
>22.3.6.1 Tilde T: Tabulate</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_6_2"
|
|
>22.3.6.2 Tilde Less-Than-Sign: Justification</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_6_3"
|
|
>22.3.6.3 Tilde Greater-Than-Sign: End of Justification</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_7"
|
|
>22.3.7 FORMAT Control-Flow Operations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_7_1"
|
|
>22.3.7.1 Tilde Asterisk: Go-To</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_7_2"
|
|
>22.3.7.2 Tilde Left-Bracket: Conditional Expression</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_7_3"
|
|
>22.3.7.3 Tilde Right-Bracket: End of Conditional Expression</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_7_4"
|
|
>22.3.7.4 Tilde Left-Brace: Iteration</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_7_5"
|
|
>22.3.7.5 Tilde Right-Brace: End of Iteration</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_7_6"
|
|
>22.3.7.6 Tilde Question-Mark: Recursive Processing</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_8"
|
|
>22.3.8 FORMAT Miscellaneous Operations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_8_1"
|
|
>22.3.8.1 Tilde Left-Paren: Case Conversion</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_8_2"
|
|
>22.3.8.2 Tilde Right-Paren: End of Case Conversion</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_8_3"
|
|
>22.3.8.3 Tilde P: Plural</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_9"
|
|
>22.3.9 FORMAT Miscellaneous Pseudo-Operations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_9_1"
|
|
>22.3.9.1 Tilde Semicolon: Clause Separator</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_9_2"
|
|
>22.3.9.2 Tilde Circumflex: Escape Upward</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_9_3"
|
|
>22.3.9.3 Tilde Newline: Ignored Newline</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_10"
|
|
>22.3.10 Additional Information about FORMAT Operations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_10_1"
|
|
>22.3.10.1 Nesting of FORMAT Operations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_10_2"
|
|
>22.3.10.2 Missing and Additional FORMAT Arguments</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_10_3"
|
|
>22.3.10.3 Additional FORMAT Parameters</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_10_4"
|
|
>22.3.10.4 Undefined FORMAT Modifier Combinations</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_11"
|
|
>22.3.11 Examples of FORMAT</A
|
|
></LI
|
|
><LI
|
|
><A HREF="22_3_Formatted_Output.html#sec_22_3_12"
|
|
>22.3.12 Notes about FORMAT</A
|
|
></LI
|
|
></UL
|
|
><P CLASS="j"
|
|
><A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> is useful for producing nicely formatted text, producing good-looking messages, and so on. <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> can generate and return a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> or output to <VAR CLASS="param"
|
|
>destination</VAR
|
|
>. </P
|
|
><P CLASS="j"
|
|
>The <VAR CLASS="param"
|
|
>control-string</VAR
|
|
> argument to <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> is actually a <A HREF="26_1_Glossary.html#format_control"
|
|
><EM CLASS="term"
|
|
>format control</EM
|
|
></A
|
|
>. That is, it can be either a <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
> or a <A HREF="26_1_Glossary.html#function"
|
|
><EM CLASS="term"
|
|
>function</EM
|
|
></A
|
|
>, for example a <A HREF="26_1_Glossary.html#function"
|
|
><EM CLASS="term"
|
|
>function</EM
|
|
></A
|
|
> returned by the <A HREF="f_formatter.html" CLASS="macref"
|
|
><B
|
|
>formatter</B
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#macro"
|
|
><EM CLASS="term"
|
|
>macro</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>If it is a <A HREF="26_1_Glossary.html#function"
|
|
><EM CLASS="term"
|
|
>function</EM
|
|
></A
|
|
>, the <A HREF="26_1_Glossary.html#function"
|
|
><EM CLASS="term"
|
|
>function</EM
|
|
></A
|
|
> is called with the appropriate output stream as its first argument and the data arguments to <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> as its remaining arguments. The function should perform whatever output is necessary and return the unused tail of the arguments (if any). </P
|
|
><P CLASS="j"
|
|
>The compilation process performed by <A HREF="f_formatter.html" CLASS="macref"
|
|
><B
|
|
>formatter</B
|
|
></A
|
|
> produces a <A HREF="26_1_Glossary.html#function"
|
|
><EM CLASS="term"
|
|
>function</EM
|
|
></A
|
|
> that would do with its <A HREF="26_1_Glossary.html#argument"
|
|
><EM CLASS="term"
|
|
>arguments</EM
|
|
></A
|
|
> as the <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> interpreter would do with those <A HREF="26_1_Glossary.html#argument"
|
|
><EM CLASS="term"
|
|
>arguments</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>The remainder of this section describes what happens if the <VAR CLASS="param"
|
|
>control-string</VAR
|
|
> is a <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
><VAR CLASS="param"
|
|
>Control-string</VAR
|
|
> is composed of simple text (<A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>characters</EM
|
|
></A
|
|
>) and embedded directives. </P
|
|
><P CLASS="j"
|
|
><A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> writes the simple text as is; each embedded directive specifies further text output that is to appear at the corresponding point within the simple text. Most directives use one or more elements of <VAR CLASS="param"
|
|
>args</VAR
|
|
> to create their output. </P
|
|
><P CLASS="j"
|
|
>A directive consists of a <A HREF="26_1_Glossary.html#tilde"
|
|
><EM CLASS="term"
|
|
>tilde</EM
|
|
></A
|
|
>, optional prefix parameters separated by commas, optional <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> and <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> modifiers, and a single character indicating what kind of directive this is. There is no required ordering between the <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> and <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> modifier. The <A HREF="26_1_Glossary.html#case"
|
|
><EM CLASS="term"
|
|
>case</EM
|
|
></A
|
|
> of the directive character is ignored. Prefix parameters are notated as signed (sign is optional) decimal numbers, or as a <A HREF="26_1_Glossary.html#single-quote"
|
|
><EM CLASS="term"
|
|
>single-quote</EM
|
|
></A
|
|
> followed by a character. For example, <CODE CLASS="f"
|
|
>~5,'0d</CODE
|
|
> can be used to print an <A HREF="26_1_Glossary.html#integer"
|
|
><EM CLASS="term"
|
|
>integer</EM
|
|
></A
|
|
> in decimal radix in five columns with leading zeros, or <CODE CLASS="f"
|
|
>~5,'*d</CODE
|
|
> to get leading asterisks. </P
|
|
><P CLASS="j"
|
|
>In place of a prefix parameter to a directive, <CODE CLASS="f"
|
|
>V</CODE
|
|
> (or <CODE CLASS="f"
|
|
>v</CODE
|
|
>) can be used. In this case, <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> takes an argument from <VAR CLASS="param"
|
|
>args</VAR
|
|
> as a parameter to the directive. The argument should be an <A HREF="26_1_Glossary.html#integer"
|
|
><EM CLASS="term"
|
|
>integer</EM
|
|
></A
|
|
> or <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
>. If the <VAR CLASS="param"
|
|
>arg</VAR
|
|
> used by a <CODE CLASS="f"
|
|
>V</CODE
|
|
> parameter is <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
>, the effect is as if the parameter had been omitted. <CODE CLASS="f"
|
|
>#</CODE
|
|
> can be used in place of a prefix parameter; it represents the number of <VAR CLASS="param"
|
|
>args</VAR
|
|
> remaining to be processed. When used within a recursive format, in the context of <CODE CLASS="f"
|
|
>~?</CODE
|
|
> or <CODE CLASS="f"
|
|
>~{</CODE
|
|
>, the <CODE CLASS="f"
|
|
>#</CODE
|
|
> prefix parameter represents the number of <A HREF="26_1_Glossary.html#format_argument"
|
|
><EM CLASS="term"
|
|
>format arguments</EM
|
|
></A
|
|
> remaining within the recursive call. </P
|
|
><P CLASS="j"
|
|
>Examples of <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format strings</EM
|
|
></A
|
|
>:</P
|
|
><FIGURE CLASS="boxfig"
|
|
><DIV CLASS="figbody"
|
|
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
|
|
><TBODY
|
|
><TR
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
|
|
><CODE CLASS="f"
|
|
>"~S"</CODE
|
|
></TD
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
|
|
> <SPAN CLASS="cmr"
|
|
>;This</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>is</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>an</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>S</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>directive</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>with</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>no</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>parameters</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>or</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>modifiers.</SPAN
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
|
|
> <CODE CLASS="f"
|
|
>"~3,-4:@s"</CODE
|
|
></TD
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
|
|
> <SPAN CLASS="cmr"
|
|
>;This</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>is</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>an</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>S</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>directive</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>with</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>two</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>parameters,</SPAN
|
|
> <CODE CLASS="f"
|
|
>3</CODE
|
|
> <SPAN CLASS="cmr"
|
|
>and</SPAN
|
|
> <CODE CLASS="f"
|
|
>-4</CODE
|
|
><SPAN CLASS="cmr"
|
|
>,</SPAN
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
|
|
></TD
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
|
|
> <SPAN CLASS="cmr"
|
|
>;</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>and</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>both</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>the</SPAN
|
|
> <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> <SPAN CLASS="cmr"
|
|
>and</SPAN
|
|
> <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> <SPAN CLASS="cmr"
|
|
>flags.</SPAN
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
|
|
> <CODE CLASS="f"
|
|
>"~,+4S"</CODE
|
|
></TD
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
|
|
> <SPAN CLASS="cmr"
|
|
>;Here</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>the</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>first</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>prefix</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>parameter</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>is</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>omitted</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>and</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>takes</SPAN
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
|
|
></TD
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
|
|
> <SPAN CLASS="cmr"
|
|
>;</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>on</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>its</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>default</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>value,</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>while</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>the</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>second</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>parameter</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>is</SPAN
|
|
> <CODE CLASS="f"
|
|
>4</CODE
|
|
><SPAN CLASS="cmr"
|
|
>.</SPAN
|
|
></TD
|
|
></TR
|
|
></TBODY
|
|
></TABLE
|
|
></DIV
|
|
><FIGCAPTION CLASS="caption"
|
|
><B
|
|
>Figure 22–6. Examples of format control strings</B
|
|
></FIGCAPTION
|
|
></FIGURE
|
|
><P CLASS="j"
|
|
><A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> sends the output to <VAR CLASS="param"
|
|
>destination</VAR
|
|
>. If <VAR CLASS="param"
|
|
>destination</VAR
|
|
> is <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
>, <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> creates and returns a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> containing the output from <VAR CLASS="param"
|
|
>control-string</VAR
|
|
>. If <VAR CLASS="param"
|
|
>destination</VAR
|
|
> is <A HREF="26_1_Glossary.html#non-nil"
|
|
><EM CLASS="term"
|
|
>non-nil</EM
|
|
></A
|
|
>, it must be a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> with a <A HREF="26_1_Glossary.html#fill_pointer"
|
|
><EM CLASS="term"
|
|
>fill pointer</EM
|
|
></A
|
|
>, a <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
>, or the symbol <SPAN CLASS="misc"
|
|
><B
|
|
>t</B
|
|
></SPAN
|
|
>. If <VAR CLASS="param"
|
|
>destination</VAR
|
|
> is a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> with a <A HREF="26_1_Glossary.html#fill_pointer"
|
|
><EM CLASS="term"
|
|
>fill pointer</EM
|
|
></A
|
|
>, the output is added to the end of the <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
>. If <VAR CLASS="param"
|
|
>destination</VAR
|
|
> is a <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
>, the output is sent to that <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
>. If <VAR CLASS="param"
|
|
>destination</VAR
|
|
> is <SPAN CLASS="misc"
|
|
><B
|
|
>t</B
|
|
></SPAN
|
|
>, the output is sent to <A HREF="26_1_Glossary.html#standard_output"
|
|
><EM CLASS="term"
|
|
>standard output</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>In the description of the directives that follows, the term <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> in general refers to the next item of the set of <VAR CLASS="param"
|
|
>args</VAR
|
|
> to be processed. The word or phrase at the beginning of each description is a mnemonic for the directive. <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> directives do not bind any of the printer control variables (<SPAN CLASS="varref"
|
|
><B
|
|
>*print-...*</B
|
|
></SPAN
|
|
>) except as specified in the following descriptions. Implementations may specify the binding of new, implementation-specific printer control variables for each <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> directive, but they may neither bind any standard printer control variables not specified in description of a <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> directive nor fail to bind any standard printer control variables as specified in the description.</P
|
|
><H3 ID="sec_22_3_1" CLASS="HeadIII"
|
|
>22.3.1 FORMAT Basic Output</H3
|
|
><H4 ID="sec_22_3_1_1" CLASS="HeadIV"
|
|
>22.3.1.1 Tilde C: Character</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="C (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde C (format directive)"
|
|
></SPAN
|
|
>The next <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> should be a <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
>; it is printed according to the modifier flags. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~C</CODE
|
|
> prints the <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
> as if by using <A HREF="f_write-char.html" CLASS="funref"
|
|
><B
|
|
>write-char</B
|
|
></A
|
|
> if it is a <EM CLASS="term"
|
|
>simple character</EM
|
|
>. <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>Characters</EM
|
|
></A
|
|
> that are not <A HREF="26_1_Glossary.html#simple"
|
|
><EM CLASS="term"
|
|
>simple</EM
|
|
></A
|
|
> are not necessarily printed as if by <A HREF="f_write-char.html" CLASS="funref"
|
|
><B
|
|
>write-char</B
|
|
></A
|
|
>, but are displayed in an <A HREF="26_1_Glossary.html#implementation-defined"
|
|
><EM CLASS="term"
|
|
>implementation-defined</EM
|
|
></A
|
|
>, abbreviated format. For example,</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~C" #\A) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "A"
|
|
(format nil "~C" #\Space) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " "</PRE
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:C</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>~C</CODE
|
|
> for <A HREF="26_1_Glossary.html#printing"
|
|
><EM CLASS="term"
|
|
>printing</EM
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>characters</EM
|
|
></A
|
|
>, but other <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>characters</EM
|
|
></A
|
|
> are “spelled out.” The intent is that this is a “pretty” format for printing characters. For <A HREF="26_1_Glossary.html#simple"
|
|
><EM CLASS="term"
|
|
>simple</EM
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>characters</EM
|
|
></A
|
|
> that are not <A HREF="26_1_Glossary.html#printing"
|
|
><EM CLASS="term"
|
|
>printing</EM
|
|
></A
|
|
>, what is spelled out is the <A HREF="26_1_Glossary.html#name"
|
|
><EM CLASS="term"
|
|
>name</EM
|
|
></A
|
|
> of the <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
> (see <A HREF="f_char-name.html" CLASS="funref"
|
|
><B
|
|
>char-name</B
|
|
></A
|
|
>). For <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>characters</EM
|
|
></A
|
|
> that are not <A HREF="26_1_Glossary.html#simple"
|
|
><EM CLASS="term"
|
|
>simple</EM
|
|
></A
|
|
> and not <A HREF="26_1_Glossary.html#printing"
|
|
><EM CLASS="term"
|
|
>printing</EM
|
|
></A
|
|
>, what is spelled out is <A HREF="26_1_Glossary.html#implementation-defined"
|
|
><EM CLASS="term"
|
|
>implementation-defined</EM
|
|
></A
|
|
>. For example,</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "~:C" #\A) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "A"
|
|
(format nil "~:C" #\Space) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Space"
|
|
;; This next example assumes an implementation-defined "Control" attribute.
|
|
(format nil "~:C" #\Control-Space)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Control-Space"
|
|
<SPAN CLASS="sp"
|
|
><SPAN CLASS="arrow withabove"
|
|
><SPAN CLASS="above"
|
|
>or </SPAN
|
|
>→</SPAN
|
|
></SPAN
|
|
> "c-Space"</PRE
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:@C</CODE
|
|
> prints what <CODE CLASS="f"
|
|
>~:C</CODE
|
|
> would, and then if the <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
> requires unusual shift keys on the keyboard to type it, this fact is mentioned. For example,</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~:@C" #\Control-Partial) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Control-<SPAN CLASS="cmr"
|
|
>∂</SPAN
|
|
> (Top-F)"</PRE
|
|
><P CLASS="j"
|
|
>This is the format used for telling the user about a key he is expected to type, in prompts, for instance. The precise output may depend not only on the implementation, but on the particular I/O devices in use. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@C</CODE
|
|
> prints the <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
> in a way that the <A HREF="26_1_Glossary.html#Lisp_reader"
|
|
><EM CLASS="term"
|
|
>Lisp reader</EM
|
|
></A
|
|
> can understand, using <CODE CLASS="f"
|
|
>#\</CODE
|
|
> syntax. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@C</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <SPAN CLASS="misc"
|
|
><B
|
|
>t</B
|
|
></SPAN
|
|
>.</P
|
|
><H4 ID="sec_22_3_1_2" CLASS="HeadIV"
|
|
>22.3.1.2 Tilde Percent: Newline</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Percent (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Percent (format directive)"
|
|
></SPAN
|
|
>This outputs a <CODE CLASS="f"
|
|
>#\Newline</CODE
|
|
> character, thereby terminating the current output line and beginning a new one. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>%</CODE
|
|
> outputs <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> newlines. No <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is used.</P
|
|
><H4 ID="sec_22_3_1_3" CLASS="HeadIV"
|
|
>22.3.1.3 Tilde Ampersand: Fresh-Line</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Ampersand (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Ampersand (format directive)"
|
|
></SPAN
|
|
>Unless it can be determined that the output stream is already at the beginning of a line, this outputs a newline. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>&</CODE
|
|
> calls <A HREF="f_terpri.html" CLASS="funref"
|
|
><B
|
|
>fresh-line</B
|
|
></A
|
|
> and then outputs <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>−1 newlines. <CODE CLASS="f"
|
|
>~0&</CODE
|
|
> does nothing.</P
|
|
><H4 ID="sec_22_3_1_4" CLASS="HeadIV"
|
|
>22.3.1.4 Tilde Vertical-Bar: Page</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Vertical-Bar (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Vertical-Bar (format directive)"
|
|
></SPAN
|
|
>This outputs a page separator character, if possible. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>|</CODE
|
|
> does this <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> times.</P
|
|
><H4 ID="sec_22_3_1_5" CLASS="HeadIV"
|
|
>22.3.1.5 Tilde Tilde: Tilde</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Tilde (format directive)"
|
|
></SPAN
|
|
>This outputs a <A HREF="26_1_Glossary.html#tilde"
|
|
><EM CLASS="term"
|
|
>tilde</EM
|
|
></A
|
|
>. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>~</CODE
|
|
> outputs <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> tildes.</P
|
|
><H3 ID="sec_22_3_2" CLASS="HeadIII"
|
|
>22.3.2 FORMAT Radix Control</H3
|
|
><H4 ID="sec_22_3_2_1" CLASS="HeadIV"
|
|
>22.3.2.1 Tilde R: Radix</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="R (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde R (format directive)"
|
|
></SPAN
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>R</CODE
|
|
> prints <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> in radix <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>. The modifier flags and any remaining parameters are used as for the <CODE CLASS="f"
|
|
>~D</CODE
|
|
> directive. <CODE CLASS="f"
|
|
>~D</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>~10R</CODE
|
|
>. The full form is <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>radix</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>commachar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>comma-interval</I
|
|
></I
|
|
>R</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
>If no prefix parameters are given to <CODE CLASS="f"
|
|
>~R</CODE
|
|
>, then a different interpretation is given. The argument should be an <A HREF="26_1_Glossary.html#integer"
|
|
><EM CLASS="term"
|
|
>integer</EM
|
|
></A
|
|
>. For example, if <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is 4:</P
|
|
><UL
|
|
><LI
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~R</CODE
|
|
> prints <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> as a cardinal English number: <CODE CLASS="f"
|
|
>four</CODE
|
|
>.</P
|
|
></LI
|
|
><LI
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:R</CODE
|
|
> prints <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> as an ordinal English number: <CODE CLASS="f"
|
|
>fourth</CODE
|
|
>.</P
|
|
></LI
|
|
><LI
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@R</CODE
|
|
> prints <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> as a Roman numeral: <CODE CLASS="f"
|
|
>IV</CODE
|
|
>.</P
|
|
></LI
|
|
><LI
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:@R</CODE
|
|
> prints <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> as an old Roman numeral: <CODE CLASS="f"
|
|
>IIII</CODE
|
|
>.</P
|
|
></LI
|
|
></UL
|
|
><P CLASS="j"
|
|
>For example:</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~,,' ,4:B" 13) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "1101"
|
|
(format nil "~,,' ,4:B" 17) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "1 0001"
|
|
(format nil "~19,0,' ,4:B" 3333) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "0000 1101 0000 0101"
|
|
(format nil "~3,,,' ,2:R" 17) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "1 22"
|
|
(format nil "~,,'|,2:D" #xFFFF) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "6|55|35"</PRE
|
|
><P CLASS="j"
|
|
>If and only if the first parameter, <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>, is supplied, <CODE CLASS="f"
|
|
>~R</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-radix*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-base*</B
|
|
></A
|
|
> to <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>, and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>If and only if no parameters are supplied, <CODE CLASS="f"
|
|
>~R</CODE
|
|
> binds <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-base*</B
|
|
></A
|
|
> to <CODE CLASS="f"
|
|
>10</CODE
|
|
>.</P
|
|
><H4 ID="sec_22_3_2_2" CLASS="HeadIV"
|
|
>22.3.2.2 Tilde D: Decimal</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="D (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde D (format directive)"
|
|
></SPAN
|
|
>An <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>, which should be an <A HREF="26_1_Glossary.html#integer"
|
|
><EM CLASS="term"
|
|
>integer</EM
|
|
></A
|
|
>, is printed in decimal radix. <CODE CLASS="f"
|
|
>~D</CODE
|
|
> will never put a decimal point after the number. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>D</CODE
|
|
> uses a column width of <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>; spaces are inserted on the left if the number requires fewer than <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
> columns for its digits and sign. If the number doesn’t fit in <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
> columns, additional columns are used as needed. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>D</CODE
|
|
> uses <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
> as the pad character instead of space. </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is not an <A HREF="26_1_Glossary.html#integer"
|
|
><EM CLASS="term"
|
|
>integer</EM
|
|
></A
|
|
>, it is printed in <CODE CLASS="f"
|
|
>~A</CODE
|
|
> format and decimal base. </P
|
|
><P CLASS="j"
|
|
>The <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier causes the number’s sign to be printed always; the default is to print it only if the number is negative. The <CODE CLASS="f"
|
|
>:</CODE
|
|
> modifier causes commas to be printed between groups of digits; <I CLASS="j"
|
|
><I
|
|
>commachar</I
|
|
></I
|
|
> may be used to change the character used as the comma. <I CLASS="j"
|
|
><I
|
|
>comma-interval</I
|
|
></I
|
|
> must be an <A HREF="26_1_Glossary.html#integer"
|
|
><EM CLASS="term"
|
|
>integer</EM
|
|
></A
|
|
> and defaults to 3. When the <CODE CLASS="f"
|
|
>:</CODE
|
|
> modifier is given to any of these directives, the <I CLASS="j"
|
|
><I
|
|
>commachar</I
|
|
></I
|
|
> is printed between groups of <I CLASS="j"
|
|
><I
|
|
>comma-interval</I
|
|
></I
|
|
> digits. </P
|
|
><P CLASS="j"
|
|
>Thus the most general form of <CODE CLASS="f"
|
|
>~D</CODE
|
|
> is <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>commachar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>comma-interval</I
|
|
></I
|
|
>D</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~D</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-radix*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-base*</B
|
|
></A
|
|
> to <CODE CLASS="f"
|
|
>10</CODE
|
|
>, and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_2_3" CLASS="HeadIV"
|
|
>22.3.2.3 Tilde B: Binary</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="B (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde B (format directive)"
|
|
></SPAN
|
|
>This is just like <CODE CLASS="f"
|
|
>~D</CODE
|
|
> but prints in binary radix (radix 2) instead of decimal. The full form is therefore <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>commachar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>comma-interval</I
|
|
></I
|
|
>B</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~B</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-radix*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-base*</B
|
|
></A
|
|
> to <CODE CLASS="f"
|
|
>2</CODE
|
|
>, and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_2_4" CLASS="HeadIV"
|
|
>22.3.2.4 Tilde O: Octal</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="O (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde O (format directive)"
|
|
></SPAN
|
|
>This is just like <CODE CLASS="f"
|
|
>~D</CODE
|
|
> but prints in octal radix (radix 8) instead of decimal. The full form is therefore <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>commachar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>comma-interval</I
|
|
></I
|
|
>O</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~O</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-radix*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-base*</B
|
|
></A
|
|
> to <CODE CLASS="f"
|
|
>8</CODE
|
|
>, and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_2_5" CLASS="HeadIV"
|
|
>22.3.2.5 Tilde X: Hexadecimal</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="X (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde X (format directive)"
|
|
></SPAN
|
|
>This is just like <CODE CLASS="f"
|
|
>~D</CODE
|
|
> but prints in hexadecimal radix (radix 16) instead of decimal. The full form is therefore <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>commachar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>comma-interval</I
|
|
></I
|
|
>X</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~X</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-radix*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, <A HREF="v_print-base.html" CLASS="varref"
|
|
><B
|
|
>*print-base*</B
|
|
></A
|
|
> to <CODE CLASS="f"
|
|
>16</CODE
|
|
>, and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H3 ID="sec_22_3_3" CLASS="HeadIII"
|
|
>22.3.3 FORMAT Floating-Point Printers</H3
|
|
><H4 ID="sec_22_3_3_1" CLASS="HeadIV"
|
|
>22.3.3.1 Tilde F: Fixed-Format Floating-Point</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="F (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde F (format directive)"
|
|
></SPAN
|
|
>The next <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is printed as a <A HREF="26_1_Glossary.html#float"
|
|
><EM CLASS="term"
|
|
>float</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>The full form is <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>F</CODE
|
|
>. The parameter <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> is the width of the field to be printed; <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is the number of digits to print after the decimal point; <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> is a scale factor that defaults to zero. </P
|
|
><P CLASS="j"
|
|
>Exactly <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> characters will be output. First, leading copies of the character <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
> (which defaults to a space) are printed, if necessary, to pad the field on the left. If the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is negative, then a minus sign is printed; if the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is not negative, then a plus sign is printed if and only if the <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier was supplied. Then a sequence of digits, containing a single embedded decimal point, is printed; this represents the magnitude of the value of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> times 10<SUP CLASS="sup"
|
|
><I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
></SUP
|
|
>, rounded to <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> fractional digits. When rounding up and rounding down would produce printed values equidistant from the scaled value of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>, then the implementation is free to use either one. For example, printing the argument <CODE CLASS="f"
|
|
>6.375</CODE
|
|
> using the format <CODE CLASS="f"
|
|
>~4,2F</CODE
|
|
> may correctly produce either <CODE CLASS="f"
|
|
>6.37</CODE
|
|
> or <CODE CLASS="f"
|
|
>6.38</CODE
|
|
>. Leading zeros are not permitted, except that a single zero digit is output before the decimal point if the printed value is less than one, and this single zero digit is not output at all if <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>=<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>+1. </P
|
|
><P CLASS="j"
|
|
>If it is impossible to print the value in the required format in a field of width <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>, then one of two actions is taken. If the parameter <I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
> is supplied, then <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> copies of that parameter are printed instead of the scaled value of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>. If the <I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
> parameter is omitted, then the scaled value is printed using more than <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> characters, as many more as may be needed. </P
|
|
><P CLASS="j"
|
|
>If the <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> parameter is omitted, then the field is of variable width. In effect, a value is chosen for <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> in such a way that no leading pad characters need to be printed and exactly <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> characters will follow the decimal point. For example, the directive <CODE CLASS="f"
|
|
>~,2F</CODE
|
|
> will print exactly two digits after the decimal point and as many as necessary before the decimal point. </P
|
|
><P CLASS="j"
|
|
>If the parameter <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is omitted, then there is no constraint on the number of digits to appear after the decimal point. A value is chosen for <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> in such a way that as many digits as possible may be printed subject to the width constraint imposed by the parameter <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> and the constraint that no trailing zero digits may appear in the fraction, except that if the fraction to be printed is zero, then a single zero digit should appear after the decimal point if permitted by the width constraint. </P
|
|
><P CLASS="j"
|
|
>If both <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> and <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> are omitted, then the effect is to print the value using ordinary free-format output; <A HREF="f_write.html" CLASS="funref"
|
|
><B
|
|
>prin1</B
|
|
></A
|
|
> uses this format for any number whose magnitude is either zero or between 10<SUP CLASS="sup"
|
|
><SPAN CLASS="cmr"
|
|
>-3</SPAN
|
|
></SUP
|
|
> (inclusive) and 10sup7 (exclusive). </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> is omitted, then if the magnitude of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is so large (or, if <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is also omitted, so small) that more than 100 digits would have to be printed, then an implementation is free, at its discretion, to print the number using exponential notation instead, as if by the directive <CODE CLASS="f"
|
|
>~E</CODE
|
|
> (with all parameters to <CODE CLASS="f"
|
|
>~E</CODE
|
|
> defaulted, not taking their values from the <CODE CLASS="f"
|
|
>~F</CODE
|
|
> directive). </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a <A HREF="26_1_Glossary.html#rational"
|
|
><EM CLASS="term"
|
|
>rational</EM
|
|
></A
|
|
> number, then it is coerced to be a <A HREF="26_1_Glossary.html#single_float"
|
|
><EM CLASS="term"
|
|
>single float</EM
|
|
></A
|
|
> and then printed. Alternatively, an implementation is permitted to process a <A HREF="26_1_Glossary.html#rational"
|
|
><EM CLASS="term"
|
|
>rational</EM
|
|
></A
|
|
> number by any other method that has essentially the same behavior but avoids loss of precision or overflow because of the coercion. If <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> and <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> are not supplied and the number has no exact decimal representation, for example <CODE CLASS="f"
|
|
>1/3</CODE
|
|
>, some precision cutoff must be chosen by the implementation since only a finite number of digits may be printed. </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a <A HREF="26_1_Glossary.html#complex"
|
|
><EM CLASS="term"
|
|
>complex</EM
|
|
></A
|
|
> number or some non-numeric <A HREF="26_1_Glossary.html#object"
|
|
><EM CLASS="term"
|
|
>object</EM
|
|
></A
|
|
>, then it is printed using the format directive <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>D</CODE
|
|
>, thereby printing it in decimal radix and a minimum field width of <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~F</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
> and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_3_2" CLASS="HeadIV"
|
|
>22.3.3.2 Tilde E: Exponential Floating-Point</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="E (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde E (format directive)"
|
|
></SPAN
|
|
>The next <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is printed as a <A HREF="26_1_Glossary.html#float"
|
|
><EM CLASS="term"
|
|
>float</EM
|
|
></A
|
|
> in exponential notation. </P
|
|
><P CLASS="j"
|
|
>The full form is <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>exponentchar</I
|
|
></I
|
|
>E</CODE
|
|
>. The parameter <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> is the width of the field to be printed; <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is the number of digits to print after the decimal point; <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> is the number of digits to use when printing the exponent; <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> is a scale factor that defaults to one (not zero). </P
|
|
><P CLASS="j"
|
|
>Exactly <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> characters will be output. First, leading copies of the character <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
> (which defaults to a space) are printed, if necessary, to pad the field on the left. If the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is negative, then a minus sign is printed; if the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is not negative, then a plus sign is printed if and only if the <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier was supplied. Then a sequence of digits containing a single embedded decimal point is printed. The form of this sequence of digits depends on the scale factor <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>. If <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> is zero, then <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> digits are printed after the decimal point, and a single zero digit appears before the decimal point if the total field width will permit it. If <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> is positive, then it must be strictly less than <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>+2; <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> significant digits are printed before the decimal point, and <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>−<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>+1 digits are printed after the decimal point. If <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> is negative, then it must be strictly greater than −<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>; a single zero digit appears before the decimal point if the total field width will permit it, and after the decimal point are printed first −<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> zeros and then <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>+<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> significant digits. The printed fraction must be properly rounded. When rounding up and rounding down would produce printed values equidistant from the scaled value of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>, then the implementation is free to use either one. For example, printing the argument <CODE CLASS="f"
|
|
>637.5</CODE
|
|
> using the format <CODE CLASS="f"
|
|
>~8,2E</CODE
|
|
> may correctly produce either <CODE CLASS="f"
|
|
>6.37E+2</CODE
|
|
> or <CODE CLASS="f"
|
|
>6.38E+2</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
>Following the digit sequence, the exponent is printed. First the character parameter <I CLASS="j"
|
|
><I
|
|
>exponentchar</I
|
|
></I
|
|
> is printed; if this parameter is omitted, then the <A HREF="26_1_Glossary.html#exponent_marker"
|
|
><EM CLASS="term"
|
|
>exponent marker</EM
|
|
></A
|
|
> that <A HREF="f_write.html" CLASS="funref"
|
|
><B
|
|
>prin1</B
|
|
></A
|
|
> would use is printed, as determined from the type of the <A HREF="26_1_Glossary.html#float"
|
|
><EM CLASS="term"
|
|
>float</EM
|
|
></A
|
|
> and the current value of <A HREF="v_read-default-float-format.html" CLASS="varref"
|
|
><B
|
|
>*read-default-float-format*</B
|
|
></A
|
|
>. Next, either a plus sign or a minus sign is printed, followed by <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> digits representing the power of ten by which the printed fraction must be multiplied to properly represent the rounded value of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>. </P
|
|
><P CLASS="j"
|
|
>If it is impossible to print the value in the required format in a field of width <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>, possibly because <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> is too large or too small or because the exponent cannot be printed in <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> character positions, then one of two actions is taken. If the parameter <I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
> is supplied, then <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> copies of that parameter are printed instead of the scaled value of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>. If the <I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
> parameter is omitted, then the scaled value is printed using more than <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> characters, as many more as may be needed; if the problem is that <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is too small for the supplied <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> or that <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> is too small, then a larger value is used for <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> or <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> as may be needed. </P
|
|
><P CLASS="j"
|
|
>If the <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> parameter is omitted, then the field is of variable width. In effect a value is chosen for <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> in such a way that no leading pad characters need to be printed. </P
|
|
><P CLASS="j"
|
|
>If the parameter <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is omitted, then there is no constraint on the number of digits to appear. A value is chosen for <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> in such a way that as many digits as possible may be printed subject to the width constraint imposed by the parameter <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>, the constraint of the scale factor <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>, and the constraint that no trailing zero digits may appear in the fraction, except that if the fraction to be printed is zero then a single zero digit should appear after the decimal point. </P
|
|
><P CLASS="j"
|
|
>If the parameter <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> is omitted, then the exponent is printed using the smallest number of digits necessary to represent its value. </P
|
|
><P CLASS="j"
|
|
>If all of <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>, <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>, and <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> are omitted, then the effect is to print the value using ordinary free-format exponential-notation output; <A HREF="f_write.html" CLASS="funref"
|
|
><B
|
|
>prin1</B
|
|
></A
|
|
> uses a similar format for any non-zero number whose magnitude is less than 10<SUP CLASS="sup"
|
|
><SPAN CLASS="cmr"
|
|
>-3</SPAN
|
|
></SUP
|
|
> or greater than or equal to 10sup7. The only difference is that the <CODE CLASS="f"
|
|
>~E</CODE
|
|
> directive always prints a plus or minus sign in front of the exponent, while <A HREF="f_write.html" CLASS="funref"
|
|
><B
|
|
>prin1</B
|
|
></A
|
|
> omits the plus sign if the exponent is non-negative. </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a <A HREF="26_1_Glossary.html#rational"
|
|
><EM CLASS="term"
|
|
>rational</EM
|
|
></A
|
|
> number, then it is coerced to be a <A HREF="26_1_Glossary.html#single_float"
|
|
><EM CLASS="term"
|
|
>single float</EM
|
|
></A
|
|
> and then printed. Alternatively, an implementation is permitted to process a <A HREF="26_1_Glossary.html#rational"
|
|
><EM CLASS="term"
|
|
>rational</EM
|
|
></A
|
|
> number by any other method that has essentially the same behavior but avoids loss of precision or overflow because of the coercion. If <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> and <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> are unsupplied and the number has no exact decimal representation, for example <CODE CLASS="f"
|
|
>1/3</CODE
|
|
>, some precision cutoff must be chosen by the implementation since only a finite number of digits may be printed. </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a <A HREF="26_1_Glossary.html#complex"
|
|
><EM CLASS="term"
|
|
>complex</EM
|
|
></A
|
|
> number or some non-numeric <A HREF="26_1_Glossary.html#object"
|
|
><EM CLASS="term"
|
|
>object</EM
|
|
></A
|
|
>, then it is printed using the format directive <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>D</CODE
|
|
>, thereby printing it in decimal radix and a minimum field width of <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~E</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
> and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_3_3" CLASS="HeadIV"
|
|
>22.3.3.3 Tilde G: General Floating-Point</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="G (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde G (format directive)"
|
|
></SPAN
|
|
>The next <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is printed as a <A HREF="26_1_Glossary.html#float"
|
|
><EM CLASS="term"
|
|
>float</EM
|
|
></A
|
|
> in either fixed-format or exponential notation as appropriate. </P
|
|
><P CLASS="j"
|
|
>The full form is <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>exponentchar</I
|
|
></I
|
|
>G</CODE
|
|
>. The format in which to print <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> depends on the magnitude (absolute value) of the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>. Let <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> be an integer such that 10<SUP CLASS="sup"
|
|
><I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
><SPAN CLASS="cmr"
|
|
>-1</SPAN
|
|
></SUP
|
|
> ≤ |<I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>| <SPAN CLASS="cmtt"
|
|
><</SPAN
|
|
> 10<SUP CLASS="sup"
|
|
><I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
></SUP
|
|
>. Let <I CLASS="j"
|
|
><I
|
|
>ee</I
|
|
></I
|
|
> equal <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
>+2, or 4 if <I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
> is omitted. Let <I CLASS="j"
|
|
><I
|
|
>ww</I
|
|
></I
|
|
> equal <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>−<I CLASS="j"
|
|
><I
|
|
>ee</I
|
|
></I
|
|
>, or <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
> if <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> is omitted. If <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is omitted, first let <I CLASS="j"
|
|
><I
|
|
>q</I
|
|
></I
|
|
> be the number of digits needed to print <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> with no loss of information and without leading or trailing zeros; then let <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> equal <CODE CLASS="f"
|
|
>(max <I CLASS="j"
|
|
><I
|
|
>q</I
|
|
></I
|
|
> (min <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> 7))</CODE
|
|
>. Let <I CLASS="j"
|
|
><I
|
|
>dd</I
|
|
></I
|
|
> equal <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>−<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>. </P
|
|
><P CLASS="j"
|
|
>If 0 ≤ <I CLASS="j"
|
|
><I
|
|
>dd</I
|
|
></I
|
|
> ≤ <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>, then <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is printed as if by the format directives </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>ww</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>dd</I
|
|
></I
|
|
>,,<I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>F~<I CLASS="j"
|
|
><I
|
|
>ee</I
|
|
></I
|
|
>@T</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>Note that the scale factor <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> is not passed to the <CODE CLASS="f"
|
|
>~F</CODE
|
|
> directive. For all other values of <I CLASS="j"
|
|
><I
|
|
>dd</I
|
|
></I
|
|
>, <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is printed as if by the format directive </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>e</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>overflowchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>exponentchar</I
|
|
></I
|
|
>E</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>In either case, an <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier is supplied to the <CODE CLASS="f"
|
|
>~F</CODE
|
|
> or <CODE CLASS="f"
|
|
>~E</CODE
|
|
> directive if and only if one was supplied to the <CODE CLASS="f"
|
|
>~G</CODE
|
|
> directive. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~G</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
> and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_3_4" CLASS="HeadIV"
|
|
>22.3.3.4 Tilde Dollarsign: Monetary Floating-Point</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Dollarsign (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Dollarsign (format directive)"
|
|
></SPAN
|
|
>The next <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is printed as a <A HREF="26_1_Glossary.html#float"
|
|
><EM CLASS="term"
|
|
>float</EM
|
|
></A
|
|
> in fixed-format notation. </P
|
|
><P CLASS="j"
|
|
>The full form is <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>$</CODE
|
|
>. The parameter <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> is the number of digits to print after the decimal point (default value 2); <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> is the minimum number of digits to print before the decimal point (default value 1); <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> is the minimum total width of the field to be printed (default value 0). </P
|
|
><P CLASS="j"
|
|
>First padding and the sign are output. If the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is negative, then a minus sign is printed; if the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is not negative, then a plus sign is printed if and only if the <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier was supplied. If the <CODE CLASS="f"
|
|
>:</CODE
|
|
> modifier is used, the sign appears before any padding, and otherwise after the padding. If <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> is supplied and the number of other characters to be output is less than <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>, then copies of <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
> (which defaults to a space) are output to make the total field width equal <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>. Then <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> digits are printed for the integer part of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>, with leading zeros if necessary; then a decimal point; then <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> digits of fraction, properly rounded. </P
|
|
><P CLASS="j"
|
|
>If the magnitude of <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is so large that more than <I CLASS="j"
|
|
><I
|
|
>m</I
|
|
></I
|
|
> digits would have to be printed, where <I CLASS="j"
|
|
><I
|
|
>m</I
|
|
></I
|
|
> is the larger of <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> and 100, then an implementation is free, at its discretion, to print the number using exponential notation instead, as if by the directive <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>q</I
|
|
></I
|
|
>,,,,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>E</CODE
|
|
>, where <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
> and <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
> are present or omitted according to whether they were present or omitted in the <CODE CLASS="f"
|
|
>~$</CODE
|
|
> directive, and where <I CLASS="j"
|
|
><I
|
|
>q</I
|
|
></I
|
|
>=<I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
>+<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>−1, where <I CLASS="j"
|
|
><I
|
|
>d</I
|
|
></I
|
|
> and <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> are the (possibly default) values given to the <CODE CLASS="f"
|
|
>~$</CODE
|
|
> directive. </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a <A HREF="26_1_Glossary.html#rational"
|
|
><EM CLASS="term"
|
|
>rational</EM
|
|
></A
|
|
> number, then it is coerced to be a <A HREF="26_1_Glossary.html#single_float"
|
|
><EM CLASS="term"
|
|
>single float</EM
|
|
></A
|
|
> and then printed. Alternatively, an implementation is permitted to process a <A HREF="26_1_Glossary.html#rational"
|
|
><EM CLASS="term"
|
|
>rational</EM
|
|
></A
|
|
> number by any other method that has essentially the same behavior but avoids loss of precision or overflow because of the coercion. </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a <A HREF="26_1_Glossary.html#complex"
|
|
><EM CLASS="term"
|
|
>complex</EM
|
|
></A
|
|
> number or some non-numeric <A HREF="26_1_Glossary.html#object"
|
|
><EM CLASS="term"
|
|
>object</EM
|
|
></A
|
|
>, then it is printed using the format directive <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>D</CODE
|
|
>, thereby printing it in decimal radix and a minimum field width of <I CLASS="j"
|
|
><I
|
|
>w</I
|
|
></I
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~$</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
> and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H3 ID="sec_22_3_4" CLASS="HeadIII"
|
|
>22.3.4 FORMAT Printer Operations</H3
|
|
><H4 ID="sec_22_3_4_1" CLASS="HeadIV"
|
|
>22.3.4.1 Tilde A: Aesthetic</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="A (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde A (format directive)"
|
|
></SPAN
|
|
>An <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>, any <A HREF="26_1_Glossary.html#object"
|
|
><EM CLASS="term"
|
|
>object</EM
|
|
></A
|
|
>, is printed without escape characters (as by <A HREF="f_write.html" CLASS="funref"
|
|
><B
|
|
>princ</B
|
|
></A
|
|
>). If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
>, its <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>characters</EM
|
|
></A
|
|
> will be output verbatim. If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
> it will be printed as <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
>; the <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> modifier (<CODE CLASS="f"
|
|
>~:A</CODE
|
|
>) will cause an <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> of <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
> to be printed as <SPAN CLASS="cmtt"
|
|
>()</SPAN
|
|
>, but if <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a composite structure, such as a <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> or <A HREF="26_1_Glossary.html#vector"
|
|
><EM CLASS="term"
|
|
>vector</EM
|
|
></A
|
|
>, any contained occurrences of <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
> will still be printed as <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>A</CODE
|
|
> inserts spaces on the right, if necessary, to make the width at least <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
> columns. The <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier causes the spaces to be inserted on the left rather than the right. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>minpad</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>A</CODE
|
|
> is the full form of <CODE CLASS="f"
|
|
>~A</CODE
|
|
>, which allows control of the padding. The <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> is padded on the right (or on the left if the <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier is used) with at least <I CLASS="j"
|
|
><I
|
|
>minpad</I
|
|
></I
|
|
> copies of <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>; padding characters are then inserted <I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
> characters at a time until the total width is at least <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>. The defaults are <CODE CLASS="f"
|
|
>0</CODE
|
|
> for <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
> and <I CLASS="j"
|
|
><I
|
|
>minpad</I
|
|
></I
|
|
>, <CODE CLASS="f"
|
|
>1</CODE
|
|
> for <I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
>, and the space character for <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~A</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, and <A HREF="v_print-readably.html" CLASS="varref"
|
|
><B
|
|
>*print-readably*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_4_2" CLASS="HeadIV"
|
|
>22.3.4.2 Tilde S: Standard</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="S (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde S (format directive)"
|
|
></SPAN
|
|
>This is just like <CODE CLASS="f"
|
|
>~A</CODE
|
|
>, but <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is printed with escape characters (as by <A HREF="f_write.html" CLASS="funref"
|
|
><B
|
|
>prin1</B
|
|
></A
|
|
> rather than <CODE CLASS="f"
|
|
>princ</CODE
|
|
>). The output is therefore suitable for input to <A HREF="f_read.html" CLASS="funref"
|
|
><B
|
|
>read</B
|
|
></A
|
|
>. <CODE CLASS="f"
|
|
>~S</CODE
|
|
> accepts all the arguments and modifiers that <CODE CLASS="f"
|
|
>~A</CODE
|
|
> does. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~S</CODE
|
|
> binds <A HREF="v_print-escape.html" CLASS="varref"
|
|
><B
|
|
>*print-escape*</B
|
|
></A
|
|
> to <SPAN CLASS="misc"
|
|
><B
|
|
>t</B
|
|
></SPAN
|
|
>.</P
|
|
><H4 ID="sec_22_3_4_3" CLASS="HeadIV"
|
|
>22.3.4.3 Tilde W: Write</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="W (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde W (format directive)"
|
|
></SPAN
|
|
>An argument, any <A HREF="26_1_Glossary.html#object"
|
|
><EM CLASS="term"
|
|
>object</EM
|
|
></A
|
|
>, is printed obeying every printer control variable (as by <A HREF="f_write.html" CLASS="funref"
|
|
><B
|
|
>write</B
|
|
></A
|
|
>). In addition, <CODE CLASS="f"
|
|
>~W</CODE
|
|
> interacts correctly with depth abbreviation, by not resetting the depth counter to zero. <CODE CLASS="f"
|
|
>~W</CODE
|
|
> does not accept parameters. If given the <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> modifier, <CODE CLASS="f"
|
|
>~W</CODE
|
|
> binds <A HREF="v_print-pretty.html" CLASS="varref"
|
|
><B
|
|
>*print-pretty*</B
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#true"
|
|
><EM CLASS="term"
|
|
>true</EM
|
|
></A
|
|
>. If given the <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> modifier, <CODE CLASS="f"
|
|
>~W</CODE
|
|
> binds <A HREF="v_print-level.html" CLASS="varref"
|
|
><B
|
|
>*print-level*</B
|
|
></A
|
|
> and <A HREF="v_print-level.html" CLASS="varref"
|
|
><B
|
|
>*print-length*</B
|
|
></A
|
|
> to <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~W</CODE
|
|
> provides automatic support for the detection of circularity and sharing. If the <A HREF="26_1_Glossary.html#value"
|
|
><EM CLASS="term"
|
|
>value</EM
|
|
></A
|
|
> of <A HREF="v_print-circle.html" CLASS="misc"
|
|
><B
|
|
>*print-circle*</B
|
|
></A
|
|
> is not <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
> and <CODE CLASS="f"
|
|
>~W</CODE
|
|
> is applied to an argument that is a circular (or shared) reference, an appropriate <CODE CLASS="f"
|
|
>#<VAR CLASS="param"
|
|
>n</VAR
|
|
>#</CODE
|
|
> marker is inserted in the output instead of printing the argument.</P
|
|
><H3 ID="sec_22_3_5" CLASS="HeadIII"
|
|
>22.3.5 FORMAT Pretty Printer Operations</H3
|
|
><P CLASS="j"
|
|
>The following constructs provide access to the <A HREF="26_1_Glossary.html#pretty_printer"
|
|
><EM CLASS="term"
|
|
>pretty printer</EM
|
|
></A
|
|
>:</P
|
|
><H4 ID="sec_22_3_5_1" CLASS="HeadIV"
|
|
>22.3.5.1 Tilde Underscore: Conditional Newline</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Underscore (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Underscore (format directive)"
|
|
></SPAN
|
|
>Without any modifiers, <CODE CLASS="f"
|
|
>~_</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-newline :linear)</CODE
|
|
>. <CODE CLASS="f"
|
|
>~@_</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-newline :miser)</CODE
|
|
>. <CODE CLASS="f"
|
|
>~:_</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-newline :fill)</CODE
|
|
>. <CODE CLASS="f"
|
|
>~:@_</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-newline :mandatory)</CODE
|
|
>.</P
|
|
><H4 ID="sec_22_3_5_2" CLASS="HeadIV"
|
|
>22.3.5.2 Tilde Less-Than-Sign: Logical Block</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Less-Than-Sign (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Less-Than-Sign (format directive)"
|
|
></SPAN
|
|
>~<...~:></CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>If <CODE CLASS="f"
|
|
>~:></CODE
|
|
> is used to terminate a <CODE CLASS="f"
|
|
>~<...~></CODE
|
|
>, the directive is equivalent to a call to <A HREF="f_pprint-logical-block.html" CLASS="macref"
|
|
><B
|
|
>pprint-logical-block</B
|
|
></A
|
|
>. The argument corresponding to the <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
> directive is treated in the same way as the <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> argument to <A HREF="f_pprint-logical-block.html" CLASS="macref"
|
|
><B
|
|
>pprint-logical-block</B
|
|
></A
|
|
>, thereby providing automatic support for non-<A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> arguments and the detection of circularity, sharing, and depth abbreviation. The portion of the <VAR CLASS="param"
|
|
>control-string</VAR
|
|
> nested within the <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
> specifies the <SPAN CLASS="kwd"
|
|
><SPAN CLASS="cmtt"
|
|
>:prefix</SPAN
|
|
></SPAN
|
|
> (or <SPAN CLASS="kwd"
|
|
><SPAN CLASS="cmtt"
|
|
>:per-line-prefix</SPAN
|
|
></SPAN
|
|
>), <SPAN CLASS="kwd"
|
|
><SPAN CLASS="cmtt"
|
|
>:suffix</SPAN
|
|
></SPAN
|
|
>, and body of the <A HREF="f_pprint-logical-block.html" CLASS="macref"
|
|
><B
|
|
>pprint-logical-block</B
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>The <VAR CLASS="param"
|
|
>control-string</VAR
|
|
> portion enclosed by <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
> can be divided into segments <CODE CLASS="f"
|
|
>~<<VAR CLASS="param"
|
|
>prefix</VAR
|
|
>~;<VAR CLASS="param"
|
|
>body</VAR
|
|
>~;<VAR CLASS="param"
|
|
>suffix</VAR
|
|
>~:></CODE
|
|
> by <CODE CLASS="f"
|
|
>~;</CODE
|
|
> directives. If the first section is terminated by <CODE CLASS="f"
|
|
>~@;</CODE
|
|
>, it specifies a per-line prefix rather than a simple prefix. The <VAR CLASS="param"
|
|
>prefix</VAR
|
|
> and <VAR CLASS="param"
|
|
>suffix</VAR
|
|
> cannot contain format directives. An error is signaled if either the prefix or suffix fails to be a constant string or if the enclosed portion is divided into more than three segments. </P
|
|
><P CLASS="j"
|
|
>If the enclosed portion is divided into only two segments, the <VAR CLASS="param"
|
|
>suffix</VAR
|
|
> defaults to the null string. If the enclosed portion consists of only a single segment, both the <VAR CLASS="param"
|
|
>prefix</VAR
|
|
> and the <VAR CLASS="param"
|
|
>suffix</VAR
|
|
> default to the null string. If the <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> modifier is used (<I CLASS="i"
|
|
><I
|
|
>i.e.</I
|
|
></I
|
|
>, <CODE CLASS="f"
|
|
>~:<...~:></CODE
|
|
>), the <VAR CLASS="param"
|
|
>prefix</VAR
|
|
> and <VAR CLASS="param"
|
|
>suffix</VAR
|
|
> default to <CODE CLASS="f"
|
|
>"("</CODE
|
|
> and <CODE CLASS="f"
|
|
>")"</CODE
|
|
> (respectively) instead of the null string. </P
|
|
><P CLASS="j"
|
|
>The body segment can be any arbitrary <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
>. This <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
> is applied to the elements of the list corresponding to the <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
> directive as a whole. Elements are extracted from this list using <A HREF="f_pprint-pop.html" CLASS="macref"
|
|
><B
|
|
>pprint-pop</B
|
|
></A
|
|
>, thereby providing automatic support for malformed lists, and the detection of circularity, sharing, and length abbreviation. Within the body segment, <CODE CLASS="f"
|
|
>~^</CODE
|
|
> acts like <A HREF="f_pprint-exit-if-list-exhausted.html" CLASS="macref"
|
|
><B
|
|
>pprint-exit-if-list-exhausted</B
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
> supports a feature not supported by <A HREF="f_pprint-logical-block.html" CLASS="macref"
|
|
><B
|
|
>pprint-logical-block</B
|
|
></A
|
|
>. If <CODE CLASS="f"
|
|
>~:@></CODE
|
|
> is used to terminate the directive (<I CLASS="i"
|
|
><I
|
|
>i.e.</I
|
|
></I
|
|
>, <CODE CLASS="f"
|
|
>~<...~:@></CODE
|
|
>), then a fill-style conditional newline is automatically inserted after each group of blanks immediately contained in the body (except for blanks after a  ⟨<I
|
|
>Newline</I
|
|
>⟩ directive). This makes it easy to achieve the equivalent of paragraph filling. </P
|
|
><P CLASS="j"
|
|
>If the <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> modifier is used with <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
>, the entire remaining argument list is passed to the directive as its argument. All of the remaining arguments are always consumed by <CODE CLASS="f"
|
|
>~@<...~:></CODE
|
|
>, even if they are not all used by the <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
> nested in the directive. Other than the difference in its argument, <CODE CLASS="f"
|
|
>~@<...~:></CODE
|
|
> is exactly the same as <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
> except that circularity detection is not applied if <CODE CLASS="f"
|
|
>~@<...~:></CODE
|
|
> is encountered at top level in a <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
>. This ensures that circularity detection is applied only to data lists, not to <A HREF="26_1_Glossary.html#format_argument"
|
|
><EM CLASS="term"
|
|
>format argument</EM
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>lists</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>" . #<VAR CLASS="param"
|
|
>n</VAR
|
|
>#"</CODE
|
|
> is printed if circularity or sharing has to be indicated for its argument as a whole. </P
|
|
><P CLASS="j"
|
|
>To a considerable extent, the basic form of the directive <CODE CLASS="f"
|
|
>~<...~></CODE
|
|
> is incompatible with the dynamic control of the arrangement of output by <CODE CLASS="f"
|
|
>~W</CODE
|
|
>, <CODE CLASS="f"
|
|
>~_</CODE
|
|
>, <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
>, <CODE CLASS="f"
|
|
>~I</CODE
|
|
>, and <CODE CLASS="f"
|
|
>~:T</CODE
|
|
>. As a result, an error is signaled if any of these directives is nested within <CODE CLASS="f"
|
|
>~<...~></CODE
|
|
>. Beyond this, an error is also signaled if the <CODE CLASS="f"
|
|
>~<...~:;...~></CODE
|
|
> form of <CODE CLASS="f"
|
|
>~<...~></CODE
|
|
> is used in the same <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
> with <CODE CLASS="f"
|
|
>~W</CODE
|
|
>, <CODE CLASS="f"
|
|
>~_</CODE
|
|
>, <CODE CLASS="f"
|
|
>~<...~:></CODE
|
|
>, <CODE CLASS="f"
|
|
>~I</CODE
|
|
>, or <CODE CLASS="f"
|
|
>~:T</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
>See also <A HREF="22_3_Formatted_Output.html#sec_22_3_6_2" CLASS="secref"
|
|
><SPAN CLASS="cmr"
|
|
>Section</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>22.3.6.2</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>(Tilde</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>Less-Than-Sign:</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>Justification)</SPAN
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_5_3" CLASS="HeadIV"
|
|
>22.3.5.3 Tilde I: Indent</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="I (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde I (format directive)"
|
|
></SPAN
|
|
>~<VAR CLASS="param"
|
|
>n</VAR
|
|
>I</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-indent :block n)</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<VAR CLASS="param"
|
|
>n</VAR
|
|
>:I</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-indent :current n)</CODE
|
|
>. In both cases, <VAR CLASS="param"
|
|
>n</VAR
|
|
> defaults to zero, if it is omitted.</P
|
|
><H4 ID="sec_22_3_5_4" CLASS="HeadIV"
|
|
>22.3.5.4 Tilde Slash: Call Function</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Slash (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Slash (format directive)"
|
|
></SPAN
|
|
>~/<VAR CLASS="param"
|
|
>name</VAR
|
|
>/</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>User defined functions can be called from within a format string by using the directive <CODE CLASS="f"
|
|
>~/<VAR CLASS="param"
|
|
>name</VAR
|
|
>/</CODE
|
|
>. The <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> modifier, the <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> modifier, and arbitrarily many parameters can be specified with the <CODE CLASS="f"
|
|
>~/<VAR CLASS="param"
|
|
>name</VAR
|
|
>/</CODE
|
|
> directive. <VAR CLASS="param"
|
|
>name</VAR
|
|
> can be any arbitrary string that does not contain a ”/”. All of the characters in <VAR CLASS="param"
|
|
>name</VAR
|
|
> are treated as if they were upper case. If <VAR CLASS="param"
|
|
>name</VAR
|
|
> contains a single <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> (<CODE CLASS="f"
|
|
>:</CODE
|
|
>) or double <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> (<CODE CLASS="f"
|
|
>::</CODE
|
|
>), then everything up to but not including the first <CODE CLASS="f"
|
|
>":"</CODE
|
|
> or <CODE CLASS="f"
|
|
>"::"</CODE
|
|
> is taken to be a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> that names a <A HREF="26_1_Glossary.html#package"
|
|
><EM CLASS="term"
|
|
>package</EM
|
|
></A
|
|
>. Everything after the first <CODE CLASS="f"
|
|
>":"</CODE
|
|
> or <CODE CLASS="f"
|
|
>"::"</CODE
|
|
> (if any) is taken to be a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> that names a <CODE CLASS="f"
|
|
>symbol</CODE
|
|
>. The function corresponding to a <CODE CLASS="f"
|
|
>~/name/</CODE
|
|
> directive is obtained by looking up the <A HREF="26_1_Glossary.html#symbol"
|
|
><EM CLASS="term"
|
|
>symbol</EM
|
|
></A
|
|
> that has the indicated name in the indicated <A HREF="26_1_Glossary.html#package"
|
|
><EM CLASS="term"
|
|
>package</EM
|
|
></A
|
|
>. If <VAR CLASS="param"
|
|
>name</VAR
|
|
> does not contain a <CODE CLASS="f"
|
|
>":"</CODE
|
|
> or <CODE CLASS="f"
|
|
>"::"</CODE
|
|
>, then the whole <VAR CLASS="param"
|
|
>name</VAR
|
|
> string is looked up in the <SPAN CLASS="packref"
|
|
><SPAN CLASS="cmtt"
|
|
>COMMON-LISP-USER</SPAN
|
|
></SPAN
|
|
> <A HREF="26_1_Glossary.html#package"
|
|
><EM CLASS="term"
|
|
>package</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>When a <CODE CLASS="f"
|
|
>~/name/</CODE
|
|
> directive is encountered, the indicated function is called with four or more arguments. The first four arguments are: the output stream, the <A HREF="26_1_Glossary.html#format_argument"
|
|
><EM CLASS="term"
|
|
>format argument</EM
|
|
></A
|
|
> corresponding to the directive, a <A HREF="26_1_Glossary.html#generalized_boolean"
|
|
><EM CLASS="term"
|
|
>generalized boolean</EM
|
|
></A
|
|
> that is <A HREF="26_1_Glossary.html#true"
|
|
><EM CLASS="term"
|
|
>true</EM
|
|
></A
|
|
> if the <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> modifier was used, and a <A HREF="26_1_Glossary.html#generalized_boolean"
|
|
><EM CLASS="term"
|
|
>generalized boolean</EM
|
|
></A
|
|
> that is <A HREF="26_1_Glossary.html#true"
|
|
><EM CLASS="term"
|
|
>true</EM
|
|
></A
|
|
> if the <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> modifier was used. The remaining arguments consist of any parameters specified with the directive. The function should print the argument appropriately. Any values returned by the function are ignored. </P
|
|
><P CLASS="j"
|
|
>The three <A HREF="26_1_Glossary.html#function"
|
|
><EM CLASS="term"
|
|
>functions</EM
|
|
></A
|
|
> <A HREF="f_pprint-fill.html" CLASS="funref"
|
|
><B
|
|
>pprint-linear</B
|
|
></A
|
|
>, <A HREF="f_pprint-fill.html" CLASS="funref"
|
|
><B
|
|
>pprint-fill</B
|
|
></A
|
|
>, and <A HREF="f_pprint-fill.html" CLASS="funref"
|
|
><B
|
|
>pprint-tabular</B
|
|
></A
|
|
> are specifically designed so that they can be called by <CODE CLASS="f"
|
|
>~/.../</CODE
|
|
> (<I CLASS="i"
|
|
><I
|
|
>i.e.</I
|
|
></I
|
|
>, <CODE CLASS="f"
|
|
>~/pprint-linear/</CODE
|
|
>, <CODE CLASS="f"
|
|
>~/pprint-fill/</CODE
|
|
>, and <CODE CLASS="f"
|
|
>~/pprint-tabular/</CODE
|
|
>). In particular they take <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> and <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> arguments.</P
|
|
><H3 ID="sec_22_3_6" CLASS="HeadIII"
|
|
>22.3.6 FORMAT Layout Control</H3
|
|
><H4 ID="sec_22_3_6_1" CLASS="HeadIV"
|
|
>22.3.6.1 Tilde T: Tabulate</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="T (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde T (format directive)"
|
|
></SPAN
|
|
>This spaces over to a given column. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>colnum</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
>T</CODE
|
|
> will output sufficient spaces to move the cursor to column <I CLASS="j"
|
|
><I
|
|
>colnum</I
|
|
></I
|
|
>. If the cursor is already at or beyond column <I CLASS="j"
|
|
><I
|
|
>colnum</I
|
|
></I
|
|
>, it will output spaces to move it to column <I CLASS="j"
|
|
><I
|
|
>colnum</I
|
|
></I
|
|
>+<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>*<I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
> for the smallest positive integer <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
> possible, unless <I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
> is zero, in which case no spaces are output if the cursor is already at or beyond column <I CLASS="j"
|
|
><I
|
|
>colnum</I
|
|
></I
|
|
>. <I CLASS="j"
|
|
><I
|
|
>colnum</I
|
|
></I
|
|
> and <I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
> default to <CODE CLASS="f"
|
|
>1</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
>If for some reason the current absolute column position cannot be determined by direct inquiry, <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> may be able to deduce the current column position by noting that certain directives (such as <CODE CLASS="f"
|
|
>~%</CODE
|
|
>, or <CODE CLASS="f"
|
|
>~&</CODE
|
|
>, or <CODE CLASS="f"
|
|
>~A</CODE
|
|
> with the argument being a string containing a newline) cause the column position to be reset to zero, and counting the number of characters emitted since that point. If that fails, <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> may attempt a similar deduction on the riskier assumption that the destination was at column zero when <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> was invoked. If even this heuristic fails or is implementationally inconvenient, at worst the <CODE CLASS="f"
|
|
>~T</CODE
|
|
> operation will simply output two spaces. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@T</CODE
|
|
> performs relative tabulation. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>colrel</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
>@T</CODE
|
|
> outputs <I CLASS="j"
|
|
><I
|
|
>colrel</I
|
|
></I
|
|
> spaces and then outputs the smallest non-negative number of additional spaces necessary to move the cursor to a column that is a multiple of <I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
>. For example, the directive <CODE CLASS="f"
|
|
>~3,8@T</CODE
|
|
> outputs three spaces and then moves the cursor to a “standard multiple-of-eight tab stop” if not at one already. If the current output column cannot be determined, however, then <I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
> is ignored, and exactly <I CLASS="j"
|
|
><I
|
|
>colrel</I
|
|
></I
|
|
> spaces are output. </P
|
|
><P CLASS="j"
|
|
>If the <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> modifier is used with the <CODE CLASS="f"
|
|
>~T</CODE
|
|
> directive, the tabbing computation is done relative to the horizontal position where the section immediately containing the directive begins, rather than with respect to a horizontal position of zero. The numerical parameters are both interpreted as being in units of <A HREF="26_1_Glossary.html#em"
|
|
><EM CLASS="term"
|
|
>ems</EM
|
|
></A
|
|
> and both default to <CODE CLASS="f"
|
|
>1</CODE
|
|
>. <CODE CLASS="f"
|
|
>~<VAR CLASS="param"
|
|
>n</VAR
|
|
>,<VAR CLASS="param"
|
|
>m</VAR
|
|
>:T</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-tab :section <VAR CLASS="param"
|
|
>n</VAR
|
|
> <VAR CLASS="param"
|
|
>m</VAR
|
|
>)</CODE
|
|
>. <CODE CLASS="f"
|
|
>~<VAR CLASS="param"
|
|
>n</VAR
|
|
>,<VAR CLASS="param"
|
|
>m</VAR
|
|
>:@T</CODE
|
|
> is the same as <CODE CLASS="f"
|
|
>(pprint-tab :section-relative <VAR CLASS="param"
|
|
>n</VAR
|
|
> <VAR CLASS="param"
|
|
>m</VAR
|
|
>)</CODE
|
|
>.</P
|
|
><H4 ID="sec_22_3_6_2" CLASS="HeadIV"
|
|
>22.3.6.2 Tilde Less-Than-Sign: Justification</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Less-Than-Sign (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Less-Than-Sign (format directive)"
|
|
></SPAN
|
|
>~<I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>minpad</I
|
|
></I
|
|
>,<I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
><<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~></CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>This justifies the text produced by processing <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> within a field at least <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
> columns wide. <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> may be divided up into segments with <CODE CLASS="f"
|
|
>~;</CODE
|
|
>, in which case the spacing is evenly divided between the text segments. </P
|
|
><P CLASS="j"
|
|
>With no modifiers, the leftmost text segment is left justified in the field, and the rightmost text segment is right justified. If there is only one text element, as a special case, it is right justified. The <CODE CLASS="f"
|
|
>:</CODE
|
|
> modifier causes spacing to be introduced before the first text segment; the <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier causes spacing to be added after the last. The <I CLASS="j"
|
|
><I
|
|
>minpad</I
|
|
></I
|
|
> parameter (default <CODE CLASS="f"
|
|
>0</CODE
|
|
>) is the minimum number of padding characters to be output between each segment. The padding character is supplied by <I CLASS="j"
|
|
><I
|
|
>padchar</I
|
|
></I
|
|
>, which defaults to the space character. If the total width needed to satisfy these constraints is greater than <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>, then the width used is <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
>+<I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>*<I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
> for the smallest possible non-negative integer value <I CLASS="j"
|
|
><I
|
|
>k</I
|
|
></I
|
|
>. <I CLASS="j"
|
|
><I
|
|
>colinc</I
|
|
></I
|
|
> defaults to <CODE CLASS="f"
|
|
>1</CODE
|
|
>, and <I CLASS="j"
|
|
><I
|
|
>mincol</I
|
|
></I
|
|
> defaults to <CODE CLASS="f"
|
|
>0</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
>Note that <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> may include <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> directives. All the clauses in <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> are processed in order; it is the resulting pieces of text that are justified. </P
|
|
><P CLASS="j"
|
|
>The <CODE CLASS="f"
|
|
>~^</CODE
|
|
> directive may be used to terminate processing of the clauses prematurely, in which case only the completely processed clauses are justified. </P
|
|
><P CLASS="j"
|
|
>If the first clause of a <CODE CLASS="f"
|
|
>~<</CODE
|
|
> is terminated with <CODE CLASS="f"
|
|
>~:;</CODE
|
|
> instead of <CODE CLASS="f"
|
|
>~;</CODE
|
|
>, then it is used in a special way. All of the clauses are processed (subject to <CODE CLASS="f"
|
|
>~^</CODE
|
|
>, of course), but the first one is not used in performing the spacing and padding. When the padded result has been determined, then if it will fit on the current line of output, it is output, and the text for the first clause is discarded. If, however, the padded text will not fit on the current line, then the text segment for the first clause is output before the padded text. The first clause ought to contain a newline (such as a <CODE CLASS="f"
|
|
>~%</CODE
|
|
> directive). The first clause is always processed, and so any arguments it refers to will be used; the decision is whether to use the resulting segment of text, not whether to process the first clause. If the <CODE CLASS="f"
|
|
>~:;</CODE
|
|
> has a prefix parameter <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>, then the padded text must fit on the current line with <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> character positions to spare to avoid outputting the first clause’s text. For example, the control string</P
|
|
><PRE CLASS="screen"
|
|
>"~%;; ~{~<~%;; ~1:; ~S~>~^,~}.~%"</PRE
|
|
><P CLASS="j"
|
|
>can be used to print a list of items separated by commas without breaking items over line boundaries, beginning each line with <CODE CLASS="f"
|
|
>;;</CODE
|
|
> . The prefix parameter <CODE CLASS="f"
|
|
>1</CODE
|
|
> in <CODE CLASS="f"
|
|
>~1:;</CODE
|
|
> accounts for the width of the comma that will follow the justified item if it is not the last element in the list, or the period if it is. If <CODE CLASS="f"
|
|
>~:;</CODE
|
|
> has a second prefix parameter, then it is used as the width of the line, thus overriding the natural line width of the output stream. To make the preceding example use a line width of 50, one would write</P
|
|
><PRE CLASS="screen"
|
|
>"~%;; ~{~<~%;; ~1,50:; ~S~>~^,~} .~%"</PRE
|
|
><P CLASS="j"
|
|
>If the second argument is not supplied, then <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> uses the line width of the <VAR CLASS="param"
|
|
>destination</VAR
|
|
> output stream. If this cannot be determined (for example, when producing a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> result), then <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> uses <CODE CLASS="f"
|
|
>72</CODE
|
|
> as the line length. </P
|
|
><P CLASS="j"
|
|
>See also <A HREF="22_3_Formatted_Output.html#sec_22_3_5_2" CLASS="secref"
|
|
><SPAN CLASS="cmr"
|
|
>Section</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>22.3.5.2</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>(Tilde</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>Less-Than-Sign:</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>Logical</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>Block)</SPAN
|
|
></A
|
|
>.</P
|
|
><H4 ID="sec_22_3_6_3" CLASS="HeadIV"
|
|
>22.3.6.3 Tilde Greater-Than-Sign: End of Justification</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Greater-Than-Sign (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Greater-Than-Sign (format directive)"
|
|
></SPAN
|
|
>~></CODE
|
|
> terminates a <CODE CLASS="f"
|
|
>~<</CODE
|
|
>. The consequences of using it elsewhere are undefined.</P
|
|
><H3 ID="sec_22_3_7" CLASS="HeadIII"
|
|
>22.3.7 FORMAT Control-Flow Operations</H3
|
|
><H4 ID="sec_22_3_7_1" CLASS="HeadIV"
|
|
>22.3.7.1 Tilde Asterisk: Go-To</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Asterisk (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Asterisk (format directive)"
|
|
></SPAN
|
|
>The next <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is ignored. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>*</CODE
|
|
> ignores the next <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> arguments. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:*</CODE
|
|
> backs up in the list of arguments so that the argument last processed will be processed again. <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>:*</CODE
|
|
> backs up <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> arguments. </P
|
|
><P CLASS="j"
|
|
>When within a <CODE CLASS="f"
|
|
>~{</CODE
|
|
> construct (see below), the ignoring (in either direction) is relative to the list of arguments being processed by the iteration. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>@*</CODE
|
|
> goes to the <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>th <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>, where 0 means the first one; <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> defaults to 0, so <CODE CLASS="f"
|
|
>~@*</CODE
|
|
> goes back to the first <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>. Directives after a <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>@*</CODE
|
|
> will take arguments in sequence beginning with the one gone to. When within a <CODE CLASS="f"
|
|
>~{</CODE
|
|
> construct, the “goto” is relative to the list of arguments being processed by the iteration.</P
|
|
><H4 ID="sec_22_3_7_2" CLASS="HeadIV"
|
|
>22.3.7.2 Tilde Left-Bracket: Conditional Expression</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Left-Bracket (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Left-Bracket (format directive)"
|
|
></SPAN
|
|
>~[<I CLASS="j"
|
|
><I
|
|
>str0</I
|
|
></I
|
|
>~;<I CLASS="j"
|
|
><I
|
|
>str1</I
|
|
></I
|
|
>~;<I CLASS="j"
|
|
><I
|
|
>...</I
|
|
></I
|
|
>~;<I CLASS="j"
|
|
><I
|
|
>strn</I
|
|
></I
|
|
>~]</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>This is a set of control strings, called <I CLASS="j"
|
|
><I
|
|
>clauses</I
|
|
></I
|
|
>, one of which is chosen and used. The clauses are separated by <CODE CLASS="f"
|
|
>~;</CODE
|
|
> and the construct is terminated by <CODE CLASS="f"
|
|
>~]</CODE
|
|
>. For example, </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>"~[Siamese~;Manx~;Persian~] Cat"</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>The <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
>th clause is selected, where the first clause is number 0. If a prefix parameter is given (as <CODE CLASS="f"
|
|
>~<I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
>[</CODE
|
|
>), then the parameter is used instead of an argument. If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is out of range then no clause is selected and no error is signaled. After the selected alternative has been processed, the control string continues after the <CODE CLASS="f"
|
|
>~]</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~[<I CLASS="j"
|
|
><I
|
|
>str0</I
|
|
></I
|
|
>~;<I CLASS="j"
|
|
><I
|
|
>str1</I
|
|
></I
|
|
>~;<I CLASS="j"
|
|
><I
|
|
>...</I
|
|
></I
|
|
>~;<I CLASS="j"
|
|
><I
|
|
>strn</I
|
|
></I
|
|
>~:;<I CLASS="j"
|
|
><I
|
|
>default</I
|
|
></I
|
|
>~]</CODE
|
|
> has a default case. If the <I CLASS="j"
|
|
><I
|
|
>last</I
|
|
></I
|
|
> <CODE CLASS="f"
|
|
>~;</CODE
|
|
> used to separate clauses is <CODE CLASS="f"
|
|
>~:;</CODE
|
|
> instead, then the last clause is an else clause that is performed if no other clause is selected. For example: </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>"~[Siamese~;Manx~;Persian~:;Alley~] Cat"</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:[<VAR CLASS="param"
|
|
>alternative</VAR
|
|
>~;<VAR CLASS="param"
|
|
>consequent</VAR
|
|
>~]</CODE
|
|
> selects the <VAR CLASS="param"
|
|
>alternative</VAR
|
|
> control string if <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, and selects the <VAR CLASS="param"
|
|
>consequent</VAR
|
|
> control string otherwise. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@[<VAR CLASS="param"
|
|
>consequent</VAR
|
|
>~]</CODE
|
|
> tests the argument. If it is <A HREF="26_1_Glossary.html#true"
|
|
><EM CLASS="term"
|
|
>true</EM
|
|
></A
|
|
>, then the argument is not used up by the <CODE CLASS="f"
|
|
>~[</CODE
|
|
> command but remains as the next one to be processed, and the one clause <VAR CLASS="param"
|
|
>consequent</VAR
|
|
> is processed. If the <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is <A HREF="26_1_Glossary.html#false"
|
|
><EM CLASS="term"
|
|
>false</EM
|
|
></A
|
|
>, then the argument is used up, and the clause is not processed. The clause therefore should normally use exactly one argument, and may expect it to be <A HREF="26_1_Glossary.html#non-nil"
|
|
><EM CLASS="term"
|
|
>non-nil</EM
|
|
></A
|
|
>. For example:</P
|
|
><PRE CLASS="screen"
|
|
> (setq *print-level* nil *print-length* 5)
|
|
(format nil
|
|
"~@[ print level = ~D~]~@[ print length = ~D~]"
|
|
*print-level* *print-length*)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " print length = 5"</PRE
|
|
><P CLASS="j"
|
|
>Note also that</P
|
|
><PRE CLASS="screen"
|
|
> (format <VAR CLASS="param"
|
|
>stream</VAR
|
|
> "...~@[<VAR CLASS="param"
|
|
>str</VAR
|
|
>~]..." ...)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN STYLE="font-size:16px;vertical-align:-2px"
|
|
>≡</SPAN
|
|
></SPAN
|
|
> (format <VAR CLASS="param"
|
|
>stream</VAR
|
|
> "...~:[~;~:*<VAR CLASS="param"
|
|
>str</VAR
|
|
>~]..." ...)</PRE
|
|
><P CLASS="j"
|
|
>The combination of <CODE CLASS="f"
|
|
>~[</CODE
|
|
> and <CODE CLASS="f"
|
|
>#</CODE
|
|
> is useful, for example, for dealing with English conventions for printing lists:</P
|
|
><PRE CLASS="screen"
|
|
>(setq foo "Items:~#[ none~; ~S~; ~S and ~S~
|
|
~:;~@{~#[~; and~] ~S~^,~}~].")
|
|
(format nil foo) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Items: none."
|
|
(format nil foo 'foo) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Items: FOO."
|
|
(format nil foo 'foo 'bar) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Items: FOO and BAR."
|
|
(format nil foo 'foo 'bar 'baz) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Items: FOO, BAR, and BAZ."
|
|
(format nil foo 'foo 'bar 'baz 'quux) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Items: FOO, BAR, BAZ, and QUUX."</PRE
|
|
><H4 ID="sec_22_3_7_3" CLASS="HeadIV"
|
|
>22.3.7.3 Tilde Right-Bracket: End of Conditional Expression</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Right-Bracket (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Right-Bracket (format directive)"
|
|
></SPAN
|
|
>~]</CODE
|
|
> terminates a <CODE CLASS="f"
|
|
>~[</CODE
|
|
>. The consequences of using it elsewhere are undefined.</P
|
|
><H4 ID="sec_22_3_7_4" CLASS="HeadIV"
|
|
>22.3.7.4 Tilde Left-Brace: Iteration</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Left-Brace (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Left-Brace (format directive)"
|
|
></SPAN
|
|
>~{<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~}</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>This is an iteration construct. The argument should be a <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
>, which is used as a set of arguments as if for a recursive call to <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
>. The <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
> <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> is used repeatedly as the control string. Each iteration can absorb as many elements of the <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> as it likes as arguments; if <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> uses up two arguments by itself, then two elements of the <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> will get used up each time around the loop. If before any iteration step the <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> is empty, then the iteration is terminated. Also, if a prefix parameter <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> is given, then there will be at most <I CLASS="j"
|
|
><I
|
|
>n</I
|
|
></I
|
|
> repetitions of processing of <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>. Finally, the <CODE CLASS="f"
|
|
>~^</CODE
|
|
> directive can be used to terminate the iteration prematurely. </P
|
|
><P CLASS="j"
|
|
>For example:</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "The winners are:~{ ~S~}."
|
|
'(fred harry jill))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "The winners are: FRED HARRY JILL."
|
|
(format nil "Pairs:~{ <~S,~S>~}."
|
|
'(a 1 b 2 c 3))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Pairs: <A,1> <B,2> <C,3>."</PRE
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:{<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~}</CODE
|
|
> is similar, but the argument should be a <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> of sublists. At each repetition step, one sublist is used as the set of arguments for processing <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>; on the next repetition, a new sublist is used, whether or not all of the last sublist had been processed. For example:</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "Pairs:~:{ <~S,~S>~}."
|
|
'((a 1) (b 2) (c 3)))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Pairs: <A,1> <B,2> <C,3>."</PRE
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@{<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~}</CODE
|
|
> is similar to <CODE CLASS="f"
|
|
>~{<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~}</CODE
|
|
>, but instead of using one argument that is a list, all the remaining arguments are used as the list of arguments for the iteration. Example:</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "Pairs:~@{ <~S,~S>~}." 'a 1 'b 2 'c 3)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Pairs: <A,1> <B,2> <C,3>."</PRE
|
|
><P CLASS="j"
|
|
>If the iteration is terminated before all the remaining arguments are consumed, then any arguments not processed by the iteration remain to be processed by any directives following the iteration construct. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:@{<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~}</CODE
|
|
> combines the features of <CODE CLASS="f"
|
|
>~:{<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~}</CODE
|
|
> and <CODE CLASS="f"
|
|
>~@{<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~}</CODE
|
|
>. All the remaining arguments are used, and each one must be a <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
>. On each iteration, the next argument is used as a <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> of arguments to <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>. Example:</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "Pairs:~:@{ <~S,~S>~}."
|
|
'(a 1) '(b 2) '(c 3))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Pairs: <A,1> <B,2> <C,3>."</PRE
|
|
><P CLASS="j"
|
|
>Terminating the repetition construct with <CODE CLASS="f"
|
|
>~:}</CODE
|
|
> instead of <CODE CLASS="f"
|
|
>~}</CODE
|
|
> forces <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> to be processed at least once, even if the initial list of arguments is null. However, this will not override an explicit prefix parameter of zero. </P
|
|
><P CLASS="j"
|
|
>If <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> is empty, then an argument is used as <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>. It must be a <A HREF="26_1_Glossary.html#format_control"
|
|
><EM CLASS="term"
|
|
>format control</EM
|
|
></A
|
|
> and precede any arguments processed by the iteration. As an example, the following are equivalent:</P
|
|
><PRE CLASS="screen"
|
|
> (apply #'format stream string arguments)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN STYLE="font-size:16px;vertical-align:-2px"
|
|
>≡</SPAN
|
|
></SPAN
|
|
> (format stream "~1{~:}" string arguments)</PRE
|
|
><P CLASS="j"
|
|
>This will use <CODE CLASS="f"
|
|
>string</CODE
|
|
> as a formatting string. The <CODE CLASS="f"
|
|
>~1{</CODE
|
|
> says it will be processed at most once, and the <CODE CLASS="f"
|
|
>~:}</CODE
|
|
> says it will be processed at least once. Therefore it is processed exactly once, using <CODE CLASS="f"
|
|
>arguments</CODE
|
|
> as the arguments. This case may be handled more clearly by the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive, but this general feature of <CODE CLASS="f"
|
|
>~{</CODE
|
|
> is more powerful than <CODE CLASS="f"
|
|
>~?</CODE
|
|
>.</P
|
|
><H4 ID="sec_22_3_7_5" CLASS="HeadIV"
|
|
>22.3.7.5 Tilde Right-Brace: End of Iteration</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Right-Brace (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Right-Brace (format directive)"
|
|
></SPAN
|
|
>~}</CODE
|
|
> terminates a <CODE CLASS="f"
|
|
>~{</CODE
|
|
>. The consequences of using it elsewhere are undefined.</P
|
|
><H4 ID="sec_22_3_7_6" CLASS="HeadIV"
|
|
>22.3.7.6 Tilde Question-Mark: Recursive Processing</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Question-Mark (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Question-Mark (format directive)"
|
|
></SPAN
|
|
>The next <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> must be a <A HREF="26_1_Glossary.html#format_control"
|
|
><EM CLASS="term"
|
|
>format control</EM
|
|
></A
|
|
>, and the one after it a <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
>; both are consumed by the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive. The two are processed as a <VAR CLASS="param"
|
|
>control-string</VAR
|
|
>, with the elements of the <A HREF="26_1_Glossary.html#list"
|
|
><EM CLASS="term"
|
|
>list</EM
|
|
></A
|
|
> as the arguments. Once the recursive processing has been finished, the processing of the control string containing the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive is resumed. Example:</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~? ~D" "<~A ~D>" '("Foo" 5) 7) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "<Foo 5> 7"
|
|
(format nil "~? ~D" "<~A ~D>" '("Foo" 5 14) 7) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "<Foo 5> 7"</PRE
|
|
><P CLASS="j"
|
|
>Note that in the second example three arguments are supplied to the <A HREF="26_1_Glossary.html#format_string"
|
|
><EM CLASS="term"
|
|
>format string</EM
|
|
></A
|
|
> <CODE CLASS="f"
|
|
>"<~A ~D>"</CODE
|
|
>, but only two are processed and the third is therefore ignored. </P
|
|
><P CLASS="j"
|
|
>With the <CODE CLASS="f"
|
|
>@</CODE
|
|
> modifier, only one <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is directly consumed. The <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> must be a <A HREF="26_1_Glossary.html#string"
|
|
><EM CLASS="term"
|
|
>string</EM
|
|
></A
|
|
>; it is processed as part of the control string as if it had appeared in place of the <CODE CLASS="f"
|
|
>~@?</CODE
|
|
> construct, and any directives in the recursively processed control string may consume arguments of the control string containing the <CODE CLASS="f"
|
|
>~@?</CODE
|
|
> directive. Example:</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~@? ~D" "<~A ~D>" "Foo" 5 7) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "<Foo 5> 7"
|
|
(format nil "~@? ~D" "<~A ~D>" "Foo" 5 14 7) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "<Foo 5> 14"</PRE
|
|
><H3 ID="sec_22_3_8" CLASS="HeadIII"
|
|
>22.3.8 FORMAT Miscellaneous Operations</H3
|
|
><H4 ID="sec_22_3_8_1" CLASS="HeadIV"
|
|
>22.3.8.1 Tilde Left-Paren: Case Conversion</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Left-Paren (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Left-Paren (format directive)"
|
|
></SPAN
|
|
>~(<I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
>~)</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>The contained control string <I CLASS="j"
|
|
><I
|
|
>str</I
|
|
></I
|
|
> is processed, and what it produces is subject to case conversion. </P
|
|
><P CLASS="j"
|
|
>With no flags, every <A HREF="26_1_Glossary.html#uppercase"
|
|
><EM CLASS="term"
|
|
>uppercase</EM
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
> is converted to the corresponding <A HREF="26_1_Glossary.html#lowercase"
|
|
><EM CLASS="term"
|
|
>lowercase</EM
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#character"
|
|
><EM CLASS="term"
|
|
>character</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:(</CODE
|
|
> capitalizes all words, as if by <A HREF="f_string-upcase.html" CLASS="funref"
|
|
><B
|
|
>string-capitalize</B
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@(</CODE
|
|
> capitalizes just the first word and forces the rest to lower case. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:@(</CODE
|
|
> converts every lowercase character to the corresponding uppercase character. </P
|
|
><P CLASS="j"
|
|
>In this example <CODE CLASS="f"
|
|
>~@(</CODE
|
|
> is used to cause the first word produced by <CODE CLASS="f"
|
|
>~@R</CODE
|
|
> to be capitalized:</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "~@R ~(~@R~)" 14 14)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "XIV xiv"
|
|
(defun f (n) (format nil "~@(~R~) error~:P detected." n)) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> F
|
|
(f 0) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Zero errors detected."
|
|
(f 1) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "One error detected."
|
|
(f 23) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Twenty-three errors detected."</PRE
|
|
><P CLASS="j"
|
|
>When case conversions appear nested, the outer conversion dominates, as illustrated in the following example:</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~@(how is ~:(BOB SMITH~)?~)")
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "How is bob smith?"
|
|
<SPAN CLASS="sp"
|
|
><SPAN CLASS="arrow withabove"
|
|
><SPAN CLASS="above"
|
|
>not </SPAN
|
|
>→</SPAN
|
|
></SPAN
|
|
> "How is Bob Smith?"</PRE
|
|
><H4 ID="sec_22_3_8_2" CLASS="HeadIV"
|
|
>22.3.8.2 Tilde Right-Paren: End of Case Conversion</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Right-Paren (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Right-Paren (format directive)"
|
|
></SPAN
|
|
>~)</CODE
|
|
> terminates a <CODE CLASS="f"
|
|
>~(</CODE
|
|
>. The consequences of using it elsewhere are undefined.</P
|
|
><H4 ID="sec_22_3_8_3" CLASS="HeadIV"
|
|
>22.3.8.3 Tilde P: Plural</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="P (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde P (format directive)"
|
|
></SPAN
|
|
>If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is not <A HREF="f_eql.html" CLASS="funref"
|
|
><B
|
|
>eql</B
|
|
></A
|
|
> to the integer <CODE CLASS="f"
|
|
>1</CODE
|
|
>, a lowercase <CODE CLASS="f"
|
|
>s</CODE
|
|
> is printed; if <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is <A HREF="f_eql.html" CLASS="funref"
|
|
><B
|
|
>eql</B
|
|
></A
|
|
> to <CODE CLASS="f"
|
|
>1</CODE
|
|
>, nothing is printed. If <I CLASS="j"
|
|
><I
|
|
>arg</I
|
|
></I
|
|
> is a floating-point <CODE CLASS="f"
|
|
>1.0</CODE
|
|
>, the <CODE CLASS="f"
|
|
>s</CODE
|
|
> is printed. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~:P</CODE
|
|
> does the same thing, after doing a <CODE CLASS="f"
|
|
>~:*</CODE
|
|
> to back up one argument; that is, it prints a lowercase <CODE CLASS="f"
|
|
>s</CODE
|
|
> if the previous argument was not <CODE CLASS="f"
|
|
>1</CODE
|
|
>. </P
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
>~@P</CODE
|
|
> prints <CODE CLASS="f"
|
|
>y</CODE
|
|
> if the argument is <CODE CLASS="f"
|
|
>1</CODE
|
|
>, or <CODE CLASS="f"
|
|
>ies</CODE
|
|
> if it is not. <CODE CLASS="f"
|
|
>~:@P</CODE
|
|
> does the same thing, but backs up first.</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~D tr~:@P/~D win~:P" 7 1) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "7 tries/1 win"
|
|
(format nil "~D tr~:@P/~D win~:P" 1 0) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "1 try/0 wins"
|
|
(format nil "~D tr~:@P/~D win~:P" 1 3) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "1 try/3 wins"</PRE
|
|
><H3 ID="sec_22_3_9" CLASS="HeadIII"
|
|
>22.3.9 FORMAT Miscellaneous Pseudo-Operations</H3
|
|
><H4 ID="sec_22_3_9_1" CLASS="HeadIV"
|
|
>22.3.9.1 Tilde Semicolon: Clause Separator</H4
|
|
><P CLASS="j"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Semicolon (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Semicolon (format directive)"
|
|
></SPAN
|
|
>This separates clauses in <CODE CLASS="f"
|
|
>~[</CODE
|
|
> and <CODE CLASS="f"
|
|
>~<</CODE
|
|
> constructs. The consequences of using it elsewhere are undefined.</P
|
|
><H4 ID="sec_22_3_9_2" CLASS="HeadIV"
|
|
>22.3.9.2 Tilde Circumflex: Escape Upward</H4
|
|
><P CLASS="j"
|
|
><CODE CLASS="f"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Circumflex (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Circumflex (format directive)"
|
|
></SPAN
|
|
>~^</CODE
|
|
> </P
|
|
><P CLASS="j"
|
|
>This is an escape construct. If there are no more arguments remaining to be processed, then the immediately enclosing <CODE CLASS="f"
|
|
>~{</CODE
|
|
> or <CODE CLASS="f"
|
|
>~<</CODE
|
|
> construct is terminated. If there is no such enclosing construct, then the entire formatting operation is terminated. In the <CODE CLASS="f"
|
|
>~<</CODE
|
|
> case, the formatting is performed, but no more segments are processed before doing the justification. <CODE CLASS="f"
|
|
>~^</CODE
|
|
> may appear anywhere in a <CODE CLASS="f"
|
|
>~{</CODE
|
|
> construct.</P
|
|
><PRE CLASS="screen"
|
|
> (setq donestr "Done.~^ ~D warning~:P.~^ ~D error~:P.")
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Done.~^ ~D warning~:P.~^ ~D error~:P."
|
|
(format nil donestr) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Done."
|
|
(format nil donestr 3) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Done. 3 warnings."
|
|
(format nil donestr 1 5) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Done. 1 warning. 5 errors."</PRE
|
|
><P CLASS="j"
|
|
>If a prefix parameter is given, then termination occurs if the parameter is zero. (Hence <CODE CLASS="f"
|
|
>~^</CODE
|
|
> is equivalent to <CODE CLASS="f"
|
|
>~#^</CODE
|
|
>.) If two parameters are given, termination occurs if they are equal. If three parameters are given, termination occurs if the first is less than or equal to the second and the second is less than or equal to the third. Of course, this is useless if all the prefix parameters are constants; at least one of them should be a <CODE CLASS="f"
|
|
>#</CODE
|
|
> or a <CODE CLASS="f"
|
|
>V</CODE
|
|
> parameter. </P
|
|
><P CLASS="j"
|
|
>If <CODE CLASS="f"
|
|
>~^</CODE
|
|
> is used within a <CODE CLASS="f"
|
|
>~:{</CODE
|
|
> construct, then it terminates the current iteration step because in the standard case it tests for remaining arguments of the current step only; the next iteration step commences immediately. <CODE CLASS="f"
|
|
>~:^</CODE
|
|
> is used to terminate the iteration process. <CODE CLASS="f"
|
|
>~:^</CODE
|
|
> may be used only if the command it would terminate is <CODE CLASS="f"
|
|
>~:{</CODE
|
|
> or <CODE CLASS="f"
|
|
>~:@{</CODE
|
|
>. The entire iteration process is terminated if and only if the sublist that is supplying the arguments for the current iteration step is the last sublist in the case of <CODE CLASS="f"
|
|
>~:{</CODE
|
|
>, or the last <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> argument in the case of <CODE CLASS="f"
|
|
>~:@{</CODE
|
|
>. <CODE CLASS="f"
|
|
>~:^</CODE
|
|
> is not equivalent to <CODE CLASS="f"
|
|
>~#:^</CODE
|
|
>; the latter terminates the entire iteration if and only if no arguments remain for the current iteration step. For example:</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~:{~@?~:^...~}" '(("a") ("b"))) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "a...b"</PRE
|
|
><P CLASS="j"
|
|
>If <CODE CLASS="f"
|
|
>~^</CODE
|
|
> appears within a control string being processed under the control of a <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive, but not within any <CODE CLASS="f"
|
|
>~{</CODE
|
|
> or <CODE CLASS="f"
|
|
>~<</CODE
|
|
> construct within that string, then the string being processed will be terminated, thereby ending processing of the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive. Processing then continues within the string containing the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive at the point following that directive. </P
|
|
><P CLASS="j"
|
|
>If <CODE CLASS="f"
|
|
>~^</CODE
|
|
> appears within a <CODE CLASS="f"
|
|
>~[</CODE
|
|
> or <CODE CLASS="f"
|
|
>~(</CODE
|
|
> construct, then all the commands up to the <CODE CLASS="f"
|
|
>~^</CODE
|
|
> are properly selected or case-converted, the <CODE CLASS="f"
|
|
>~[</CODE
|
|
> or <CODE CLASS="f"
|
|
>~(</CODE
|
|
> processing is terminated, and the outward search continues for a <CODE CLASS="f"
|
|
>~{</CODE
|
|
> or <CODE CLASS="f"
|
|
>~<</CODE
|
|
> construct to be terminated. For example:</P
|
|
><PRE CLASS="screen"
|
|
> (setq tellstr "~@(~@[~R~]~^ ~A!~)")
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "~@(~@[~R~]~^ ~A!~)"
|
|
(format nil tellstr 23) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Twenty-three!"
|
|
(format nil tellstr nil "losers") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " Losers!"
|
|
(format nil tellstr 23 "losers") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Twenty-three losers!"</PRE
|
|
><P CLASS="j"
|
|
>Following are examples of the use of <CODE CLASS="f"
|
|
>~^</CODE
|
|
> within a <CODE CLASS="f"
|
|
>~<</CODE
|
|
> construct.</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "~15<~S~;~^~S~;~^~S~>" 'foo)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " FOO"
|
|
(format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "FOO BAR"
|
|
(format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar 'baz)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "FOO BAR BAZ"</PRE
|
|
><H4 ID="sec_22_3_9_3" CLASS="HeadIV"
|
|
>22.3.9.3 Tilde Newline: Ignored Newline</H4
|
|
><P CLASS="j"
|
|
><A HREF="26_1_Glossary.html#tilde"
|
|
><EM CLASS="term"
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Newline (format directive)"
|
|
></SPAN
|
|
><SPAN CLASS="idx" DATA-KIND="idxtext" DATA-TERM="Tilde Newline (format directive)"
|
|
></SPAN
|
|
>Tilde</EM
|
|
></A
|
|
> immediately followed by a <A HREF="26_1_Glossary.html#newline"
|
|
><EM CLASS="term"
|
|
>newline</EM
|
|
></A
|
|
> ignores the <A HREF="26_1_Glossary.html#newline"
|
|
><EM CLASS="term"
|
|
>newline</EM
|
|
></A
|
|
> and any following non-newline <A HREF="26_1_Glossary.html#whitespace"
|
|
><EM CLASS="term"
|
|
>whitespace</EM
|
|
></A
|
|
><SPAN CLASS="meaning"
|
|
><SUB CLASS="sub"
|
|
><SPAN CLASS="cmr"
|
|
>1</SPAN
|
|
></SUB
|
|
></SPAN
|
|
> characters. With a <CODE CLASS="f"
|
|
>:</CODE
|
|
>, the <A HREF="26_1_Glossary.html#newline"
|
|
><EM CLASS="term"
|
|
>newline</EM
|
|
></A
|
|
> is ignored, but any following <A HREF="26_1_Glossary.html#whitespace"
|
|
><EM CLASS="term"
|
|
>whitespace</EM
|
|
></A
|
|
><SPAN CLASS="meaning"
|
|
><SUB CLASS="sub"
|
|
><SPAN CLASS="cmr"
|
|
>1</SPAN
|
|
></SUB
|
|
></SPAN
|
|
> is left in place. With an <CODE CLASS="f"
|
|
>@</CODE
|
|
>, the <A HREF="26_1_Glossary.html#newline"
|
|
><EM CLASS="term"
|
|
>newline</EM
|
|
></A
|
|
> is left in place, but any following <A HREF="26_1_Glossary.html#whitespace"
|
|
><EM CLASS="term"
|
|
>whitespace</EM
|
|
></A
|
|
><SPAN CLASS="meaning"
|
|
><SUB CLASS="sub"
|
|
><SPAN CLASS="cmr"
|
|
>1</SPAN
|
|
></SUB
|
|
></SPAN
|
|
> is ignored. For example:</P
|
|
><PRE CLASS="screen"
|
|
> (defun type-clash-error (fn nargs argnum right-type wrong-type)
|
|
(format *error-output*
|
|
"~&~S requires its ~:[~:R~;~*~]~
|
|
argument to be of type ~S,~%but it was called ~
|
|
with an argument of type ~S.~%"
|
|
fn (eql nargs 1) argnum right-type wrong-type))
|
|
(type-clash-error 'aref nil 2 'integer 'vector) prints:
|
|
AREF requires its second argument to be of type INTEGER,
|
|
but it was called with an argument of type VECTOR.
|
|
NIL
|
|
(type-clash-error 'car 1 1 'list 'short-float) prints:
|
|
CAR requires its argument to be of type LIST,
|
|
but it was called with an argument of type SHORT-FLOAT.
|
|
NIL</PRE
|
|
><P CLASS="j"
|
|
>Note that in this example newlines appear in the output only as specified by the <CODE CLASS="f"
|
|
>~&</CODE
|
|
> and <CODE CLASS="f"
|
|
>~%</CODE
|
|
> directives; the actual newline characters in the control string are suppressed because each is preceded by a tilde.</P
|
|
><H3 ID="sec_22_3_10" CLASS="HeadIII"
|
|
>22.3.10 Additional Information about FORMAT Operations</H3
|
|
><H4 ID="sec_22_3_10_1" CLASS="HeadIV"
|
|
>22.3.10.1 Nesting of FORMAT Operations</H4
|
|
><P CLASS="j"
|
|
>The case-conversion, conditional, iteration, and justification constructs can contain other formatting constructs by bracketing them. These constructs must nest properly with respect to each other. For example, it is not legitimate to put the start of a case-conversion construct in each arm of a conditional and the end of the case-conversion construct outside the conditional:</P
|
|
><PRE CLASS="screen"
|
|
> (format nil "~:[abc~:@(def~;ghi~
|
|
:@(jkl~]mno~)" x) ;Invalid!</PRE
|
|
><P CLASS="j"
|
|
>This notation is invalid because the <CODE CLASS="f"
|
|
>~[...~;...~]</CODE
|
|
> and <CODE CLASS="f"
|
|
>~(...~)</CODE
|
|
> constructs are not properly nested. </P
|
|
><P CLASS="j"
|
|
>The processing indirection caused by the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive is also a kind of nesting for the purposes of this rule of proper nesting. It is not permitted to start a bracketing construct within a string processed under control of a <CODE CLASS="f"
|
|
>~?</CODE
|
|
> directive and end the construct at some point after the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> construct in the string containing that construct, or vice versa. For example, this situation is invalid:</P
|
|
><PRE CLASS="screen"
|
|
>(format nil "~@?ghi~)" "abc~@(def") ;Invalid!</PRE
|
|
><P CLASS="j"
|
|
>This notation is invalid because the <CODE CLASS="f"
|
|
>~?</CODE
|
|
> and <CODE CLASS="f"
|
|
>~(...~)</CODE
|
|
> constructs are not properly nested.</P
|
|
><H4 ID="sec_22_3_10_2" CLASS="HeadIV"
|
|
>22.3.10.2 Missing and Additional FORMAT Arguments</H4
|
|
><P CLASS="j"
|
|
>The consequences are undefined if no <VAR CLASS="param"
|
|
>arg</VAR
|
|
> remains for a directive requiring an argument. However, it is permissible for one or more <VAR CLASS="param"
|
|
>args</VAR
|
|
> to remain unprocessed by a directive; such <VAR CLASS="param"
|
|
>args</VAR
|
|
> are ignored.</P
|
|
><H4 ID="sec_22_3_10_3" CLASS="HeadIV"
|
|
>22.3.10.3 Additional FORMAT Parameters</H4
|
|
><P CLASS="j"
|
|
>The consequences are undefined if a format directive is given more parameters than it is described here as accepting.</P
|
|
><H4 ID="sec_22_3_10_4" CLASS="HeadIV"
|
|
>22.3.10.4 Undefined FORMAT Modifier Combinations</H4
|
|
><P CLASS="j"
|
|
>The consequences are undefined if <A HREF="26_1_Glossary.html#colon"
|
|
><EM CLASS="term"
|
|
>colon</EM
|
|
></A
|
|
> or <A HREF="26_1_Glossary.html#at-sign"
|
|
><EM CLASS="term"
|
|
>at-sign</EM
|
|
></A
|
|
> modifiers are given to a directive in a combination not specifically described here as being meaningful.</P
|
|
><H3 ID="sec_22_3_11" CLASS="HeadIII"
|
|
>22.3.11 Examples of FORMAT</H3
|
|
><PRE CLASS="screen"
|
|
> (format nil "foo") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "foo"
|
|
(setq x 5) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> 5
|
|
(format nil "The answer is ~D." x) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "The answer is 5."
|
|
(format nil "The answer is ~3D." x) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "The answer is 5."
|
|
(format nil "The answer is ~3,'0D." x) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "The answer is 005."
|
|
(format nil "The answer is ~:D." (expt 47 x))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "The answer is 229,345,007."
|
|
(setq y "elephant") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "elephant"
|
|
(format nil "Look at the ~A!" y) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Look at the elephant!"
|
|
(setq n 3) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> 3
|
|
(format nil "~D item~:P found." n) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "3 items found."
|
|
(format nil "~R dog~:[s are~; is~] here." n (= n 1))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "three dogs are here."
|
|
(format nil "~R dog~:*~[s are~; is~:;s are~] here." n)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "three dogs are here."
|
|
(format nil "Here ~[are~;is~:;are~] ~:*~R pupp~:@P." n)
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Here are three puppies."</PRE
|
|
><PRE CLASS="screen"
|
|
>(defun foo (x)
|
|
(format nil "~6,2F|~6,2,1,'*F|~6,2,,'?F|~6F|~,2F|~F"
|
|
x x x x x x)) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> FOO
|
|
(foo 3.14159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 3.14| 31.42| 3.14|3.1416|3.14|3.14159"
|
|
(foo -3.14159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " -3.14|-31.42| -3.14|-3.142|-3.14|-3.14159"
|
|
(foo 100.0) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "100.00|******|100.00| 100.0|100.00|100.0"
|
|
(foo 1234.0) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "1234.00|******|??????|1234.0|1234.00|1234.0"
|
|
(foo 0.006) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 0.01| 0.06| 0.01| 0.006|0.01|0.006"</PRE
|
|
><PRE CLASS="screen"
|
|
>(defun foo (x)
|
|
(format nil
|
|
"~9,2,1,,'*E|~10,3,2,2,'?,,'$E|~
|
|
~9,3,2,-2,'%@E|~9,2E"
|
|
x x x x))
|
|
(foo 3.14159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 3.14E+0| 31.42$-01|+.003E+03| 3.14E+0"
|
|
(foo -3.14159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " -3.14E+0|-31.42$-01|-.003E+03| -3.14E+0"
|
|
(foo 1100.0) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 1.10E+3| 11.00$+02|+.001E+06| 1.10E+3"
|
|
(foo 1100.0L0) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 1.10L+3| 11.00$+02|+.001L+06| 1.10L+3"
|
|
(foo 1.1E13) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "*********| 11.00$+12|+.001E+16| 1.10E+13"
|
|
(foo 1.1L120) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "*********|??????????|%%%%%%%%%|1.10L+120"
|
|
(foo 1.1L1200) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "*********|??????????|%%%%%%%%%|1.10L+1200"</PRE
|
|
><P CLASS="j"
|
|
>As an example of the effects of varying the scale factor, the code</P
|
|
><PRE CLASS="screen"
|
|
>(dotimes (k 13)
|
|
(format t "~%Scale factor ~2D: |~13,6,2,VE|"
|
|
(- k 5) (- k 5) 3.14159))</PRE
|
|
><P CLASS="j"
|
|
>produces the following output:</P
|
|
><PRE CLASS="screen"
|
|
>Scale factor -5: | 0.000003E+06|
|
|
Scale factor -4: | 0.000031E+05|
|
|
Scale factor -3: | 0.000314E+04|
|
|
Scale factor -2: | 0.003142E+03|
|
|
Scale factor -1: | 0.031416E+02|
|
|
Scale factor 0: | 0.314159E+01|
|
|
Scale factor 1: | 3.141590E+00|
|
|
Scale factor 2: | 31.41590E-01|
|
|
Scale factor 3: | 314.1590E-02|
|
|
Scale factor 4: | 3141.590E-03|
|
|
Scale factor 5: | 31415.90E-04|
|
|
Scale factor 6: | 314159.0E-05|
|
|
Scale factor 7: | 3141590.E-06|</PRE
|
|
><PRE CLASS="screen"
|
|
>(defun foo (x)
|
|
(format nil "~9,2,1,,'*G|~9,3,2,3,'?,,'$G|~9,3,2,0,'%G|~9,2G"
|
|
x x x x))
|
|
(foo 0.0314159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 3.14E-2|314.2$-04|0.314E-01| 3.14E-2"
|
|
(foo 0.314159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 0.31 |0.314 |0.314 | 0.31 "
|
|
(foo 3.14159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 3.1 | 3.14 | 3.14 | 3.1 "
|
|
(foo 31.4159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 31. | 31.4 | 31.4 | 31. "
|
|
(foo 314.159) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 3.14E+2| 314. | 314. | 3.14E+2"
|
|
(foo 3141.59) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 3.14E+3|314.2$+01|0.314E+04| 3.14E+3"
|
|
(foo 3141.59L0) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " 3.14L+3|314.2$+01|0.314L+04| 3.14L+3"
|
|
(foo 3.14E12) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "*********|314.0$+10|0.314E+13| 3.14E+12"
|
|
(foo 3.14L120) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "*********|?????????|%%%%%%%%%|3.14L+120"
|
|
(foo 3.14L1200) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "*********|?????????|%%%%%%%%%|3.14L+1200"</PRE
|
|
><PRE CLASS="screen"
|
|
>(format nil "~10<foo~;bar~>") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "foo bar"
|
|
(format nil "~10:<foo~;bar~>") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " foo bar"
|
|
(format nil "~10<foobar~>") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " foobar"
|
|
(format nil "~10:<foobar~>") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " foobar"
|
|
(format nil "~10:@<foo~;bar~>") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " foo bar "
|
|
(format nil "~10@<foobar~>") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "foobar "
|
|
(format nil "~10:@<foobar~>") <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> " foobar "</PRE
|
|
><PRE CLASS="screen"
|
|
>(FORMAT NIL "Written to ~A." #P"foo.bin")
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Written to foo.bin."</PRE
|
|
><H3 ID="sec_22_3_12" CLASS="HeadIII"
|
|
>22.3.12 Notes about FORMAT</H3
|
|
><P CLASS="j"
|
|
>Formatted output is performed not only by <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
>, but by certain other functions that accept a <A HREF="26_1_Glossary.html#format_control"
|
|
><EM CLASS="term"
|
|
>format control</EM
|
|
></A
|
|
> the way <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> does. For example, error-signaling functions such as <A HREF="f_cerror.html" CLASS="funref"
|
|
><B
|
|
>cerror</B
|
|
></A
|
|
> accept <A HREF="26_1_Glossary.html#format_control"
|
|
><EM CLASS="term"
|
|
>format controls</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>Note that the meaning of <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
> and <SPAN CLASS="misc"
|
|
><B
|
|
>t</B
|
|
></SPAN
|
|
> as destinations to <A HREF="f_format.html" CLASS="funref"
|
|
><B
|
|
>format</B
|
|
></A
|
|
> are different than those of <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
> and <SPAN CLASS="misc"
|
|
><B
|
|
>t</B
|
|
></SPAN
|
|
> as <A HREF="26_1_Glossary.html#stream_designator"
|
|
><EM CLASS="term"
|
|
>stream designators</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>The <CODE CLASS="f"
|
|
>~^</CODE
|
|
> should appear only at the beginning of a <CODE CLASS="f"
|
|
>~<</CODE
|
|
> clause, because it aborts the entire clause in which it appears (as well as all following clauses).</P
|
|
></SECTION
|
|
></DIV
|
|
><DIV CLASS="footer"
|
|
><DIV CLASS="btmnav"
|
|
><A HREF="22_2_The_Lisp_Pretty_Printer.html" CLASS="prev"
|
|
>←</A
|
|
><A HREF="22_4_Printer_Dictionary.html" CLASS="next"
|
|
>→</A
|
|
></DIV
|
|
><DIV CLASS="trail"
|
|
>Conversion to HTML copyright 2023 by Gilbert Baumann</DIV
|
|
></DIV
|
|
></DIV
|
|
><SCRIPT
|
|
>domReady();</SCRIPT
|
|
></BODY
|
|
></HTML
|
|
> |