Converts a number to a string and formats it according to the sFormat specification.
[ s = ] Format ( x, sFormatSpec )
The Format procedure syntax has the following parts:
|
Name |
Type |
Description |
|
s |
BString |
Formatted number |
|
x |
Val Any |
Number to convert |
|
sFormatSpec |
Val BString |
Format specifications |
The sFormat specification has the following components:
['literal'] [number] [decimal] [exponent] [k]['literal'][(arithmetic)]
where:
|
number |
[[+ | -][9,...][#,...][0,...][0 | X | x | 8 | 2]] |
|
decimal |
[.[0,...][#,...][9,...]] |
|
exponent |
[[E | e][+ | -][9,...][#,...][0,...]] |
and the parts are:
|
Part |
Value |
Description |
|
'literal' |
literal |
A string of literal characters inserted into the result before or after the number. Use single quotation marks( ' ), not double quotation marks( " ) around the literal character(s), for example, (2.5,"## 'VAC' "). To insert special characters, such as a double quotation mark, use the escape sequence ( \ ), for example, Format(2.5,"##.# '\"VAC\"' ") will result in: 2.5"VAC". |
|
sign |
+ (plus) |
If the number is positive or zero, then adds a plus sign. If the number is negative, does not add a plus sign. The sign does not count in the number of formatted spaces. |
|
- (minus) |
If the number is negative, then adds a minus sign. Otherwise does not add any sign. The sign does not count in the number of formatted spaces. |
|
|
leading / trailing |
9 |
Placeholder: Put a numeral (0-9) or a zero for each "9" used, up to the number of significant digits in the number. Any non-significant zeros past the decimal point at the end of the number are ignored. Any plus or minus signs in the format take up one space. If the number is negative and no minus sign is used in the format, then the left-most 9 is used for the minus sign. |
|
# |
Placeholder: Force a number (0-9) or a space for each "#" used, up to the number of significant digits in the number. If the number of significant digits is equal to or greater than the number of #s, all the significant digits will be used. For #s used to the left of the decimal point, if the number of significant digits is less than the number of #s, a space is placed in the left-most unused #s. For #s used to the right of the decimal point, if the number of significant digits is less than the number of #s, only the significant digits will be used. If the number is negative and no minus sign is used in the format, then the minus sign is placed immediately to the left of the first significant digit and uses up one of the #s. |
|
|
0 |
Placeholder: Force a number (of base) or a zero for each "0" used, for at least the number of significant digits in the data. If the number is negative and no minus sign is used in the format, then the left-most 0 is used for the minus sign. |
|
|
base 0, 2, X,x,8 count as one digit |
0 |
Base 10 number |
|
X \ x |
Unsigned hexadecimal - not used with the sign, decimal component, or k. |
|
|
8 |
Unsigned octal number - not used with the sign, decimal component, or k. |
|
|
2 |
Unsigned binary number - not used with the sign, decimal component, or k. |
|
|
other |
E \ e |
The base-10 exponent, for example, 2e6 = 2x10**6 = 2 million. |
|
k |
Engineering units: p, n, u, m, km, M, G, or T. See table below. |
|
|
arithmetic |
An expression surrounded by parentheses. For example: (+10/-100*66) |
|
|
any other characters |
Other characters in the format are ignored. |
At least two placeholders (#) are required before the decimal point and after the optional "E" or "e". The first placeholder at the beginning of sFormat is used for the minus sign ('-') for negative dx and a space (' ') for positive dx. The first placeholder after "E" or "e" is used for a negative exponent ('-') or a positive exponent ('+'). If fewer than two placeholders are supplied to the function, two are used. If sFormat does not contain placeholders, the function returns a converted number like the Str function returns with lBase as 10.
The format specification sFormat never causes dx value to be truncated, if sFormat does not contain enough placeholders before the decimal point (or after the "E" or "e" in the case of floating point syntax) to contain the converted number. However, ATEasy rounds the numeric-exp to fit the required decimal characters after the decimal point.
The engineering units are:
|
Unit |
Name |
Value |
|
p |
pico |
10**(-12) |
|
n |
nano |
10**(-9) |
|
u |
micro |
10**(-6) |
|
m |
milli |
10**(-3) |
|
k |
kilo |
10**3 |
|
M |
mega |
10**6 |
|
G |
giga |
10**9 |
|
T |
tera |
10**12 |
Spaces between the components of the format specification are ignored but can help for clarity in reading the format.
If overflow occurs in the specification to the left of the decimal point, for example, there are more significant digits than the format specifies, ATEasy will "stretch" the format to have the same number of significant digits as the number. If overflow occurs on the right of the decimal point, ATEasy will round-off to the number of digits specified in the format. For example:
s=Format(-3456.7891, "99.99") !s is "-3456.79"
The Print Using statement can be used to output a number converted to a string in the same format specifications as the Format function.
! Number bases and placeholders:
s=Format(10,"00000X") ! s is "00000A"
s=Format(10,"00000x") ! s is "00000a"
s=Format(10,"000008") ! s is "000012"
s=Format(10,"000002") ! s is "001010"
s=Format(10,"000000") ! s is "000010"
s=Format(10,"#####X") ! s is " A"
s=Format(10,"#####8") ! s is " 12"
s=Format(10,"#####2") ! s is " 1010"
s=Format(10,"#####0") ! s is " 10"
s=Format(10,"99999X") ! s is "A"
s=Format(10,"999998") ! s is "12"
s=Format(10,"999992") ! s is "1010"
s=Format(10,"999990") ! s is "10"
! Literals:
s=Format(34,"# 'VDC'") ! s is "34VDC"
! Plus sign:
s=Format(4, "+##") !s is " +4"
! Minus sign:
s=Format(-34.56, "####.##") ! s is " -34.56"
! # placeholders to the right of the decimal point:
s=Format(-345678.56, "####.####") ! s is "-345678.5600"
! 9s versus #s:
s=Format(45.63, "+999.999") ! s is "+45.63"
s=Format(45.63, "+###.###") ! s is " +45.630"
s=Format(-456, "+#####") ! s is " -456"
! Use 0s instead of 9s:
s=Format(-456, "-00000") ! s is "-00456"
! e exponent:
s=Format(-34.56, "##.##e###") ! s is "-3.46e+01"
! arithmetic expressions are evaluated from left to right:
s=Format(12, "999.9(+10/-100*66)") ! s is "-14.5"
! In that example, the math is: 12+10/-100*66, which evaluates (from left to right without precedence) to -14.52, but since only two significant digits were used for the input and only one 9 is used to the right of the decimal point, the result is "-14.5"
! arithmetic can be used to show percentages:
s=Format(0.38,"(*100)999 '%' ") ! s is "38%"
! dl is of type DLOng
dl=1034851382260
s=Format(dl, "X") ! s="F0F1F2F3F4"