219 lines
8.2 KiB
HTML
219 lines
8.2 KiB
HTML
<html>
|
||
<head>
|
||
<title>sprintf</title>
|
||
<meta name="Author" content="Joey">
|
||
<link rel="stylesheet" type="text/css" href="../webdocs.css">
|
||
</head>
|
||
<body>
|
||
<h1><a name="ape_sprintf"></a>sprintf</h3>
|
||
<p>The <b>sprintf</b> function writes formatted data to a string.</p>
|
||
|
||
<PRE class="syntax"><b>extern sprintf</b>
|
||
<b> stringvar</b><i> output$</i> // output string
|
||
<b> string</b><i> format</i> // format-control string
|
||
<b> </b><i>...</i> // optional arguments
|
||
</PRE>
|
||
|
||
<h4>Parameters</h4>
|
||
|
||
<dl>
|
||
<dt><i>output$</i></dt>
|
||
<dd>[out] String variable to receive the formatted output. The maximum length
|
||
of the output is 1024 characters.</dd>
|
||
<dt><i>format</i></dt>
|
||
<dd>[in] String that contains the format-control specifications.
|
||
In addition to ordinary ASCII characters, a format specification for each
|
||
argument appears in this string. For more information about the format
|
||
specification, see the Remarks section.</dd>
|
||
<dt><i>...</i></dt>
|
||
<dd>[in] Specifies one or more optional arguments. The number and type (either
|
||
string or float) of argument parameters depend on the corresponding format-control
|
||
specifications in the <i>format</i> parameter.</dd>
|
||
</dl>
|
||
|
||
<h4>Remarks</h4>
|
||
<p>Using sprintf is similar to using the <b>echo</b>, <b>console</b>, and
|
||
string assignment ape commands, except that those functions are native ape
|
||
commands (no need for the <b>extern</b> keyword) and cannot take string
|
||
variables as the format parameter (you must supply a quoted string literal).
|
||
|
||
<p>The format-control string contains format specifications that determine the
|
||
output format for the arguments following the <i>format</i> parameter. Format
|
||
specifications, discussed below, always begin with a percent sign (%). If a
|
||
percent sign is followed by a character that has no meaning as a format field,
|
||
an error message is printed to the console. To produce a single percent sign
|
||
character, use %% as a format field.</p>
|
||
|
||
<p>The format-control string is read from left to right. When the first format
|
||
specification (if any) is encountered, it causes the value of the first argument
|
||
after the format-control string to be converted and copied to the output buffer
|
||
according to the format specification. The second format specification causes
|
||
the second argument to be converted and copied, and so on. If there are more
|
||
arguments than format specifications, the extra arguments are ignored. If there
|
||
are not enough arguments for all of the format specifications, an error message
|
||
is printed to the console.</p>
|
||
|
||
<p>In-depth format specification information can be found in the Microsoft
|
||
documentation for the
|
||
<a class="external" href="http://msdn.microsoft.com/library/devprods/vs6/visualc/vccore/_crt_format_specification_fields_.2d_.printf_and_wprintf_functions.htm">
|
||
printf format specification</a>.
|
||
Note that although the APE
|
||
sprintf function supports all flag, width, and precision format specifiers,
|
||
it does not support the character (<b>c</b> and <b>C</b>), pointer (<b>p</b>),
|
||
progress (<b>n</b>), and unicode string (<b>S</b>) types. It also does not
|
||
support the <b>h</b> | <b>l</b> | <b>I64</b> | <b>L</b> optional specifiers.
|
||
It also supports up to ten format specifiers.
|
||
|
||
<p>What follows is an abridged version of the important stuff sprintf can do.
|
||
A format specification has the following form:</p>
|
||
|
||
<P><B>%</B>[<I>flags</I>][<I>width</I>][<B>.</B><I>precision</I>]<I>type</I></P>
|
||
|
||
<table>
|
||
<tr>
|
||
<th width=12% align=left>Flag</th>
|
||
<th width=64% align=left>Meaning</th>
|
||
</tr>
|
||
<tr>
|
||
<td><b><EFBFBD></b></td>
|
||
<td>Pad the output with blanks or zeros to the right to fill the field width, justifying
|
||
output to the left. If this flag is omitted, the output is padded to the left, justifying
|
||
it to the right.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><b>+</b></td>
|
||
<td>Prefix the output value with a sign (+ or <20>) if the output value is of a signed type.
|
||
Default is sign displayed only for negative numbers.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><b>#</b></td>
|
||
<td>Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><b>0</b></td>
|
||
<td>Pad the output value with zeros to fill the field width. If this field is omitted,
|
||
the output value is padded with blank spaces.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i>blank</i> (' ')</td>
|
||
<td>Prefix the output value with a blank if the output value is signed and positive; the blank
|
||
is ignored if both the blank and + flags appear. Default is no blank.</td>
|
||
</tr>
|
||
<tr>
|
||
<th align=left>Field</th>
|
||
<th align=left>Meaning</th>
|
||
</tr>
|
||
<tr>
|
||
<td><i>width</i></td>
|
||
<td>Copy the specified minimum number of characters to the output buffer. The <i>width</i> field
|
||
is a nonnegative integer. The width specification never causes a value to be truncated;
|
||
if the number of characters in the output value is greater than the specified width, or if the
|
||
<i>width</i> field is not present, all characters of the value are printed, subject to the
|
||
precision specification.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><b>.</b><i>precision</i></td>
|
||
<td>For numbers, copy the specified minimum number of digits to the output buffer. If the number
|
||
of digits in the argument is less than the specified precision, the output value is padded on the
|
||
left with zeros. The value is not truncated when the number of digits exceeds the specified precision.
|
||
If the specified precision is 0 or omitted entirely, or if the period (<b>.</b>) appears without a
|
||
number following it, the precision is set to 1.<hr>
|
||
For strings, copy the specified maximum number of characters to the output buffer.<hr>
|
||
<b>Unsupported:</b> Using the asterisk (<b>*</b>) to denote variable precision.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i>type</i></td>
|
||
<td>Output the corresponding argument as a character, a string, or a number.
|
||
See the following for legal values.</td>
|
||
</tr>
|
||
<tr>
|
||
<th align=left>Type Value</th>
|
||
<th align=left>Meaning</ht>
|
||
</tr>
|
||
<tr>
|
||
<td>d</td>
|
||
<td>APE float displays as signed decimal integer. Equivalent to i.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>i</td>
|
||
<td>APE float displays as signed decimal integer. Equivalent to d.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>o</td>
|
||
<td>APE float displays as unsigned octal integer.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>u</td>
|
||
<td>Ape float displays as unsigned decimal integer.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>x, X</td>
|
||
<td>Ape float displays as unsigned hexadecimal integer in lowercase or uppercase.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>e, E</td>
|
||
<td>Ape float displays as signed value having the form
|
||
[ <20> ]<i>d</i><b>.</b><i>dddd</i> <b>e</b> [<i>sign</i>]<i>ddd</i> where <i>d</i> is a
|
||
single decimal digit, <i>dddd</i> is one or more decimal digits, <i>ddd</i> is exactly
|
||
three decimal digits, and <i>sign</i> is + or <20>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>f</td>
|
||
<td>Ape float displays as signed value having the form [ <20> ]<i>dddd</i><b>.</b><i>dddd</i>,
|
||
where <i>dddd</i> is one or more decimal digits. The number of digits before the decimal
|
||
point depends on the magnitude of the number, and the number of digits after the decimal
|
||
point depends on the requested precision.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>g, G</td>
|
||
<td>Ape float displays as signed value printed in <b>f</b> or <b>e</b> format, whichever
|
||
is more compact for the given value and precision. The <b>e</b> format is used only
|
||
when the exponent of the value is less than <20>4 or greater than or equal to the precision
|
||
argument. Trailing zeros are truncated, and the decimal point appears only if one or
|
||
more digits follow it.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>n</td>
|
||
<td><b>Unsupported</b>: progress integer.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>p</td>
|
||
<td><b>Unsupported</b>: pointer value.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>s</td>
|
||
<td>Ape string is displayed. Characters are printed up to the end of the string
|
||
or until the precision value is reached.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>S</td>
|
||
<td><b>Unsupported</b>: Unicode strings.</td>
|
||
</tr>
|
||
</table>
|
||
</p>
|
||
<h4>Examples</h4>
|
||
<pre>@fval = 20.58
|
||
@sval$ = "hello"
|
||
|
||
extern sprintf s$ "float: %.1f" @fval
|
||
// float: 20.6
|
||
|
||
extern sprintf s$ "integer: %i" @fval
|
||
// integer: 21
|
||
|
||
extern sprintf s$ "integer: %04i" @fval
|
||
// integer: 0021
|
||
|
||
extern sprintf s$ "integer: %8i" @fval
|
||
// integer: 21
|
||
// (note extra space)
|
||
|
||
extern sprintf s$ "string: %s, %s!" @sval$ "world"
|
||
// string: hello, world!
|
||
|
||
extern sprintf s$ "string: %.3s" @sval$
|
||
// string: hel
|
||
|
||
</pre>
|
||
</body>
|
||
</html>
|