Core Function Fmt

Revision as of 19:08, 29 August 2013

Fmt( <format control>, <params> )

Description

Returns a formatted string (similar to the C sprintf() function).

Parameters

format control

The format and flags to use (see Remarks).

params

Variables that will be output according to the "format control".

Return Value

Success: Return the formatted string according to "variable format" defined in the "format control" parameter.

Failure: Returns "" (blank string).

Remarks

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

$result = Hex(1033);
println($result); // prints "409"
 
$result = Hex(1033, 4);
println($result); // prints "0409"
 
$result = Hex(1033, 8);
println($result); // prints "00000409"

Example with cast on a $variable

$var = 1033;
$result = Hex((int)$var);
println($result); // prints "409"
 
$result = Hex((int)$var, 4);
println($result); // prints "0409"
 
$result = Hex((int)$var, 8);
println($result); // prints "00000409"