Debian Codegraph @

docsrc/xlisp/xlisp-doc/internals/c-printf.htm

raw
1 <html><head>
2
3 <title>ANSI C 'printf' Format</title>
4
5 <style type="text/css">
6 .example {
7 color: #000000;
8 background-color: #F5F5F5;
9 padding: 8px;
10 border: #808080;
11 border-style: solid;
12 border-width: 1px;
13 width:auto;
14 }
15 .button {
16 color: #000000;
17 background-color: #F5F5F5;
18 padding-top: 1px;
19 padding-bottom: 1px;
20 padding-left: 4px;
21 padding-right: 8px;
22 border: #808080;
23 border-style: solid;
24 border-width: 1px;
25 white-space: pre;
26 }
27 .box {
28 color: #000000;
29 padding-top: 4px;
30 padding-bottom: 4px;
31 padding-left: 16px;
32 padding-right: 16px;
33 border: #808080;
34 border-style: solid;
35 border-width: 1px;
36 }
37 </style>
38
39 </head>
40
41 <body>
42
43 <a href="../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
44 <a href="../manual/contents.htm">Contents</a> |
45 <a href="../tutorials/tutorials.htm">Tutorials</a> |
46 <a href="../examples/examples.htm">Examples</a> |
47 <a href="../reference/reference-index.htm">Reference</a>
48
49 <hr>
50
51 <h1>ANSI C 'printf' Format</h1>
52
53 <hr>
54
55 <p><b>Nyquist/XLISP:</b> The
56 <nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> and
57 <nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
58 variables define format strings for the underlying 'sprintf' <nobr>C
59 function</nobr>. <nobr>In C,</nobr> the same format string specification is
60 used for 'fprint' [writes to <nobr>a file]</nobr>, 'printf' [writes to
61 standard output] and 'sprintf' [writes to another string]. These three
62 functions are meant in the following text with 'the printf functions'.</p>
63
64 <p><b>ANSI C:</b> The printf functions write output under control of a
65 format string that specifies how subsequent arguments are converted for
66 output. If there are insufficient arguments for the format, the behavior is
67 undefined. If the format is exhausted while arguments remain, the excess
68 arguments are evaluated but are otherwise ignored. The printf functions
69 return when the end of the format string is encountered.</p>
70
71 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
72
73 <a name="format-string"></a>
74
75 <hr>
76
77 <h2>Format String</h2>
78
79 <hr>
80
81 <p>The format string is composed of zero or more directives, which are
82 ordinary characters <nobr>[except &quot;%&quot;]</nobr>, which are copied
83 unchanged to the output stream, and conversion specifications, each of which
84 results in fetching zero or more subsequent arguments. Each conversion
85 specification is introduced by the <nobr>character &quot;%&quot;</nobr>:</p>
86
87 <pre class="example">
88 <font color="#AA0000">%</font>[<font color="#0000CC">flags</font>][<font color="#0000CC">field-with</font>][<font color="#0000CC">precision</font>][<font color="#0000CC">data-type</font>]<font color="#880000">conversion-type</font>
89 </pre>
90
91 <p>After the &quot;%&quot;, the following appear in sequence:</p>
92
93 <ul>
94
95 <li><p><b>Flags</b> - Zero or more <a href="#flags">flags</a> that modify
96 the meaning of the conversion specification.</p></li>
97
98 <li><p><b>Field Width</b> - <nobr>An optional</nobr> decimal integer
99 specifying a minimum field width. <nobr>If the</nobr> converted value has
100 fewer characters than the field width, it will be padded with spaces on the
101 left to the field width. <nobr>The field</nobr> is padded on the right if
102 the <nobr><a href="#minus-flag">&nbsp;&minus;&nbsp;</a> flag</nobr> has been
103 given, or padded with zeros if the
104 <nobr><a href="#zero-flag">&nbsp;0&nbsp;</a> flag</nobr> had been
105 given. <nobr>A negative</nobr> integer, given as '<nobr>field width</nobr>'
106 argument, is interpreted as a
107 <nobr><a href="#minus-flag">&nbsp;&minus;&nbsp;</a> flag</nobr> followed by
108 a positive <nobr>field width</nobr>.</p></li>
109
110 <li><p><b>Precision</b> - <nobr>An optional</nobr> decimal integer that
111 gives the minimum number of digits to appear for
112 <a href="#integer">integer</a> conversions, the number of digits to appear
113 after the
114 <nobr>decimal-point</nobr> character for <nobr>floating-point</nobr>
115 <nobr><a href="#float-e">&nbsp;e&nbsp;</a></nobr> and
116 <nobr><a href="#float-f">&nbsp;f&nbsp;</a></nobr> conversions, or the
117 maximum number of significant digits for the <nobr>floating-point</nobr>
118 <nobr><a href="#float-g">&nbsp;g&nbsp;</a></nobr> conversion.</p>
119
120 <p>The precision takes the form of a period character followed by an
121 optional decimal integer:</p>
122
123 <pre class="example">
124 .[<font color="#0000CC">integer</font>]
125 </pre>
126
127 <p><nobr>If the</nobr> integer is omitted, it is treated as zero, a
128 negative precision argument is taken as if it were missing.</p>
129
130 <p><b>Note:</b> <nobr>In C</nobr>, the precision also specifies the
131 maximum number of characters to be written from a string in <nobr>'s'
132 conversion</nobr>, but &quot;%s&quot; should not be used in the XLISP
133 <nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
134 <nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
135 variables, otherwise XLISP will crash.</p></li>
136
137 </li>
138
139 <li><p><b>Data Type</b> - <nobr>An optional</nobr> character specifying a
140 <nobr><a href="#data-type">data type</a></nobr> to be used for the
141 conversion.</p>
142
143 <p><b>XLISP:</b> Nyquist/XLISP uses <nobr>C 'long'</nobr> signed integers
144 and <nobr>C 'double'</nobr> floats only, so with <nobr>floating-point</nobr>
145 numbers no special <nobr><a href="#data-type">data type</a></nobr> needs to
146 be given, while <a href="#integer">integer</a> conversions should always be
147 prefixed by a <nobr>'l' [lowercase L]</nobr>, otherwise the printed
148 representation of integer numbers may be differently than the behaviour of
149 the Nyquist/XLISP functions.</nobr></p></li>
150
151 <li><p><b>Conversion Type</b> - <nobr>A character</nobr> that specifies the
152 <nobr><a href="#conversion-type">conversion type</a></nobr> to be
153 applied.</p></li>
154
155 </ul>
156
157 <p><b>Not with Nyquist/XLISP:</b> <nobr>In C</nobr>, a '<nobr>field
158 width</nobr>' or 'precision', or both, may be indicated by an asterisk *
159 instead of a digit string. In this case, an int argument supplies the field
160 width or precision. The arguments specifying field width or precision, or
161 both, shall appear [in that order] before the argument [if any] to be
162 converted.</p>
163
164 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
165
166 <a name="flags"></a>
167
168 <hr>
169
170 <h2>Flags</h2>
171
172 <hr>
173
174 <p>The flag characters and their meanings are:</p>
175
176 <p><div class="box">
177
178 <dl>
179
180 <a name="minus-flag"></a>
181
182 <dt><p><nobr>&minus;&nbsp; [minus sign character]</nobr></p></dt>
183
184 <dd><p>The result of the conversion will be <nobr>left-justified</nobr>
185 within the field.</p></dd>
186
187 <a name="plus-flag"></a>
188
189 <dt><p><nobr>+&nbsp; [plus sign character]</nobr></p></dt>
190
191 <dd><p>The result of a signed conversion will always begin with a plus or
192 minus sign.</p></dd>
193
194 <a name="space-flag"></a>
195
196 <dt><p><nobr><i>space</i>&nbsp; [space character]</nobr></p></dt>
197
198 <dd><p>If the first character of a signed conversion is not a sign, or if a
199 signed conversion results in no characters, a space will be prepended to the
200 result. <nobr>If the</nobr> 'space' and
201 <nobr><a href="#plus-flag">&nbsp;+&nbsp;</a> flags</nobr> both appear, the
202 'space' flag will be ignored.</p></dd>
203
204 <a name="hash-flag"></a>
205
206 <dt><p><nobr>#&nbsp; [hash character]</nobr></p></dt>
207
208 <dd><p>The result is to be converted to an 'alternate form':</p>
209
210 <p>Octal Numbers - For o conversion, it increases the precision to force the
211 first digit of the result to be a zero.</p>
212
213 <p>Hexadecimal Numbers - For x or X conversion, a nonzero result will have
214 0x or 0X prepended to it.</p>
215
216 <p>Floating-point Numbers - For e, E, f, g, and G conversions, the result
217 will always contain a decimal-point character, even if no digits follow it
218 (normally, a decimal-point character appears in the result of these
219 conversions only if a digit follows it). For g and G conversions, trailing
220 zeros will not be removed from the result. For other conversions, the
221 behavior is undefined.</p>
222
223 </dd>
224
225 <a name="zero-flag"></a>
226
227 <dt><p><nobr>0&nbsp; [number zero character]</nobr></p></dt>
228
229 <dd><p>For integer d, i, o, u, x, X, and floating-point e, E, f, g, G
230 conversions, leading zeros [following any indication of sign or base] are
231 used to pad to the <nobr><a href="#format-string">field width</a></nobr>.
232 <nobr>No <a href="#space-flag">space</a></nobr> padding is performed.
233 <nobr>If the</nobr> '0' and
234 <nobr><a href="#minus-flag">&nbsp;&minus;&nbsp;</a> flags</nobr> both
235 appear, the <nobr>'0' flag</nobr> will be ignored. For integer d, i, o, u,
236 x, X conversions, if a <a href="#format-string">precision</a> is specified,
237 the <nobr>'0' flag</nobr> will be ignored. <nobr>For other</nobr>
238 conversions, the behavior is undefined.</p></dd>
239
240 </dl>
241
242 </div></p>
243
244 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
245
246 <a name="data-type"></a>
247
248 <hr>
249
250 <h2>Data Type</h2>
251
252 <hr>
253
254 <p><div class="box">
255
256 <dl>
257
258 <dt><p><nobr><b>h</b>&nbsp; [lowercase H character]</nobr></p></dt>
259
260 <dd><p>A following d, i, o, u, x, or X conversion specifier applies to a
261 short int or unsigned short int argument [the argument will have been
262 promoted according to the integral promotions, and its value shall be
263 converted to short int or unsigned short int before printing].</p>
264
265 <p>A following n conversion specifier applies to a pointer to a short int
266 argument.</p></dd>
267
268 <dt><p><nobr><b>l</b>&nbsp; [lowercase L character]</nobr></p></dt>
269
270 <dd><p>A following d, i, o, u, x, or X conversion specifier applies to a
271 long int or unsigned long int argument.</p>
272
273 <p>A following n conversion specifier applies to a pointer to a long int
274 argument.</p></dd>
275
276 <dt><p><nobr><b>L</b>&nbsp; [uppercase L character]</nobr></p></dt>
277
278 <dd><p>A following e, E, f, g, or G conversion specifier applies to a long
279 double argument.</p></dd>
280
281 </dl>
282
283 </div></p>
284
285 <p>If an h, l, or L appears with any other conversion specifier, the
286 behavior is undefined.</p>
287
288 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
289
290 <a name="conversion-type"></a>
291
292 <hr>
293
294 <h2>Conversion Type</h2>
295
296 <hr>
297
298 <p><b>Integer</b> conversion:</p>
299
300 <p><div class="box">
301
302 <dl>
303
304 <a name="integer"></a>
305
306 <dt><p><nobr><b>d</b>, <b>i</b>, <b>o</b>, <b>u</b>, <b>x</b>,
307 <b>X</b></nobr></p></dt>
308
309 <dd><p>The integer argument is converted to:
310
311 <p><table cellpadding="0" cellspacing="0"><tbody>
312 <tr>
313 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
314 <td align="center"><nobr>d</nobr></td>
315 <td><nobr>&nbsp;&rarr;&nbsp;</nobr></td>
316 <td><nobr>signed decimal</nobr></td>
317 </tr>
318 <tr>
319 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
320 <td align="center"><nobr>i</nobr></td>
321 <td><nobr>&nbsp;&rarr;&nbsp;</nobr></td>
322 <td><nobr>signed decimal</nobr></td>
323 </tr>
324 <tr>
325 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
326 <td align="center"><nobr>o</nobr></td>
327 <td><nobr>&nbsp;&rarr;&nbsp;</nobr></td>
328 <td><nobr>unsigned octal</nobr></td>
329 </tr>
330 <tr>
331 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
332 <td align="center"><nobr>u</nobr></td>
333 <td><nobr>&nbsp;&rarr;&nbsp;</nobr></td>
334 <td><nobr>unsigned decimal</nobr></td>
335 </tr>
336 <tr>
337 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
338 <td align="center"><nobr>x</nobr></td>
339 <td><nobr>&nbsp;&rarr;&nbsp;</nobr></td>
340 <td><nobr>unsigned hexadecimal, using 'abcdef'</nobr></td>
341 </tr>
342 <tr>
343 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
344 <td align="center"><nobr>X</nobr></td>
345 <td><nobr>&nbsp;&rarr;&nbsp;</nobr></td>
346 <td><nobr>unsigned hexadecimal, using 'ABCDEF'</nobr></td>
347 </tr>
348 </tbody></table></p>
349
350 <p>The <a href="#format-string">precision</a> specifies the minimum number
351 of digits to appear. <nobr>If the</nobr> value being converted can be
352 represented in fewer digits, it will be expanded with leading zeros. The
353 default precision <nobr>is 1</nobr>. The result of converting a zero value
354 with an explicit precision of zero results in no characters.</p>
355
356 <b>XLISP:</b> Nyquist/XLISP uses <nobr>C 'long'</nobr> signed integers, so
357 the integer conversions should always be prefixed by a <nobr>'l' [lowercase
358 L]</nobr> indicating a '<nobr>long int</nobr>' <nobr>C
359 <a href="#data-type">data type</a></nobr>, otherwise the printed
360 representation of integer numbers may be differently than the behaviour of
361 the Nyquist/XLISP functions.</p></dd>
362
363 </dl>
364
365 </div></p>
366
367 <p><b>Floating-point</b> conversion:</p>
368
369 <p><div class="box">
370
371 <dl>
372
373 <a name="float-f"></a>
374
375 <dt><p><b>f</b></p></dt>
376
377 <dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
378 'double' is converted to decimal notation in the style:</p>
379
380 <pre class="example">
381 [-]<font color="#0000CC">ddd</font>.<font color="#0000CC">ddd</font>
382 </pre>
383
384 <p>where the number of digits after the <nobr>decimal-point</nobr> character
385 is equal to the <a href="#format-string">precision</a> specification.
386 <nobr>If the</nobr> <a href="#format-string">precision</a> is missing, it is
387 taken <nobr>as 6</nobr>. <nobr>If the</nobr>
388 <a href="#format-string">precision</a> is explicitly zero, no
389 <nobr>decimal-point</nobr> character appears. <nobr>If a</nobr>
390 <nobr>decimal-point</nobr> character appears, at least one digit appears
391 <nobr>before it</nobr>. <nobr>The value</nobr> is rounded to the appropriate
392 number of digits.</p></dd>
393
394 <a name="float-e"></a>
395
396 <dt><p><b>e</b>, <b>E</b></p></dt>
397
398 <dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
399 'double' is converted in the style:</p>
400
401 <pre class="example">
402 [-]<font color="#0000CC">d</font>.<font color="#0000CC">ddd</font><font color="#AA0000">e</font>+-<font color="#0000CC">dd</font>
403 </pre>
404
405 <p>where there is one digit before the <nobr>decimal-point</nobr> character
406 [which is nonzero if the argument is nonzero] and the number of digits after
407 it is equal to the <a href="#format-string">precision</a>. <nobr>If
408 the</nobr> <a href="#format-string">precision</a> is missing, it is taken
409 <nobr>as 6</nobr>. <nobr>If the</nobr>
410 <a href="#format-string">precision</a> is zero, no
411 <nobr>decimal-point</nobr> character appears. <nobr>The value</nobr> is
412 rounded to the appropriate number of digits. <nobr>The exponent</nobr>
413 always contains at least two digits. <nobr>If the</nobr> value is zero, the
414 exponent is zero. <nobr>The &quot;E&quot;</nobr> conversion specifier will
415 produce a number with 'E' instead of 'e' introducing the exponent.</p> </dd>
416
417 <a name="float-g"></a>
418
419 <dt><p><b>g</b>, <b>G</b></p></dt>
420
421 <dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
422 'double' is converted in style <a href="#float-f">&nbsp;f&nbsp;</a> or
423 <a href="#float-e">&nbsp;e&nbsp;</a> or in style
424 <a href="#float-e">&nbsp;E&nbsp;</a> in the case of a &quot;G&quot;
425 conversion specifier, with the <a href="#format-string">precision</a>
426 specifying the number of significant digits. <nobr>If an</nobr> explicit
427 <a href="#format-string">precision</a> is zero, it is taken <nobr>as
428 1</nobr>. <nobr>The style</nobr> used depends on the value converted.
429 <nobr>Style <a href="#float-">&nbsp;e&nbsp;</a></nobr> will be used only if
430 the exponent resulting from such a conversion is less <nobr>than -4</nobr>
431 or greater than or equal to the <a href="#format-string">precision</a>.
432 Trailing zeros are removed from the fractional portion of the result.
433 <nobr>A decimal-point</nobr> character appears only if it is followed by
434 <nobr>a digit</nobr>.</p></dd>
435
436 </dl>
437
438 </div></p>
439
440 <p>Other conversion types defined <nobr>in ANSI C</nobr>, but <b>not</b> to
441 be used with the XLISP
442 <nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> and
443 <nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
444 variables, because XLISP will produce nonsense or just simply will crash:</p>
445
446 <p><div class="box">
447
448 <dl>
449
450 <dt><p><b>c</b></p></dt>
451
452 <dd><p>The integer argument is converted to an '<nobr>unsigned char</nobr>',
453 and the resulting character is written.</p>
454
455 <p><b>XLISP:</b> If the
456 <nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
457 <nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
458 variable is set to &quot;%c&quot;, then with integers or
459 <nobr>floating-point</nobr> numbers, the lowest <nobr>8 bit</nobr> of the
460 internal binary representation will be interpreted as an
461 <a href="">ASCII</a> character.</p></dd>
462
463 <dt><p><b>s</b></p></dt>
464
465 <dd><p>The argument shall be a pointer to an array of character type.
466 Characters from the array are written up to [but not including] a
467 terminating null character. <nobr>If the</nobr>
468 <a href="#format-string">precision</a> is specified, no more than that many
469 characters are written. <nobr>If the</nobr>
470 <a href="#format-string">precision</a> is not specified or is greater than
471 the size of the array, the array shall contain a null character.</p>
472
473 XLISP: If </dd>
474
475 <dt><p><b>p</b></p></dt>
476
477 <dd><p>The argument shall be a pointer to 'void'. The value of the pointer
478 is converted to a sequence of printable characters, in an
479 <nobr>implementation-defined</nobr> manner.</p></dd>
480
481 <dt><p><b>n</b></p></dt>
482
483 <dd><p>The argument shall be a pointer to an integer into which is written
484 the number of characters written to the output stream so far by this call to
485 the <nobr>C 'fprintf'</nobr> function.<nobr> No argument</nobr> is
486 converted.</p></dd>
487
488 <dt><p><b>%</b></p></dt>
489
490 <dd><p><nobr>A &quot;%&quot;</nobr> is written. <nobr>No argument</nobr> is
491 converted. <nobr>The complete</nobr> conversion specification <nobr>shall be
492 &quot;%%&quot;</nobr>.</p></dd>
493
494 </dl>
495
496 </div></p>
497
498 <p>If a conversion specification is invalid, the behavior is undefined.
499 <nobr>In no</nobr> case does a nonexistent or small
500 <nobr><a href="#format-string">field width</a></nobr> cause truncation of a
501 field. <nobr>If the</nobr> result of a conversion is wider than the
502 <nobr><a href="#format-string">field width</a></nobr>, the field is expanded
503 to contain the conversion result.</p>
504
505 <p>The minimum value for the maximum number of characters produced by
506 any single conversion shall be 509.</p>
507
508 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
509
510 <hr>
511
512 <a href="../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
513 <a href="../manual/contents.htm">Contents</a> |
514 <a href="../tutorials/tutorials.htm">Tutorials</a> |
515 <a href="../examples/examples.htm">Examples</a> |
516 <a href="../reference/reference-index.htm">Reference</a>
517
518 </body></html>