Core Function SPrintf
SPrintf( <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 dictionary using keys/values only then it will treated very differently see example for dictionary 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 Printf( <format control>, <params> ).
Unlike AutoIt (And similar programs) there is no buffer overflow chance, each "variable" is not limited to any amount characters it can be as big as it needs to be.
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
b Integer Binary number.
B Long Integer Binary number.
d, i Integer Signed decimal integer.
D Long Integer Signed decimal long integer.
o Integer Unsigned octal integer.
O Long Integer Unsigned octal long integer.
u Integer Unsigned decimal integer.
U Long Integer Unsigned decimal long 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.
c Character A single character.
V SV Interpret integer as Sputnik's standard integer type.
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:
sprintf( "%.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
Before we begin
// Anything you can do in Printf you can return it as a string using Sprintf // Like so.. $value = sprintf("%%e = '%e'\n", 777); print($value);
Large example
$n = 43951789; $u = -43951789; // notice the double %%, this prints a literal '%' character Printf("%%d = '%d'\n", $n); //'43951789' standard integer representation Printf("%%e = '%e'\n", $n); //'4.395179e+007' scientific notation Printf("%%u = '%u'\n", $n); //'43951789' unsigned integer representation of a positive integer Printf("%%u <0 = '%u'\n", $u); //'4251015507' unsigned integer representation of a negative integer Printf("%%f = '%f'\n", $n); //'43951789.000000' floating point representation Printf("%%.2f = '%.2f'\n", $n); //'43951789.00' floating point representation 2 digits after the decimal point Printf("%%o = '%o'\n", $n); //'247523255' octal representation Printf("%%s = '%s'\n", $n); //'43951789' string representation Printf("%%x = '%x'\n", $n); //'29ea6ad' hexadecimal representation (lower-case) Printf("%%X = '%X'\n", $n); //'29EA6AD' hexadecimal representation (upper-case) Printf("%%+d = '%+d'\n", $n); //'+43951789' sign specifier on a positive integer Printf("%%+d <0= '%+d'\n", $u); //'-43951789' sign specifier on a negative integer $s = 'monkey'; $t = 'many monkeys'; Printf("%%s = [%s]\n", $s); //[monkey] standard string output Printf("%%10s = [%10s]\n", $s); //[ monkey] right-justification with spaces Printf("%%-10s = [%-10s]\n", $s); //[monkey ] left-justification with spaces Printf("%%010s = [%010s]\n", $s); //[0000monkey] zero-padding works on strings too Printf("%%10.10s = [%10.10s]\n", $t); //[many monke] left-justification but with a cutoff of 10 characters Printf("%04d-%02d-%02d\n", 2008, 4, 1);
If you are wondering how the hell to do a 64-bit signed integer
// Recommended way Printf("Int64 value is: '%D' ok\n", @Int64_Max); // Alternative Printf("Int64 value is: '%I64d' ok\n", @Int64_Max);
If you are wondering how the hell to do a 64-bit unsigned integer
// Recommended way Printf("UInt64 value is: '%U' ok\n", @UInt64_Max); // Alternative Printf("UInt64 value is: '%llu' ok\n", @UInt64_Max);
Example of using arrays
$n = 777; $t = array(100, 200, 300, 400); Printf("Single value is '%d' but lets do an array of values '%d' cool huh?\n", $n, $t);
Example of using arrays with seperator
$n = 777; $t = array("fmtSeparator" => "-", 100, 200, 300, 400); Printf("Single value is '%d' but lets do an array of values '%d' cool huh?\n", $n, $t);
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"); Printf("Ints '%d' \nFloats '%g' \nStrings '%s'\n", $ints, $floats, $strings);
Example using "fmtSeparator", "fmtBegin" and "fmtEnd"
$arr = array("fmtSeparator" => "\n", "fmtBegin" => "0x", "fmtEnd" => "<-- Hex yup", 0..50); Printf("Hex of the array\n%x\n", $arr);
More examples
Printf( '%+d\n', 42 ); # '+42' Printf( '%4d\n', 42 ); # ' 42' Printf( '%04d\n', 42 ); # '0042' Printf( '%X\n', 0x1337f00d ); # '1337F00D'
Using an array as the format string
$arr = array("huey", "dewey", "louie"); say sprintf($arr); # 'huey dewey louie' $arr = array(10, 11, 12); say sprintf('%x', $arr); # 'abc' $arr = array("fmtSeparator" => " ", 10, 11, 12); say sprintf('%x', $arr); # 'a b c' $arr = array("fmtSeparator" => " ", 65, 66, 67); say sprintf('%c', $arr); # 'a b c' $arr = array("fmtSeparator" => '; ', 1, 2, 3); say sprintf('%02d', $arr); # '01; 02; 03'
Using an array (as a dictionary) as the format string
$arr = array("foo" => 1, "bar" => 2); say sprintf($arr); # 'foo 1 # bar 2' $arr = array("foo" => 1, "bar" => 2, "testingFooBar" => 3); say sprintf($arr); # 'foo 1 # bar 2 # testingFooBar 3'
Using an array (as a dictionary) as the only param
$arr = array("Apples" => 5, "Oranges" => 10); say sprintf('%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 sprintf('%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 sprintf('%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 sprintf('%s cost %d euros', $arr); # '>>>Apples cost 5 euros<<<;>>>Oranges cost 10 euros<<<' $arr = array("fmtSeparator" => " -- ", "huey" => 1, "dewey" => 2, "louie" => 3); say sprintf('%s', $arr); # 'huey -- dewey -- louie' $arr = array("fmtSeparator" => " -- ", "huey" => 1, "dewey" => 2, "louie" => 3); say sprintf('%s(%d)', $arr); # 'huey(1) -- dewey(2) -- louie(3)' say sprintf("%s is %.3f AU away from the sun", "Earth", 1); # Prints "Earth is 1.000 AU away from the sun" say sprintf("%s is %.3f AU away from the sun", array("Earth" => 1)); # Prints "Earth is 1.000 AU away from the sun"
Example of using %V
// The %V will use whatever Sputnik data type is given and translate it into // the appropriate sprintf() type so a $var containing an Int32 using %V becomes %d say "Now singles"; Printf("Int64 value is: '%V' ok\n", (char)65); Printf("Int64 value is: '%V' ok\n", null); Printf("Int64 value is: '%V' ok\n", true); Printf("Int64 value is: '%V' ok\n", false); Printf("Int64 value is: '%V' ok\n", (sbyte)77); Printf("Int64 value is: '%V' ok\n", (byte)100); Printf("Int64 value is: '%V' ok\n", (int16)777); Printf("Int64 value is: '%V' ok\n", (int32)777); Printf("Int64 value is: '%V' ok\n", (int64)777); Printf("Int64 value is: '%V' ok\n", (uint16)777); Printf("Int64 value is: '%V' ok\n", (uint32)777); Printf("Int64 value is: '%V' ok\n", (uint64)777); Printf("Int64 value is: '%V' ok\n", (float)777.42); Printf("Int64 value is: '%V' ok\n", (double)777.77); Printf("Int64 value is: '%V' ok\n", "Hello"); say "Now arrays"; Printf("Int64 value is: '%V' ok\n", array((char)65, (char)'a')); Printf("Int64 value is: '%V' ok\n", array(null, null, null)); Printf("Int64 value is: '%V' ok\n", array(true, false, (bool)1, (bool)0)); Printf("Int64 value is: '%V' ok\n", array((sbyte)77, (sbyte)11, (sbyte)22)); Printf("Int64 value is: '%V' ok\n", array((byte)100, (byte)200, (byte)202)); Printf("Int64 value is: '%V' ok\n", array((int16)777, (int16)778, (int16)778)); Printf("Int64 value is: '%V' ok\n", array((int32)1337, (int32)7331, (int32)1373)); Printf("Int64 value is: '%V' ok\n", array((int64)131, (int64)121, (int64)141)); Printf("Int64 value is: '%V' ok\n", array((uint16)1, (uint16)2, (uint16)3)); Printf("Int64 value is: '%V' ok\n", array((uint32)111, (uint32)222, (uint32)333)); Printf("Int64 value is: '%V' ok\n", array((uint64)1110, (uint64)2220, (uint64)3330)); Printf("Int64 value is: '%V' ok\n", array((float)777.77, (float)777.11, (float)777.22)); Printf("Int64 value is: '%V' ok\n", array((float)42.77, (float)42.11, (float)42.22)); Printf("Int64 value is: '%V' ok\n", array("Hello", "World", "ok"));
Yet another example
$n = 43951789; $u = -43951789; $c = 65; // ASCII 65 is 'A' // notice the double %%, this prints a literal '%' character Printf("%%b = '%b'\n", $n); // binary representation (32 bit size) Printf("%%B = '%B'\n", @Int64_Max); // binary representation (64 bit size) Printf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function Printf("%%d = '%d'\n", $n); // standard integer representation Printf("%%e = '%e'\n", $n); // scientific notation Printf("%%u = '%u'\n", $n); // unsigned integer representation of a positive integer Printf("%%u = '%u'\n", $u); // unsigned integer representation of a negative integer Printf("%%f = '%f'\n", $n); // floating point representation Printf("%%o = '%o'\n", $n); // octal representation Printf("%%s = '%s'\n", $n); // string representation Printf("%%x = '%x'\n", $n); // hexadecimal representation (lower-case) Printf("%%X = '%X'\n", $n); // hexadecimal representation (upper-case) Printf("%%+d = '%+d'\n", $n); // sign specifier on a positive integer Printf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer
