User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:format [2019/07/14 17:00]
cl:functions:format [2019/07/18 14:00] (current)
Line 1: Line 1:
 +====== Function FORMAT ======
 +
 +====Syntax====
 +  * **format** //​destination//​ //​control-string//​ ''&​rest''​ //args// → //result//
 +
 +====Arguments and Values====
 +  * //​destination//​ - **[[CL:​Constant Variables:​nil]]**,​ **[[CL:​Constant Variables:​t]]**,​ a //​[[CL:​Glossary:​stream]]//,​ or a //​[[CL:​Glossary:​string]]//​ with a //​[[CL:​Glossary:​fill pointer]]//​.
 +  * //​control-string//​ - a //​[[CL:​Glossary:​format control]]//​.
 +  * //args// - //​[[CL:​Glossary:​format arguments]]//​ for //​control-string//​.
 +  * //result// - if //​destination//​ is //​[[CL:​Glossary:​non-nil]]//,​ then **[[CL:​Constant Variables:​nil]]**;​ otherwise, a //​[[CL:​Glossary:​string]]//​.
 +
 +====Description====
 +**format** produces formatted output by outputting the characters of //​control-string//​ and observing that a //​[[CL:​Glossary:​tilde]]//​ introduces a directive. The character after the tilde, possibly preceded by prefix parameters and modifiers, specifies what kind of formatting is desired. Most directives use one or more elements of //args// to create their output.
 +
 +If //​destination//​ is a //​[[CL:​Glossary:​string]]//,​ a //​[[CL:​Glossary:​stream]]//,​ or **[[CL:​Constant Variables:​t]]**,​ then the //result// is **[[CL:​Constant Variables:​nil]]**. Otherwise, the //result// is a //​[[CL:​Glossary:​string]]//​ containing the "​output"​.
 +
 +**format** is useful for producing nicely formatted text, producing good-looking messages, and so on. **format** can generate and return a //​[[CL:​Glossary:​string]]//​ or output to //​destination//​.
 +
 +For details on how the //​control-string//​ is interpreted,​ see section {\secref\FormattedOutput}.
 +
 +====Examples====
 +None.
 +
 +====Affected By====
 +**[[CL:​Variables:​star-standard-output-star|*standard-output*]]**,​ **[[CL:​Variables:​star-print-escape-star|*print-escape*]]**,​ **[[CL:​Variables:​star-print-radix-star|*print-radix*]]**,​ **[[CL:​Variables:​star-print-base-star|*print-base*]]**,​ **[[CL:​Variables:​star-print-circle-star|*print-circle*]]**,​ **[[CL:​Variables:​star-print-pretty-star|*print-pretty*]]**,​ **[[CL:​Variables:​star-print-level-star|*print-level*]]**,​ **[[CL:​Variables:​star-print-length-star|*print-length*]]**,​ **[[CL:​Variables:​star-print-case-star|*print-case*]]**,​ **[[CL:​Variables:​star-print-gensym-star|*print-gensym*]]**,​ **[[CL:​Variables:​star-print-array-star|*print-array*]]**.
 +
 +====Exceptional Situations====
 +If //​destination//​ is a //​[[CL:​Glossary:​string]]//​ with a //​[[CL:​Glossary:​fill pointer]]//,​ the consequences are undefined if destructive modifications are performed directly on the //​[[CL:​Glossary:​string]]//​ during the //​[[CL:​Glossary:​dynamic extent]]// of the call.
 +
 +====See Also====
 +  * **[[CL:​Functions:​write|Function WRITE]]**
 +  * {\secref\ImplementationDefinedScripts}
 +
 +====Notes====
 +None.
 +
 +\issue{FORMAT-STRING-ARGUMENTS:​SPECIFY} \issue{STRING-OUTPUT-STREAM-BASHING:​UNDEFINED}