|
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)
...
A$ = mMoney1(1000,10)
' "$ 1,000"
B$ = mMoney2(1000,10)
' " $1,000" |