Core Function SPrintf

From Sputnik Wiki
(Difference between revisions)
Jump to: navigation, search
(→Remarks)
Line 1: Line 1:
 
<pre>
 
<pre>
−
SPrintf( <expression>, <expressions>... )
+
SPrintf( <format control>, <params> )
 
</pre>
 
</pre>
  
 
=== Description ===
 
=== Description ===
  
−
Create a formatted string.
+
Returns a formatted string (similar to the C sprintf() function).
  
−
=== expression ===
+
=== Parameters ===
  
−
The format string and flags to use (see Remarks).
+
==== format control ====
  
−
==== expressions ====
+
The format and flags to use (see Remarks).
  
−
Variables that will be output according to the "Format Control".
+
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):
 +
 
 +
<pre>
 +
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
 +
</pre>
 +
 
 +
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 ===
 
=== Return Value ===
  
−
Success: Returns the formatted string.  
+
Success: Return the formatted string according to "variable format" defined in the "format control" parameter.
  
−
Failure: Returns an empty string.
+
Failure: Returns "" (blank string).  
  
 
=== Remarks ===
 
=== Remarks ===
  
−
If you are looking for something that works similar to C's sprintf() function see this [[Core Function Fmt|Fmt( <format control>, <params> )]]
+
If you wish to immediately print to the console rather than return a string you should see [[Core Function Printf|Printf( <format control>, <params> )]].
  
−
Warning: If you expect to use int, byte, float etc in the params then you must cast it as such for example:
+
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'''
 +
 
 +
<pre>
 +
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.
 +
</pre>
 +
 
 +
        F'''lag Specification'''
 +
 
 +
<pre>
 +
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.
 +
</pre>
 +
 
 +
        '''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'''
 +
 
 +
<pre>
 +
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. 
 +
</pre>
 +
 
 +
=== Example ===
 +
 
 +
Large example
  
 
<syntaxhighlight lang="sputnik">
 
<syntaxhighlight lang="sputnik">
−
$myint = 100;
+
$n = 43951789;
−
$val = SPrintf("Value is 0x\{0:x}", (int)$myint); // The (int) will only take in $myint
+
$u = -43951789;
−
println($val);
+
  
−
$myint = 100;
+
// notice the double %%, this prints a literal '%' character
−
$myint2 = 100;
+
vPrintf("%%d = '%d'\n", $n);            //'43951789'          standard integer representation
−
$val = SPrintf("Value is 0x\{0:x}", (int)($myint + $myint2)); // The (int) will now take in $myint AND $myint2
+
vPrintf("%%e = '%e'\n", $n);             //'4.395179e+007'    scientific notation
−
println($val);
+
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("sprintf", @args));
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Note how $myint was cast as an int? using (int)$myint this is vital since if you dont do that it might send a string or a float you never really know with $variables so its best to cast it.
+
If you are wondering how the hell to do a 64-bit signed integer
  
−
There is an alternative method example:
+
<syntaxhighlight lang="sputnik">
 +
// Recommended way
 +
vPrintf("Int64 value is: '%D' ok\n", @Int64_Max);
 +
// Alternative
 +
vPrintf("Int64 value is: '%I64d' ok\n", @Int64_Max);
 +
 
 +
Function vPrintf()
 +
{
 +
print(CallArray("sprintf", @args));
 +
}
 +
</syntaxhighlight>
 +
 
 +
If you are wondering how the hell to do a 64-bit unsigned integer
  
 
<syntaxhighlight lang="sputnik">
 
<syntaxhighlight lang="sputnik">
−
$myint = 100;
+
// Recommended way
−
$val = SPrintf("Value is 0x\{0:x}", int($myint));
+
vPrintf("UInt64 value is: '%U' ok\n", @UInt64_Max);
 +
// Alternative
 +
vPrintf("UInt64 value is: '%llu' ok\n", @UInt64_Max);
 +
 
 +
Function vPrintf()
 +
{
 +
print(CallArray("sprintf", @args));
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Its up to you to decide which one to use.
+
Example of using arrays
  
−
Go see [[Core Function Printf|Printf( <expression>, <expressions>... )]] for details on the format string
+
<syntaxhighlight lang="sputnik">
 +
$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);
  
−
Anything thats valid for Printf to print to console window is also valid for SPrintf to use to create strings.
+
Function vPrintf()
 +
{
 +
print(CallArray("sprintf", @args));
 +
}
 +
</syntaxhighlight>
  
−
=== Example ===
+
Example of using arrays with seperator
  
 
<syntaxhighlight lang="sputnik">
 
<syntaxhighlight lang="sputnik">
−
$val = SPrintf("Value is '0x\{0:x}'", (int)100);
+
$n = 777;
−
Printf($val); // Prints 0x64 since the {0:x} is telling it to place param 0 as :x meaning hex
+
$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("sprintf", @args));
 +
}
 +
</syntaxhighlight>
 +
 
 +
Large example with arrays
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
$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("sprintf", @args));
 +
}
 +
</syntaxhighlight>
 +
 
 +
Example using "fmtSeparator",  "fmtBegin" and "fmtEnd"
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
$arr = array("fmtSeparator" => "\n", "fmtBegin" => "0x", "fmtEnd" => "<-- Hex yup", 0..50);
 +
vPrintf("Hex of the array\n%x\n", $arr);
 +
 
 +
Function vPrintf()
 +
{
 +
print(CallArray("sprintf", @args));
 +
}
 +
</syntaxhighlight>
 +
 
 +
More examples
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
vPrintf(  '%+d\n', 42  ); # '+42'
 +
vPrintf(  '%4d\n', 42  ); # '  42'
 +
vPrintf(  '%04d\n', 42  ); # '0042'
 +
vPrintf(  '%X\n', 0x1337f00d  ); # '1337F00D'
 +
 
 +
Function vPrintf()
 +
{
 +
print(CallArray("sprintf", @args));
 +
}
 +
</syntaxhighlight>
 +
 
 +
Using an array as the format string
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
$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'
 +
</syntaxhighlight>
 +
 
 +
Using an array (as a dictionary) as the format string
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
$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'
 +
</syntaxhighlight>
 +
 
 +
Using an array (as a dictionary) as the only param
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
$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"
 +
</syntaxhighlight>
 +
 
 +
Example of using %V
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
// 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";
 +
vPrintf("Int64 value is: '%V' ok\n", (char)65);
 +
vPrintf("Int64 value is: '%V' ok\n", null);
 +
vPrintf("Int64 value is: '%V' ok\n", true);
 +
vPrintf("Int64 value is: '%V' ok\n", false);
 +
vPrintf("Int64 value is: '%V' ok\n", (sbyte)77);
 +
vPrintf("Int64 value is: '%V' ok\n", (byte)100);
 +
vPrintf("Int64 value is: '%V' ok\n", (int16)777);
 +
vPrintf("Int64 value is: '%V' ok\n", (int32)777);
 +
vPrintf("Int64 value is: '%V' ok\n", (int64)777);
 +
vPrintf("Int64 value is: '%V' ok\n", (uint16)777);
 +
vPrintf("Int64 value is: '%V' ok\n", (uint32)777);
 +
vPrintf("Int64 value is: '%V' ok\n", (uint64)777);
 +
vPrintf("Int64 value is: '%V' ok\n", (float)777.42);
 +
vPrintf("Int64 value is: '%V' ok\n", (double)777.77);
 +
vPrintf("Int64 value is: '%V' ok\n", "Hello");
 +
 
 +
say "Now arrays";
 +
vPrintf("Int64 value is: '%V' ok\n", array((char)65, (char)'a'));
 +
vPrintf("Int64 value is: '%V' ok\n", array(null, null, null));
 +
vPrintf("Int64 value is: '%V' ok\n", array(true, false, (bool)1, (bool)0));
 +
vPrintf("Int64 value is: '%V' ok\n", array((sbyte)77, (sbyte)11, (sbyte)22));
 +
vPrintf("Int64 value is: '%V' ok\n", array((byte)100, (byte)200, (byte)202));
 +
vPrintf("Int64 value is: '%V' ok\n", array((int16)777, (int16)778, (int16)778));
 +
vPrintf("Int64 value is: '%V' ok\n", array((int32)1337, (int32)7331, (int32)1373));
 +
vPrintf("Int64 value is: '%V' ok\n", array((int64)131, (int64)121, (int64)141));
 +
vPrintf("Int64 value is: '%V' ok\n", array((uint16)1, (uint16)2, (uint16)3));
 +
vPrintf("Int64 value is: '%V' ok\n", array((uint32)111, (uint32)222, (uint32)333));
 +
vPrintf("Int64 value is: '%V' ok\n", array((uint64)1110, (uint64)2220, (uint64)3330));
 +
vPrintf("Int64 value is: '%V' ok\n", array((float)777.77, (float)777.11, (float)777.22));
 +
vPrintf("Int64 value is: '%V' ok\n", array((float)42.77, (float)42.11, (float)42.22));
 +
vPrintf("Int64 value is: '%V' ok\n", array("Hello", "World", "ok"));
 +
 
 +
Function vPrintf()
 +
{
 +
print(CallArray("sprintf", @args));
 +
}
 +
</syntaxhighlight>
 +
 
 +
Yet another example
 +
 
 +
<syntaxhighlight lang="sputnik">
 +
// notice the double %%, this prints a literal '%' character
 +
vPrintf("%%b = '%b'\n", $n); // binary representation (32 bit size)
 +
vPrintf("%%B = '%B'\n", @Int64_Max); // binary representation (64 bit size)
 +
vPrintf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function
 +
vPrintf("%%d = '%d'\n", $n); // standard integer representation
 +
vPrintf("%%e = '%e'\n", $n); // scientific notation
 +
vPrintf("%%u = '%u'\n", $n); // unsigned integer representation of a positive integer
 +
vPrintf("%%u = '%u'\n", $u); // unsigned integer representation of a negative integer
 +
vPrintf("%%f = '%f'\n", $n); // floating point representation
 +
vPrintf("%%o = '%o'\n", $n); // octal representation
 +
vPrintf("%%s = '%s'\n", $n); // string representation
 +
vPrintf("%%x = '%x'\n", $n); // hexadecimal representation (lower-case)
 +
vPrintf("%%X = '%X'\n", $n); // hexadecimal representation (upper-case)
 +
 
 +
vPrintf("%%+d = '%+d'\n", $n); // sign specifier on a positive integer
 +
vPrintf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer
 +
 
 +
Function vPrintf()
 +
{
 +
print(CallArray("sprintf", @args));
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
[[Category:Core Function]]
 
[[Category:Core Function]]

Revision as of 14:07, 31 August 2013

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

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("sprintf", @args));
}

If you are wondering how the hell to do a 64-bit signed integer 

// Recommended way
vPrintf("Int64 value is: '%D' ok\n", @Int64_Max);
// Alternative
vPrintf("Int64 value is: '%I64d' ok\n", @Int64_Max);
 
Function vPrintf()
{
	print(CallArray("sprintf", @args));
}

If you are wondering how the hell to do a 64-bit unsigned integer 

// Recommended way
vPrintf("UInt64 value is: '%U' ok\n", @UInt64_Max);
// Alternative
vPrintf("UInt64 value is: '%llu' ok\n", @UInt64_Max);
 
Function vPrintf()
{
	print(CallArray("sprintf", @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("sprintf", @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("sprintf", @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("sprintf", @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("sprintf", @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("sprintf", @args));
}

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";
vPrintf("Int64 value is: '%V' ok\n", (char)65);
vPrintf("Int64 value is: '%V' ok\n", null);
vPrintf("Int64 value is: '%V' ok\n", true);
vPrintf("Int64 value is: '%V' ok\n", false);
vPrintf("Int64 value is: '%V' ok\n", (sbyte)77);
vPrintf("Int64 value is: '%V' ok\n", (byte)100);
vPrintf("Int64 value is: '%V' ok\n", (int16)777);
vPrintf("Int64 value is: '%V' ok\n", (int32)777);
vPrintf("Int64 value is: '%V' ok\n", (int64)777);
vPrintf("Int64 value is: '%V' ok\n", (uint16)777);
vPrintf("Int64 value is: '%V' ok\n", (uint32)777);
vPrintf("Int64 value is: '%V' ok\n", (uint64)777);
vPrintf("Int64 value is: '%V' ok\n", (float)777.42);
vPrintf("Int64 value is: '%V' ok\n", (double)777.77);
vPrintf("Int64 value is: '%V' ok\n", "Hello");
 
say "Now arrays";
vPrintf("Int64 value is: '%V' ok\n", array((char)65, (char)'a'));
vPrintf("Int64 value is: '%V' ok\n", array(null, null, null));
vPrintf("Int64 value is: '%V' ok\n", array(true, false, (bool)1, (bool)0));
vPrintf("Int64 value is: '%V' ok\n", array((sbyte)77, (sbyte)11, (sbyte)22));
vPrintf("Int64 value is: '%V' ok\n", array((byte)100, (byte)200, (byte)202));
vPrintf("Int64 value is: '%V' ok\n", array((int16)777, (int16)778, (int16)778));
vPrintf("Int64 value is: '%V' ok\n", array((int32)1337, (int32)7331, (int32)1373));
vPrintf("Int64 value is: '%V' ok\n", array((int64)131, (int64)121, (int64)141));
vPrintf("Int64 value is: '%V' ok\n", array((uint16)1, (uint16)2, (uint16)3));
vPrintf("Int64 value is: '%V' ok\n", array((uint32)111, (uint32)222, (uint32)333));
vPrintf("Int64 value is: '%V' ok\n", array((uint64)1110, (uint64)2220, (uint64)3330));
vPrintf("Int64 value is: '%V' ok\n", array((float)777.77, (float)777.11, (float)777.22));
vPrintf("Int64 value is: '%V' ok\n", array((float)42.77, (float)42.11, (float)42.22));
vPrintf("Int64 value is: '%V' ok\n", array("Hello", "World", "ok"));
 
Function vPrintf()
{
	print(CallArray("sprintf", @args));
}

Yet another example 

// notice the double %%, this prints a literal '%' character
vPrintf("%%b = '%b'\n", $n); // binary representation (32 bit size)
vPrintf("%%B = '%B'\n", @Int64_Max); // binary representation (64 bit size)
vPrintf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function
vPrintf("%%d = '%d'\n", $n); // standard integer representation
vPrintf("%%e = '%e'\n", $n); // scientific notation
vPrintf("%%u = '%u'\n", $n); // unsigned integer representation of a positive integer
vPrintf("%%u = '%u'\n", $u); // unsigned integer representation of a negative integer
vPrintf("%%f = '%f'\n", $n); // floating point representation
vPrintf("%%o = '%o'\n", $n); // octal representation
vPrintf("%%s = '%s'\n", $n); // string representation
vPrintf("%%x = '%x'\n", $n); // hexadecimal representation (lower-case)
vPrintf("%%X = '%X'\n", $n); // hexadecimal representation (upper-case)
 
vPrintf("%%+d = '%+d'\n", $n); // sign specifier on a positive integer
vPrintf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer
 
Function vPrintf()
{
	print(CallArray("sprintf", @args));
}
Retrieved from "http://ubersoft.org/Sputnik/wiki/index.php/Core_Function_SPrintf"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox