Value Format Code
There are two types of value format codes used in DataScene: standard and
custom. A standard value format code takes the form Axy, where A
is the format specifier and must be one of the legal format characters, and xy
is the optional precision specifier (ranging from 0 to 99) that controls the
number of significant digits or zeros to the right of the decimal point. The following table lists the
legal format characters that can be used as a format specifier.
| Format Specifier |
Name |
Description |
| E or e |
Scientific |
The value is displayed using the scientific notation in the
form of "-d.ddd...E+ddd"
or "-d.ddd...e+ddd", where each 'd' represents a digit (0-9). If
the value is negative, a minus sign will precede the result string.
There is always one
digit precedes the decimal point in the result string. If the precision
specifier is left out, six digits will be used after the decimal point. The case of the format specifier
determines whether to prefix the
exponent with an 'E' or an 'e'. The exponent in the result string always
include a plus or
minus sign and at least three digits - it is padded with
zeros if necessary. |
| F or f |
Fixed-point |
The value is displayed using the fixed-point notation in
the form of "-ddd.ddd..."
where each 'd' represents a digit (0-9). If
the value is negative, a minus sign will precede the result string. If the precision specifier is
left out, two digits will be used after the decimal point. |
| G or g |
General |
The value is displayed in the most compact form of either
the fixed-point or the scientific notation. If the precision specifier is
left out or
zero, 15 digits will be used after the decimal point. If the scientific notation is
used, the exponent in the displayed string is prefixed with 'E' or 'e'
depending on the case of the format
specifier.
|
| N or n |
Number |
The value is displayed in the form of "-d,ddd,ddd.ddd...",
where each 'd' represents a digit (0-9). If
the value is negative, a minus sign will precede the result string. Thousand separators are inserted
into the digits to the left of the decimal point. If the precision specifier is
left out, two digits will be used after the decimal point. |
| P or p |
Percent |
The number is displayed as a percentage. If
the value is negative, a minus sign will precede the result string. If the
precision specifier is left out, two digits will be used after the decimal point. |
| R or r |
Round-trip |
The number is displayed in a form that will be parsed back into the same numeric value.
The precision specifier is ignored. |
Any value format code that does not fit the definition of a standard value
format code is treated as a custom value format code. The following table shows the characters that can be used to create
a custom value format code.
| Format character |
Name |
Description |
| 0 |
Zero placeholder |
If the value that is being formatted has a digit in the position
where a '0' appears in the value format code, then that digit will be copied
to the result string. The positions of the leftmost '0' before the
decimal point and the rightmost '0' after the decimal point determine
the range of digits that are always present in the result string. |
| # |
Digit placeholder |
If the value that is being formatted has a digit in the position
where a '#' appears in the format string, then that digit will be copied
to the result string. Otherwise, nothing will be copied to that position in
the result string. It is important to note that the digit '0' is not
displayed unless it is a significant digit in the result string. |
| . |
Decimal point |
The first '.' character in the value format code determines
the location of the decimal separator in the result string; all other '.' characters are ignored. |
| , |
Thousand separator and number scaling |
The ',' character serves two purposes. First, if the
value format code contains a ',' character that appears to the left of the decimal point
and in between two digit placeholders (0 or #), then thousand separators
will be inserted into the result string. Second, if the value format
code contains one or multiple ',' characters that appear immediately to the left of the decimal point, then the number
that is being formatted will be
divided by the number of the ',' characters multiplied by 1000 before it
is formatted. For instance, the value format code "0,," will
cause 20,000,000 to be displayed as 20.
|
| % |
Percentage placeholder |
The presence of a '%' character in the value format code
causes the number being formatted to be multiplied by 100 before it is formatted. The
'%' symbol is inserted in the result string at the location
where the '%' appears in the value format code. |
| E0, E+0, E-0, e0, e+0, e-0
|
Scientific notation |
If the value format code contains "E", "E+",
"E-", "e", "e+", or "e-" followed immediately by at least
one '0' character, then the number will be formatted using the scientific
notation. The number of the '0' characters following the scientific
notation indicator specifies the minimum number of digits to use for the exponent. The "E+" and "e+"
codes indicate that a plus or minus sign should always precede
the exponent. The "E", "E-", "e", or
"e-" codes indicate that a sign character should precede the
exponent only if it is negative. |
|
Escape character |
The '' character in the value format code causes the next character in the
value format code to be treated as an escape sequence.
|
| 'ABC'
"ABC"
|
Literal string |
Any characters enclosed in single or double quotes in
the value format code are
copied to the result string literally. They do not affect formatting. |
| ; |
Section separator |
The ';' character in the value format code is used to separate sections for
positive, negative, and zero numbers in the result string (see below). |
| Other |
All other characters |
All other characters in the value format code are copied to the result string as
literals in the position they appear in the value format code. |
Please note that for a fixed-point value format code (that not containing an
"E0", "E+0", "E-0", "e0",
"e+0", or "e-0"), the number being formatted is rounded to as many decimal
places as the number of digit placeholders to the right of the decimal point. If there
is no decimal point present in the value format code, the number being formatted
is rounded to the
nearest integer. If the number being formatted has more digits than the number
of digit placeholders
to the left of the decimal point, the extra digits are copied to the result
string immediately before the first digit placeholder.
Different formatting can be applied to a value depending on whether it is
positive, negative, or zero. To achieve this behavior, a custom value format code may
contain up to three sections separated by the section separator ';':
- If the value format code contains only one section, it applies to all values.
- If the value format code contains two sections, the first section applies to positive values and
zeros, and the second section applies to negative values. If the number
being formatted is negative but becomes zero after rounding according to the
format code in the second section, then the resulting zero is formatted according
to the first section.
- If the value format code contains three sections, the first section applies to positive values, the
second section applies to negative values, and the third section applies to
zeros. If the second section is empty (having nothing between the two semicolons),
then the first section will apply to all nonzero values.
If the number being formatted is nonzero but becomes zero after rounding
according to the format code in the first or second section, then the resulting
zero is formatted according to the third section.
It is important to note that if this type of formatting is used, negative values are
always displayed without the minus sign unless the user explicitly
include it as part of the custom format specifier.
|
