|
fmt$ |
Format characters that will determine how the numeric
expression should be formatted. This expression is termed the mask.
There may be up to 18 digit-formatting digits on either side of the decimal
point. The mask may not contain literal characters unless each character
is preceded with a backslash (\) escape character, or the literal characters
are enclosed in quotes.
fmt$ may contain
one, two or three formatting masks, separated by semicolon (;) characters:
|
One mask |
If fmt$ contains just one format mask, the
mask is used to format all possible values of num_expression.
For example: |
|
|
x$ = FORMAT$(z!, "000.00") |
|
Two masks |
If fmt$ contains two format masks, the first
mask is used for positive values (=> 0), and the second mask is used
for negative values (< 0). For example: |
|
|
x$ = FORMAT$(-100, "+00000.00;-000") |
|
Three masks |
If fmt$ contains three masks, the first mask
is used for positive values (> 0), the second mask for negative values
(< 0), and the third mask is used if num_expression is zero
(0). For example: |
|
|
FOR y! = -0.5! TO 0.5! STEP 0.5!
x$ = FORMAT$(y!, "+.0;-.0; .0")
NEXT y! |
Digit placeholders in a mask do not have to be contiguous.
This allows you to format a single number into multiple displayed parts.
For example:
A$ = FORMAT$(123456, "00\:00\:00")
' 12:34:56
The following table shows the characters you can
use to create the user-defined format strings (masks) and the definition
of each formatting character:
|
Character |
Definition |
|
Empty string |
[null string] No formatting takes place.
The number is converted to Extended-precision and formatted similarly
to STR$, but without the leading space that STR$ applies to non-negative
numbers.
A$=FORMAT$(0.2)
' .200000002980232
A$=FORMAT$(0.2!, "")
' .200000002980232
A$=FORMAT$(0.2#)
' .2
A$=FORMAT$(0.2#, "")
' .2 |
|
0 |
[zero] Digit
placeholder. PowerBASIC will insert a digit or 0 in that position.
If there is a digit in num_expression in
the position where the 0 appears in the format string, return that digit.
Otherwise, return "0". If the number being formatted has
fewer digits than there are zeros (on either side of the decimal point)
in the format expression, 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,
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 format
expression, the extra digits are displayed without truncation. If
the numeric value is negative, the negation symbol will be treated as
a decimal digit. Therefore, care should be exercised when displaying
negative values with this placeholder style. In such cases, it is
recommended that multiple masks be used.
' Numeric padded with leading zero characters
A$ = FORMAT$(999%, "00000000")
' 00000999 |
|
# |
[Number symbol] Digit placeholder. If
there is a digit for this position, PowerBASIC replaces this placeholder
with a digit, nothing, or 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, PowerBASIC will either:
a)
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).
For example:
' No leading spaces and trailing spaces
A$ = FORMAT$(0.75!, "####.###")
' 0.75
' Up to 3 Leading spaces before decimal
A$ = FORMAT$(0.75!, "* ##.###")
' 0.75
' Using asterisks for padding characters
A$ = FORMAT$(0.75!, "*=##.###")
' ===0.75=
FORMAT$ may also return a string that is larger
than the number of characters in the mask:
A$ = FORMAT$(999999.9, "#.#")
' 999999.9 |
|
. |
[period] Decimal
placeholder. Determines the position of the decimal point in the
resultant formatted string.
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] Percentage placeholder. PowerBASIC
multiplies num_expression by 100, and adds a trailing percent symbol.
For example:
x$ = FORMAT$(1 / 5!, "0.0%")
' 20.0% |
|
, |
[comma] Thousand 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).
A$ = FORMAT$(1234567@, "#,")
' 1,234,567
A$ = FORMAT$(12345@, "#,.00")
' 12,345.00
A$ = FORMAT$(12345@, "#.00,")
' 12,345.00
A$ = FORMAT$(1212.46, "$00,000.00") ' $01,212.46
A$ = FORMAT$(1000%, """#""#,")
' #1,000
A$ = FORMAT$(1234567@, "0,") '
1,234,567 |
|
*x |
[asterisk] Digit placeholder and fill-character.
Instructs PowerBASIC 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 own choice of character). The *x specifier
acts as two digit (#) fields.
A$ = FORMAT$(9999.9@,"$**####,.00")' $**9,999.90
A$ = FORMAT$(0@,"$*=###0,.00#")
' $=====0.00=
A$ = FORMAT$(0@,"$* ####0,.00")
' $ 0.00 |
|
E- e- E+ e+ |
[e] Scientific format. PowerBASIC will
use scientific notation in the formatted output. Use E- or e- to
place a minus sign in front of negative exponents. Use E+ or e+
to place a minus sign in front of negative exponents and a plus sign in
front of non-negative exponents.
In order to be recognized as a format sequence,
the E-, e-, E+, or e+ must be placed between two digit placeholder characters.
For example:
A$ = FORMAT$( 99.999, "0.0E-##")
' 1.0E2
A$ = FORMAT$(-99.999, "0.0E-##")
' -1.0E2
A$ = FORMAT$( 99.999, "0.0E+##")
' 1.0E+2
A$ = FORMAT$(-99.999, "0.0E+##")
' -1.0E+2
A$ = FORMAT$(0.1!, "0.0e+##")
' 1.0e-1 |
|
" |
[double-quote] Quoted string. PowerBASIC
treats all characters up to the next quotation mark as-is, without interpreting
them as digit placeholders or format characters. Also see backslash.
For example:
A$ = FORMAT$(12, $DQ+"##"+$DQ+"##")
' ##12
A$ = FORMAT$(5.55, """XYZ=""#.##\#")
' XYZ=5.55#
A$ = FORMAT$(25, """x=""#")
' x=25
A$ = FORMAT$(999, """Total ""#")
' Total 999
A$ = FORMAT$(5, $DQ+"x="+$DQ+"#")
' x=5 |
|
\x |
[backslash] Escaped character prefix.
PowerBASIC 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,
FORMAT$ 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.
A$ = FORMAT$(23, "(* 0\%)")
' ( 23%)
A$ = FORMAT$(99999, "#\#")
' 99999#
A$ = FORMAT$(5, "\"+$DQ+$DQ+"x="+$DQ+
_
"#\"+$DQ)
' "x=5"
A$ = FORMAT$(5, "\""""x=""#\""")
' "x=5"
A$ = FORMAT$(1000%, """#####,""")
' "#####," |
|
|
Restrictions |
You cannot pass a string
expression or string variable in num_expression. Do not
place more than one decimal point in the mask.
FORMAT$ can return the maximum possible number of
digits (up to 4932 for Extended-precision); however, the resulting digits
will be meaningless beyond the actual precision of num_expression.
Consequently, the value of num_expression may produce formatted
strings that are wider than the length of fmt$, 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:
A$ = FORMAT$(0.5##, "0")
' 0
A$ = FORMAT$(1.5##, "0")
' 2
A$ = FORMAT$(2.5##, "0")
' 2
A$ = FORMAT$(2.51##, "0")
' 3
Semicolon characters, being mask delimiters, should
not be used for other purposes in mask strings unless prefixed with an
escaped character symbol (\).
FORMAT$, when used with some formatting characters
such as the thousands separator (comma), may not produce a "right-justified"
formatted string. The simple solution is to apply separate justification
with the RSET statement or the RSET$ function. For example:
A$ = SPACE$(12)
RSET A$ = FORMAT$(1,"#,###.00")
' 1.00
RSET A$ = FORMAT$(1000, "#,.00")
' 1,000.00
RSET A$ = FORMAT$(1000000,"#,###.00")' 1,000,000.00
B$ = RSET$(FORMAT$(1e6, "#,"),10)
' " 1,000,000"
One further enhancement would be to combine this
into a MACRO function, for example:
MACRO mMoney1(d,l) = "$"+RSET$(FORMAT$(d,"#,"),l-1)
MACRO mMoney2(d,l) = RSET$(FORMAT$(d,"$#,"),l)
' code here
A$ = mMoney1(1000,10)
' "$ 1,000"
B$ = mMoney2(1000,10)
' " $1,000" |