home *** CD-ROM | disk | FTP | other *** search
/ PC World 2002 May / PCWorld_2002-05_cd.bin / Komunik / sambar / sambar51p.exe / syshelp / cscript / funcs / PRINTF.HTM < prev    next >
Encoding:
Text File  |  2002-01-05  |  17.6 KB  |  390 lines

  1. <H3>SYNOPSIS</H3>
  2.      int printf(const char *format, /* args*/ ...);
  3. <BR>
  4.      int sprintf(char *s, const char *format, /* args*/ ...);
  5. <BR>
  6. <BR>
  7. The printf() function places output on the output stream stdout.
  8. The sprintf() function places output, followed by the null byte (\0),  
  9. in consecutive bytes starting at <I>s</I>; the CScript engine ensures
  10. that enough storage is available.
  11. <BR>
  12. Each of these functions converts, formats, and prints its <I>args</I> 
  13. under control of the <I>format</I>. The <I>format</I> is a character
  14. string, beginning and ending in its initial shift state, if any.   
  15. The <I>format</I> is composed  of zero or more directives defined as follows:
  16. <P>
  17. <UL>
  18. <LI><I>ordinary</I> <I>characters</I>, which are simply  copied  to  the 
  19. output stream;</LI>
  20. <LI><I>escape</I> <I>sequences</I>, which represent non-graphic  characters; 
  21. and</LI> 
  22. <LI><I>conversion</I> <I>specifications</I>, each of  which  results  in the 
  23. fetching of zero or more arguments.</LI>
  24. </UL>
  25. <P>
  26. The results are undefined if there  are  insufficient  arguments for the 
  27. <I>format</I>. If the <I>format</I> is exhausted while arguments remain, 
  28. the excess arguments  are  evaluated  but  are otherwise ignored.
  29. Conversions can be applied to the  <I>n</I>th  argument  after  the
  30. <I>format</I>  in the argument list, rather than to the next unused
  31. argument. In this case,  the  conversion  character %  (see below) is 
  32. replaced by the sequence %<I>n</I>$, where <I>n</I> is a decimal integer 
  33. in the range [1, NL_ARGMAX], giving the position  of
  34. the argument in the argument list. This feature provides for
  35. the definition of format strings that select arguments in an
  36. order  appropriate  to  specific languages (see the EXAMPLES section).
  37. <P>
  38. In format strings containing  the  %<I>n</I>$  form  of  conversion
  39. specifications,  numbered arguments in the argument list can
  40. be referenced from  the  format  string  as  many  times  as
  41. required.
  42. <P>
  43. In format  strings  containing  the  %  form  of  conversion
  44. specifications,  each  argument in the argument list is used
  45. exactly once.
  46. <P>
  47. <B>Escape Sequences</B><BR>
  48. The following escape sequences produce the associated action
  49. on display devices capable of the action:
  50. <UL>
  51. <LI><B>\n</B> Newline. Move the printing position to  the  start
  52. of the next line.</LI>
  53. <LI><B>\r</B> Carriage return. Move the printing position to the
  54. start of the current line.</LI>
  55. <LI><B>\t</B> Horizontal tab. Move the printing position to  the
  56. next  implementation-defined  horizontal tab position on the current line.</LI>
  57. </UL>
  58. <P>
  59. <B>Conversion Specifications</B><BR>
  60. Each conversion specification is introduced by the character
  61. %  or by the character sequence %<I>n</I>$, after which the following
  62. appear in sequence:
  63. <P>
  64. <UL>
  65. <LI>An optional  field,  consisting  of  a  decimal  digit
  66. string followed by a $, specifying the next <I>args</I> to be
  67. converted. If this field is  not  provided,  the  <I>args</I>
  68. following the last <I>args</I> converted will be used.</LI>
  69.  
  70. <LI>Zero or more <I>flags</I> (in any order),  which  modify  the
  71. meaning of the conversion specification.</LI>
  72.  
  73. <LI>An optional minimum  <I>field</I>  <I>width</I>.  If  the  converted
  74. value has fewer bytes than the field width, it will be
  75. padded with spaces by default on the left; it will  be
  76. padded  on the right, if the left-adjustment flag (-),
  77. described below, is given  to  the  field  width.  The
  78. field  width  takes  the  form  of  an  asterisk  (*),
  79. described below, or a decimal integer.<BR>
  80.  
  81. If the conversion  character  is  s,  a  standard-conforming  
  82. application  interprets the field width as  the  
  83. minimum  number  of
  84. bytes  to  be  printed; an application that is not
  85. standard-conforming interprets the field width  as
  86. the  minimum  number of columns of screen display.
  87. For  an  application   that   is   not   standard-
  88. conforming,  %10s means if the converted value has
  89. a screen width of 7 columns,  3  spaces  would  be
  90. padded on the right.
  91. <BR>
  92. If the format is %ws, then the field width  should
  93. be   interpreted  as the minimum number of columns
  94. of screen display.</LI>
  95.  
  96. <LI>An optional <I>precision</I> that gives the minimum number of
  97. digits  to  appear for the d, i, o, u, x, or X conversions (the field 
  98. is padded with  leading  zeros);  the
  99. number  of  digits to appear after the radix character
  100. for the e, E, and f conversions, the maximum number of
  101. significant digits for the g and G conversions; or the
  102. maximum number of bytes to be printed from a string in
  103. s  and S conversions.  The precision takes the form of
  104. a period (.)  followed  either  by  an  asterisk  (*),
  105. described  below, or an optional decimal digit string,
  106. where a null digit string is treated as 0.  If a  precision  
  107. appears  with  any other conversion character,
  108. the behavior is undefined.<BR>
  109.  
  110. If  the  conversion  character  is  s  or   S,   a
  111. standard-conforming application interprets the precision 
  112. as the maximum number  of bytes  to  be  written; an application that is not
  113. standard-conforming interprets  the  precision  as
  114. the  maximum  number of columns of screen display.
  115. For  an  application   that   is   not   standard-conforming,  
  116. %.5s  would print only the portion of
  117. the string that would display in 5 screen columns.
  118. Only complete characters are written.
  119.  
  120. For %ws, the precision should  be  interpreted  as
  121. the  maximum  number of columns of screen display.
  122. The precision takes the form of a period (.)  followed  by  a  
  123. decimal  digit  string; a null digit
  124. string is treated as zero.  Padding  specified  by
  125. the  precision  overrides the padding specified by
  126. the field width.</LI>
  127.  
  128. <LI>An optional h specifies that a following d, i,  o,  u,
  129. x,  or  X conversion character applies to a type short
  130. int or unsigned short int argument (the argument  will
  131. be  promoted  according to the integral promotions and
  132. its value converted to  type  short  int  or  unsigned
  133. short  int  before  printing); an optional h specifies
  134. that a following n conversion character applies  to  a
  135. pointer  to  a type short int argument. An optional  l
  136. (ell) specifies that a following  d, i, o, u, x, or  X
  137. conversion  character  applies  to  a type long int or
  138. unsigned long  int  argument;  an  optional   l  (ell)
  139. specifies  that  a  following   n conversion character
  140. applies to a pointer to a type long int  argument.  An
  141. optional  ll (ell ell)  specifies that a following  d,
  142. i, o, u, x, or  X conversion character  applies  to  a
  143. type  long  long  or   unsigned long long argument; an
  144. optional  ll (ell ell)  specifies that a following   n
  145. conversion  character  applies to a pointer to a  long
  146. long argument. An optional L specifies that a  following
  147. e, E, f, g, or G conversion character applies to a
  148. long double argument. If an h, l, or L appears  before
  149. any  other conversion character, the behavior is undefined.</LI>
  150.  
  151. <LI>A <I>conversion</I> <I>character</I> (see below) that indicates  the
  152. type of conversion to be applied.</LI>
  153. </UL>
  154. <P>
  155. A field width or precision may be indicated by  an  asterisk
  156. (*) instead of a digit string. In this case, an integer <I>args</I>
  157. supplies the field width or precision.   The  <I>args</I>  that  is
  158. actually  converted  is  not  fetched  until  the conversion
  159. letter is seen, so the <I>args</I> specifying field width or precision
  160. must  appear before the <I>args</I> (if any) to be converted.
  161. If the <I>precision</I> argument is negative, it will be changed to
  162. zero.  A negative field width argument is taken as a - flag,
  163. followed by a positive field width. A negative precision  is
  164. taken  as  if  the precision were omitted. In format strings
  165. containing the %<I>n</I>$ form of  a  conversion  specification,  a
  166. field  width  or  precision may be indicated by the sequence
  167. *<I>m</I>$,  where  <I>m</I>  is  a  decimal  integer  in  the  range  [1,
  168. NL_ARGMAX]  giving  the position in the argument list (after
  169. the format argument) of an integer argument  containing  the
  170. field width or precision, for example:
  171. <P>
  172. <BLOCKQUOTE>
  173.      <CODE>printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);</CODE>
  174. </BLOCKQUOTE>
  175. <P>
  176. The <I>format</I> can contain either numbered  argument  specifications
  177. (that is, %<I>n</I>$ and *<I>m</I>$), or unnumbered argument specifications
  178. (that is, % and *), but normally not both. The only exception to this 
  179. is that %% can be mixed with the %<I>n</I>$ form.  The results  of  mixing  
  180. numbered  and  unnumbered  argument specifications  in  a <I>format</I> 
  181. string are undefined. When numbered argument specifications are used, 
  182. specifying  the  <I>N</I>th argument  requires  that all the leading 
  183. arguments, from the first to the (<I>N</I>-<I>1</I>)th, are specified in 
  184. the format string.
  185. <P>
  186. <B>Flag Characters</B><BR>
  187. The flag characters and their meanings are:
  188. <BR>
  189. <UL>
  190. <LI><B>'</B> The integer portion of the  result  of  a  decimal
  191. conversion  (%i,  %d,  %u,  %f, %g, or %G) will be
  192. formatted with thousands' grouping characters. For
  193. other  conversions  the behavior is undefined. The
  194. non-monetary grouping character is used.</LI>
  195.  
  196. <LI><B>-</B> The  result  of  the  conversion  will  be   left-justified  
  197. within  the  field.  (It will be right-justified if this flag is not 
  198. specified.)
  199. <LI><B>+</B> The result of  a  signed  conversion  will  always
  200. begin  with a sign (+ or -). (It will begin with a
  201. sign only when a negative value  is  converted  if
  202. this flag is not specified.)</LI>
  203. <LI><B>space</B> If the first character of a signed  conversion  is
  204. not  a  sign,  a  space  will be placed before the
  205. result. This means that if the space and  +  flags
  206. both appear, the space flag will be ignored.
  207. <LI><B>#</B> The value is to be converted to an alternate form.
  208. For c, d, i, s, and u conversions, the flag has no
  209. effect. For an o conversion, it increases the precision  to  
  210. force the first digit of the result to be a zero. 
  211. For x (or  X)  conversion,  a  non-zero
  212. result  will  have 0x (or 0X) prepended to it. For
  213. e, E, f, g, and G  conversions,  the  result  will
  214. always  contain  a  radix  character,  even  if no
  215. digits follow the point (normally, a decimal point
  216. appears in the result of these conversions only if
  217. a digit follows it).  For  g  and  G  conversions,
  218. trailing zeros will not be removed from the result
  219. as they normally are.</LI>
  220. <LI><B>0</B> For d, i, o, u, x, X, e, E, f, g,  and  G  conversions,  
  221. leading zeros (following any indication of
  222. sign or base) are used to pad to the field  width;
  223. no  space  padding  is  performed.  If the 0 and -
  224. flags both appear, the 0 flag will be ignored. For
  225. d,  i,  o, u, x, and X conversions, if a precision
  226. is specified, the 0  flag  will  be  ignored.  For
  227. other conversions, the behavior is undefined.
  228. </UL>
  229. <P>
  230. <B>Conversion Characters</B><BR>
  231. Each conversion character results in fetching zero  or  more
  232. <I>args</I>.  The  results  are undefined if there are insufficient
  233. <I>args</I> for the format. If the format is exhausted  while  <I>args</I>
  234. remain, the excess <I>args</I> are ignored.
  235. <P>
  236. The conversion characters and their meanings are:
  237. <UL>
  238. <LI><B>d,i</B> The int argument is converted to a signed  decimal
  239. in  the style [-]<I>dddd</I>. The precision specifies the
  240. minimum number of digits to appear; if  the  value
  241. being   converted  can  be  represented  in  fewer
  242. digits, it will be expanded  with  leading  zeros.
  243. The default precision is 1. The result of converting 0 
  244. with an explicit precision of 0 is no  characters.</LI>
  245.  
  246. <LI><B>o</B> The unsigned int argument is converted to unsigned
  247. octal  format  in  the  style  <I>dddd</I>. The precision
  248. specifies the minimum number of digits to  appear;
  249. if the value being converted can be represented in
  250. fewer digits, it will  be  expanded  with  leading
  251. zeros.  The  default precision is 1. The result of
  252. converting 0 with an explicit precision of 0 is no
  253. characters.</LI>
  254.  
  255. <LI><B>u</B> The unsigned int argument is converted to unsigned
  256. decimal  format  in  the style <I>dddd</I>. The precision
  257. specifies the minimum number of digits to  appear;
  258. if the value being converted can be represented in
  259. fewer digits, it will  be  expanded  with  leading
  260. zeros.  The  default precision is 1. The result of
  261. converting 0 with an explicit precision of 0 is no
  262. characters.</LI>
  263.  
  264. <LI><B>x</B> The unsigned int argument is converted to unsigned
  265. hexadecimal  format in the style <I>dddd</I>; the letters
  266. abcdef  are  used.  The  precision  specifies  the
  267. minimum  number  of digits to appear; if the value
  268. being  converted  can  be  represented  in   fewer
  269. digits,  it  will  be expanded with leading zeros.
  270. The default precision is 1. The result of converting
  271. ing  0 with an explicit precision of 0 is no characters.</LI>
  272.  
  273. <LI><B>X</B> Behaves the same as  the  x  conversion  character
  274. except  that  letters  ABCDEF  are used instead of abcdef.</LI>
  275.  
  276. <LI><B>f</B> The double <I>args</I> is converted to  decimal  notation
  277. in  the  style  [-]<I>ddd</I>.<I>ddd</I>,  where  the  number of
  278. digits   after   the    radix    character    
  279. is equal to the precision specification. If the precision is 
  280. omitted from <I>arg</I>,  six
  281. digits are output; if the  precision is explicitly
  282. zero and the # flag is  not  specified,  no  radix
  283. character  appears.  If a radix character appears,
  284. at least 1 digit appears before it. The  value  is
  285. rounded to the appropriate number of digits.</LI>
  286.  
  287. <LI><B>e,E</B> The  double  <I>args</I>  is  converted  to   the   style
  288. [-]<I>d</I>.<I>ddd</I>e<B>_</B><I>dd</I>,  where there is one digit before the
  289. radix character (which is non-zero if the argument
  290. is  non-zero) and the number of digits after it is
  291. equal to the  precision.  When  the  precision  is
  292. missing, six digits are produced; if the precision
  293. is zero and the # flag is not specified, no  radix
  294. character  appears.   The  E  conversion character
  295. will produce a number with E instead of  e  introducing  the 
  296. exponent. The exponent always contains
  297. at least two digits.  The value is rounded to  the
  298. appropriate number of digits.</LI>
  299.  
  300. <LI><B>g,G</B> The double <I>args</I> is printed in style f or e (or  in
  301. style  E in the case of a G conversion character),
  302. with the precision specifying the number of significant  digits.  
  303. If  the  precision is zero, it is
  304. taken as one. The style used depends on the  value
  305. converted: style e (or E) will be used only if the
  306. exponent resulting from  the  conversion  is  less
  307. than -4 or greater than or equal to the precision.
  308. Trailing zeros are  removed  from  the  fractional
  309. part of the result. A radix character appears only
  310. if it is followed by a digit.</LI>
  311.  
  312. <LI><B>c</B> The int <I>args</I> is converted to an unsigned char, and
  313. the resulting byte is printed.</LI>
  314.  
  315. <LI><B>s</B> The <I>args</I>  is  taken  to  be  a  string  (character
  316. pointer)  and characters from the string are written
  317. up to (but not including) a  terminating  null
  318. byte.  If  a  precision  is specified, a standard-conforming  application  
  319. will write only the number of bytes specified by precision;  an  
  320. application  that  is   not   standard-conforming  will  write  only  
  321. the  portion of the string that will  display in the number of columns
  322. of screen display specified by precision.
  323. <BR>
  324. If the precision is not specified, it is taken  to
  325. be  infinite,  so  all  bytes up to the first null
  326. byte are printed. A null value for <I>args</I> will yield
  327. undefined results.</LI>
  328.  
  329. <LI><B>%</B> Print a %; no argument is  converted.  The  entire
  330. conversion specification must be %%.</LI>
  331. </UL>
  332. <P>
  333. If a conversion specification does  not  match  one  of  the
  334. above forms, the behavior is undefined.
  335. <P>
  336. If a floating-point value is the internal representation for
  337. infinity,  the  output  is  [<B>_</B>]<I>Infinity</I>,  where  <I>Infinity</I> 
  338. is either Infinity or Inf,  depending  on  the  desired  output
  339. string  length.  Printing  of  the  sign  follows  the rules
  340. described above.
  341. <P>
  342. If a floating-point value is the internal representation for
  343. "not-a-number,"  the  output is [<B>_</B>]<I>NaN</I>. Printing of the sign
  344. follows the rules described above.
  345. <P>
  346. In no case does a non-existent or small  field  width  cause
  347. truncation  of  a  field;  if  the result of a conversion is
  348. wider than the field width, the field is simply expanded  to
  349. contain  the  conversion  result.  Characters  generated  by
  350. printf() are  printed  as  if  the  function had been called.
  351. <P>
  352. <H3>RETURN VALUES</H3>
  353. The printf() and sprintf() functions return  the number  of  bytes  
  354. transmitted  (not including the \0 in the case of sprintf()).  The  
  355. snprintf()  function  returns  the number of characters formatted, 
  356. that is, the number of characters that were written to the buffer. 
  357. Each function returns a negative value if an output error was encountered.
  358. <P>
  359. <H3>EXAMPLES</H3>
  360. Example 1: To print the language-independent date  and  time
  361. format, the following statement could be used:
  362. <BLOCKQUOTE>
  363. printf (format, weekday, month, day, hour, min);
  364. </BLOCKQUOTE>
  365. For American usage, <I>format</I> could be a pointer to the string:
  366. <BLOCKQUOTE>
  367. "%s, %s %d, %d:%.2d\n"
  368. </BLOCKQUOTE>
  369. producing the message:
  370. <BLOCKQUOTE>
  371.      Sunday, July 3, 10:02
  372. </BLOCKQUOTE>
  373. whereas for German usage, <I>format</I> could be a pointer  to  the string:
  374. <BLOCKQUOTE>
  375.      "%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
  376. </BLOCKQUOTE>
  377. producing the message:
  378. <BLOCKQUOTE>
  379. Sonntag, 3. Juli, 10:02
  380. </BLOCKQUOTE>
  381. Example 2: To print a date and time in the form Sunday, July
  382. 3,  10:02,  where  weekday  and  month are pointers to null-terminated strings:
  383. <BLOCKQUOTED>
  384.      printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min);
  385. </BLOCKQUOTED>
  386. Example 3: To print pi to 5 decimal places:
  387. <BLOCKQUOTED>
  388.      printf("pi = %.5f", 4 * atan(1.0));
  389. </BLOCKQUOTED>
  390.