A Number Format Specifier as used in the function FormatFloat, determines the display format of an input number as it is passed into the function and converted to a String, using a display skeleton specified.

The following format specifiers are supported in the format string.

Basic Codes

Specifier

Represents

0

Digit placeholder.

If the value being formatted has a digit in the position where zero (0) appears in the format string, then that digit is copied to the output string. Otherwise, a zero (0) is stored in that position in the output string.

#

Digit placeholder.

If the value being formatted has a digit in the position where a hash (#) appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.

.

Decimal point.

The first decimal point or full-stop character (.) in the format string determines the location of the decimal separator in the formatted value.

Any additional decimal point or full-stop character (.) is ignored.

,

Thousand separator.

If the format string contains one or more comma (,) characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point.

The placement and number of comma characters (,) in the format string does not affect the output, except to indicate that thousand separators are wanted. If the input value has no thousands, then the comma (,) will be ignored in the output display.

E+

e+

E-

e-

Scientific notation. This can be either upper case or lower case.

If any of the strings E+, E-, e+, or e- are contained in the format string, the number is formatted using scientific notation.

A group of up to four zero(0) characters can immediately follow the E+, E-, e+, or e- to determine the minimum number of digits in the exponent.

The E+ and e+ formats cause a plus sign (+) to be output for positive exponents, and a minus sign (-) to be output for negative exponents.

The E- and e- formats output a sign character only for negative exponents.

'xx'

"xx"

Characters enclosed in single or double quotation marks are output as such, and do not affect formatting.

;

A semi-colon (;) separates sections for positive, negative, and zero numbers in the format string.

The locations of the leftmost zero (0) before the decimal point in the format string, and the rightmost zero(0) after the decimal point in the format string, determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders to the right of the decimal point. These placeholders can be either zero (0) or hash (#), and will behave as specified above.

If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number. In other words, the input string contains 12345.59, but the format specifies 0, so the output will be 12346. If the input string contains 12345.09, but the format specifies 0, so the output will be 12345.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the decimal point character (.) in the format string, the extra digits are output before the first digit placeholder. In other words, the input string contains 12345.59, but the format specifies 0, so the output will be 12346. And a large number such as 12341234.567890123456 will be output as 12341235. With a format specifier as 0.00 for the input 12345.09 and 12341234.56789, the output will be 12345.09 and 12341234.57 respectively.

To allow different formats for positive, negative, and zero values, the format string can contain either one, two or three sections separated by semicolons, as follows:

  • One section: The format string applies to all values.

  • Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

  • Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

Using thus format scenario and the specifier FormatFloat( ‘0.00 “CR”;-0.00 “DB”;0 “Nil”’, <myinput>) would result in the following in the Log.

//Value is 560.72
LogInfo(FormatFloat('0.00 "CR";-0.00 "DB"', -560.72));
LogInfo(FormatFloat('0.00 "CR";-0.00 "DB"', 560.72));
//Value is 0.00
LogInfo(FormatFloat('0.00;-0.00;"Nil"', 0.0));
LogInfo('');

If the section for negative values or the section for zero values is empty, that is if there is nothing between the semicolons that delimits the section, then the format for positive values is used irrespective, as the following illustrates.

// Set up a floating point number
mynegativefloat := -654321.654321;
mysmallfloat := 998877.123;
LogInfo(FormatFloat('', mysmallfloat)); //Result is 998877.123
LogInfo(FormatFloat('0.00;', mynegativefloat)); //Result is -654321.65
LogInfo(FormatFloat('', mynegativefloat)); //Result is -654321.654321
LogInfo(FormatFloat(';0.00', mysmallfloat)); //Result is 998877.123
LogInfo(FormatFloat(' ;0.00 "NEG"', mynegativefloat)); //Result is 654321.65 NEG

If the section for positive values is empty or if the entire format string is empty, the value is formatted using general floating-point formatting as below.

// Set up a floating point number
myfloat := 12341234123412341234.5678901234561234;
LogInfo(FormatFloat('', myfloat)); //Result ia 1.23412341234123E19

Please also refer to the FormatFloat function.

The following code produces a Log entry that displays examples of the various numeric number formats.

To view the corresponding results as sent and displayed in a Log, copy this code into an Action custom script and then run it. Make sure that your send Log settings are active in the Action.

procedure ScriptEvent (var Value : variant);
var
myfloat : extended;
mynegativefloat : extended;
mysmallfloat : extended;
myzerofloat : extended;
evensmaller : double;
begin
 
// Set up a floating point number
myfloat := 12341234.567890123456;
mynegativefloat := -987654321.987654321;
mysmallfloat := 998877.123;
myzerofloat := 0;
evensmaller := 25;
LogInfo('');
 
// Testing the length displayed
LogInfo('Our small test number is '+FloatToStr(mysmallfloat));
LogInfo('This is 0.0000 . . . . '+FormatFLoat('0.0000', mysmallfloat));
LogInfo('This is 0.#### . . . . '+FormatFLoat('0.####', mysmallfloat));
LogInfo('This is #.#### . . . . '+FormatFLoat('#.####', mysmallfloat));
LogInfo('');
 
// Display a sample value using all of the format options
LogInfo('Our test number is '+FloatToStr(myfloat));
LogInfo('***NOTE that our test number had 12 decimal places but only 7 are displayed here.');
LogInfo('Our negative test number is '+FloatToStr(mynegativefloat));
LogInfo('***NOTE that our test negative number had 9 decimal places but only 6 are displayed here.');
LogInfo('Our small test number is '+FloatToStr(mysmallfloat));
LogInfo('***NOTE Our small test number had 3 decimal places and all are displayed here.');
LogInfo('');
 
// Round and remove the decimal value
LogInfo('Round and remove any decimals');
LogInfo('##### . . . . '+FormatFloat('#####', myfloat));
LogInfo('00000 . . . . '+FormatFloat('00000', myfloat));
LogInfo('0 . . . . '+FormatFloat('0' , myfloat));
LogInfo('#,##0 . . . . '+FormatFloat('#,##0', myfloat));
LogInfo(',0 . . . . '+FormatFloat(',0' , myfloat));
LogInfo('');
 
// Include the decimal value
LogInfo('Include any decimals to x decimal places');
LogInfo('0.#### . . . . '+FormatFloat('0.####', myfloat));
LogInfo('0.###### . . . . '+FormatFloat('0.######', myfloat));
LogInfo('0.0000 . . . . '+FormatFloat('0.0000', myfloat));
LogInfo('0.000000 . . . . '+FormatFloat('0.000000', myfloat));
LogInfo(',0.000000 . . . . '+FormatFloat(',0.000000', myfloat));
LogInfo('');
 
// Currency format
LogInfo('Currency format');
LogInfo('$,0.00 . . . . '+FormatFloat('$,0.00', mysmallfloat));
LogInfo('$ ,0.00 . . . . '+FormatFloat('$ ,0.00', mysmallfloat));
LogInfo('');
 
// Percentages
LogInfo('Percentage format');
LogInfo(',0.00% . . . . '+FormatFloat(',0.00%', myfloat));
LogInfo(',0.00 % . . . . '+FormatFloat(',0.00 %', myfloat));
LogInfo('0.####% . . . . '+FormatFloat('0.####%', myfloat));
LogInfo(',0.###### % . . . . '+FormatFloat(',0.###### %', myfloat));
LogInfo('#.#####0 % . . . . '+FormatFloat('#.#####0 %', mysmallfloat));
LogInfo('');
 
// Scientific format
LogInfo('Scientific format');
LogInfo('0.0000000E+00 . . . . '+FormatFloat('0.0000000E+00', myfloat));
LogInfo('0.0000000E-00 . . . . '+FormatFloat('0.0000000E-00', myfloat));
LogInfo('#.#######E-## . . . . '+FormatFloat('#.#######E-##', myfloat));
LogInfo('');
 
// Include freeform text
LogInfo('Include freeform text, including the use of double-quotes to embed text');
LogInfo('"Value = "0.0 . . . . '+FormatFloat('"Value = "0.0', myfloat));
LogInfo('"The size was "0.0 . . . . '+FormatFloat('"The size was "0.0', myfloat));
LogInfo('"Number of hens = ",0.00000 . . . . '+FormatFloat('"Number of hens = ",0.00000', myfloat));
LogInfo('"Nigel has ",0" potatoes!" . . . . '+FormatFloat('"Nigel has ",0', mysmallfloat)+' potatoes!');
LogInfo('"The ",#.####" kgs are there." . . . . '+FormatFloat('"The ",#.####', myfloat)+' kgs are there.');
LogInfo('"My ",#.####" pigs are pink." . . . . '+FormatFloat('"My ",#.####', evensmaller)+ ' pigs are pink.');
LogInfo('');
 
// Different formatting for negative numbers
LogInfo('Format options for negative numbers');
LogInfo('0.0 . . . . '+FormatFloat('0.0', mynegativefloat));
LogInfo(',0.00000000 . . . . '+FormatFloat(',0.00000000',mynegativefloat));
LogInfo(',#.## . . . . '+FormatFloat(',#.##',mynegativefloat));
LogInfo('');
 
// Formatting with a set fixed negative number
LogInfo('Format options for negative numbers keyed directly into FormatFloat');
LogInfo('Using -1234.567 and 1234.567');
LogInfo('0.0 . . . . '+FormatFloat('0.0', -1234.567));
LogInfo('0.0 "CR";-0.0 "DB" . . . . '+FormatFloat('0.0 "CR";-0.0 "DB"', -1234.567));
LogInfo('0.0 "CR";-0.0 "DB" . . . . '+FormatFloat('0.0 "CR";-0.0 "DB"', 1234.567));
LogInfo('');
 
// Different format for zero value
LogInfo('Format options for zero values');
LogInfo('0.0 . . . . '+FormatFloat('0.0', 0.0));
LogInfo('0.0;-0.0;"Nothing" . . . . '+FormatFloat('0.0;-0.0;"Nothing"', 0.0));
LogInfo('0.0000 . . . . '+FormatFloat('0.0000', myzerofloat));
LogInfo('');
 
LogInfo('The end!');
LogInfo('');
end;