Core Function Fmt
Fmt( <format control>, <params> )
Contents |
Description
Returns a formatted string (similar to the C sprintf() function).
Parameters
format control
The format and flags to use (see Remarks).
This can be either a string or an array that will be converted into a string
params
Variables that will be output according to the "format control".
The variables can also be arrays with their own unique designated separator.
When using arrays you may have any/all/none of the following Keys (Case-Sensitive):
KEY WHAT IT DOES "fmtSeparator" Allows you to define a separator for each element in the array to use "fmtBegin" Allows you to define a string to add to the beginning of each element in the array "fmtEnd" Allows you to define a string to add to the end of each element in the array
See example for more information.
If there is just one param and it is a full hash (dictionary) using keys/values only then it will treated very differently see example for hash stuff.
Return Value
Success: Return the formatted string according to "variable format" defined in the "format control" parameter.
Failure: Returns "" (blank string).
Remarks
If you wish to immediately print to the console rather than return a string you should see PrintfC( <format control>, <params> ).
To prevent buffer overflow, each "variable" is limited to 65535 characters.
If you want to have "%" in the format control you must enter "%%".
"variable format" is; %[flags] [width] [.precision] type
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 Specification
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 c, d, i, u, or s. Decimal point appears only if digits follow it.
Trailing zeros are truncated.
Precision Specification
The third optional field of the format specification is the precision specification. It specifies a nonnegative decimal integer, preceded by a period (.), which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits (see Table below). Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If precision is specified as 0 and the value to be converted is 0, the result is no characters output, as shown below:
Fmt( "%.0d", 0 ); /* No characters return */
How Precision Values Affect Type
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
Large example
$n = 43951789; $u = -43951789; // notice the double %%, this prints a literal '%' character vPrintf("%%d = '%d'\n", $n); //'43951789' standard integer representation vPrintf("%%e = '%e'\n", $n); //'4.395179e+007' scientific notation vPrintf("%%u = '%u'\n", $n); //'43951789' unsigned integer representation of a positive integer vPrintf("%%u <0 = '%u'\n", $u); //'4251015507' unsigned integer representation of a negative integer vPrintf("%%f = '%f'\n", $n); //'43951789.000000' floating point representation vPrintf("%%.2f = '%.2f'\n", $n); //'43951789.00' floating point representation 2 digits after the decimal point vPrintf("%%o = '%o'\n", $n); //'247523255' octal representation vPrintf("%%s = '%s'\n", $n); //'43951789' string representation vPrintf("%%x = '%x'\n", $n); //'29ea6ad' hexadecimal representation (lower-case) vPrintf("%%X = '%X'\n", $n); //'29EA6AD' hexadecimal representation (upper-case) vPrintf("%%+d = '%+d'\n", $n); //'+43951789' sign specifier on a positive integer vPrintf("%%+d <0= '%+d'\n", $u); //'-43951789' sign specifier on a negative integer $s = 'monkey'; $t = 'many monkeys'; vPrintf("%%s = [%s]\n", $s); //[monkey] standard string output vPrintf("%%10s = [%10s]\n", $s); //[ monkey] right-justification with spaces vPrintf("%%-10s = [%-10s]\n", $s); //[monkey ] left-justification with spaces vPrintf("%%010s = [%010s]\n", $s); //[0000monkey] zero-padding works on strings too vPrintf("%%10.10s = [%10.10s]\n", $t); //[many monke] left-justification but with a cutoff of 10 characters vPrintf("%04d-%02d-%02d\n", 2008, 4, 1); Function vPrintf() { print(CallArray("fmt", @args)); }
If you are wondering how the hell to do a 64-bit signed integer
vPrintf("Int64 value is: '%I64d' ok\n", @Int64_Max); Function vPrintf() { print(CallArray("fmt", @args)); }
If you are wondering how the hell to do a 64-bit unsigned integer
vPrintf("Int64 value is: '%llu' ok\n", @UInt64_Max); Function vPrintf() { print(CallArray("fmt", @args)); }
Example of using arrays
$n = 777; $t = array(100, 200, 300, 400); vPrintf("Single value is '%d' but lets do an array of values '%d' cool huh?\n", $n, $t); Function vPrintf() { print(CallArray("fmt", @args)); }
Example of using arrays with seperator
$n = 777; $t = array("fmtSeparator" => "-", 100, 200, 300, 400); vPrintf("Single value is '%d' but lets do an array of values '%d' cool huh?\n", $n, $t); Function vPrintf() { print(CallArray("fmt", @args)); }
Large example with arrays
$ints = array("fmtSeparator" => "-", 100, 200, 300, 400); $floats = array("fmtSeparator" => "#", 100.2, 777.42, 133.77, 88.1); $strings = array("fmtSeparator" => "#", "One", "Two", "Three"); vPrintf("Ints '%d' \nFloats '%g' \nStrings '%s'\n", $ints, $floats, $strings); Function vPrintf() { print(CallArray("fmt", @args)); }
Example using "fmtSeparator", "fmtBegin" and "fmtEnd"
$arr = array("fmtSeparator" => "\n", "fmtBegin" => "0x", "fmtEnd" => "<-- Hex yup", 0..50); vPrintf("Hex of the array\n%x\n", $arr); Function vPrintf() { print(CallArray("fmt", @args)); }
More examples
vPrintf( '%+d\n', 42 ); # '+42' vPrintf( '%4d\n', 42 ); # ' 42' vPrintf( '%04d\n', 42 ); # '0042' vPrintf( '%X\n', 0x1337f00d ); # '1337F00D' Function vPrintf() { print(CallArray("fmt", @args)); }
Using an array as the format string
$arr = array("huey", "dewey", "louie"); say fmt($arr); # 'huey dewey louie' $arr = array(10, 11, 12); say fmt('%x', $arr); # 'abc' $arr = array("fmtSeparator" => " ", 10, 11, 12); say fmt('%x', $arr); # 'a b c' $arr = array("fmtSeparator" => '; ', 1, 2, 3); say fmt('%02d', $arr); # '01; 02; 03'
Using an array (as a dictionary) as the format string
$arr = array("foo" => 1, "bar" => 2); say fmt($arr); # 'foo 1 # bar 2' $arr = array("foo" => 1, "bar" => 2, "testingFooBar" => 3); say fmt($arr); # 'foo 1 # bar 2 # testingFooBar 3' $arr = array("Apples" => 5, "Oranges" => 10); say fmt('%s cost %d euros', $arr); # 'Apples cost 5 euros # Oranges cost 10 euros' // Of course you can still use the fmtSeparator $arr = array("fmtSeparator" => ";", "Apples" => 5, "Oranges" => 10); say fmt('%s cost %d euros', $arr); # 'Apples cost 5 euros;Oranges cost 10 euros' // Of course fmtBegin and fmtEnd are useable too $arr = array("fmtBegin" => ">>>", "fmtEnd" => "<<<", "Apples" => 5, "Oranges" => 10); say fmt('%s cost %d euros', $arr); # '>>>Apples cost 5 euros<<< # >>>Oranges cost 10 euros<<<' // Can use them all $arr = array("fmtSeparator" => ";", "fmtBegin" => ">>>", "fmtEnd" => "<<<", "Apples" => 5, "Oranges" => 10); say fmt('%s cost %d euros', $arr); # '>>>Apples cost 5 euros<<<;>>>Oranges cost 10 euros<<<'
