2.5.9.6 vFormatString
The vFormatString custom structure is a string that specifies the formatting information to determine how a value is displayed. If vFormatString is an empty string, the result string is an empty string.
A vFormatString is composed of casting notation, field pictures, and format strings.
Casting notation: The casting notation specifies the unit of the value to be formatted and the display unit of the value. If present it MUST appear at the beginning of the vFormatString. If the casting notation is present, the notation is stripped from the format string before the formatting is performed. It MUST satisfy the following ABNF.
-
ABNF:
-
CastingNotation = "<" [ SourceUnit ] "," [ DisplayUnit ] ">" SourceUnit = string-value DisplayUnit = string-value
-
-
The first string-value specifies a unit of the value to be formatted. It MUST be a vUnitString or a value equal to "$".
-
The second string-value specifies a unit displayed in the resulting string. It MUST be a vUnitString or a value equal to "$".
-
The value to be formatted is converted as follows. If the value to be formatted is a vScalar and SourceUnit is a vUnitString, the value is multiplied by a factor that converts the unit of SourceUnit into the custom internal unit type associated with the type of the unit of SourceUnit. If the value to be formatted is a vScalar and SourceUnit is equal to "$", the value is converted to PtgCy. If DisplayUnit is a vUnitString, the resulting value is multiplied by a factor that converts the custom internal unit type associated with the type of the unit of DisplayUnit into the unit of DisplayUnit. If DisplayUnit is "$", the resulting value is converted to PtgCy.
Field picture: A field picture is a predefined index that specifies format strings. If the format string contains a field picture, it is replaced by the corresponding format string as specified in vFieldPicture before the formatting is performed. It MUST satisfy the following ABNF.
-
ABNF:
-
Field-picture = "{<" unsigned-int-value ">}" / "esc("unsigned-int-value ")"
-
-
The first unsigned-int-value specifies a field picture index. It MUST be a vFieldPicture. If it is not found in the table of vFieldPicture, the default value is following. If the value that is formatted is a PtgCy or vNumAny (except PtgDate, PtgEDay, PtgEHour, PtgEMin, PtgESec, or PtgEWeek), the default value is zero. If the value that is formatted is a PtgDate, PtgEDay, PtgEHour, PtgEMin, PtgESec, or PtgEWeek, the default value is 200. Otherwise, the formatting returns an empty string.
-
The second unsigned-int-value specifies a field picture index. It MUST be a vFieldPicture. If it is greater than 18, the default value is zero.
String format strings: If the format string contains the character "@", the value string is formatted into the result string as specified by the following table. The result strings produced by these format strings are influenced by the language specified for the formatting. The default value for the language is specified by the Language property, defined in [ISO/IEC29500-2:2012] section 11, from the Core XML part of a web drawing.
-
Format Character
Name
Description
\
Escape character
The next character is inserted into the result string and is not interpreted as a format character.
For example, to display the backslash character, "\\" is used.
"text"
'text'
Literal string
The text enclosed in quotation marks is inserted into the result string and the characters are not interpreted as format characters.
@
Text placeholder
The value string is inserted into the result string.
@+
Uppercase text placeholder
The value string is converted to uppercase and inserted into the result string.
@-
Lowercase text placeholder
The value string is converted to lowercase and inserted into the result string.
For example, FORMAT("Hello", "@ @+ @-") displays "Hello HELLO hello".
Date/Time format strings: If the format string does not contain the characters "@", "#", or "0", and does contain the characters "h", "H", "m", "M", "s", "S", "d", "D", "y", "Y", "t", "T", "g", "G", "n", "N", "e", "E", "w", "W", "c", or "C", the value is formatted as specified by the following table. The result strings produced by these format strings are influenced by the language and calendar that are specified for the formatting. The default value for the language is specified by the Language property, defined in [ISO/IEC29500-2:2012] section 11, from the Core XML part of a web drawing.
-
In the following table, the format character values listed on multiple lines in the same table row are equivalent.
|
Format Character |
Name |
Description |
|---|---|---|
|
d |
Day placeholder |
The day of the month as a number is inserted into the result string. |
|
dd |
Day placeholder |
The day of the month as a two-digit number, with a leading zero if necessary, is inserted into the result string. |
|
ddd w |
Short day of week placeholder |
The day as an abbreviation is inserted into the result string. |
|
dddd ww |
Long day of week placeholder |
The day as a full name is inserted into the result string. |
|
M |
Month placeholder |
The month as a number is inserted into the result string. |
|
MM |
Month placeholder |
The month as a two-digit number, with a leading zero if necessary, is inserted into the result string. |
|
MMM |
Month placeholder |
The name of the month in abbreviated form is inserted into the result string. |
|
MMMM |
Month placeholder |
The full name of the month is inserted into the result string. |
|
yy |
Year placeholder |
The year as a two-digit number is inserted into the result string. |
|
yyyy |
Year placeholder |
The year as a four-digit number is inserted into the result string. |
|
h |
Hour placeholder |
The hour in 12-hour form is inserted into the result string. |
|
hh |
Hour placeholder |
The hour as a two-digit number, with a leading zero if necessary, in 12-hour form is inserted into the result string. |
|
H |
Hour placeholder |
The hour in 24-hour form is inserted into the result string. |
|
HH |
Hour placeholder |
The hour as a two-digit number, with a leading zero if necessary, in 24-hour form is inserted into the result string. |
|
m |
Minute placeholder |
The minute is inserted into the result string. |
|
mm |
Minute placeholder |
The minute as a two-digit number, with a leading zero if necessary, is inserted into the result string. |
|
s |
Second placeholder |
The second is inserted into the result string. |
|
ss |
Second placeholder |
The second as a two-digit number, with a leading zero if necessary, is inserted into the result string. |
|
t |
AM/PM abbreviation |
The first character of the AM/PM designator for the value is inserted into the result string. |
|
tt am/pm |
AM/PM designator |
The AM/PM designator for the value is inserted into the result string. |
|
ddddd |
Short date placeholder |
The value is formatted using a format string "M/d/yyyy" and inserted to the result string.
For example, FORMAT(DATETIME("6/25/07 12:05"), "ddddd") displays 6/25/2007. |
|
dddddd |
Long date placeholder |
The value is formatted using a format string "dddd, MMMM dd, yyyy" and inserted to the result string.
For example, FORMAT(DATETIME("6/25/07 12:05"), "dddddd") displays Monday, June 25, 2007. |
|
c |
Short date/time placeholder |
The value is formatted using a format string "M/d/yyyy h:mm:ss tt" and inserted to the result string. If the time value is zero, the value is formatted using a format string "M/d/yyyy" and inserted to the result string.
For example, FORMAT(DATETIME("6/25/07 12:05"), "c") displays 6/25/2007 12:05:00 PM. |
|
C |
Long date/time placeholder |
The value is formatted using a format string "dddd, MMMM dd, yyyy h:mm:ss tt" and inserted to the result string.
For example, FORMAT(DATETIME("6/25/07 12:05"), "C") displays Monday, June 25, 2007 12:05:00 PM. |
|
T |
Long time placeholder |
The value is formatted using a format string "h:mm:ss tt" and inserted to the result string.
For example, FORMAT(DATETIME("6/25/07 12:05"), "T") displays 12:05:00 PM. |
|
/ |
Date separator |
The date separator is inserted into the result string. |
|
: |
Time separator |
The time separator is inserted into the result string. |
|
[y] [Y] |
Elapsed years placeholder |
The elapsed year value is inserted into the result string. |
|
[yy] [YY] |
Elapsed years placeholder |
The elapsed year value, as a two-digit number with a leading zero if necessary, is inserted into the result string. |
|
[w] [W] |
Elapsed weeks placeholder |
The elapsed week value is inserted into the result string. |
|
[ww] [WW] |
Elapsed weeks placeholder |
The elapsed week value, as a two-digit number with a leading zero if necessary, with a leading zero is inserted into the result string. |
|
[d] [D] |
Elapsed days placeholder |
The elapsed day value is inserted into the result string. |
|
[dd] [DD] |
Elapsed days placeholder |
The elapsed day value, as a two-digit number with a leading zero if necessary, is inserted into the result string. |
|
[h] [H] |
Elapsed hours placeholder |
The elapsed hour value is inserted into the result string. |
|
[hh] [HH] |
Elapsed hours placeholder |
The elapsed hour value, as a two-digit number with a leading zero if necessary, is inserted into the result string. |
|
[m] |
Elapsed minutes placeholder |
The elapsed minute value is inserted into the result string. |
|
[mm] |
Elapsed minutes placeholder |
The elapsed minute value, as a two-digit number with a leading zero if necessary, is inserted into the result string. |
|
[s] |
Elapsed seconds placeholder |
The elapsed second value is inserted into the result string. |
|
[ss] |
Elapsed seconds placeholder |
The elapsed second value, as a two-digit number with a leading zero if necessary, is inserted into the result string. |
Numeric format strings: If the format string does not contain the characters "@", and does contain the characters "#" or "0", the value is formatted as specified by the following table. The result strings produced by some of these format strings are influenced by the language that is specified for the formatting. The default value for the language is specified by the Language property, defined in [ISO/IEC29500-2:2012] Section 11, from the Core XML part of a web drawing.
-
Format Character
Name
Description
#
Digit placeholder
If the value being formatted has a digit in the position where the '#' appears in the format string, that digit is inserted into the result string. If the value has more digits than there are placeholders to the left of the decimal, all digits are inserted into the result string. If the value has more digits than there are placeholders to the right of the decimal, the fraction is rounded to the number of placeholders.
For example, FORMAT(0.0239, "#.###") displays as .024.
0
Zero placeholder
The digit in the position where the '0' appears in the format string is inserted into the result string. If the value has more digits than there are placeholders to the left of the decimal, all digits are inserted into the result string. If the value has more digits than there are placeholders to the right of the decimal, the fraction is rounded to the number of placeholders.
For example, FORMAT(0.0239, "0.00000") displays as 0.02390.
.
Decimal separator
The first '.' character in the format string determines the location of the decimal separator in the formatted value. Any additional '.' characters are ignored.
,
Thousands separator
If the format string contains a ',' character between two digit placeholders (0 or #) and if one is present to the left of the decimal point, the result string has a thousands separator inserted between each group of three digits to the left of the decimal separator.
E+
Scientific notation
If the format string contains at least one digit placeholder to the right of this character, the number is formatted using scientific notation with an 'E' inserted between the mantissa and the exponent. The number of digit placeholders following the scientific notation indicator determines the minimum number of digits to output for the exponent. A sign character '+' precedes the exponent.
For example, FORMAT(12345.67,"###.#E+0") displays as 123.5E+2.
e+
Scientific notation
If the format string contains at least one digit placeholder to the right of this character, the number is formatted using scientific notation with an 'e' inserted between the mantissa and the exponent. The number of digit placeholders following the scientific notation indicator determines the minimum number of digits to output for the exponent. A sign character '+' precedes the exponent.
E-
Scientific notation
If the format string contains at least one digit placeholder to the right of this character, the number is formatted using scientific notation with an 'E' inserted between the mantissa and the exponent. The number of digit placeholders following the scientific notation indicator determines the minimum number of digits to output for the exponent. A sign character '-' only precedes negative exponents.
e-
Scientific notation
If the format string contains at least one digit placeholder to the right of this character, the number is formatted using scientific notation with an 'e' inserted between the mantissa and the exponent. The number of digit placeholders following the scientific notation indicator determines the minimum number of digits to output for the exponent. A sign character '-' only precedes negative exponents.
/
Fraction placeholder
The value is formatted as a whole number and fraction, and inserted into the result string. The number of digits of the denominator is determined by the number of digit placeholders following the fraction placeholder. The maximum number of digits of a denominator is 5. The value is rounded to the nearest fraction and the simplest form of the fraction is inserted into the result string.
For example, FORMAT(12.43, "# #/#") displays as 12 3/7.
{space}
Space placeholder
A space character is inserted into the result string.
u
Lower case, Short label placeholder
A unit measurement of the numeric value in lower case, and an abbreviated form is inserted into the result string.
For example, FORMAT(12.43in, "#.## u") displays as 12.43 in.
U
Upper case, Short label placeholder
A unit measurement of the numeric value in upper case, and an abbreviated form is inserted into the result string.
For example, FORMAT(12.43in, "#.## U") displays as 12.43 IN.
uu
Lower case, Long label placeholder
A unit measurement of the numeric value in lower case is inserted into the result string.
For example, FORMAT(12.43in, "#.## uu") displays as 12.43 inches.
UU
Upper case, Long label placeholder
A unit measurement of the numeric value in upper case is inserted into the result string.
For example, FORMAT(12.43in, "#.## UU") displays as 12.43 INCHES.
uuu
Lower case, Universal label placeholder
A unit measurement of the numeric value in lower case, and a universal form is inserted into the result string.
For example, FORMAT(12.43in, "#.## uuu") displays as 12.43 in.
UUU
Upper case, Universal label placeholder
A unit measurement of the numeric value in upper case, and a universal form is inserted into the result string.
For example, FORMAT(12.43in, "#.## UUU") displays as 12.43 IN.