3. Script Language > String commands > !Format Strings > FMT.

FMT. - Format Numeric Output

Previous Top Next

MiniRobotLanguage (MRL)

FMT. Command

Format Numeric Output

Intention

This command can be used to format numeric output according to a format-prototype contained in P2. FMT. has 3 modes of operation.

In Mode 1, you can just specify a number of digits. Here are some examples:

$$NUM=25.22222

FMT.$$NUM|3

DBP.$$NUM

' result is "25.2"

$$NUM=125.22222

FMT.$$NUM|3

DBP.$$NUM

' result is "125"

$$NUM=125.22222

FMT.$$NUM|(4+1)

DBP.$$NUM

' result is "125.22"

In Mode 2 you can specify a pattern which will be used for the formatting. It must contain non numeric characters, that are all characters except "0123456789", while not being a formula in (..) .

Example:

$$NUM=125.22222

FMT.$$NUM|00.000

DBP.$$NUM

' Result is "125.222"

$$NUM=125.22223

FMT.$$NUM|0+00

DBP.$$NUM

' Result is "1+25"

$$NUM=082324

FMT.$$NUM|00\:00\:00

DBP.$$NUM

' Result is "08:23:24"

Syntax

FMT.[P1][|P2]

Parameter Explanation

P1 - Source and Target-variable, must contain a number

or formula in (..).

P2 - There are four modes of operation, depending on the

format of P2.

First: You can specify a pure numeric parameter, then

this will be the number of digits in the output.

Second: You can use one pattern to format the output

according to this pattern.

Third: You can specify two patterns, separated by a colon.

Then the first one will be used for positive numbers,

the second one will specify the format for negative numbers.

Fourth: You can specify tthree patterns, each separated

by a colon. Then the first pattern will be used to format

positive numbers, the second pattern will specify the format

for negative numbers. And the third pattern will specify the

format of a zero.

The following table shows the characters you can use to

create the user-defined format strings (patterns) and what

they are good for.

(empty) - If P2 is omitted, the number is just trimmed

at both sides, similar to VBT.

0 - digit placeholder. FMT. will either insert a digit or

a 0. If there is a digit in num_expression in the position

where the 0 appears in the pattern string, FMT. return that

digit. Otherwise FMT. return a "0".

If the number being formatted has fewer digits than there are

zeros (on either side of the decimal point) in the pattern,

leading or trailing zeros are added.

If the number has more digits to the right of the decimal

point than there are zeros to the right of the decimal point

in the format expression, then the number is rounded to as

many decimal places as there are zeros in the mask.

If the number has more digits to the left of the decimal

point than there are zeros to the left of the decimal point

in the pattern, then the extra digits are displayed without

truncation.

If the numeric value is negative, the negation symbol will

be treated as a decimal digit. Therefore take care, when

displaying negative values with this placeholder style.

In such cases, it is recommended that multiple patterns are

be used.

# - digit placeholder. If there is a digit for this position,

FMT. replaces this placeholder with that digit, with nothing,

or with a user-specified character. Unlike the 0 digit

placeholder, if the numeric value has the fewer digits than

there are # characters on either side of the decimal

placeholder, FMT. will either omit this character position

from the final formatted string; or substitute a

user-specified replacement character if one has been defined

(see the asterisk (*) character for more information).

To specify leading spaces, prefix the mask with "* "

(asterisk and a space character).

PUS.0.23

FMT.|*=##.###

DBP.$$000

ENR.

' Result is "===0.23="

. (period-sign) Decimal placeholder. Determines the position

of the decimal point in the result.

If any numeric field is specified to the left of the decimal

point, at least one digit will always result, even if only a

zero. The zero is not considered to be a "leading" zero if

it is the only digit to the left of the decimal. Placing

more than one period character in the fmt$ string will

produce undefined results.

% (percent-sign) Percentage placeholder. FMT. multiplies

the specified source number with 100, and adds a trailing

percent symbol. For example:

VAN.$$NUM=0.2

FMT.$$NUM|0.0%

DBP.$$NUM

ENR.

' Result is 20.0%

, (comma-sign) Thousands separator. Used to separate thousands

from hundreds within a number that has four or more digits to

the left of the decimal point. In order to be recognized as a

format character, the comma must be placed immediately after a

digit placeholder character (also see Restrictions below).

VAN.$$NUM=2312.56

FMT.$$NUM|$00,000.00

DBP.$$NUM

ENR.

' Result is $02,312.56

*x (asterisk + specified character of your choice)

Digit placeholder and fill-character.

Instructs FMT. to insert a digit or character "x" in that

position. If there is a digit in num_expression at the position

where the * appears in the format string, that digit is used.

Otherwise, the "x" character is used (where "x" represents your

specified character). The *x specifier acts as two digit (#)

fields.

VAN.$$NUM=8888.9

FMT.$$NUM|$**####,.00

DBP.$$NUM

ENR.

' Result is $**8,888.90

" (double-quote) Quoted string. FMT. treats all characters up to

the next quotation mark as-is, without interpreting them as

digit placeholders or format characters. Also see backslash.

VAN.$$NUM=54.3

VAR.$$FOR="x="#

FMT.$$NUM|$$FOR

DBP.$$NUM

ENR.

' Result is "x=54"

\x (backslash) Escaped character prefix. FMT. treats the character

"x" immediately following the backslash (\) as a literal

character rather than a digit placeholder or a formatting

character. Many characters in a mask have a special meaning and

cannot be used as literal characters unless they are preceded by

a backslash.

The backslash itself is not copied. To display a backslash, use

two backslashes (\\). To display a literal double-quote, use

two double-quote characters.

To simplify the mask string for common numeric formats, FMT.

permits the dollar symbol, the left and right parenthesis

symbols, the plus and minus symbols, and the space character

("$()+- ") to pass through from the mask string into the

formatted output string, without requiring an escape (\) prefix

character.

Example

'*************************************

' FMT.-Sample

'*************************************

' Format up to 6 digits

$$NUM=125.22223

FMT.$$NUM|(4+2)

DBP.$$NUM

END.

Remarks

Limitations:

You cannot pass a non-numeric expression or text-string to be formatted.

Also you should not place more than one decimal point in the pattern.

FMT. can return the maximum possible number of digits (that is up to 4932 for Extended-precision); however, the resulting digits will be meaningless beyond the actual precision.

Consequently, the specified value may produce formatted strings that are wider than the length of the specified pattern, for example:

A$ = FORMAT$(3e30!, "#,###") ' returns 41 characters

Rounding, if necessary, is implemented by the "banker's rounding" principle: if the fractional digit being rounded off is exactly five, with no trailing digits, the number is rounded to the nearest even number. This provides better results, on average, and follows the IEEE standard. For example:

VAN.$$NUM=3e30

VAR.$$FOR=#,###

FMT.$$NUM|$$FOR

DBP.$$NUM

ENR.

Result is:

3,000,000,000,000,000,000,000,000,000,000

String Operations

String Operations

FMT. - Format Numeric Output

Previous Top Next