The sprintf function writes formatted data to a string.
extern sprintf stringvar output$ // output string string format // format-control string ... // optional arguments
Using sprintf is similar to using the echo, console, and string assignment ape commands, except that those functions are native ape commands (no need for the extern keyword) and cannot take string variables as the format parameter (you must supply a quoted string literal).
The format-control string contains format specifications that determine the output format for the arguments following the format 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.
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.
In-depth format specification information can be found in the Microsoft documentation for the printf format specification. Note that although the APE sprintf function supports all flag, width, and precision format specifiers, it does not support the character (c and C), pointer (p), progress (n), and unicode string (S) types. It also does not support the h | l | I64 | L optional specifiers. It also supports up to ten format specifiers.
What follows is an abridged version of the important stuff sprintf can do. A format specification has the following form:
%[flags][width][.precision]type
| Flag | Meaning |
|---|---|
| – | 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. |
| + | Prefix the output value with a sign (+ or –) if the output value is of a signed type. Default is sign displayed only for negative numbers. |
| # | Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase). |
| 0 | Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces. |
| blank (' ') | 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. |
| Field | Meaning |
| width | Copy the specified minimum number of characters to the output buffer. The width 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 width field is not present, all characters of the value are printed, subject to the precision specification. |
| .precision | 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 (.) appears without a
number following it, the precision is set to 1. For strings, copy the specified maximum number of characters to the output buffer. Unsupported: Using the asterisk (*) to denote variable precision. |
| type | Output the corresponding argument as a character, a string, or a number. See the following for legal values. |
| Type Value | Meaning |
| d | APE float displays as signed decimal integer. Equivalent to i. |
| i | APE float displays as signed decimal integer. Equivalent to d. |
| o | APE float displays as unsigned octal integer. |
| u | Ape float displays as unsigned decimal integer. |
| x, X | Ape float displays as unsigned hexadecimal integer in lowercase or uppercase. |
| e, E | Ape float displays as signed value having the form [ – ]d.dddd e [sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or –. |
| f | Ape float displays as signed value having the form [ – ]dddd.dddd, where dddd 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. |
| g, G | Ape float displays as signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than –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. |
| n | Unsupported: progress integer. |
| p | Unsupported: pointer value. |
| s | Ape string is displayed. Characters are printed up to the end of the string or until the precision value is reached. |
| S | Unsupported: Unicode strings. |
@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