C/the.ansi.c.programming.language/c.programming.notes.int/sx2e.html

   1 <!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
   2 <!-- This collection of hypertext pages is Copyright 1995-7 by Steve Summit. -->
   3 <!-- This material may be freely redistributed and used -->
   4 <!-- but may not be republished or sold without permission. -->
   5 <html>
   6 <head>
   7 <link rev="owner" href="mailto:scs@eskimo.com">
   8 <link rev="made" href="mailto:scs@eskimo.com">
   9 <title>16.5: Formatted Output
  10 (<TT>printf</TT> and friends)</title>
  11 <link href="sx2d.html" rev=precedes>
  12 <link href="sx2f.html" rel=precedes>
  13 <link href="sx2.html" rev=subdocument>
  14 </head>
  15 <body>
  16 <H2>16.5: Formatted Output
  17 (<TT>printf</TT> and friends)</H2>
  18
  19 <p>C's venerable <TT>printf</TT> function,
  20 which we've been using since day one,
  21 prints or writes formatted output to the standard output.
  22 As we've seen
  23 (by example, if not formally),
  24 <TT>printf</TT>'s operation is controlled by its first,
  25 ``format'' argument,
  26 which is either a simple string to be printed
  27 or a string containing percent signs and other characters
  28 which cause the formatted values of <TT>printf</TT>'s other arguments
  29 to be interspersed with the other text (if any) of the format string.
  30 </p><p>So far,
  31 we've been using simple format specifiers
  32 such as <TT>%d</TT>, <TT>%f</TT>, and <TT>%s</TT>.
  33 But format specifiers can actually consist of several parts.
  34 You can specify a ``field width'';
  35 for example, <TT>%5d</TT> prints an integer in a field five characters wide,
  36 padding the integer's value
  37 with extra characters
  38
  39 if necessary
  40 so that at least five characters are printed.
  41 You can specify a ``precision'';
  42 for example,
  43 <TT>%.2f</TT> formats a floating-point number
  44 with two digits printed after the decimal point.
  45 You can also
  46 add certain characters which
  47 specify various options,
  48 such as how a too-narrow field is to be padded out to its field width,
  49 or what type of number you're printing.
  50 For example, %-5d indicates that the padding characters
  51 should be added after the field's value
  52 (so that it's left-justified),
  53 and %ld indicates that you're printing a <TT>long </TT>
  54 instead of a plain <TT>int</TT>.
  55 </p><p>Formally, then,
  56 the complete framework
  57 for a <TT>printf</TT> format specifier
  58 looks like
  59 <pre>
  60         % <I>flags</I> <I>width</I> . <I>precision</I> <I>modifier</I> <I>character</I>
  61 </pre>
  62 where all of the parts
  63 except the <TT>%</TT> and the final
  64
  65 character
  66 are optional.
  67 </p><p>The <I>width</I> gives the <em>minimum</em> overall width of the output
  68 (the <dfn>field</dfn>)
  69 generated by this format specifier.
  70 If the output (the number of digits or characters)
  71 would be less than the width,
  72 it will be padded on the right
  73 (or left, if the <TT>-</TT> flag is present),
  74 usually with spaces.
  75 If the output for the field ends up being larger than the specified width,
  76 however, the field essentially overflows or grows;
  77 the output is not truncated or anything.
  78 That is, <TT>printf("%2d", 12345)</TT> prints <TT>12345</TT>.
  79 </p><p>The <I>precision</I> is either:
  80 <UL><li>The number of digits printed after the decimal point,
  81 for the floating-point formats <TT>%e</TT>, <TT>%f</TT>, and <TT>%g</TT>;
  82 or
  83 <li>The <em>maximum</em> number of characters to be printed,
  84 for <TT>%s</TT>;
  85 or
  86 <li>The <em>minimum</em> number of digits to be printed,
  87 for the integer formats <TT>%d</TT>, <TT>%o</TT>, <TT>%x</TT>, and <TT>%u</TT>.
  88 </UL>For example,
  89 <TT>printf("%.3s", "Hello, world!")</TT> prints <TT>Hel</TT>,
  90 and
  91 <TT>printf("%.5d", 12)</TT> prints <TT>00012</TT>.
  92 </p><p>Either the <I>width</I> or the <I>precision</I>
  93 (or both)
  94 can be specified as <TT>*</TT>,
  95 which indicates that the next <TT>int</TT> argument from the argument list
  96 should be used as the field width or precision.
  97 For example,
  98 <TT>printf("%.*f", 2, 76.54321)</TT> prints <TT>76.54</TT>.
  99 </p><p>The <I>flags</I> are a few optional characters
 100 which modify the conversion in some way.
 101 They are:
 102 <UL><li><cw>-</>
 103 Force left adjustment,
 104 by padding
 105 (out to the field width)
 106 on the right.
 107
 108 <li><cw>0</>
 109 Use 0 as the padding character,
 110 instead of a space.
 111 <li>space
 112 For numeric formats,
 113 if the converted number is positive,
 114
 115 leave an extra space before it
 116 (so that it will line up with negative numbers if printed in columns).
 117 <li><cw>+</>
 118 Print positive numbers with a leading <TT>+</TT> sign.
 119 <li><cw>#</>
 120 Use an ``alternate form'' of the conversion.
 121 (The details of the ``alternate forms'' are described below,
 122 under the individual format characters.)
 123 </UL></p><p>The <I>modifier</I> specifies the size of the corresponding argument:
 124 <TT>l</TT> for <TT>long int</TT>,
 125 <TT>h</TT> for <TT>short int</TT>,
 126 <TT>L</TT> for <TT>long double</TT>.
 127
 128 </p><p>Finally,
 129 the
 130 format character
 131 controls the overall appearance of the conversion
 132 (and,
 133 along with the <I>modifier</I>,
 134 specifies the type of the corresponding argument).
 135 We've seen many of these already.
 136 The complete list of format characters is:
 137 <UL><li><cw>c</>
 138 Print a single character.
 139 The corresponding argument is an <TT>int</TT>
 140 (or,
 141 by the default argument promotions,
 142
 143 a <TT>char</TT> or <TT>short int</TT>).
 144 <li><cw>d</>
 145 Print a decimal integer.
 146 The corresponding argument is an <TT>int</TT>,
 147 or a <TT>long int</TT> if the <TT>l</TT> modifier appears,
 148 or a <TT>short int</TT> if the <TT>h</TT> modifier appears.
 149 If the number is negative,
 150 it is preceded by a <TT>-</TT>.
 151 If the space flag appears and the the number is positive,
 152
 153 it is preceded by a space.
 154 If the <TT>+</TT> flag appears and the the number is positive,
 155 it is preceded by a <TT>+</TT>.
 156 <li><cw>e</>
 157 Print a floating-point number in scientific notation:
 158 <TT>[-]m.nnnnnne[-]nn</TT>
 159 .
 160 The corresponding argument is
 161 either a <TT>float</TT> or a <TT>double</TT>
 162 or,
 163 if the <TT>L</TT> modifier appears,
 164 a <TT>long double</TT>.
 165 The <I>precision</I> gives the number of places after the decimal point;
 166 the default is 6.
 167 If the <TT>#</TT> flag appears,
 168 a decimal point will be printed even if the <I>precision</I> is 0.
 169 <li><cw>E</>
 170 Like <TT>e</TT>,
 171 but use a capital <TT>E</TT> to set off the exponent.
 172 <li><cw>f</>
 173 Print a floating-point decimal number
 174 (<TT>mmm.nnnnnn</TT>).
 175 The corresponding argument is either
 176 a <TT>float</TT> or a <TT>double</TT>
 177 or,
 178 if the <TT>L</TT> modifier appears,
 179 a <TT>long double</TT>.
 180 The <I>precision</I> gives the number of places after the decimal point;
 181 the default is 6.
 182 If the <TT>#</TT> flag appears,
 183 a decimal point will be printed even if the <I>precision</I> is 0.
 184 <li><cw>g</>
 185 Use either <TT>e</TT> or <TT>f</TT>,
 186 whichever works best given the range and precision of the number.
 187
 188 (Roughly speaking,
 189 ``works best'' means
 190 to
 191 display the most precision in the least space.)
 192 If the <TT>#</TT> flag appears,
 193 don't strip trailing <TT>0</TT>'s.
 194 <li><cw>G</>
 195 Like <TT>g</TT>,
 196 but use <TT>E</TT> instead of <TT>e</TT>.
 197 <li><cw>i</>
 198 Just like <TT>d</TT>.
 199 <li><cw>n</>
 200 The corresponding argument is an <TT>int *</TT>.
 201 Rather than printing anything,
 202 <TT>%n</TT> stores the number of characters printed so far
 203 (by this call to <TT>printf</TT>)
 204 into the integer pointed to by the corresponding argument.
 205 For example, if the variable <TT>np</TT> is an <TT>int</TT>,
 206 <TT>printf("%s %n%s!", "Hello", &amp;n, "world")</TT>
 207 stores 6 into <TT>np</TT>.
 208 <li><cw>o</>
 209 Print an unsigned integer, in octal (base 8).
 210 The corresponding argument is an <TT>unsigned int</TT>,
 211 or an <TT>unsigned long int</TT> if the <TT>l</TT> modifier appears,
 212 or an <TT>unsigned short int</TT> if the <TT>h</TT> modifier appears.
 213 If the <TT>#</TT> flag appears,
 214 and the number is nonzero,
 215 it will be preceded by an extra <TT>0</TT>,
 216 to make it look like a C octal constant.
 217 <li><cw>p</>
 218 Print a pointer value
 219 (the pointer, not what it points to),
 220 in some implementation-defined format.
 221 The corresponding argument is a <TT>void *</TT>.
 222 Usually, the value printed
 223 is the numeric value of the pointer--that is,
 224 the memory address pointed to--in
 225 hexadecimal.
 226 For the segmented architecture of the IBM PC,
 227 pointers are often printed using a <TT>segment:offset</TT> notation.
 228 <li><cw>s</>
 229 Print a string.
 230 The corresponding argument is a <TT>char *</TT>
 231 (which may result from an array of <TT>char</TT>).
 232 If the optional <I>precision</I> is present,
 233 at most that many characters of the string will be printed
 234 (if the <TT>\0</TT> isn't encountered first).
 235 <li><cw>u</>
 236 Print an unsigned decimal integer.
 237 The corresponding argument is an <TT>unsigned int</TT>,
 238 or an <TT>unsigned long int</TT> if the <TT>l</TT> modifier appears,
 239 or an <TT>unsigned short int</TT>
 240 if the <TT>h</TT> modifier appears.
 241 <li><cw>x</>
 242 Print an unsigned integer, in hexadecimal (base 16).
 243 The corresponding argument is an <TT>unsigned int</TT>,
 244 or an <TT>unsigned long int</TT> if the <TT>l</TT> modifier appears,
 245 or an <TT>unsigned short int</TT> if the <TT>h</TT> modifier appears.
 246 If the <TT>#</TT> flag appears,
 247 and the number is nonzero,
 248 it will be preceded by the characters <TT>0x</TT>,
 249 to make it look like a C hexadecimal constant.
 250 <li><cw>X</>
 251 Like <TT>x</TT>,
 252 except that the capital letters
 253 <TT>A</TT>, <TT>B</TT>, <TT>C</TT>, <TT>D</TT>, <TT>E</TT>, and <TT>F</TT>
 254 are used for the hexadecimal digits 10-15.
 255 (Also, the <TT>#</TT> flag leads to a leading <TT>0X</TT>.)
 256 <li><cw>%</>
 257 Print a single <TT>%</TT> sign.
 258 There is no corresponding argument.
 259 </UL>
 260 </p><p>When you want to print to an arbitrary stream,
 261 instead of standard output,
 262 just use <TT>fprintf</TT>,
 263 which takes a leading <TT>FILE *</TT> argument:
 264 <pre>
 265         fprintf(stderr, "Syntax error on line %d\n", lineno);
 266 </pre>
 267 </p><p>Sometimes,
 268 it's useful to do some <TT>printf</TT>-like formatting,
 269 but <em>not</em> output the string right away.
 270 The <TT>sprintf</TT> function is a <TT>printf</TT> variant
 271 which ``prints'' to an in-memory string
 272 rather than to a <TT>FILE *</TT> stream.
 273 For example,
 274 one way to convert an integer to a string
 275 (the opposite of <TT>atoi</TT>)
 276 is:
 277 <pre>
 278         int i = 123;
 279         char string[20];
 280         sprintf(string, "%d", i);
 281 </pre>
 282 One thing to be careful of with <TT>sprintf</TT>,
 283 though,
 284 is that it's up to you
 285 to make sure that the destination string
 286 is big enough.
 287 </p><hr>
 288 <p>
 289 Read sequentially:
 290 <a href="sx2d.html" rev=precedes>prev</a>
 291 <a href="sx2f.html" rel=precedes>next</a>
 292 <a href="sx2.html" rev=subdocument>up</a>
 293 <a href="top.html">top</a>
 294 </p>
 295 <p>
 296 This page by <a href="http://www.eskimo.com/~scs/">Steve Summit</a>
 297 // <a href="copyright.html">Copyright</a> 1996-1999
 298 // <a href="mailto:scs@eskimo.com">mail feedback</a>
 299 </p>
 300 </body>
 301 </html>