User Tools


Differences

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

Link to this comparison view

cl:functions:write-to-string [2019/11/11 05:00]
cl:functions:write-to-string [2019/11/11 22:00] (current)
Line 1: Line 1:
 +====== Function WRITE-TO-STRING,​ PRIN1-TO-STRING,​ PRINC-TO-STRING ======
 +
 +====Syntax====
 +  * **write-to-string** //object// ''&​key''​ //array// //base// //case// //circle// //escape// //gensym// //length// //level// //lines// //​miser-width//​ //​pprint-dispatch//​ //pretty// //radix// //​readably//​ //​right-margin//​ → ////​string//​
 +  * **prin1-to-string** //object// → //string//
 +  * **princ-to-string** //object// → //string//
 +
 +====Arguments and Values====
 +  * //object// - an //​[[CL:​Glossary:​object]]//​.
 +  * //array// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //base// - a //​[[CL:​Glossary:​radix]]//​.
 +  * //case// - a //​[[CL:​Glossary:​symbol]]//​ of //​[[CL:​Glossary:​type]]//​ ''​(member :upcase :downcase :​capitalize)''​.
 +  * //circle// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //escape// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //gensym// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //length// - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //level// - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //lines// - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //​miser-width//​ - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //​pprint-dispatch//​ - a //​[[CL:​Glossary:​pprint dispatch table]]//.
 +  * //pretty// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //radix// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //​readably//​ - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //​right-margin//​ - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //string// - a //​[[CL:​Glossary:​string]]//​.
 +
 +====Description====
 +**write-to-string**,​ **prin1-to-string**,​ and **princ-to-string** are used to create a //​[[CL:​Glossary:​string]]//​ consisting of the printed representation of //object//.
 +
 +//object// is effectively printed as if by **[[CL:​Functions:​write]]**,​ **[[CL:​Functions:​prin1]]**,​ or **[[CL:​Functions:​princ]]**,​ respectively,​ and the //​[[CL:​Glossary:​characters]]//​ that would be output are made into a //​[[CL:​Glossary:​string]]//​.
 +
 +**write-to-string** is the general output function. It has the ability to specify all the parameters applicable to the printing of //object//.
 +
 +**prin1-to-string** acts like **write-to-string** with '':​escape [[CL:​Constant Variables:​t]]'',​ that is, escape characters are written where appropriate.
 +
 +**princ-to-string** acts like **write-to-string** with '':​escape [[CL:​Constant Variables:​nil]] :readably [[CL:​Constant Variables:​nil]]''​. Thus no //​[[CL:​Glossary:​escape]]//​ //​[[CL:​Glossary:​characters]]//​ are written.
 +
 +All other keywords that would be specified to **write-to-string** are default values when **prin1-to-string** or **princ-to-string** is invoked.
 +
 +The meanings and defaults for the keyword arguments to **write-to-string** are the same as those for **[[CL:​Functions:​write]]**.
 +
 +====Examples====
 +<​blockquote>​
 +(prin1-to-string "​abc"​) → "​\"​abc\""​
 +(princ-to-string "​abc"​) → "​abc"​
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +**[[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*]]**,​ **[[CL:​Variables:​star-read-default-float-format-star|*read-default-float-format*]]**.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​write|Function WRITE]]**
 +
 +====Notes====
 +<​blockquote> ​
 +(write-to-string //object// {//key// //​argument//​}''​*''​) ​
 +  ≡ (with-output-to-string (#​1=#:​string-stream) (write //object// :stream #1# {//key// //​argument//​}''​*''​))
 +(princ-to-string //​object//​) ​
 +  ≡ (with-output-to-string (string-stream) (princ //object// string-stream))
 +(prin1-to-string //​object//​) ​
 +  ≡ (with-output-to-string (string-stream) (prin1 //object// string-stream)) </​blockquote>​
 +
 +\issue{PRINC-READABLY:​X3J13-DEC-91}