Returns a formatted string (similar to the C sprintf() function).
StringFormat ( "format control" [, var1 [, ... var32]] )
| format control | The format and flags to use (see Remarks). |
| var1...var32 | Up to 32 variables that will be output according to the "format control". |
To prevent buffer overflow, each "variable" is limited to 65535 characters.
Escape characters can be contain in the "format control" such as \n (@LF), \r (@CR), \t (@TAB]. So if you want to have a "\" you need to use \\, samething for "%" %%.
"variable format" is; %[flags] [width] [.precision] type
If a format specification is invalid, the behaviour is undefined. If you specify invalid input you can in special circumstances create unhandled exception and cause program termination.
Width Specification
The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values — depending on whether the – flag (for left alignment) is specified — until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).
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 width is not given, all characters of the value are printed (subject to the precision specification).
Type Specification
| Type | Variable type | Output format |
|---|---|---|
| d, i | Integer | Signed decimal integer. |
| o | Integer | Unsigned octal integer. |
| u | Integer | Unsigned decimal integer. |
| x | Integer | Unsigned hexadecimal integer, using "abcdef". |
| X | Integer | Unsigned hexadecimal integer, using "ABCDEF". |
| e | Float | 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 -. |
| E | Float | Identical to the e format except that E rather than e introduces the exponent. |
| f | Float | 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 | Float | 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. |
| G | Float | Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate). |
| s | String | String. |
| Flag | Meaning | Default |
|---|---|---|
| - | Left align the result within the given field width. | Right align. |
| + | Prefix the output value with a sign (+ or -) if the output value is of a signed type. | Sign appears only for negative signed values (-). |
| 0 | If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and - appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored. | No padding. |
| 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. | No blank appears. |
| # | When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. | No blank appears. |
| # | When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. | Decimal point appears only if digits follow it. |
| # | When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. Ignored when used with d, i, u, or s. |
Decimal point appears only if digits follow it. Trailing zeros are truncated. |
| Type | Meaning | Default |
|---|---|---|
| d, i, u, o, x, X | The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. | Default precision is 1. |
| e, E | The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded. | Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed. |
| f The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. | Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed. | |
| g, G | The precision specifies the maximum number of significant digits printed. | Six significant digits are printed, with any trailing zeros truncated. |
| s | The precision specifies the maximum number of characters to be printed. Characters in excess of precision are not printed. | Characters are printed until a null character is encountered. |
Example()
Func Example()
Local $iInt_Unsigned = 43951789
Local $iInt_Negative = -43951789
ConsoleWrite(@CRLF & "Numeric Formats" & @CRLF)
PrintFormat($iInt_Unsigned, "%d", "standard positive integer with no sign", 1) ; 43951789
PrintFormat($iInt_Negative, "%d", "standard negative integer with sign", 1) ; -43951789
PrintFormat($iInt_Unsigned, "%i", "standard integer", 1) ; 43951789
PrintFormat($iInt_Unsigned, "%09i", "9 digits with leading zero", 1) ; 043951789
PrintFormat($iInt_Unsigned, "%e", "scientific notation") ; 4.395179e+007
PrintFormat($iInt_Unsigned, "%u", "unsigned integer with positive integer", 1) ; 43951789
PrintFormat($iInt_Negative, "%u", "unsigned integer with negative integer", 1) ; 4251015507
PrintFormat($iInt_Unsigned, "%f", "floating point") ; 43951789.000000
PrintFormat($iInt_Unsigned, "%.2f", "floating point with 2 digits after decimal point", 1) ; 43951789.00
PrintFormat($iInt_Unsigned, "%o", "octal", 1) ; 247523255
PrintFormat($iInt_Unsigned, "%s", "string", 1) ; 43951789
PrintFormat($iInt_Unsigned, "%x", "hexadecimal (lower-case)", 1) ; 29ea6ad
PrintFormat($iInt_Unsigned, "%X", "hexadecimal (upper-case)", 1) ; 29EA6AD
PrintFormat($iInt_Unsigned, "%+d", "sign specifier on a positive integer", 1) ; +43951789
PrintFormat($iInt_Negative, "%+d", "sign specifier on a negative integer", 1) ; -43951789
Local $sString = "string"
Local $sString_Long = "longstring"
ConsoleWrite(@CRLF & "String Formats - [ ] used to show beginning/end of string" & @CRLF)
PrintFormat($sString, "[%s]", "standard string", 1) ; [string]
PrintFormat($sString, "[%10s]", "10 chars right justified with added spaces") ; [ string]
PrintFormat($sString, "[%-10s]", "10 chars left justified with added spaces") ; [string ]
PrintFormat($sString_Long, "[%10.8s]", "right justified but precision 8 so truncated") ; [ longer s]
PrintFormat($sString_Long, "[%-10.8s]", "left justifed but precision 8 so truncated") ; [longer s ]
PrintFormat($sString, "[%010s]", "10 chars with leading zero") ; [0000string]
ConsoleWrite(@CRLF & "Date Format - each % uses a new parameter" & @CRLF)
ConsoleWrite('"%02i\%02i\%04i" 0n (1, 9, 2013) => ' & StringFormat("%02i\%02i\%04i", 1, 9, 2013) & @CRLF)
ConsoleWrite(@CRLF & "Just string to format without Vars" & @CRLF)
ConsoleWrite('"Some \texample text\n" => ' & StringFormat('Some \texample text\n'))
EndFunc ;==>Example
Func PrintFormat($vVar, $sFormat, $sExplan, $iTab = 0)
ConsoleWrite('"' & $sFormat & '" on ' & $vVar & @TAB & ' => ' & StringFormat($sFormat, $vVar))
If $iTab Then ConsoleWrite(@TAB)
ConsoleWrite(@TAB & " ; " & $sExplan & @CRLF)
EndFunc ;==>PrintFormat